Referência de mapeamento de campos

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.

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.

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

{
  "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.
`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.

{
  "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.

{
  "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.

{
  "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 também estão disponíveis como operações Kazaam.

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.

Ordem de execução

Quando o Flowker executa um node executor:

Mapeamentos de entrada são aplicados primeiro — os dados do workflow são mapeados para o formato de entrada do executor.
Transformações Kazaam são executadas em seguida sobre a entrada mapeada (se definidas).
A chamada ao executor é feita para o serviço externo.
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.

Visão geral

Guias

Console

Operações

Referência de mapeamento de campos

Mapeamento de entrada

Campos de uma entrada de mapeamento

Mapeamento de saída

Transformações inline

Tipos de transformação disponíveis

Transformações Kazaam

Campos de uma operação Kazaam

Ordem de execução

Solução de problemas

​Mapeamento de entrada

​Campos de uma entrada de mapeamento

​Mapeamento de saída

​Transformações inline

​Tipos de transformação disponíveis

​Transformações Kazaam

​Campos de uma operação Kazaam

​Ordem de execução

​Solução de problemas

Mapeamento de entrada

Campos de uma entrada de mapeamento

Mapeamento de saída

Transformações inline

Tipos de transformação disponíveis

Transformações Kazaam

Campos de uma operação Kazaam

Ordem de execução

Solução de problemas