> ## 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.

# Referência de mapeamento de campos

> Referência completa para mapeamentos de entrada, mapeamentos de saída e transformações de dados em nodes executor do Flowker.

Mapeamentos de campos e transformações permitem remodelar dados entre o seu workflow e serviços externos sem escrever código. Eles são definidos dentro do objeto `data` dos nodes executor na definição do seu workflow.

<Note>
  Esses campos ficam dentro da propriedade `data` do node — um objeto chave-valor flexível que varia por tipo de node. Eles não são campos separados no nível superior do schema do workflow.
</Note>

## Mapeamento de entrada

***

O mapeamento de entrada converte campos do workflow nos campos esperados por um executor. O Flowker aplica os mapeamentos de entrada **antes** de chamar o serviço externo.

Defina um array `inputMapping` no objeto `data` do node executor. Cada entrada especifica um `source` (caminho do campo do workflow) e um `target` (campo do executor para o qual é mapeado).

```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" }
    ]
  }
}
```

### Campos de uma entrada de mapeamento

| Campo            | Tipo    | Obrigatório | Descrição                                                                                                             |
| ---------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `source`         | string  | Sim         | JSONPath para o valor de origem (ex: `workflow.customer.cpf`).                                                        |
| `target`         | string  | Sim         | JSONPath para o campo de destino (ex: `executor.document`).                                                           |
| `transformation` | object  | Não         | Transformação opcional a ser aplicada durante o mapeamento. Consulte [Transformações inline](#transformações-inline). |
| `required`       | boolean | Não         | Se `true`, o mapeamento falha quando o caminho de origem não existe. Padrão: `false`.                                 |

## Mapeamento de saída

***

O mapeamento de saída extrai campos da resposta do executor e os escreve de volta no contexto do workflow. Os nodes subsequentes podem então acessar os valores mapeados. O Flowker aplica os mapeamentos de saída **depois** de receber a resposta.

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

Os mesmos campos da entrada de mapeamento se aplicam ao mapeamento de saída (`source`, `target`, `transformation`, `required`).

## Transformações inline

***

Quando um simples mapeamento campo-a-campo não é suficiente, anexe um objeto `transformation` a uma entrada de mapeamento. A transformação é aplicada ao valor de origem antes de escrevê-lo no destino.

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

### Tipos de transformação disponíveis

| Tipo                | O que faz                                      | Campos de configuração                         |
| ------------------- | ---------------------------------------------- | ---------------------------------------------- |
| `remove_characters` | Remove caracteres especificados de uma string. | `characters` — string de caracteres a remover. |
| `add_prefix`        | Adiciona uma string antes do valor do campo.   | `prefix` — string a adicionar antes.           |
| `add_suffix`        | Adiciona uma string depois do valor do campo.  | `suffix` — string a adicionar depois.          |
| `to_uppercase`      | Converte uma string para maiúsculas.           | —                                              |
| `to_lowercase`      | Converte uma string para minúsculas.           | —                                              |

## Transformações Kazaam

***

Para transformações avançadas de JSON para JSON que vão além do mapeamento de campos, defina um array `transforms` no objeto `data` do node executor. Elas usam o motor de transformação [Kazaam](https://github.com/qntfy/kazaam).

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

### Campos de uma operação Kazaam

| Campo       | Tipo    | Obrigatório | Descrição                                                                            |
| ----------- | ------- | ----------- | ------------------------------------------------------------------------------------ |
| `operation` | string  | Sim         | O tipo de operação Kazaam (ex: `shift`, `concat`, `remove_characters`).              |
| `spec`      | object  | Sim         | Configuração específica da operação.                                                 |
| `require`   | boolean | Não         | Se `true`, todos os caminhos referenciados em `spec` devem existir. Padrão: `false`. |

O Kazaam suporta operações como `shift` (mover/renomear campos), `concat` (combinar campos), `coalesce` (primeiro valor não nulo) e `default` (definir valores de fallback). As operações customizadas listadas em [transformações inline](#transformações-inline) também estão disponíveis como operações Kazaam.

<Note>
  Ao usar transformações customizadas como `remove_characters` como operações Kazaam, o objeto `spec` deve incluir um campo `path` apontando para o caminho JSON dos dados a transformar. Isso difere das transformações inline, em que o caminho é derivado automaticamente do mapeamento `source`/`target`.
</Note>

## Ordem de execução

***

Quando o Flowker executa um node executor:

1. **Mapeamentos de entrada** são aplicados primeiro — os dados do workflow são mapeados para o formato de entrada do executor.
2. **Transformações Kazaam** são executadas em seguida sobre a entrada mapeada (se definidas).
3. A chamada ao executor é feita para o serviço externo.
4. **Mapeamentos de saída** são aplicados à resposta — os dados do executor são mapeados de volta para o contexto do workflow.

## Solução de problemas

***

Se uma transformação falha durante a execução, o passo é marcado como `failed` com uma mensagem indicando qual mapeamento causou o erro.

Problemas comuns:

* **Caminho de origem não existe** — verifique se o node upstream realmente produz o campo que você está referenciando. Defina `required: true` para capturar campos ausentes antecipadamente.
* **Incompatibilidade de tipos** — conversões de string para número não são automáticas. Use uma transformação para converter formatos.
* **Spec Kazaam inválida** — verifique o nome da operação e a estrutura da spec conforme a documentação do Kazaam.