Utility Functions

Nine general-purpose functions are available to a Function step:

Function	Payload	Returns
`base64-encode`	the value itself	base64 string
`base64-decode`	the base64 string itself	the decoded value
`JSON-XML`	`{json, options}`	XML text
`XML-JSON`	`{xml, options}`	JSON
`Handlebars Template`	`{template, variables}`	rendered string
`Mapping`	`{data, path}`	the mapped object
`secret-key-get-node`	`{key}`	`{value}` or `{error}`
`function-invoke-node`	`{invocation_type, payload, subject}`	the raw reply
`SFTP`	connection and file details	a string

Every result below was produced by running the shipped function, except where an entry says otherwise.

base64-encode

The payload is the value itself, not an object wrapping it. A string is encoded as it is; anything else is serialised to JSON first. Payload {"a": 1, "b": "x"} → "eyJhIjoxLCJiIjoieCJ9" Payload "hello world" → "aGVsbG8gd29ybGQ=" To encode a value from an earlier step, the whole payload is the expression:

"$.BUILD_REPORT.body"

base64-decode

The payload is the base64 string. The decoded text is returned parsed if it is valid JSON, and as text otherwise. There is no option to control this. Payload "eyJhIjoxLCJiIjoieCJ9" → {"a": 1, "b": "x"} Payload "aGVsbG8gd29ybGQ=" → "hello world" A downstream step therefore has to cope with either shape unless you know what was encoded.

JSON-XML

object | array | string

required

The value to convert. A string is parsed as JSON first.

object

Only useXmlJs is read — see the warning below. Every other key the form offers is ignored.

Payload

{ "json": { "order": { "id": "ord_88", "lines": [{ "sku": "A-1", "qty": "1" }, { "sku": "B-2", "qty": "3" }] } } }

Returns

<?xml version="1.0"?><order><id>ord_88</id><lines><sku>A-1</sku><qty>1</qty></lines><lines><sku>B-2</sku><qty>3</qty></lines></order>

An array becomes a repeated element. null and "" become a self-closing tag. &, < and > in text are escaped. The XML declaration is always emitted.

Do not set useXmlJs. With it on, the function returns <?xml version="1.0"?> and nothing else — the library it switches to expects a different input format and silently produces an empty document.The options table this function’s form shows — spaces, compact, ignoreDeclaration, fullTagEmptyElement and the rest — has no effect either. Only useXmlJs is read, and only to pick a code path. The output is always unindented and always carries the declaration.

Failure. A json string that is not valid JSON returns {"error": "The JSON structure is invalid"}.

XML-JSON

string

required

The XML text to convert.

object

Parsing options. Unlike JSON-XML, these are honoured.

The options worth knowing:

Option	Effect
`compact`	Produce the readable nested shape instead of the verbose element list.
`nativeType`	Convert numeric and boolean text to real numbers and booleans.
`trim`	Strip whitespace around text nodes.
`ignoreAttributes`	Drop element attributes.
`ignoreDeclaration`	Drop the `<?xml?>` declaration from the result.
`alwaysArray`	Always wrap sub-elements in an array, even when there is one.

Payload

{ "xml": "<order><id>ord_88</id><line sku=\"A-1\">1</line></order>" }

Returns — the default, verbose form:

{"elements":[{"type":"element","name":"order","elements":[{"type":"element","name":"id","elements":[{"type":"text","text":"ord_88"}]},{"type":"element","name":"line","attributes":{"sku":"A-1"},"elements":[{"type":"text","text":"1"}]}]}]}

Payload with {"compact": true, "nativeType": true, "ignoreAttributes": true} over <o><n>42</n></o>:

{ "o": { "n": { "_text": 42 } } }

Set compact: true unless you have a reason not to. The default shape is an element tree that takes several JSONPath hops per field.

The function itself returns JSON text. Because that text is valid JSON, the flow runtime re-parses it, so the step’s result is an object and $.STEP_ID.o.n._text works. This is derived from the invocation path rather than observed end to end.

Failure. Malformed XML returns {"error": "Unexpected close tag\nLine: 0\nColumn: 10\nChar: >"} — the parser’s own message, with line and column.

Handlebars Template

string

required

A Handlebars template.

object

required

The values the template refers to.

Payload

{
  "template": "Hi {{name}}, you have {{count}} open items.\n{{#each items}}- {{this.ref}} ({{this.status}})\n{{/each}}",
  "variables": {
    "name": "Dana",
    "count": 2,
    "items": [{ "ref": "T-104", "status": "open" }, { "ref": "T-106", "status": "waiting" }]
  }
}

Returns

Hi Dana, you have 2 open items.
- T-104 (open)
- T-106 (waiting)

Two behaviours to plan for:

A missing variable renders as nothing. {{missing}} produces an empty string, not an error. A template that silently loses a field is the usual failure here.
{{ }} escapes HTML; {{{ }}} does not. <b>&</b> renders as <b>&</b> through the double form. Use the triple form for text that is not going into HTML.

Mapping

Reshapes data using JSONPath, the same idea as the Map step.

object

required

The data to read from.

object | string | array

required

The mapping. Strings beginning with $. are resolved against data.

Use the Map step instead. This function is an older copy of the same mapper and it does not behave the same way. Verified against both engines with identical input:

"$.items[*].sku" over a two-item list gives ["A-1", "B-2"] from the Map step and "A-1" from this function — only the first match.
A path that matches nothing gives [] from the Map step; this function drops the key from the result entirely.
A concatenation template beginning with literal text is prefixed with the word undefined. "Order " followed by two resolved segments comes back as "undefinedOrder ord_88 for Dana" where the Map step gives "Order ord_88 for Dana". Starting the template with a path instead avoids it.

The one thing this function does that the Map step does not is a per-item mapping over a list, using a three-element array: Payload

{
  "data": { "items": [{ "sku": "A-1", "qty": 1 }, { "sku": "B-2", "qty": 3 }] },
  "path": { "lines": ["$.items[*]", { "code": "$.sku", "n": "$.qty" }, { "merge": false }] }
}

Returns

{ "lines": [{ "code": "A-1", "n": 1 }, { "code": "B-2", "n": 3 }] }

Set merge to true to collapse the produced list into a single object instead. For anything more involved, an Eval step is clearer and does not carry these defects.

secret-key-get-node

Reads one account-shared secret by name.

string

required

The secret’s name. Plain names only — a name containing a . is refused.

Payload

{ "key": "PARTNER_SFTP_PASSWORD" }

Returns

{ "value": "..." }

A name that does not exist returns {"error": "PARTNER_SFTP_PASSWORD not found"}.

A . in the key is a scope separator, not part of the name, and is refused. Personal secrets and platform credentials live under dotted prefixes, so this function reads account-shared secrets only.To use a personal secret, put SECRET::user.<KEY>:: in a node’s configuration instead. The platform substitutes it against your own identity before the run starts.

SECRET::<name>:: works anywhere in any node’s configuration, not just here — the whole configuration is scanned and the references replaced before the first step runs. That is usually simpler than a separate step, and it keeps the secret out of the run’s step results.

function-invoke-node

Invokes another function by its mesh subject.

string

required

"RequestResponse" to wait for the result, or "Async" to fire and continue.

object

required

The input for the target function. Serialised to JSON before it is sent.

string

required

The target function’s subject.

string

A correlation ID carried through to the invocation.

integer

Timeout for the call.

The result is the raw reply envelope, not the invoked function’s return value. The declared output schema is an untyped object, and the value that comes back carries the reply’s own fields rather than the function’s output. This entry is derived from source; it has not been run end to end.To call one more built-in function, add a second Function step. To call another flow, use a nested flow.

SFTP

Uploads one file to an SFTP server. The connection is closed after the transfer, whether it succeeded or not.

string

required

Hostname or IP.

integer

required

Port number.

string

required

Username.

string

required

The file’s contents, as text.

string

required

Destination path on the server, including the filename.

string

Password authentication. Use SECRET::<name>:: rather than a literal.

string

Key authentication, as the key’s text.

integer

Milliseconds to wait for the connection. Default 10000.

integer

Milliseconds to wait for the transfer. Default 30000.

object

{"serverHostKey": ["..."]} — host key algorithms to offer, for servers that need a specific one.

Payload

{
  "host": "sftp.partner.example",
  "port": 22,
  "username": "exports",
  "password": "SECRET::PARTNER_SFTP_PASSWORD::",
  "filePath": "/inbound/orders-2026-08-20.csv",
  "fileContents": "$.BUILD_CSV"
}

Failure. Two timeouts produce their own messages, both returned as {"error": "…"}:

"Server took too long to connect. Make sure the host and the port are correct."
"File took too long to send."

Anything else — bad credentials, a path that does not exist — comes back as the SFTP client’s own message.

fileContents is text. To send a binary file, hold it as base64 and have the receiving side decode it; this function does not decode base64 for you.

The same job in a Rules step

Some of what these functions do also exists as an operator inside the rules engine, and the two sets are not interchangeable — an operator only works inside a Rules step or a Condition step’s payload, and a function only works inside a Function step.

Job	Function	Rules operator
JSONPath lookup	`Mapping`	`jPath` / `jsonPath`
Fill placeholders in a string	`Handlebars Template`	`stringTemplate`
Parse a JSON string	none — `base64-decode` parses as a side effect	`jsonParse`
Serialise to a JSON string	none	`jsonStringify`

The operators are terser and keep the work in one step; the functions handle bigger inputs and richer templates. Two differences are worth knowing before you swap one for the other:

jPath takes [data, path] and returns an array, so {"operator": "jPath", "input": [{"a": {"b": 7}}, "$.a.b"]} produces [7], not 7.
stringTemplate numbers its placeholders from one and writes them {{1}}, {{2}} — it is not Handlebars. {"operator": "stringTemplate", "input": ["Hello {{1}} and {{2}}", "Sam", "Dana"]} produces "Hello Sam and Dana".

A misspelled operator name fails a Rules step outright and says so; a function name is chosen from a list, so it cannot be misspelled at all. Where the two genuinely differ is everything else — a rule that produces nothing is dropped silently, while a function that fails returns an error object you can branch on.

Rules Engine

The operator set and how a Rules step is written

Map Step

The mapper to use instead of Mapping

Eval Step

JavaScript, for anything no function covers

Functions Overview

The full catalogue

Get Started

Spaces

Meetings

Forms

Assistants

Collaboration

Flows

Account Management

Advanced

Developers

Utility Functions

Utility Functions

base64-encode

base64-decode

JSON-XML

XML-JSON

Handlebars Template

Mapping

secret-key-get-node

function-invoke-node

SFTP

The same job in a Rules step

Rules Engine

Map Step

Eval Step

Functions Overview

​Utility Functions

​base64-encode

​base64-decode

​JSON-XML

​XML-JSON

​Handlebars Template

​Mapping

​secret-key-get-node

​function-invoke-node

​SFTP

​The same job in a Rules step

​Related

Rules Engine

Map Step

Eval Step

Functions Overview

Utility Functions

base64-encode

base64-decode

JSON-XML

XML-JSON

Handlebars Template

Mapping

secret-key-get-node

function-invoke-node

SFTP

The same job in a Rules step

Related