YAML Authoring Guide - Buzen ESB Docs

1. Canonical route shape

Recommended structure for all authored routes:

- route:
    id: order-processing
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: correlationId
            simple: "${header.X-Correlation-ID}"
        - to:
            uri: "jms:queue:orders.in"

Alternate top-level shape is accepted, but wrapped form with route: is preferred for tooling consistency.

2. Core authoring rules

Use explicit route IDs. Do not rely on auto-generated Camel IDs.
Include from.uri and explicit steps list.
Prefer kebab-case route IDs for readability and deterministic APIs.
Keep one functional concern per route for easier lifecycle control.
Add explicit error handling for non-trivial integrations.

3. Single-route constraints in app APIs and Flow Designer

Runtime can load multi-route files, but app route create/update endpoints enforce single-route content:

POST /api/v1/apps/{appId}/routes
PUT /api/v1/apps/{appId}/routes/{routeId}/content

Flow Designer import is also single-document, single-route oriented. Unsupported constructs may be preserved as custom nodes with warnings.

Schema: buzen-flow-designer-route.schema.json

4. Route IDs, step IDs, and collisions

Route IDs must be unique in active runtime context.
Route duplication workflows can auto-rename ingress paths, but route ID uniqueness still applies.
When app APIs detect duplicate Flow Designer generated step IDs (node_*), Buzen can regenerate them.
Duplicate non-generated user step IDs must be manually corrected.

5. Ingress path safety

Inbound HTTP style routes are validated against reserved platform paths. Conflicts cause deployment/update failure.

Typical reserved prefixes:

/api/v1 (management API base path)
/actuator
/console
/ws
/api-docs, /swagger-ui, /v3/api-docs

Do not design app routes on reserved prefixes even if requests appear to route in isolated tests.

6. Variables, placeholders, and data sources

Use global variable placeholders:

{{partner.base-url}}
{{db.user}}

Manage these via:

/api/v1/variables
/api/v1/data-sources for managed JDBC sources

DB routes should prefer dataSourceRef over embedding credentials in URIs.

- route:
    id: customer-lookup
    from:
      uri: "direct:lookup"
      steps:
        - to:
            uri: "buzen-db:execute?dataSourceRef=crm-db&query=select+*+from+customers+where+id=:#id"

7. DB Query authoring (buzen-db:execute)

The buzen-db:execute component is the canonical database step in Buzen ESB. It wraps Camel SQL with managed data source resolution and is the only URI scheme that round-trips through the Flow Designer.

Key URI options

Option	Type	Default	Purpose
dataSourceRef	string	primaryDb	Name of a managed data source (created via /api/v1/data-sources)
query	string		URL-encoded SQL statement
outputType	enum	SelectList	SelectList, SelectOne, StreamList, UpdateCount
useBodyAsParameters	boolean	true	Bind named params from body map fields
useHeadersAsParameters	boolean	false	Bind named params from message headers
useBodyAsSql	boolean	false	Execute SQL text from the message body instead of the query option

Named parameter syntax

Use :#paramName placeholders in SQL. Parameters bind from the message body (when useBodyAsParameters=true) or from headers (when useHeadersAsParameters=true).

-- Named parameters from body map
INSERT INTO orders(id, name) VALUES (:#id, :#name)

-- Where clause with body parameter
SELECT * FROM customers WHERE id = :#id

Example: HTTP POST to database insert

- route:
    id: http-to-db-insert
    from:
      uri: "platform-http:/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to:
            uri: "buzen-db:execute?dataSourceRef=ordersDb&query=insert+into+orders(id,name)+values(:#id,:#name)&outputType=UpdateCount&useBodyAsParameters=true"
        - setBody:
            constant: '{"status":"created"}'

Example: database read with header param

- route:
    id: db-lookup
    from:
      uri: "direct:lookup"
      steps:
        - to:
            uri: "buzen-db:execute?dataSourceRef=crmDb&query=select+*+from+customers+where+id=:#customerId&outputType=SelectOne&useHeadersAsParameters=true"

For Flow Designer routes, always use buzen-db:execute rather than raw Camel sql: URIs. Raw sql: routes will not import into the visual editor. See Database URI disambiguation.

8. Reference patterns

Pattern: HTTP -> JMS

- route:
    id: webhook-to-jms
    from:
      uri: "platform-http:/webhook/orders?httpMethodRestrict=POST"
      steps:
        - unmarshal:
            json: {}
        - to:
            uri: "jms:queue:orders.in"

Pattern: Robust outbound HTTP with dead letter

- route:
    id: outbound-partner-call
    errorHandler:
      deadLetterChannel:
        deadLetterUri: "jms:queue:dead.letter"
        useOriginalMessage: true
        maximumRedeliveries: 3
        redeliveryDelay: 1000
    from:
      uri: "direct:invokePartner"
      steps:
        - to:
            uri: "https://partner.example.com/api/orders"

Pattern: split + aggregate

- route:
    id: split-and-aggregate
    from:
      uri: "direct:bulk"
      steps:
        - split:
            simple: "${body.items}"
            steps:
              - to:
                  uri: "bean:itemProcessor?method=process"
        - to:
            uri: "bean:resultCollector?method=finish"

9. Pre-deploy checklist

Route contains explicit id and valid from.uri.
One route per file for app API and Flow Designer workflows.
No reserved ingress collisions.
Variables and dataSourceRef values exist in target environment.
Route and step IDs are unique.
Manifest autoStart values reflect intended startup behavior.

Reference sources: yaml-authoring-guide.md and app-route-upsert-request.schema.json.