Entradas do Workflow
- O que são entradas de workflow e quais variáveis cada tipo de trigger expõe
- Como referenciar essas variáveis com expressões CEL nas etapas
- Como definir entradas personalizadas para workflows manuais
Entradas do workflow são os valores que transportam dados do evento trigger para as etapas do seu workflow. Você os lê dentro das etapas com expressões CEL (Common Expression Language), de modo que cada etapa se adapta aos dados específicos de cada execução em vez de usar valores fixos.
Como funcionam os campos CEL
Todo campo habilitado para CEL em uma etapa (texto, URL, body, filtro, condição e assim por diante) recebe um valor no formato de objeto {expr: "..."}. Quando o workflow executa, a expressão dentro de expr é avaliada contra o contexto de execução atual e substituída pelo resultado.
Por exemplo, o campo de texto de uma etapa de mensagem pode ser:
{"expr": "'Hello ' + contact.name + ', your appointment is confirmed for ' + format_datetime(occurrenceDate, 'YYYY-MM-DD')"}
Se contact.name for "Maria Silva" e occurrenceDate for 15 de março de 2025, a etapa envia:
"Hello Maria Silva, your appointment is confirmed for 2025-03-15."
Para campos com muito texto você também pode usar a função tpl(), que preenche placeholders de chave simples {key} a partir de um objeto de valores: tpl('Hello {name}', {name: contact.name}).
A sintaxe de chaves duplas {{ }} não se aplica aqui — ela existe somente nos templates de mensagem do WhatsApp.
Variáveis por tipo de trigger
As variáveis disponíveis para um workflow dependem do seu tipo de trigger. Estas estão sempre presentes:
| Variável | Descrição |
|---|---|
company | O objeto da empresa (companyName, _id, options, planId) |
step(N) | A saída da etapa N (indexada a partir de 0), ex.: step(0).data |
Um trigger hook (dispara ao criar/atualizar/excluir um documento) também expõe:
| Variável | Descrição |
|---|---|
doc | O documento sendo criado, atualizado ou excluído |
prev | O estado anterior do documento (apenas em atualização) |
op | A operação do ciclo de vida que disparou o hook, ex.: afterCreate, afterUpdate ou afterDelete (um de beforeSave/afterSave/beforeCreate/afterCreate/beforeUpdate/afterUpdate/beforeDelete/afterDelete) |
model | O modelo dynadata que disparou o hook (ex.: contacts, ct:events) |
Um trigger temporal (executa em um agendamento) expõe:
| Variável | Descrição |
|---|---|
occurrenceDate | A data/hora agendada para esta ocorrência |
Quando um workflow executa a partir de uma conversa com um agente, as variáveis do contexto do agente também ficam acessíveis, incluindo contact (contact.name, contact.contactIdentification para o identificador do canal como um número de telefone ou nome de usuário, e contact.channelType para o canal) e contactMessage (contactMessage.body.text para o texto de uma mensagem recebida).
Usando entradas nas etapas
Ao configurar uma etapa na seção Etapas, defina cada campo CEL com um valor {expr: "..."} que referencie as variáveis acima. Você pode combinar texto estático com várias variáveis em uma única expressão:
{"expr": "'Dear ' + contact.name + ', you have an upcoming appointment on ' + format_datetime(occurrenceDate, 'DD/MM/YYYY') + '.'"}
Entradas personalizadas para workflows manuais
Quando um workflow usa um trigger manual, você pode definir campos de entrada personalizados na seção Parâmetros. O funcionário os preenche antes de executar o workflow — útil quando o workflow precisa de informações que nenhum evento automático fornece.
Cada parâmetro tem um nome, um tipo e uma descrição opcional. O nome se torna uma variável CEL de nível superior: um parâmetro chamado report_date é referenciado como report_date (não parameters.report_date).
Tipos de parâmetro
| Tipo | O que o funcionário informa |
|---|---|
string | Texto livre — ou uma lista fixa, veja Valores permitidos abaixo |
number | Um valor numérico |
boolean | Uma caixa de seleção |
datetime | Uma data/hora |
ref | Um documento escolhido de outro model — defina qual com o seletor Ref: events, conversations, messages, contacts, services, agents, webhooks, workflows, employees ou notifications |
file | Um arquivo do armazenamento do seu workspace |
O valor de execução de um parâmetro file é um objeto de referência de armazenamento -- {bucket, fullPath, name?} -- e não uma string de caminho. A referência é validada contra o seu workspace no início da execução, antes de qualquer registro de execução ser criado: uma referência que aponta para fora do seu workspace, ou para um arquivo inexistente, rejeita a execução com Workflow input '<name>' file was not found or is not accessible from this workspace. (a mesma mensagem nos dois casos, para que o erro não sirva para sondar arquivos de outros workspaces). Repasse o objeto de referência inteiro para uma etapa que aceite arquivos. O inputFiles da ação de código recebe um array de referências, então um parâmetro contract entra como {expr: "[contract]"} -- passar {expr: "contract"} faz a etapa falhar com inputFiles must evaluate to an array of storage refs.
Opções por parâmetro
- Obrigatório -- desativado por padrão. O modal de execução não envia enquanto um parâmetro obrigatório não estiver preenchido. Só os parâmetros
filesão reconferidos no servidor: umfileobrigatório deixado vazio rejeita a execução antes de qualquer coisa executar. Nos demais tipos o sinalizador não é reconferido quando a execução vem da API/v1, de uma ação de workflow ou do MCP. - Valores permitidos (somente parâmetros
string) -- ative Enable Enums e liste os valores permitidos em Enum. O modal de execução passa a mostrar uma lista com esses valores em vez de um campo de texto livre. Isso é metadado do modal de execução, não uma regra de validação: nada confere o valor da execução contra a lista, então uma execução iniciada pela API/v1, por uma ação de workflow ou pelo MCP pode trazer qualquer string. Proteja o valor dentro do próprio workflow quando um valor fora da lista puder causar dano. - Ref (somente parâmetros
ref) -- de qual model o seletor lê, entre os dez listados acima.
Por exemplo, defina um parâmetro report_date; o funcionário o insere ao clicar em Executar, e suas etapas o leem como:
{"expr": "report_date"}
O mesmo workflow então produz resultados diferentes dependendo do que o funcionário insere a cada vez.