Expressões, parâmetros e variáveis

Tipos, limites, precedência de valores, modelos de texto e condições JSON para decisões de Workflow.

Três mecanismos diferentes

Dova separa os modelos de texto dos campos de Mapping, os parâmetros tipados de execução e as condições JSON de Workflow. Cada mecanismo tem sintaxe e alcance próprios. Um modelo ${field} não é uma condição de decisão; um booleano JSON não é a string "true"; um parâmetro secreto é uma referência protegida, não uma senha para inserir em um arquivo.

Use parâmetros para representar variações de ambiente e tarefa que não alteram a estrutura do processo. Use variáveis de Workflow quando a definição de orquestração as incluir. Use condições para escolher ramificações com base nos valores ou estados disponíveis. A seção Sessions explica onde editar esses valores, e Workflows mostra sua relação com as tarefas.

Definição de parâmetros

Cada definição aceita name, type, description, required, sensitive, overridable, scopes, default, enum, minimum, maximum e maxLength. O contrato aceita até 100 definições com nomes únicos. O nome começa com uma letra, tem até 64 caracteres e pode conter letras, números, sublinhado, ponto e hífen. Os prefixos sys. e dova. são reservados.

Tipo	Valor aceito e observações
`string`	String; comprimento máximo padrão de 4000, se não houver outro limite.
`integer`	Inteiro JSON; um booleano não é aceito como inteiro.
`number`	Número finito; não aceita booleanos, infinito ou NaN.
`boolean`	Booleano JSON `true` ou `false`, não o texto equivalente.
`datetime`	Texto ISO com fuso horário; normalizado para UTC e precisão de segundos.
`json`	Valor JSON limitado a 32768 bytes pelo normalizador.
`secret`	Referência de segredo validada, não o valor do segredo em texto aberto.

Description tem limite de 300 caracteres. Max length aceita valores entre 1 e 32768. Minimum não pode superar Maximum. Enum precisa conter de 1 a 50 candidatos, é normalizado conforme o tipo e não está disponível para JSON ou Secret. Um parâmetro Sensitive precisa usar o tipo Secret: marcar uma string comum não a transforma em um segredo protegido.

As referências Secret reconhecem os esquemas gcp-secret, aws-secretsmanager, azure-keyvault, vault e worker-secret. Essa sintaxe pertence aos parâmetros de orquestração; não deve ser confundida com as formas específicas de Customer vault em Connections. A resolução de uma referência depende da infraestrutura e das autorizações correspondentes.

Camadas e precedência

Ordem de aplicação	Camada	Uso conceitual
1	Padrão da definição	Valor base quando não há substituição permitida.
2	`global`	Configuração geral da execução.
3	`environment`	Variação do ambiente selecionado.
4	`worker`	Variação associada ao ambiente de execução.
5	`task`	Valor específico da tarefa.

Uma camada posterior substitui o valor anterior conforme as regras de validação. Scopes limita as camadas aceitas e Overridable participa do controle de substituição. Required exige um valor após a resolução dos padrões e das camadas. O resultado preserva a procedência do valor, permitindo diagnosticar por que o valor esperado pelo autor não foi aplicado.

Por exemplo, defina REGION como String com o padrão NORTE. Uma camada Environment com SUR deve prevalecer sobre esse padrão; uma camada Task permitida com CENTRO deve prevalecer sobre ambas. Não remova restrições de escopo para contornar um erro sem conferir quem tem autoridade sobre essa configuração.

Modelos de Calculated field

O modelo reconhece ${nombre} para campos do registro e ${param.nombre} para parâmetros. A substituição produz texto com limite de 4000 caracteres. Um identificador reconhecido, mas ausente, é substituído por uma string vazia. O nome do campo é procurado como chave do registro; um ponto no nome não garante acesso a um objeto aninhado.

Com uma linha contendo name = Ana e o parâmetro region = SUR, o modelo Cliente ${name} / ${param.region} produz Cliente Ana / SUR. A expressão ${amount} * 2 produz texto com * 2; ela não calcula uma multiplicação. Use os componentes de transformação adequados, sem inserir código esperando avaliação dinâmica.

O resolvedor de valor parametrizado reconhece uma referência completa ${param.nombre}. Isso não significa que todos os campos de todos os conectores aceitem interpolação parcial. Confira o contrato do componente antes de transferir um modelo de um campo para outro.

Condições JSON de Workflow

Uma condição simples contém ref, op e, com exceção de dois operadores, value. As referências aceitas são parameters.nombre, variables.nombre, tasks.identificador.status e tasks.identificador.outputs.nombre. Elas não permitem acesso arbitrário a propriedades do servidor nem código executável.

Operador	Significado
`eq`, `ne`	Igualdade ou diferença em relação ao valor JSON esperado.
`gt`, `gte`, `lt`, `lte`	Comparação ordenada; tipos incompatíveis retornam falso.
`in`, `not_in`	Presença ou ausência em uma lista fornecida como Value.
`contains`	Presença em uma string, lista ou dicionário do contexto.
`exists`	A referência existe; não exige Value.
`truthy`	Avalia o valor lógico do dado; não exige Value.

Se uma referência não existir, as comparações comuns retornam falso. Exists distingue ausência de um valor existente, porém vazio. In e Not in exigem uma lista como valor esperado. Os números precisam continuar sendo números JSON; a comparação não garante conversão automática de texto.

Os grupos all e any combinam de 1 a 20 expressões; not nega uma expressão. São rejeitados níveis superiores a cinco e árvores com mais de 40 nós. O valor de comparação tem limite de 4096 bytes. Esses limites favorecem condições revisáveis; divida decisões complexas em tarefas claras.

{
  "all": [
    {"ref": "parameters.RUN_MODE", "op": "eq", "value": "full"},
    {"ref": "tasks.load.status", "op": "eq", "value": "succeeded"}
  ]
}

A referência load precisa corresponder ao identificador real de uma tarefa. As saídas só podem ser consultadas quando estiverem presentes no contexto. O exemplo não declara uma saída universal de contagens nem presume nomes de campos de um conector.

Decisões e estados

Os tipos de tarefa são Start, Session, Decision, Timer e End. Os vínculos oferecem Success, Failure, Always e Expression. Uma decisão exige ramificações True e False complementares: uma expressão e sua negação direta. A interface constrói a ramificação falsa com not da verdadeira; não escreva duas condições independentes que possam ser verdadeiras ou falsas ao mesmo tempo.

Os estados terminais reconhecidos incluem Succeeded, Failed, Skipped, Cancelled e Terminated. Ready, Queued, Running, Waiting e Retry wait são estados ativos. A preparação de uma tarefa considera seus antecessores terminais e a política de junção. Always não permite ignorar todos os requisitos de orquestração.

Prova de conceito e diagnóstico

Prepare um Workflow sintético com uma Session que processe duas linhas, uma Decision e duas ramificações de finalização. Defina RUN_MODE como String com os valores permitidos full e sample. Use uma condição de igualdade sobre parameters.RUN_MODE, execute primeiro com full e depois com sample, e confira a troca da ramificação ativa, mantendo a complementaridade.

Depois teste um valor fora de Enum e um booleano onde se exige String. O resultado esperado é uma rejeição de validação, não uma conversão silenciosa. Execute em um ambiente autorizado e registre o resultado observado. Se uma ramificação não for ativada, revise tipo JSON, nome técnico, camada efetiva, estado do antecessor e existência da referência antes de alterar a lógica.