Interpolação e Substituição de Parâmetros

A Interpolação e Substituição de Parâmetros é o mecanismo da Engine responsável por injetar dados dinâmicos nos payloads, cabeçalhos, URLs e configurações de cada etapa do fluxo antes de enviá-los para execução pelos runners.

O motor de substituição analisa as expressões anotadas nas configurações do nó e substitui as marcações dinâmicas pelos valores reais presentes na memória da sessão de forma não-bloqueante.

---

Fontes de Dados para Substituição

Durante a execução de uma etapa, o motor de substituição carrega e disponibiliza quatro namespaces ou escopos de dados distintos:

Fontes de dados do motor de substituição

                     ┌─────────────────────────────────────────┐
                     │          MOTOR DE SUBSTITUIÇÃO          │
                     └────────────────────┬────────────────────┘
                                          │
    ┌──────────────────┬──────────────────┼─────────────────────────────────┬──────────────────┐
    ▼                  ▼                  ▼                                 ▼                  ▼
┌──────────────┐   ┌──────────────┐   ┌────────────────────────┐   ┌──────────────┐   ┌──────────────┐
│  $entrada    │   │    $dados    │   │       $historico       │   │  $variaveis  │   │   $unicidade │
│(Transação)   │   │  (Sessão)    │   │ (Runners já Executados)│   │  (Ambiente)  │   │   (Gerador)  │
└──────────────┘   └──────────────┘   └────────────────────────┘   └──────────────┘   └──────────────┘

Dados da Transação de Entrada (`$entrada`)

Acesso direto aos parâmetros brutos enviados pelo cliente no momento da chamada inicial.

Dados Dinâmicos da Sessão (`$dados`)

Acesso ao estado dinâmico e acumulado dos dados da sessão em memória. É o escopo utilizado por runners como o Script JS para manipular e gravar objetos que precisam ser lidos em nós subsequentes.

Histórico de Execução de Etapas (`$historico`)

Acesso aos dados e respostas devolvidos especificamente por etapas que já foram executadas anteriormente na mesma sessão.

Variáveis do Ambiente (`$variaveis`)

Acesso aos pares de chave e valor das Variáveis de Ambiente cadastradas para o ambiente e versão em execução.

Gerador de Unicidade (`$unicidade`)

Provedor de identificadores únicos para apoio à geração de chaves temporárias, correlacionadores ou tokens aleatórios.

1. Dados da Transação de Entrada ($entrada)

• Exemplo de Expressão: ${entrada.body.cliente.cpf} ou ${entrada.queryParams.status}

• Conteúdo: Objetos contendo o corpo (body), query params e tokens de autorização (auth) recebidos na transação.

2. Dados Dinâmicos da Sessão ($dados)

• Exemplo de Expressão: ${dados.pedido.id} ou ${dados.usuario.email}

3. Histórico de Execução de Etapas ($historico)

• Exemplo de Expressão: ${historico.etapa_consulta_cep.body.logradouro}

• Estrutura: O histórico armazena o corpo da resposta (body), o código de status HTTP (status), cabeçalhos (headers) e o tempo de execução de etapas anteriores.

4. Variáveis do Ambiente ($variaveis)

• Exemplo de Expressão: ${variaveis.URL_SERVICO_PAGAMENTO} ou ${variaveis.TIMEOUT_PADRAO}

• Uso Típico: Evita hardcode de URLs, chaves de API externas ou parâmetros de configuração sensíveis nas etapas do fluxo.

5. Gerador de Unicidade ($unicidade)

• Exemplo de Expressão: ${unicidade.uuid}

---

Sintaxe e Exemplos de Uso

A interpolação utiliza a notação ${escopo.propriedade} para substituição de valores dentro de objetos JSON ou textos das configurações.

Exemplo em uma Configuração de Etapa HTTP (HTTP_CLIENT):

Se uma etapa de requisição HTTP externa precisa enviar um payload contendo dados da entrada, o ID gerado na etapa anterior e uma variável do ambiente:

configuracao-etapa-http.json

{
  "url": "${variaveis.URL_SERVICO_AUTORIZACAO}/v1/aprovar",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer ${entrada.auth.token}",
    "Content-Type": "application/json"
  },
  "body": {
    "codigoCliente": "${entrada.body.clienteId}",
    "transacaoOriginal": "${historico.etapa_busca_banco.body.transacao_id}",
    "identificadorExecucao": "${unicidade.uuid}"
  }
}

---

Execução Assíncrona e Alta Performance

O motor de substituição realiza o carregamento e a resolução dessas variáveis de forma altamente performática e não-bloqueante:

• Carregamento Paralelo: As fontes de dados (entrada, dados, historico, variaveis) são carregadas em paralelo do cache de sessão antes da etapa ser enviada ao runner.

• Processamento por Expressão Regular: A Engine varre a definição JSON da etapa, identifica as marcações no padrão ${...}, resolve a navegação no objeto correspondente e realiza a substituição do nó antes de despachar a instrução de trabalho no barramento de eventos.

• Resiliência a Atributos Nulos: Se uma expressão apontar para uma propriedade inexistente no objeto em memória, o motor trata a substituição de forma graciosa sem interromper abruptamente a sessão (salvo se a ausência do valor violar regras de validação do runner que receberá a instrução).