Pular para o conteúdo principal

Add Variable

1. Visão Geral​

O componente Add Variable (add-variable) cria e armazena variáveis que podem ser usadas em qualquer ponto posterior do fluxo de execução. As variáveis criadas ficam disponíveis para os demais componentes do mesmo fluxo através de referências no corpo da mensagem.

Use este componente quando precisar:

  • Guardar um resultado intermediário para reaproveitar mais adiante.
  • Criar um "apelido" curto para uma expressão complexa, evitando repeti-la várias vezes.
  • Manter um valor calculado durante a execução de um fluxo.

Não é indicado para persistir dados entre execuções diferentes (isso é papel do componente Local Storage, com escopo APPLICATION) — as variáveis do Add Variable só existem durante a execução atual.

2. Pré-requisitos​

Não há credenciais, licenças ou acessos externos necessários. O componente funciona internamente na engine de fluxo, sem chamadas de rede.

3. Autenticação e Conexão​

Não aplicável — este componente não se conecta a nenhum sistema externo.

4. Configuração / Operações Suportadas​

O componente tem uma única operação: definir uma ou mais variáveis.

CampoObrigatórioTipoDescriçãoExemplo
variablesSimObjeto (mapa chave/valor) ou texto JSON equivalenteCada chave vira o nome da variável. Cada valor pode ser um texto fixo ou uma expressão que busca dados na mensagem. Se o valor resultante for um texto no formato de objeto ({...}) ou lista ([...]), ele é automaticamente interpretado como JSON.{"userAge": "idade do usuário", "category": "categoria do pedido"}
stopOnErrorNãoTexto ("true"/"false")Define se o fluxo para quando ocorre um erro ao processar as variáveis. Valor padrão: "true"."false"
executeOnErrorNãoTextoNome de uma função a ser chamada automaticamente se ocorrer um erro. Essa função precisa existir em um subfluxo separado disparado por um componente Function."handleVariableError"
onBeforeExecuteNãoTextoNome de uma função a ser executada antes deste componente rodar. Não aceita expressões, apenas o nome literal da função."validarEntrada"
onAfterExecuteNãoTextoNome de uma função a ser executada depois deste componente rodar. Não aceita expressões, apenas o nome literal da função."enriquecerDados"

Se variables não for informado, o componente simplesmente não faz nada e segue o fluxo sem erro (fica registrado um aviso no log).

Comportamento em caso de erro: se o valor de variables não estiver em um formato reconhecido (nem objeto, nem texto JSON válido), ou se algo falhar durante o processamento, o componente interrompe a execução com uma mensagem de erro descrevendo a causa.

5. Exemplos Práticos​

Exemplo simples: um fluxo recebe um pedido e quer guardar a idade do cliente e a categoria do pedido como variáveis, para usar depois em uma condição.

Entrada (corpo da mensagem recebida pelo fluxo):

{
  "cliente": { "nome": "Maria Silva", "idade": 34 },
  "pedido": { "categoria": "eletronicos", "valor": 1500 }
}

Configuração do componente:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.cliente.idade}",
      "category": "{$.body.pedido.categoria}"
    }
  }
}

Resposta (o corpo da mensagem segue igual, mas agora com as variáveis disponíveis para os próximos passos do fluxo):

{
  "cliente": { "nome": "Maria Silva", "idade": 34 },
  "pedido": { "categoria": "eletronicos", "valor": 1500 },
  "variables": {
    "userAge": 34,
    "category": "eletronicos"
  }
}

Exemplo avançado: o mesmo cenário, mas agora com tratamento de erro. Se a idade ou a categoria não existirem na mensagem (por exemplo, um campo faltando), o fluxo não é interrompido (stopOnError desligado) e uma função de tratamento (executeOnError) é chamada automaticamente.

Entrada (agora sem o campo idade):

{
  "cliente": { "nome": "João Souza" },
  "pedido": { "categoria": "moveis", "valor": 800 }
}

Configuração do componente:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.cliente.idade}",
      "category": "{$.body.pedido.categoria}"
    },
    "stopOnError": "false",
    "executeOnError": "handleVariableError"
  }
}

Resposta (o fluxo continua e a função handleVariableError é chamada recebendo, por exemplo):

{
  "success": false,
  "errorMessage": "Não foi possível resolver a variável 'userAge'",
  "errorType": "FlowException"
}

6. Erros Comuns e Troubleshooting​

Erro / SintomaCausa provávelComo resolver
"Invalid variables configuration format. Expected Map or JSON string."O campo variables foi preenchido com um tipo que não é nem objeto nem texto JSON válido.Revisar a configuração e garantir que variables seja um objeto chave/valor ou uma string JSON válida.
"Error processing variables in add-variable component: ..."Falha ao resolver alguma expressão dentro dos valores das variáveis.Verificar se os caminhos/expressões usados nos valores realmente existem na mensagem de entrada.
Variável some ou aparece vaziaO caminho usado no valor não encontrou nada na mensagem.Conferir se o campo referenciado existe na mensagem naquele ponto do fluxo.

⚠️ CONFIRMAR: o código não deixa claro qual sintaxe exata de expressão (JSONPath, MVEL ou outra) é aceita nos valores das variáveis — isso depende de um mecanismo de tradução comum a vários componentes, não documentado neste arquivo.