Gatilhos

Um gatilho é o que dá partida em uma execução de fluxo de trabalho. Todo fluxo de trabalho precisa de pelo menos um. O GCM traz cerca de duas dúzias de gatilhos integrados cobrindo membros, presença, doações, formulários, agendamentos e webhooks externos.

Grupos de gatilhos

Grupo	Quando dispara
Instantâneo	Bem na hora em que um evento acontece no banco de dados (membro criado, doação registrada, etc.)
Agendado	Em uma expressão cron ou data futura única
Manual	Quando um admin inicia o fluxo de trabalho manualmente

Gatilhos instantâneos (membro)

Gatilho	Dispara quando
member.created	Um novo registro de membro é salvo
member.updated	Qualquer campo em um membro muda
member.deleted	Um membro é excluído logicamente
member.birthday	A date_of_birth de um membro corresponde à data de hoje
member.marked_lost	lost_at é definido em um membro
member.recovered	lost_at é limpo em um membro anteriormente perdido
member.type_changed	O tipo de membro muda (ex.: Visitante → Membro)
member.unit_assigned	Um membro é adicionado a uma unidade organizacional
member.unit_removed	Um membro é removido de uma unidade organizacional
member.group_assigned	Um membro é adicionado a um pequeno grupo
member.group_removed	Um membro é removido de um pequeno grupo
member.ministry_assigned	Um membro é adicionado a um ministério
member.ministry_removed	Um membro é removido de um ministério
member.school_enrolled	Um membro começa um programa escolar
member.school_graduated	Um membro conclui um programa escolar
member.school_removed	Um membro é removido de um programa escolar
member.note_added	Uma nota é adicionada ao perfil de um membro
member.tagged	Uma tag é adicionada a um membro

Gatilhos instantâneos (presença e doações)

Gatilho	Dispara quando
attendance.marked	Um membro tem presença registrada em uma reunião
attendance.removed	Uma linha de presença é excluída
giving.recorded	Uma doação é criada (manual ou online)
donation.refunded	Uma doação é reembolsada

Gatilhos instantâneos (outros)

Gatilho	Dispara quando
event.created	Um evento de calendário é criado
form.submitted	Um formulário público é enviado (ex.: formulário de visitante)
webhook.received	Um sistema externo faz POST para a URL de webhook de entrada da sua igreja

Gatilhos agendados

Gatilho	Quando
schedule	Cron recorrente — ex.: toda segunda às 9h
schedule.once	Um momento futuro único
scheduled_query	Consulta periódica ao banco de dados (ex.: verificação noturna de sem presença há 6 semanas)

O gatilho schedule usa sintaxe cron padrão. Traduzimos para o fuso horário da sua igreja (definido em Configurações → Organização), então 0 9 * * 1 significa "9h de segunda no horário local da sua igreja".

Gatilhos manuais

Gatilho	Quando
manual	Um admin clica no botão de executar agora
manual_enrollment	Um admin inscreve um ou mais membros diretamente

Útil para envios pontuais — ex.: uma mensagem "temos uma mudança de culto amanhã".

Configuração de gatilho

A maioria dos gatilhos tem configuração extra:

• Filtros — só disparar quando condições extras valerem. Ex.: member.created onde o tipo de membro é Visitante.
• Escopo por unidade organizacional — só disparar para membros em unidades específicas.
• Escopo por tipo de adesão — só disparar para visitantes, membros, líderes, etc.

Esses filtros são avaliados antes de uma execução ser enfileirada — eventos não correspondentes pulam o fluxo de trabalho sem criar uma linha de execução.

Sujeito e tokens

Cada gatilho dispara com um sujeito — geralmente o membro a que o evento diz respeito. Esse sujeito está disponível em todo o fluxo de trabalho como tokens de mesclagem:

• {{trigger.member.first_names}} — para um gatilho de membro.
• {{trigger.donation.amount}} — para giving.recorded.
• {{trigger.attendance.meeting.name}} — para attendance.marked.

O seletor de tokens mostra o que está disponível com base no gatilho que você escolheu.

Fluxos de trabalho multi-gatilho

Um fluxo de trabalho pode ter vários gatilhos que convergem todos para a mesma sequência de ações. Padrão comum:

• Boas-vindas a novos chegados com member.created e member.recovered como gatilhos, ambos levando a um envio de "boas-vindas".

Os dois gatilhos se conectam a um nó de junção de gatilhos que se ramifica para as ações compartilhadas.

Salvaguardas de frequência

Alguns gatilhos disparam muito. member.updated vai disparar toda vez que alguém tocar em qualquer campo. Para evitar fluxos de trabalho descontrolados:

• Use filtros de gatilho para estreitar o que é elegível (só quando o status muda).
• Use limitação de taxa no nível do fluxo de trabalho — no máximo N execuções por membro por dia.
• Use chaves de idempotência em ações de envio de mensagem para que retries não dupliquem.

WARNING

O erro clássico: um fluxo de trabalho que atualiza um campo personalizado em member.updated, causando um loop infinito. O construtor avisa você se criar esse padrão; por favor preste atenção ao aviso.

Perguntas comuns

Posso acionar em uma mudança de campo personalizado? Sim — use member.updated com um filtro na chave específica do campo.

Por que meu fluxo de trabalho member.created não está rodando para membros importados em massa? A importação em massa pula gatilhos de fluxo de trabalho por padrão para evitar mensagear todo mundo durante uma migração. Há uma caixa de seleção na tela de revisão da importação para optar por incluir.

Um único evento pode disparar vários fluxos de trabalho? Sim. Cada fluxo de trabalho com um gatilho correspondente dispara independentemente. A ordem não é garantida.

Próximos passos

• Ações — o que fazer depois do gatilho.
• Multi-etapa e atrasos — sequenciamento.
• Monitoramento de execuções — ver o que disparou e por quê.