Kamelets

A Kamelet (“Kamel route snippet”) is a reusable, parameterized Camel route packaged as a single YAML file. It encapsulates a block of integration logic behind a small set of named properties. You call it from a connector with kamelet:<name>?prop=value instead of repeating the underlying route. Grand Central connectors use kamelets for every reusable step: the outbound HTTP call, vendor SDK calls, and the structured exception handlers. Kamelets are a native Apache Camel concept. For more information, see Apache Camel Kamelets documentation. They run in the connector’s Camel K and Quarkus runtime. Each kamelet is a Kubernetes custom resource (kind: Kamelet). The connector build loads platform and custom kamelets from the classpath.

Platform and upstream kamelet repositories

The grandcentral-platform-kamelets repository contains the platform kamelets and publishes them as a Maven artifact (com.backbase.gc.generic:grandcentral-platform-kamelets). Connectors that use grandcentral-bom already depend on this artifact. Call a platform kamelet by name (kamelet:<name>). Each kamelet is one *.kamelet.yaml file under src/main/resources/kamelets.

Platform kamelets: bb-ecos-core/grandcentral-platform-kamelets
Upstream catalog and examples: apache/camel-kamelets

Before you write a kamelet, check both repositories. Most connectors need only the platform kamelets. For the outbound REST call, use the gc-http-caller kamelet. For more information, see Call REST endpoints. For more information about error mapping, see Exception-handler kamelets.

Kamelet types

Every kamelet declares its type through the camel.apache.org/kamelet.type label. The following table shows the three types.

Type	Role	Example
`source`	Starts a flow or produces data; the connector calls it with `.to(...)`	`gc-http-caller`, `gc-asb-producer-caller`, exception-handler kamelets
`sink`	Consumes data at the end of a flow	None in the platform catalog
`action`	Transforms or processes data mid-flow	`pgp-transform`

Anatomy of a kamelet

A kamelet is one YAML document with four parts: metadata, a definition (its public contract), its dependencies, and a template (the route itself). The following sample is a shortened gc-http-caller. It keeps the URL step. For the full property list, see Call REST endpoints.

apiVersion: camel.apache.org/v1alpha1
kind: Kamelet
metadata:
  name: gc-http-caller                      # must match the file name <name>.kamelet.yaml
  labels:
    camel.apache.org/kamelet.type: "source" # source | sink | action
spec:
  definition:                               # the public contract (JSON Schema)
    title: "HTTP Source"
    description: |-
      Performs an HTTP request to a specified URL
    type: object
    properties:
      method:
        title: Method
        description: The HTTP method to use.
        type: string
        default: GET
        enum: ["GET", "POST", "PUT", "DELETE", "PATCH"]
      errorTemplate:
        title: JOLT Mapping Template
        description: JOLT Mapping Template for exception handling
        type: string
        default: transform-error-details.json
    # required: [ ... ]                      # list properties the caller must supply
  dependencies:                             # Camel components / Maven artifacts it needs
    - "camel:http"
    - "camel:kamelet"
  template:                                 # the actual Camel route
    beans:
      - name: httpRequestProcessor
        type: "#class:com.backbase.grandcentral.sdk.processor.HttpRequestProcessor"
    from:
      uri: "kamelet:source"                 # entry point for a source/action kamelet
      steps:
        - setHeader:
            name: CamelHttpMethod
            constant: "{{method}}"          # {{property}} interpolates a definition property
        - setHeader:
            name: CamelHttpUri
            simple: "${exchangeProperty.gc-http-caller-url}"
        - toD:
            uri: "${header.CamelHttpUri}"
        - to: "kamelet:sink"                # returns the exchange to the calling route

Key points:

metadata.name must match the file name (<name>.kamelet.yaml) and is the name callers use in kamelet:<name>.
spec.definition is a JSON Schema. Each properties entry becomes a query parameter. Give every property a title, description, type, and a default where sensible; list mandatory ones under required.
{{property}} interpolates a declared property into the route. Use {{?property}} for an optional one that may be unset.
kamelet:source and kamelet:sink are the fixed input and output endpoints that wire the kamelet into the caller’s exchange. A source or an action reads from kamelet:source and ends with to: kamelet:sink. A sink reads from kamelet:source and routes to the external system instead.
spec.dependencies must list every Camel component and Maven artifact the template uses, so the runtime resolves them at build time.

How a connector calls a kamelet

From a connector route, address the kamelet by name and pass properties as query parameters:

.setProperty("gc-http-caller-url", simple("{{vendor.base.url}}/api/path"))
.to("kamelet:gc-http-caller?method=GET&gc-http-caller-retry={{retryFlag}}");

Set object inputs (headers, query parameters, and path variables) as exchange properties or headers before the call. Pass single values as query parameters. For the full gc-http-caller contract, see Call REST endpoints.

Create a custom kamelet

Add a custom kamelet only when no platform or upstream kamelet fits, such as a vendor SDK caller or a transformation shared across operations. To add the kamelet, follow these steps:

Name it. Choose a lowercase, hyphenated name and create src/main/resources/kamelets/<name>.kamelet.yaml. Match the naming convention (for example <vendor>-api-caller, <vendor>-properties, or <purpose>-handler).
Pick the type. Set camel.apache.org/kamelet.type to source, sink, or action.
Define the contract. Under spec.definition.properties, declare each input with title, description, type, and a default. Add required inputs to required. Keep the contract small, and prefer sensible defaults over many mandatory properties.
Declare dependencies. List every Camel component and Maven artifact under spec.dependencies.
Write the route. For a source or an action, start spec.template.from at kamelet:source, add the steps, reference the beans you need, and finish with to: kamelet:sink. For a sink, start at kamelet:source and route to the external system instead of kamelet:sink. Interpolate properties with {{property}} or {{?property}}.
Package it. Keep the file under src/main/resources/kamelets/. The connector build packages that file with the connector. The grandcentral-bom dependency provides the platform kamelets.
Run the connector. On a cluster, use mvn kamel:dev. For more information, see Test and validate.
Document the inputs. Add the kamelet, its properties, exchange properties, and defaults to the table in the connector repository README file. Other connector developers use that table when they call the kamelet.

Kamelet tools

Kameleon: a standalone web editor for writing and revising kamelet YAML. Use it to draft the definition and template before you commit the file.
mvn kamel:dev: builds the connector and runs it on the cluster. For more information, see Test and validate.
Apache reference: the Kamelet development guide, which documents every field and additional options such as data types and error handling.

Next step

For the kamelet used on every outbound REST call, see Call REST endpoints.

Overview

Capabilities

Developer guides

Security and reliability

Platform administration

Connector Studio

Reference

Platform and upstream kamelet repositories

Kamelet types

Anatomy of a kamelet

How a connector calls a kamelet

Create a custom kamelet

Kamelet tools

Next step

​Platform and upstream kamelet repositories

​Kamelet types

​Anatomy of a kamelet

​How a connector calls a kamelet

​Create a custom kamelet

​Kamelet tools

​Next step

Platform and upstream kamelet repositories

Kamelet types

Anatomy of a kamelet

How a connector calls a kamelet

Create a custom kamelet

Kamelet tools

Next step