Working with request and response data

An executor node sends data to an external service and receives data back. The service names its own fields, and your workflow names its own. Mappings are how you move values between the two. They are a list of source-to-target entries on the node. Flowker applies them to the request before the call and to the response after it. You need this whenever the shape your workflow carries is not the shape the service accepts. One example is a document that must travel without punctuation. Another is an amount that belongs under a nested object, or a score that a later node reads under a short name.

Before you start

A provider configuration for the service, and an executor node that references it. See Reference the provider configuration from a workflow node.
The field names the service expects. When the service’s OpenAPI document is in the registry, Derive an operation schema returns inputSchema (the operation’s request body) and outputSchema (its success response). Both give you the field names you write as mapping targets and sources.
A workflow in draft status. To edit an active workflow, deactivate it and move it to draft, then activate it again.

Do not send executorId on a node that calls an operation of an uploaded OpenAPI document. Such a node names the operation with operation_path and operation_method. Flowker fills the executorId in for you, from the provider configuration the node points at, before it validates the workflow. It does this when you create the workflow and when you update it. Connecting your own API walks that whole path. The nodes on this page name http, the generic HTTP connector, which does need an explicit executorId.

Step 1: Know what a mapping can read

Every mapping reads from the workflow context, one JSON object that grows as the execution advances:

Path	What it holds
`workflow`	The trigger payload: the `inputData` of an execution request, or the body a webhook route received. A webhook route also adds `workflow._webhook` with the call’s metadata — see Webhook metadata.
`execution.id`	The execution identifier.
`execution.startedAt`	When the execution started, in UTC.
`<nodeId>`	The output of each executor node that has completed, under that node’s id.

Address a value by its path from one of those top-level keys:

Source	What it selects
`workflow.customer.document`	A nested field of the trigger payload.
`workflow.items[0].sku`	One element of an array.
`workflow.items[*].sku`	The same field across every element, as an array.
`workflow`	The whole trigger payload as an object.
`score-transaction.body.score`	A field of the `score-transaction` node’s output.

A mapping source is a plain path. Do not wrap it in ${...}. Inside a mapping Flowker reads a ${...} string as a literal path name that selects nothing.

Step 2: Declare the input mapping

Input mappings live in an inputMapping array inside the executor node’s data object. Each entry moves one value into the outgoing request body.

Field	Type	Required	Description
`source`	string	Yes	The path in the workflow context to read.
`target`	string	Yes	The path in the outgoing request body to write. A dotted target creates the nested object — `payment.amount` sends `{"payment":{"amount":…}}`.
`transformation`	object	No	A change applied to the value after it lands on the target. See Step 4.
`required`	boolean	No	Whether the source path must exist. Defaults to `false`. Applies to the whole node — see below.

The mapped result is the request body. Write each target exactly as the service expects to receive it: there is no wrapper object and no prefix to add.

Example: map the trigger payload into a fraud check

{
  "id": "score-transaction",
  "type": "executor",
  "name": "Score transaction",
  "position": { "x": 200, "y": 0 },
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "method": "POST",
    "path": "/score-transaction",
    "inputMapping": [
      { "source": "workflow.transactionId", "target": "reference" },
      { "source": "workflow.amount", "target": "payment.amount" },
      { "source": "workflow.customer.document", "target": "payment.document" }
    ]
  }
}

With a trigger payload of {"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}, the service receives:

{
  "reference": "txn-98765",
  "payment": { "amount": 1500, "document": "12345678900" }
}

When a source selects nothing

A source path that is absent from the context is not an error. Flowker still writes the target, with the value null, and the request goes out. Set required: true when the node must not call the service without a value. Flowker then checks every source path on that node before it builds the request, and fails the step when any of them is absent. The execution fails and the step reports input transformation failed.

required applies to the node, not to the one entry that carries it. If any entry in a node’s inputMapping sets required: true, every source path in that array must resolve. To keep some fields optional, leave required off across the whole node.

Give each target one entry. When two entries write the same target, the last one wins.

Step 3: Decide what builds the request body

A node has three sources for a request body. Only data.body is exclusive: when present, it is the whole body. Without it, Flowker composes the body from the other two sources, with the mapping overlay written over the config literals:

data.body

An explicit body template wins outright. Flowker resolves its ${...} references against the workflow context and sends the result. While data.body is present, inputMapping, transforms, and config contribute nothing to the body.Every ${...} reference here must resolve. One that does not fails the node with FLK-0143, before any call goes out (the opposite of a mapping source, which resolves to null). Use data.body when a missing value must stop the workflow, and a mapping when the request must go out regardless.

inputMapping or transforms

Otherwise Flowker builds an overlay from inputMapping. When inputMapping is empty it builds the overlay from transforms instead. The two are mutually exclusive: a node with at least one inputMapping entry never runs its transforms on the input.

config literals

Literal values in data.config seed the body. With an overlay present, the literals are the base and the overlay wins on any key both set. One node can therefore combine fixed values with mapped ones. With no overlay, the literals are the body on their own.

Transport never becomes body content. Before config can seed the body, Flowker removes these names from it: method, path, url, endpointName, query, headers, auth, retry, timeout, timeout_seconds, request_format, success_status_codes, content_digest, allowedHosts, and allowedPrivateHosts. A node that keeps transport in config by mistake therefore sends none of it to the destination. An auth block placed there can never ship as request content. The node reads its own transport from the top of its data object: path, endpointName, method, headers, query, auth, timeout_seconds, retry, success_status_codes, request_format, and content_digest. The outbound host allow-lists are not among them: you set allowedHosts and allowedPrivateHosts on the provider configuration, where each applies to every node that calls through it.

Example: fixed values plus mapped ones

{
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "method": "POST",
    "path": "/score-transaction",
    "config": {
      "channel": "web",
      "payment": { "currency": "BRL" }
    },
    "inputMapping": [
      { "source": "workflow.transactionId", "target": "reference" },
      { "source": "workflow.amount", "target": "payment.amount" }
    ]
  }
}

The literals and the mapped values merge, and nesting merges with nesting:

{
  "channel": "web",
  "reference": "txn-98765",
  "payment": { "currency": "BRL", "amount": 1500 }
}

Step 4: Reshape a value on its way through

When the service needs a value in a different form, attach a transformation to the mapping entry. It applies to the value after it lands on the target.

Type	What it does	Config
`remove_characters`	Removes the given characters from the text.	`characters` — the characters to remove.
`add_prefix`	Puts text in front of the value.	`prefix` — the text to add.
`add_suffix`	Puts text after the value.	`suffix` — the text to add.
`to_uppercase`	Converts the text to uppercase.	—
`to_lowercase`	Converts the text to lowercase.	—

Two rules to write them by:

They act on text. A value that is not text reaches the target unchanged.
The prefix and suffix values each need at least one character, and a single space counts. The characters value needs at least one character that is not a space, a tab, or a line break. A value that does not meet this fails the step at run time.

Example: normalize a document and stamp a reference

{
  "inputMapping": [
    {
      "source": "workflow.customer.document",
      "target": "payer.document",
      "transformation": {
        "type": "remove_characters",
        "config": { "characters": ".-/" }
      }
    },
    {
      "source": "workflow.customer.name",
      "target": "payer.name",
      "transformation": { "type": "to_uppercase" }
    },
    {
      "source": "workflow.transactionId",
      "target": "payer.reference",
      "transformation": {
        "type": "add_prefix",
        "config": { "prefix": "BR-" }
      }
    }
  ]
}

From {"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}, the node sends:

{
  "payer": {
    "document": "12345678900",
    "name": "ADA LOVELACE",
    "reference": "BR-txn-98765"
  }
}

Whole-document transforms

For work that entry-by-entry mapping does not express (combining two fields, choosing the first value that is present, filling a default), declare a transforms array instead. Each operation reads the whole workflow context and writes the whole overlay. Flowker accepts shift (move or rename), concat (join values), coalesce (first value present), default (fill a missing key), extract (lift a subtree to the root), delete (drop a key), timestamp, uuid, and pass. The five transformation types above are available here too. As operations they take the target path in the spec as path.

Example: shift and a default in one node

{
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "transforms": [
      {
        "operation": "shift",
        "spec": {
          "reference": "workflow.transactionId",
          "payment.amount": "workflow.amount"
        }
      },
      { "operation": "default", "spec": { "channel": "web" } }
    ]
  }
}

The node sends:

{
  "reference": "txn-98765",
  "payment": { "amount": 1500 },
  "channel": "web"
}

shift, concat, coalesce, extract, delete, and timestamp accept require: true, which demands that every path the spec names exists, the same way required works on a mapping entry.

transforms runs only when the node has no inputMapping. Use one or the other in a given node, never both.

Step 5: Read the response back out

Output mappings extract fields from the response and store them in the workflow context under the node’s id, so later nodes read short, stable names. Declare them in an outputMapping array in the node’s data, with the same four entry fields as an input mapping. An output source is a path into the response envelope, not into the response body:

Path	What it holds
`status`	The HTTP status code.
`status_text`	The HTTP status line, such as `200 OK`.
`url`	The URL Flowker requested, with the query string it assembled.
`headers`	The response headers, as a key-value object under their canonical names, such as `Content-Type`. A header the service sent more than once arrives as one comma-separated value.
`body`	The response body, parsed when the response is `application/json`, a type whose name ends in `+json`, or an XML type — `application/xml`, `text/xml`, or a type whose name ends in `+xml`.
`raw_body`	The response exactly as it arrived, as text. Present for an XML response.
`body_format`	Set to `xml` when an XML body was decoded.
`body_parse_error`	Present in place of `body` when an XML body could not be decoded, so the workflow can branch on it.

Response fields therefore sit under body:

{
  "outputMapping": [
    { "source": "body.score", "target": "score" },
    { "source": "body.decision", "target": "decision" },
    { "source": "status", "target": "httpStatus" }
  ]
}

On a node with the id score-transaction, that stores:

{ "score": 42, "decision": "review", "httpStatus": 200 }

A downstream mapping then reads score-transaction.score and score-transaction.httpStatus, and a downstream data.body reads ${score-transaction.score}. A node that declares no outputMapping stores the whole envelope under its id instead, and downstream nodes read the envelope path directly: score-transaction.body.score. Add an output mapping when you want the shorter name. Skip it when the envelope path is clear enough. An output source that selects nothing behaves like an input one. Flowker stores the target as null unless an entry on that node sets required: true.

Step 6: Check the mapping before you call the service

Preview an executor request uses the mapping, transformation, and request-assembly paths without making a service-network call. It does not read the vault or fetch an authentication token. The preview masks with *** the credential the authentication type declares where it appears as a value. Any other value, including a free-form authentication parameter, can appear as Flowker would send it. Send the node, the provider configuration it targets, and a sample payload. The provider configuration goes in the request itself, so preview does not need a saved provider configuration:

POST /v1/workflows/preview-request

{
  "node": {
    "executorId": "http",
    "method": "POST",
    "path": "/score-transaction",
    "inputMapping": [
      {
        "source": "workflow.customer.document",
        "target": "payer.document",
        "transformation": {
          "type": "remove_characters",
          "config": { "characters": ".-/" }
        }
      },
      {
        "source": "workflow.customer.name",
        "target": "payer.name",
        "transformation": { "type": "to_uppercase" }
      },
      {
        "source": "workflow.transactionId",
        "target": "payer.reference",
        "transformation": {
          "type": "add_prefix",
          "config": { "prefix": "BR-" }
        }
      }
    ]
  },
  "providerConfig": {
    "providerId": "http",
    "config": { "base_url": "https://api.fraudshield.example.com" },
    "allowedHosts": ["api.fraudshield.example.com"]
  },
  "sampleInput": {
    "transactionId": "txn-98765",
    "customer": { "document": "123.456.789-00", "name": "ada lovelace" }
  }
}

Your sampleInput becomes the trigger payload, so the mapping sources read it as workflow.*, exactly as they will at run time. The response is the assembled request:

{
  "method": "POST",
  "url": "https://api.fraudshield.example.com/score-transaction",
  "headers": { "Content-Type": "application/json" },
  "body": "{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}",
  "curl": "curl -X POST -H 'Content-Type: application/json' --data '{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}' 'https://api.fraudshield.example.com/score-transaction'",
  "unresolved": []
}

Each transformation resolved: the punctuation is gone from the document, the name is uppercase, and the reference carries its prefix. No call reached the service. Read it in this order:

Check the URL

It is the provider configuration’s base URL plus the node’s path. A path you did not expect is a node field to fix, not a mapping.

Check the body against the field names the service expects

Every target should appear where the service wants it. A field carrying null is a source path that selects nothing.

Check unresolved

It lists the ${...} references in the node’s headers, query, and URL that the preview could not resolve. Flowker leaves them literal in the rendered request. An unresolved reference in data.body fails the preview with FLK-0143 instead.

To check a node’s fixed fields against the catalog executor’s schema as well, call Validate a node configuration. Send the node’s configuration in config and, in mappedTargets, the target paths your inputMapping supplies. Flowker counts those as satisfied, so a node that maps a required field from the trigger passes the check.

What goes wrong

Symptom	Cause	Fix
The service receives a field set to `null`.	The `source` path is absent from the workflow context.	Compare the path with a preview’s rendered body. Set `required: true` on the node when it must not run without the value.
The service receives a nested object it did not ask for.	The `target` carries a prefix.	Write the target exactly as the service expects it. A target of `executor.accountId` sends an `executor` object.
The request body is empty.	The node has no `data.body`, no mapping and no `transforms`, and its `config` holds only transport names.	Add the values as `config` literals or as mapping entries.
The mappings appear to be ignored.	The node also carries `data.body`, which is the only body source while it is present.	Remove `data.body` to let the mappings build the body.
`transforms` appears to be ignored.	The node has at least one `inputMapping` entry.	Remove the `inputMapping` entries, or move the logic into them.
A downstream node reads nothing.	The reference does not name the producing node.	Read `<nodeId>.<target>` in a mapping, or `${<nodeId>.<target>}` in `data.body`. There is no shared top-level namespace.
An output mapping stores `null`.	The `source` omits the envelope prefix.	Map `body.score`, not `score`.

Error code	When	What it means
`FLK-0140`	Create, update, or activate	The node’s `inputMapping` does not form a valid specification — most often an unknown `transformation.type`.
`FLK-0141`	Create, update, or activate	The same, for the node’s `outputMapping`.
`FLK-0142`	Create, update, or activate	The same, for the node’s `transforms`.
`FLK-0143`	Run time	A `${...}` reference in the node’s `data.body` does not resolve against the workflow context. The node fails without calling the service.

See the Flowker error list for every code.

What’s next

Integration guide

Create the provider configuration a node calls through, and set its authentication.

Configuring a webhook trigger

Choose the payload contract that fills the workflow namespace your mappings read.

Overview

Guides

Console

Operations

Working with request and response data

Before you start

Step 1: Know what a mapping can read

Step 2: Declare the input mapping

When a source selects nothing

Step 3: Decide what builds the request body

Step 4: Reshape a value on its way through

Whole-document transforms

Step 5: Read the response back out

Step 6: Check the mapping before you call the service

What goes wrong

What’s next

Integration guide

Configuring a webhook trigger

​Before you start

​Step 1: Know what a mapping can read

​Step 2: Declare the input mapping

​When a source selects nothing

​Step 3: Decide what builds the request body

​Step 4: Reshape a value on its way through

​Whole-document transforms

​Step 5: Read the response back out

​Step 6: Check the mapping before you call the service

​What goes wrong

​What’s next

Integration guide

Configuring a webhook trigger

Before you start

Step 1: Know what a mapping can read

Step 2: Declare the input mapping

When a source selects nothing

Step 3: Decide what builds the request body

Step 4: Reshape a value on its way through

Whole-document transforms

Step 5: Read the response back out

Step 6: Check the mapping before you call the service

What goes wrong

What’s next