Node configuration

Selecting a node on the canvas opens its inspector. What you see is derived from the node type's own declaration, so it differs per node — but the grammar behind it is small and fixed. This page is that grammar: the field types a node can declare, what each one does to the form, and which of them keep access data out of the workflow document.

What the inspector shows

However different two nodes look, the inspector has the same four parts:

• Configuration fields — the node's own settings. Required ones are shown; optional ones sit behind a single control that says how many there are.
• Input — the data arriving on the node's input port, and a picker for building an expression out of an upstream node's output, the trigger payload, or a workflow variable, rather than typing the path by hand.
• Output and test — the ports and fields the node produces, stated before anything has run, plus running this one node against a sample input and reading the log lines it produced. You can pin a sample so the next node down can be built against real-shaped data.
• Execution settings — the engine's per-step settings (retry, onError, timeoutSeconds) under their own heading, separate from the node's own options. See Failure handling.

Testing one node at a time is where a mapping gets fixed. Do it before you wire the next node, not after you have wired five.

The field types

Every configuration field declares a key, a label, and a type. The type decides the control and the validation:

A field can also carry a default, a placeholder, and validation — a pattern, a minimum and maximum, a minimum and maximum length. Required fields are marked, and a node with unfilled required fields blocks activation; see Validation and the activation gate.

expressionAllowed: which fields accept ${{ … }}

A field declares whether it accepts an expression. Where expressionAllowed is set, ${{ … }} works anywhere in the value — on its own, or interpolated into literal text. Where it is not, your text is taken literally, braces and all.

That is worth internalising, because a brace-laden string sitting unresolved in a config field looks like a broken expression when it is really a field that never accepted one. The inspector's input picker only offers to write an expression into fields that accept one, which is the quickest way to tell.

One field type is deliberately excluded: a field that other fields' resolution depends on may not be expression-capable, because its value has to be known while you are still editing rather than at run time. See Dynamic behaviour.

credentials-ref: pointing at a credential

A credentials-ref field names the credential type — or several types — that the node accepts. The field then offers only your tenant's instances of those types, and what is stored on the node is the identity of the instance you picked, never its contents.

{
  "id": "pull-orders",
  "nodeSlug": "revenexx:entity-api",
  "nodeVersion": "1.0.0",
  "config": {
    "credentials": "<the credential instance you picked>",
    "resource": "orders",
    "operation": "list"
  }
}

At execution time the runtime resolves that instance into live access data — including, where the credential type authenticates with OAuth, a freshly minted access token. A retried step gets a fresh token rather than replaying a stale one. See Credentials.

secret-ref: pointing at a secret

A secret-ref field stores the key of a tenant secret — SUPPLIER_FEED_TOKEN — and nothing else. The value is fetched inside the node as it executes, and it never enters the workflow document or the run history.

There is no expression root for secrets, deliberately. A secret-ref field is the only way a secret reaches a node. See Secrets.

dynamic-schema: fields that resolve while you edit

Some nodes cannot know their own fields until you have told them what you are talking to. Generic API Call is the example that ships: pick a resource and an operation, and that operation's parameters appear as real, typed fields.

A node declares that with a dynamic-schema marker field. When the fields it depends on have values, the marker is replaced by the flat set of fields the node resolves for them. Two related behaviours belong to the same mechanism:

• A select or multiselect field can have its options resolved live instead of listing them statically — a dropdown of what actually exists in the connected system, filtered as you type.
• An output port set can be resolved the same way, so the ports you wire reflect the shape the chosen operation returns.

All three resolve while you are editing, and the result is captured into the workflow when you save. Nothing is resolved again at run time, which is why a saved workflow keeps running the shape it was built against even if the far system's schema shifts underneath it. Re-open and re-save the node to pick up a change.

For the authoring side of this — loadOptions, resolveConfigSchema, resolveOutputs — see Dynamic behaviour.

Notes on a node

You can also leave a note on a node. It shows as a small marker on the card, never reaches the engine, and is the cheapest way to explain to the next person why a mapping is the way it is.

Where to go next

• Expressions — the syntax the expression-capable fields accept.
• Node catalog — which node needs which credential type.
• Credentials and Secrets — what the two reference field types pick from.
• Failure handling — the execution settings that sit alongside a node's own options.