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 assistente); 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.
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.
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.
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.