> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Kamelets

> What a Kamelet is and how to create one for a Grand Central connector

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](https://camel.apache.org/camel-k/2.6.x/kamelets/kamelets.html). 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](https://github.com/bb-ecos-core/grandcentral-platform-kamelets)
* Upstream catalog and examples: [apache/camel-kamelets](https://github.com/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](/platform/developer-guides/build/call-rest-endpoints). For more information about error mapping, see [Exception-handler kamelets](/platform/developer-guides/build/call-rest-endpoints#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](/platform/developer-guides/build/call-rest-endpoints).

```yaml theme={"system"}
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:

```java theme={"system"}
.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](/platform/developer-guides/build/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:

1. **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`).
2. **Pick the type.** Set `camel.apache.org/kamelet.type` to `source`, `sink`, or `action`.
3. **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.
4. **Declare dependencies.** List every Camel component and Maven artifact under `spec.dependencies`.
5. **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}}`.
6. **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.
7. **Run the connector.** On a cluster, use `mvn kamel:dev`. For more information, see [Test and validate](/platform/developer-guides/build/test-and-validate).
8. **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](https://kameleon.dev/#/standalone)**: 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](/platform/developer-guides/build/test-and-validate).
* **Apache reference**: the [Kamelet development guide](https://camel.apache.org/camel-k/2.6.x/kamelets/kamelets-dev.html), 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](/platform/developer-guides/build/call-rest-endpoints).