> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Field mapping reference

> Complete reference for input mappings, output mappings, and data transformations in Flowker executor nodes.

Field mappings and transformations let you reshape data between your workflow and external services without writing code. They are defined inside the `data` object of executor nodes in your workflow definition.

<Note>
  These fields live inside the node's `data` property — a flexible key-value object that varies by node type. They are not separate top-level fields in the workflow schema.
</Note>

## Input mapping

***

Input mapping converts workflow fields into the fields expected by an executor. Flowker applies input mappings **before** calling the external service.

Define an `inputMapping` array in the executor node's `data` object. Each entry specifies a `source` (a workflow field path) and a `target` (the executor field it maps to).

```json theme={null}
{
  "id": "executor-balance",
  "type": "executor",
  "name": "Check Balance",
  "data": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "inputMapping": [
      { "source": "workflow.customerId", "target": "executor.accountId" },
      { "source": "workflow.amount", "target": "executor.minimumBalance" }
    ]
  }
}
```

### Mapping entry fields

| Field            | Type    | Required | Description                                                                                             |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `source`         | string  | Yes      | JSONPath to the source value (e.g., `workflow.customer.cpf`).                                           |
| `target`         | string  | Yes      | JSONPath to the target field (e.g., `executor.document`).                                               |
| `transformation` | object  | No       | Optional transformation to apply during mapping. See [Inline transformations](#inline-transformations). |
| `required`       | boolean | No       | If `true`, the mapping fails when the source path doesn't exist. Defaults to `false`.                   |

## Output mapping

***

Output mapping extracts fields from the executor's response and writes them back into the workflow context. Downstream nodes can then access the mapped values. Flowker applies output mappings **after** receiving the response.

```json theme={null}
{
  "data": {
    "outputMapping": [
      { "source": "executor.currentBalance", "target": "workflow.balance" },
      { "source": "executor.accountStatus", "target": "workflow.status" }
    ]
  }
}
```

The same entry fields apply as input mapping (`source`, `target`, `transformation`, `required`).

## Inline transformations

***

When a simple field-to-field mapping isn't enough, attach a `transformation` object to a mapping entry. The transformation is applied to the source value before writing it to the target.

```json theme={null}
{
  "source": "workflow.phone",
  "target": "executor.phoneNumber",
  "transformation": {
    "type": "remove_characters",
    "config": {
      "characters": ".- ()"
    }
  }
}
```

### Available transformation types

| Type                | What it does                               | Config fields                                  |
| ------------------- | ------------------------------------------ | ---------------------------------------------- |
| `remove_characters` | Strips specified characters from a string. | `characters` — string of characters to remove. |
| `add_prefix`        | Prepends a string to a field value.        | `prefix` — string to prepend.                  |
| `add_suffix`        | Appends a string to a field value.         | `suffix` — string to append.                   |
| `to_uppercase`      | Converts a string to uppercase.            | —                                              |
| `to_lowercase`      | Converts a string to lowercase.            | —                                              |

## Kazaam transformations

***

For advanced JSON-to-JSON transformations that go beyond field mapping, define a `transforms` array in the executor node's `data` object. These use the [Kazaam](https://github.com/qntfy/kazaam) transformation engine.

```json theme={null}
{
  "data": {
    "transforms": [
      {
        "operation": "shift",
        "spec": {
          "outputField": "inputField"
        }
      }
    ]
  }
}
```

### Kazaam operation fields

| Field       | Type    | Required | Description                                                                |
| ----------- | ------- | -------- | -------------------------------------------------------------------------- |
| `operation` | string  | Yes      | The Kazaam operation type (e.g., `shift`, `concat`, `remove_characters`).  |
| `spec`      | object  | Yes      | Operation-specific configuration.                                          |
| `require`   | boolean | No       | If `true`, all paths referenced in `spec` must exist. Defaults to `false`. |

Kazaam supports operations like `shift` (move/rename fields), `concat` (combine fields), `coalesce` (first non-null value), and `default` (set fallback values). The custom operations listed in [inline transformations](#inline-transformations) are also available as Kazaam operations.

<Note>
  When using custom transforms like `remove_characters` as Kazaam operations, the `spec` object must include a `path` field pointing to the JSON path of the data to transform. This differs from inline transformations, where the path is derived automatically from the `source`/`target` mapping.
</Note>

## Execution order

***

When Flowker executes an executor node:

1. **Input mappings** are applied first — workflow data is mapped to executor input format.
2. **Kazaam transforms** run next on the mapped input (if defined).
3. The executor call is made to the external service.
4. **Output mappings** are applied to the response — executor data is mapped back to the workflow context.

## Troubleshooting

***

If a transformation fails during execution, the step is marked as `failed` with a message indicating which mapping caused the error.

Common issues:

* **Source path doesn't exist** — check that the upstream node actually produces the field you're referencing. Set `required: true` to catch missing fields early.
* **Type mismatch** — string-to-number conversions are not automatic. Use a transformation to convert formats.
* **Invalid Kazaam spec** — verify the operation name and spec structure against the Kazaam documentation.