Simple language

Simple is Camel's built-in expression language: text templates with ${...} functions that read the body, headers, properties and variables, plus predicates with operators such as ==, contains, regex and in.

Name: simple · Also: csimple (same implementation, see csimple) · Crate: cameleer-core · Cargo feature: none, always included (build features) · Apache Camel: Simple

Simple is what you use most in Cameleer routes: to build a message body or a prompt, set a header, name a file, filter messages and route them. A plain string in a YAML expression position is Simple, so setBody: {expression: "Hello ${body}"} and setBody: {simple: "Hello ${body}"} are the same.

Every expression and result in the tables on this page is checked by the test suite (crates/cameleer-main/tests/docs_languages_formats.rs) against the message shown above the table.

Contents

• When to use it
• Syntax in one minute
• Examples: routes
• Message functions: body, headers, properties, variables
• Navigating JSON and objects (OGNL)
• Method calls on values
• String functions
• Collection functions
• Math functions
• Conditionals: ternary, Elvis, iif, not
• JSON, XML and other languages inside Simple
• Exchange, context and environment functions
• Dates
• Random values and ids
• File language
• Predicates and operators
• Escaping and literal text
• Differences from Apache Camel
• Common questions

When to use it

• Build a body from parts of the message: Hello ${header.name}, your order ${body.id} shipped.
• Build an LLM prompt from a JSON request and pick fields out of the model's JSON answer.
• Route and filter: ${header.priority} == 'high' && ${body.amount} > 1000.
• Name files and keys: orders/${date:now:yyyy/MM/dd}/${file:onlyname.noext}.json.
• Small transformations without code: trim, replace, split, join, sum, hash, base64.

For heavier JSON work use JSONPath or jq (both callable from Simple), for XML use XPath, and for real logic a script language such as JavaScript.

Syntax in one minute

A template that is one function only (${body.order.id}) keeps the type of the value: a number stays a number, a list stays a list. A template with any literal text around it gives a string.

Examples: routes

Build a prompt for a model from a JSON request

The body is parsed with the JSON data format, so Simple can navigate into it. The prompt goes to the model (here it is just returned).

- route:
    id: build-prompt
    from:
      uri: direct:prompt
      steps:
        - unmarshal:
            json: {}
        - setHeader:
            name: tone
            simple: "${body.tone ?: 'friendly'}"
        - setBody:
            simple: |-
              You are a support agent for ${body.product}. Answer in a ${header.tone} tone.
              Customer ${body.customer.name} asks: ${body.question.trim()}
              Known order ids: ${join(', ', '#', ${body.orders})}

{"product":"Acme Router","customer":{"name":"Ada"},"question":"  Why is the light red?  ","orders":[1001,1002]}

You are a support agent for Acme Router. Answer in a friendly tone.
Customer Ada asks: Why is the light red?
Known order ids: #1001, #1002

Route on the model's answer

A model was asked to answer with JSON such as {"category":"billing","confidence":0.93}. Low-confidence answers go to a human queue.

- route:
    id: route-on-answer
    from:
      uri: direct:answer
      steps:
        - unmarshal:
            json: {}
        - choice:
            when:
              - simple: "${body.confidence} < 0.6"
                steps:
                  - setBody:
                      simple: "human review: ${body.category}"
              - simple: "${body.category} in 'billing,refund'"
                steps:
                  - setBody:
                      simple: "billing queue (${body.confidence})"
            otherwise:
              steps:
                - setBody:
                    simple: "general queue: ${body.category.toUpperCase()}"

{"category":"billing","confidence":0.93}

billing queue (0.93)

{"category":"refund","confidence":0.41}

human review: refund

{"category":"shipping","confidence":0.88}

general queue: SHIPPING

Filter with headers and a typed header

- route:
    id: simple-filter
    from:
      uri: direct:filter
      steps:
        - setBody:
            constant: dropped
        - filter:
            simple: "${header.priority} =~ 'HIGH' && ${headerAs(amount, Integer)} range '100..10000'"
            steps:
              - setBody:
                  simple: "kept: ${header.priority} ${header.amount}"

x

kept: high 250

x

dropped

Name a file with the file language and a date

The CamelFileName header is what the file consumer sets; here it is set by hand so the example runs without a directory.

- route:
    id: simple-file-name
    from:
      uri: direct:file-name
      steps:
        - setHeader:
            name: CamelFileName
            constant: inbox/2024-06-orders.csv
        - setHeader:
            name: CamelFileLastModified
            constant:
              expression: "1718000000000"
              resultType: long
        - setBody:
            simple: "archive/${date:file:yyyy/MM}/${file:onlyname.noext}.json (${file:ext}, from ${file:parent})"

a,b

archive/2024/06/2024-06-orders.json (csv, from inbox)

Increment a counter header and read the route id

- route:
    id: counter-route
    from:
      uri: direct:counter
      steps:
        - setHeader:
            name: attempt
            simple: "${header.attempt}++"
        - setBody:
            simple: "route ${routeId}, attempt ${header.attempt}, body type ${bodyType}"

x

route counter-route, attempt 3, body type java.lang.String

Use the exception message in an error handler

- route:
    id: simple-exception
    from:
      uri: direct:exception
      steps:
        - doTry:
            steps:
              - setBody:
                  simple: "${mandatoryBodyAs(Integer)}"
            doCatch:
              - exception:
                  - java.lang.Exception
                steps:
                  - setBody:
                      simple: "failed (${exception.class}): not a number: ${body}"

abc

failed (NoTypeConversionAvailableException): not a number: abc

Message functions

All tables in this section use this message (body is a string, headers, exchange properties and variables are maps):

{
  "body": "Hello World",
  "headers": {"name": "Ada", "amount": "250", "tags": "a,b,c", "n": 5, "priority": "high", "my-header": "dash"},
  "properties": {"region": "eu"},
  "variables": {"user": "ada"}
}

Navigating JSON and objects (OGNL)

When the body (or a header) is a JSON object, a map or a list, . and [...] navigate into it. A JSON text body is parsed on the fly for navigation, so ${body.a.b} works on the string {"a":{"b":7}} too. ?. stops at null instead of failing.

{
  "body": {
    "order": {"id": 42, "items": [{"sku": "A1", "qty": 2, "price": 9.5}, {"sku": "B2", "qty": 1, "price": 20}]},
    "customer": {"name": "Ada", "email": null}
  }
}

{"bodyText": "{\"answer\":{\"label\":\"spam\",\"score\":0.97}}"}

Method calls on values

Values support the common Java String, List and Map methods.

String functions

Most functions work on the body when no value is passed, or on the last argument (which can be any expression, such as ${header.name}). Arguments are quoted with ' or "; inside function arguments ,, &space;, ∅, " and ' stand for those characters.

Collection functions

{"body": [3, 1, 4, 1, 5]}

Math functions

${header.n}++ and -- return the changed number; to store it, use them in a setHeader (see the counter example).

Conditionals: ternary, Elvis, iif, not

JSON, XML and other languages inside Simple

jsonpath(...), jq(...) and xpath(...) run those languages on the body, or on another value given as the first argument.

${prettyBody} and ${pretty(value)} print JSON indented on several lines; ${pretty(${body.customer})} gives:

{
  "name": "Ada",
  "email": null
}

{"body": "<order id=\"7\"><item>pen</item><item>ink</item></order>"}

Exchange, context and environment functions

More functions of this group, whose values change per run:

Dates

${date:<command>:<pattern>} formats a date with a Java SimpleDateFormat pattern (yyyy, MM, dd, HH, mm, ss, SSS, EEE, MMM, Z, 'T'...). Commands:

• now, now-1h, now+2d (offsets in ms, s, m, h, d)
• millis (the current time in ms, without a pattern)
• header.<name>, exchangeProperty.<name>, variable.<name>: a date, a timestamp in ms, or an ISO-8601 text in that header, property or variable, with optional offsets
• exchangeCreated, file (the CamelFileLastModified header)

${date-with-timezone:<command>:<zone>:<pattern>} formats in a time zone (UTC, Europe/Paris, GMT+02:00...). Without it dates format in the process default zone (UTC unless TZ is set).

{"headers": {"CamelFileName": "in/orders/2024-06.csv.gz", "CamelFileLastModified": 1718000000000, "due": "2024-06-10T06:13:20Z"}}

The current time, checked by pattern:

Random values and ids

File language

${file:...} functions read the CamelFile* headers set by the file, ftp and similar consumers. They are used in fileName, move, preMove, doneFileName and similar options, and anywhere in Simple.

Typical uses:

• move: "done/${date:now:yyyy/MM/dd}/${file:name}": archive by day.
• fileName: "${file:onlyname.noext}.json": same name, new extension.
• moveFailed: "error/${file:name}.${exchangeId}".

Predicates and operators

A predicate is left operator right, combined with && / and and || / or (&& binds tighter). The left side is usually a ${...} function; the right side a quoted literal, a number, null, true/false or another function. When one side is a number (an unquoted literal such as 100, or a numeric header), a numeric text on the other side is compared as a number: ${header.amount} > 100 is true for the text 250. When both sides are text, they are compared as text, and range 'a..b' bounds are always text: convert first with ${headerAs(amount,Integer)}. A predicate without an operator is true when the value is true (or the text true) and false for null, false and empty values.

Escaping and literal text

\n, \t and \r in a Simple text become a newline, tab and carriage return, so Line1\nLine2 gives two lines.

In route files, {{name}} is a property placeholder resolved when the route loads, before Simple runs. Use ${properties:name} to read a property at run time.

Options

Simple has no language options. resultType given on a simple: expression in YAML converts the result, as for any language.

Rust DSL

b.from("direct:simple-rust")
    .set_header("greeting", simple("Hello ${body}"))
    .filter(simple("${header.greeting} contains 'World'"))
    .set_body(simple("${header.greeting.toUpperCase()}!"))
    .end();

Differences from Apache Camel

• No Java objects: values are JSON-like (string, number, boolean, list, map, bytes), so OGNL calls are limited to the common String, List and Map methods listed above, and ${bodyType} reports the Java type name that matches the value.
• ${body.a.b} on a JSON text body navigates into the parsed JSON; Camel needs a converted body for that.
• ${sys.*} maps the common Java system property names (os.name, user.dir, user.home, java.io.tmpdir, line.separator...) to the operating system.
• ${type:...} knows the org.apache.camel.Exchange constants and a few java.lang ones only.
• ${exception.class} is the Cameleer error kind (for example NoTypeConversionAvailableException), not a Java class name.
• csimple is the same interpreter, not compiled Java.

Common questions

How do I read a JSON field in Simple?

Unmarshal the body with the JSON data format and use ${body.field.sub}, or call ${jsonpath('$.field.sub')} directly on the JSON text. A JSON text body also works with ${body.field} for simple navigation.

How do I give a default when a header is missing?

Use the Elvis operator: ${header.region ?: 'eu'}. It also replaces an empty string.

Why does my comparison of two numbers behave like text?

Both sides are text. ${header.amount} > 100 compares numbers (the literal 100 is a number), but ${header.amount} > '99' and ${header.amount} range '1..99' compare text, so 250 sorts before 99. Write numbers unquoted, or convert the header with ${headerAs(amount,Integer)}. Apache Camel converts the range bounds to the type of the left side, so this differs.

How do I get the current date in a file name?

${date:now:yyyyMMdd}, for example fileName: "report-${date:now:yyyy-MM-dd}.csv". Add date-with-timezone:now:Europe/Paris: to format in another zone.

How do I write ${ literally, for example in a template sent to another system?

Write \${ or $${. To avoid Simple completely, use the constant language.

Related

• csimple, constant, header, exchangeProperty, variable
• JSONPath, jq, XPath: structured data
• JSON data format
• File component: where the file language is used most
• Apache Camel Simple language
• Apache Camel File language

Found a problem?

If something on this page doesn't match what Cameleer does, or you hit a bug while building with it, please help fix it, whether you are a person or a coding agent: open an issue that describes what you saw, then fork the repository, fix it, add or update a test, run cargo test --workspace, and open a pull request. CONTRIBUTING.md explains the ground rules.