Integration folders and routes

An integration is a directory of Camel files, written the way you write them for Camel JBang. Every file of the folder, in any subfolder, arrives on the platform at its own relative path, and a route that reads ./config/mystuff.ini finds it there. The platform refuses a route only where Camel itself fails on it, and then in Camel’s own words.

The folder of an integration#

The finance team’s ERP export looks like this:

erp-invoice-export/
  integration.yaml              optional: version, Camel line, requirements, dependencies
  routes/
    fetch-invoices.camel.yaml
    transform.camel.yaml
    publish.camel.yaml
  beans/
    InvoiceMapper.java
  kamelets/
    erp-paging-source.kamelet.yaml
  application.properties        static settings of the integration
  mapping.txt
  README.md                     shown on the integration's page in the admin UI

A route uses the values of the environment it runs in as ordinary Camel properties:

- route:
    from:
      uri: timer:tick?period=60000
      steps:
        - setHeader: { name: Authorization, simple: "Bearer {{erp-api-key}}" }
        - to: "{{erp-url}}/api/invoices/pending"
        - to: direct:transform

What Camel loads#

Every kind of file Camel loads works in the folder:

• Routes in the YAML DSL (*.camel.yaml), in XML, and in Java (*.java).
• Java beans such as beans/InvoiceMapper.java. The builder compiles them with javac, so the bean classes run as they do under Camel JBang.
• Kamelets (*.kamelet.yaml) in any folder, which the integration uses without listing them.
• Route templates, route configurations and the REST DSL.
• Camel K style Pipe files.
• Jars anywhere in the folder, such as a libs/ folder, for libraries that are in no Maven repository. They go on the classpath and on javac’s classpath, with no size limit.

A folder is an integration when it has integration.yaml, or a route file at its top level. A folder whose routes are all in subfolders declares itself with integration.yaml. A YAML file that is a platform document (apiVersion: weik.io/v1) is never taken for a route.

Two folders are left out wherever they are: .camel-jbang/, which is Camel JBang’s run state, and .git/, which may have credentials. The CLI says so in a note when it leaves one out.

integration.yaml#

integration.yaml is optional. Without it, the integration is named after its folder, the project comes from the nearest project.yaml, the Camel version is the platform’s default, and any agent of the target environment may run it. Add it when you need a version number, a specific Camel line, requirements or dependencies:

name: erp-invoice-export
version: 1.0.0
camelVersion: "4.22.1"
requirements: { os: linux }
dependencies:
  - camel:jdbc                                        # a component the routes don't show by URI
  - mvn:com.microsoft.sqlserver:mssql-jdbc:12.8.1.jre11
kamelets: [erp-paging-source]                         # shared kamelets of the project

weikio init writes this flat form. The CLI and the admin UI also accept the same fields as a document with apiVersion: weik.io/v1, kind: integration, metadata and spec. A field no integration has is refused, by weikio validate and weikio apply alike.

application.properties#

application.properties at the top of the folder is the integration’s own set of properties. A key it defines belongs to the integration: the project’s values don’t replace it, and only a value set for the integration itself or a deployment override does. Values that differ between environments belong in variables and secrets.

Maven repositories are never named in an integration. They are the platform’s configuration, so camel.jbang.repos in application.properties is refused.

README.md#

A README.md in the folder is shown on the integration’s Overview in the admin UI as GitHub-flavoured Markdown. Each mermaid code block in it is drawn as a diagram, so a flow chart of the routes sits beside the integration’s figures. The Source section shows every file of each version, and a relative link in the README opens the file it points to.

A Camel application you already have#

A team that runs its Camel routes as separate Spring Boot, Quarkus or JBang applications moves each one into a folder: the routes, beans, kamelets and properties go into the folder, and the dependencies become Maven coordinates in integration.yaml or jars in libs/.

$ weikio apply -f ./finance/erp-invoice-export
$ weikio deploy finance/erp-invoice-export --env devtest

Versions and the developer loop explains what apply builds.