Extension Libraries

On top of the CEL standard library and Octo's own functions, the runtime enables seven of cel-go's utility libraries: cleaning up strings, sorting and de-duplicating lists, base64-encoding, rounding, turning a list into a lookup map, testing set membership, and pulling values out of semi-structured text.

They are registered through the same seam as everything else, so they are available with nothing to turn on in every expression: block settings, if/switch conditions, foreach items, validate rules, connector fields, source payloads, and a template's {{ }} spans. Reach for them before adding a foreach, since most collection work that used to need a loop is now a single expression.

Every example on this page was verified with octo eval; results are shown as it prints them. See samples/cel-extensions.yaml for a flow that uses most of them together.

Strings

Receiver-style string manipulation. format also gives you interpolation without reaching for a template.

format

string.format(list) substitutes each argument in order: %s renders any value, %d an integer, %f a double (%.2f fixes the precision), %e scientific notation, %b/%o/%x/%X binary, octal, and hex. A literal percent is %%.

In a flow, a log line that stays readable as it grows:

- type: log
  name: emit
  settings:
    message: '"order %s: %d lines".format([body.id, size(body.lines)])'

Lists

Collection reshaping. sortBy and distinct have no standard-CEL workaround at all; before these, both meant a foreach.

sort works on comparable scalars: int, uint, double, bool, duration, timestamp, string, bytes. Sorting a list of objects is sortBy with the key to sort on. Both sort ascending; compose with reverse() for descending.

In a flow, the three most expensive lines, largest first:

- type: set-payload
  name: top-lines
  settings:
    value: 'body.lines.sortBy(l, l.amount).reverse().slice(0, 3)'

Encoders

Base64, which an expression previously could not do at all.

encode takes bytes, so convert first with bytes(...); decode returns bytes, so wrap it in string(...) to read it as text. Encoding is standard base64 with padding, not the URL-safe alphabet.

In a flow, a basic-auth header built from the environment:

- type: rest
  name: call-api
  settings:
    connector: orders-api
    method: GET
    path: /v1/orders
    headers:
      Authorization: '"Basic " + base64.encode(bytes(env.API_USER + ":" + env.API_TOKEN))'

Math

Aggregation over a mapped collection, and rounding.

bitOr, bitXor, bitNot, and bitShiftRight round out the bit operations. isInf completes the float guards alongside isNaN and isFinite, which matter because JSON has a single number type, so a value that arrived as a double can be anything.

bin/octo eval --expr 'math.round(1.005 * 100.0) / 100.0'
# {"ok":true,"result":1}          <- not 1.01

bin/octo eval --expr 'math.round(1.015 * 100.0) / 100.0'
# {"ok":true,"result":1.01}       <- this one happens to work

math.round is still the right tool for a value that is genuinely fractional, such as a rate, a score, or a percentage, where a cent is not on the line.

math.greatest and math.least take either a list or a set of arguments, which is what makes a maximum over a collection a single expression:

- type: set-variable
  name: largest-line
  settings:
    name: topLineCents
    value: 'math.greatest(body.lines.map(l, l.qty * l.unitPriceCents))'

Two-variable comprehensions

The standard macros (map, filter, all, exists) bind one variable, which on a map is the key, leaving the value out of reach. These bind both, and add transforms that produce a map rather than a list.

On a list the first variable is the index; on a map it is the key. transformMap keeps the keys and rewrites the values; transformMapEntry chooses both, so it is what turns a list into a lookup map, the reshaping that most often forced a foreach. An entry whose expression yields an empty map {} is skipped, which is how transformMapEntry filters.

- type: set-payload
  name: index-by-sku
  settings:
    value: 'body.lines.transformMapEntry(i, l, {l.sku: l.qty})'

Sets

List membership as a predicate, for routing and filtering on tags, scopes, or roles.

sets.contains(a, b) is true when every element of b appears in a. It is the subset test, so the required scopes go second:

- type: if
  name: may-write
  condition: 'sets.contains(vars.scopes, ["orders:write"])'

Regex

Extraction from semi-structured text: the closest thing to a parser for a format Octo does not decode natively. Patterns are RE2, with no backreferences or lookaheads, and linear-time by construction.

extract and extractAll return the capture group when the pattern has exactly one, and the whole match when it has none. More than one capture group is an error, so use a non-capturing group (?:…) for the parts you do not want. In replace, \1…\9 insert the corresponding group.

Remember the YAML quoting rule: the pattern is a CEL string literal, so a regex \d is written \\d inside it.

- type: set-variable
  name: extract-order-id
  settings:
    name: orderId
    value: 'regex.extract(body.reference, "ORDER-(\\d+)").orValue("unknown")'

Absent results

regex.extract reports "no match" as an optional, a successful result meaning absent rather than a failure. Octo resolves an optional to its value, or to null when it is absent, so a miss flows on as a null field rather than failing the message. Three ways to handle one:

optional.unwrap drops the misses from a list of them, which is how a whole column gets extracted at once:

optional.unwrap(["a1", "zz"].map(s, regex.extract(s, "a(\\d)")))
# {"ok":true,"result":["1"]}

first() and last() on a list are optionals too, which is why [].first() is null instead of an out-of-range error.

What is not available

The libraries are pinned to specific versions (runtime/core/expr/stdext.go), so this vocabulary does not shift under an existing flow when cel-go is upgraded. Deliberately outside it:

Names outside the catalogue fail at compile time, when the flow is built, so a typo like "abc".toUpper() fails the deployment with undeclared reference to 'toUpper', never a live message.