Tipos de Trigger
- Os três tipos de trigger disponíveis: temporal, hook e manual
- Como cada tipo de trigger funciona e quando usá-lo
- Como configurar o trigger na seção Gatilho do formulário de workflow
Um trigger (Gatilho) é a condição que inicia seu workflow. Todo workflow tem exatamente um trigger, e você o seleciona no dropdown Tipo na seção Gatilho do formulário de criação de workflow. Existem três tipos de trigger para escolher.
Temporal -- triggers agendados
Um trigger temporal executa seu workflow em um cronograma, similar a um cron job. Use quando você quer que seu workflow execute em um horário específico ou em um intervalo recorrente.
Exemplos de triggers temporais:
- Executar todo dia útil de manhã às 9:00 para enviar lembretes de consultas
- Executar uma vez por semana na segunda-feira para gerar um relatório resumido
- Executar a cada hora para verificar conversas inativas
Quando você seleciona o tipo de trigger temporal, o formulário exibe campos onde você define o cronograma como uma regra de recorrência iCalendar: dtstart (a primeira ocorrência, uma data-hora), repeats (se repete) e rrule (a regra de recorrência, ex.: FREQ=DAILY;INTERVAL=1 ou FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR). Não há um campo cron ou timezone separado -- o agendamento é expresso inteiramente pela RRULE ancorada em dtstart.
Triggers temporais são ideais para tarefas recorrentes que não dependem de um evento específico acontecendo no sistema. Pense neles como tarefas agendadas que executam como um relógio.
Hook -- triggers baseados em eventos
Um trigger hook dispara quando um evento específico ocorre no sistema. Use quando você quer que seu workflow reaja a um evento como uma nova mensagem chegando ou um contato sendo criado.
Exemplos de triggers hook:
- Uma nova mensagem é recebida em uma conversa
- Um novo contato é criado no banco de dados
- Uma conversa é aberta de um canal específico
- Uma consulta ou evento é agendado ou atualizado
Quando você seleciona o tipo de trigger hook, você especifica o model (a coleção a observar, ex.: contacts) e o op -- a operação do ciclo de vida que dispara o hook. O op é um de beforeSave, afterSave, beforeCreate, afterCreate, beforeUpdate, afterUpdate, beforeDelete ou afterDelete (hooks before* disparam antes da gravação e hooks after* disparam depois que ela é concluída). Em ambos os casos o workflow recebe um snapshot somente leitura do documento -- um workflow nunca pode modificar ou cancelar a gravação que o disparou, e um workflow que falha nunca bloqueia a gravação.
O documento alterado fica então disponível para as etapas do workflow como a variável CEL doc (com prev para o estado anterior em atualizações, mais op e model). Por exemplo, referencie o nome do novo registro com {"expr": "doc.name"}. Note que contact, conversation e contactMessage só são preenchidos quando um workflow executa com um contexto de mensageria/pai (como um workflow invocado a partir de um agente); para um trigger hook simples eles estão vazios, então leia o registro disparador por meio de doc. Não há uma variável trigger de nível superior.
Triggers hook são o tipo de trigger mais comum. Eles permitem que seus workflows respondam em tempo real a eventos no sistema, como mensagens de boas-vindas, notificações e atualizações de dados.
Filtro do hook
Você também pode definir uma expressão CEL filter opcional no trigger hook para restringir quais alterações disparam o workflow. Ela é avaliada contra as mesmas variáveis doc e prev e deve resultar em verdadeiro para o workflow executar -- se retornar falso ou falhar ao ser avaliada, o workflow é ignorado. Use-a para casos como "uma conversa é aberta de um canal específico", em que model e op sozinhos disparariam para todos os canais.
O filtro enxerga o documento do mesmo jeito que as condições de etapa: todo id é sua string hex (hexadecimal) de 24 caracteres e toda data uma string ISO 8601. Compare ids diretamente, por exemplo doc.channelId == "65f0c1d2e3a4b5c6d7e8f901".
Um filtro roda a cada gravação correspondente -- em messages / afterCreate, isso é cada mensagem que entra ou sai -- por isso ele tem um orçamento próprio: 1000 ms, um quinto do que uma condição de etapa recebe. Coloque o teste barato primeiro: && e || param no primeiro operando que decide, então em doc.createdBy == "contact" && … o resto nunca roda para uma mensagem do bot.
Um filtro que falha -- com erro, ou passando dos seus 1000 ms -- nunca dispara o workflow, seja qual for a configuração Em caso de erro. A falha é gravada nos logs de execução da empresa (a visualização Logs simples do workflow) como "Workflow hook filter could not be evaluated, so the workflow was not triggered", com a expressão e o erro; depois de um timeout, a entrada também sugere como deixar o filtro mais barato. A entrada é limitada a uma por hora por workflow, mas em cada processo do servidor separadamente: o limite fica na memória desse processo, então outra réplica do servidor, ou um reinício, pode gravar a mesma falha de novo dentro da hora. A entrada segue o Log Level do workflow, como as demais linhas que o workflow grava.
Manual -- acionado pelo funcionário
Um trigger manual significa que o workflow não inicia automaticamente. Em vez disso, um funcionário o inicia clicando no botão Executar na página do workflow. Use quando você quer que uma pessoa decida quando o workflow deve executar.
Exemplos de triggers manuais:
- Um funcionário executa um workflow de limpeza de dados em massa quando necessário
- Um líder de equipe aciona um workflow de geração de relatório sob demanda
- Um agente de suporte dispara manualmente uma sequência de acompanhamento para um contato específico
Quando você seleciona o tipo de trigger manual, você pode opcionalmente definir campos de entrada personalizados que o funcionário preenche quando inicia o workflow. Por exemplo, você pode pedir ao funcionário para inserir um ID de contato ou selecionar um intervalo de datas antes que a execução comece.
Importante: O botão Executar só aparece depois que o workflow está ativado e salvo. Enquanto você está criando um novo workflow, ele não ficará disponível.
Triggers manuais são ótimos para workflows que requerem julgamento humano sobre quando executar. Você também pode definir entradas personalizadas para que o funcionário forneça dados específicos cada vez que o workflow é iniciado.
Escolhendo o trigger certo
| Você quer... | Use este trigger |
|---|---|
| Executar uma automação em um cronograma fixo (diário, semanal, por hora) | temporal |
| Reagir a um evento no sistema (nova mensagem, novo contato) | hook |
| Deixar um funcionário decidir quando executar o workflow | manual |
Cada workflow suporta exatamente um trigger. Se você precisa que o mesmo conjunto de etapas execute para eventos diferentes, crie um workflow separado para cada tipo de trigger.