Utility Functions
Nine general-purpose functions are available to a Function step:
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:
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
Payloadnull and "" become a self-closing tag. &, < and > in text are escaped. The XML declaration is always emitted.
Failure. A json string that is not valid JSON returns {"error": "The JSON structure is invalid"}.
XML-JSON
The options worth knowing:
Payload
{"compact": true, "nativeType": true, "ignoreAttributes": true} over <o><n>42</n></o>:
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.{"error": "Unexpected close tag\nLine: 0\nColumn: 10\nChar: >"} — the parser’s own message, with line and column.
Handlebars Template
Payload- 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. 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: Payloadmerge 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. Payload{"error": "PARTNER_SFTP_PASSWORD not found"}.
function-invoke-node
Invokes another function by its mesh subject.SFTP
Uploads one file to an SFTP server. The connection is closed after the transfer, whether it succeeded or not.{"serverHostKey": ["..."]} — host key algorithms to offer, for servers that need a specific one.{"error": "…"}:
"Server took too long to connect. Make sure the host and the port are correct.""File took too long to send."
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.
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:
jPathtakes[data, path]and returns an array, so{"operator": "jPath", "input": [{"a": {"b": 7}}, "$.a.b"]}produces[7], not7.stringTemplatenumbers 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.
Related
Rules Engine
The operator set and how a Rules step is written
Map Step
The mapper to use instead of
MappingEval Step
JavaScript, for anything no function covers
Functions Overview
The full catalogue