Skip to main content
Um gatilho de agendamento começa um workflow em uma cadência que você escreve como uma expressão cron. O Flowker registra cada disparo como uma ocorrência, então um disparo que não pôde acontecer na hora não se perde. Ele espera em uma lista de retidas até você executá-lo ou descartá-lo. Use esta página para escrever o gatilho, confirmar a cadência e trabalhar a lista de retidas.

​
Antes de começar

  • Um workflow em status draft. Apenas um workflow em rascunho aceita uma edição, então escreva o gatilho antes de ativá-lo. Veja Primeiros passos com o Flowker para o caminho de criar e ativar.
  • O binário do worker rodando com o scheduler habilitado. A variável SCHEDULER_ENABLED resolve para true a menos que você a defina como false, e a fila precisa de SCHEDULER_REDIS_HOST. Sem host, o binário do worker não sobe e nenhum workflow agendado dispara. Confira essa variável primeiro quando seus agendamentos nunca dispararem. Veja Variáveis do scheduler.
  • A permissão read no recurso workflows para listar ocorrências e contagens, e update no mesmo recurso para executar ou descartar uma.

​
Passo 1: Escreva o nó de gatilho de agendamento

Gatilhos já vêm prontos. Você os descobre no catálogo e nunca cria um. Obter um gatilho do catálogo devolve o JSON Schema do gatilho de agendamento a partir da instância em execução:
O gatilho de agendamento é um nó com type: "trigger" e estes campos no seu data:

​
O que a expressão cron aceita

Cinco campos, separados por espaços. Cada campo aceita *, um valor, uma lista (0,30), um intervalo (9-17) ou um passo (*/15, 9-17/2). O dia da semana vai de 0 a 7, onde tanto 0 quanto 7 significam domingo. Quando você restringe o dia do mês e o dia da semana ao mesmo tempo, o agendamento dispara em um dia que combina com qualquer um dos campos. A expressão 0 9 13 * 5 dispara no dia 13 e em toda sexta-feira. Um minuto é a cadência mais fina que uma expressão de 5 campos consegue descrever. Para algo mais rápido, receba a chamada conforme ela chega com um gatilho de webhook. O Flowker confere a expressão quando você salva o workflow e de novo quando você o ativa, e responde FLK-0117 quando ela não vale. Estas formas não valem:
  • Uma expressão de seis campos, como */30 * * * * *.
  • Uma macro, como @daily ou @every 5m.
  • Um dia ou mês por nome, como MON, MON-FRI ou sun.
  • Um token L ou #, como 0 9 L * * ou 0 9 * * 5#2.
  • Um valor fora do intervalo do seu campo, como 60 minutos, 24 horas, dia do mês 0 ou 32, mês 13 ou dia da semana 8.
  • Um passo /0.

​
Como o timezone funciona

Os campos do cron são hora de relógio na zona que você nomeia, e toda hora que a API devolve é UTC. Um agendamento 0 9 * * * em America/Sao_Paulo reporta 12:00Z. Uma zona que observa horário de verão mantém a hora de relógio ao longo da mudança: a mesma expressão em America/New_York reporta 14:00Z no inverno e 13:00Z no verão.

​
Passo 2: Ative o workflow e leia a cadência

1

Salve o workflow

Envie o nó com o resto do seu workflow para Criar um workflow, ou para Atualizar um workflow se o rascunho já existe. O Flowker valida o cron aqui.
2

Confira a cadência antes de se comprometer com ela

Listar as próximas ocorrências agendadas calcula os próximos disparos direto do gatilho, então você pode lê-los enquanto o workflow ainda é um rascunho.
limit aceita de 1 a 50 e o padrão é 10. Um valor fora desse intervalo responde FLK-0304.
3

Ative-o

Chame Ativar um workflow. O produtor restrito ao líder faz uma varredura em um intervalo padrão de 60 segundos. Depois de uma varredura bem-sucedida, o Flowker registra e enfileira a próxima ocorrência para o horário dela.
O Flowker registra apenas o próximo disparo, nunca um calendário de disparos futuros. Quando essa ocorrência roda, o motor registra o disparo seguinte, então a cadência se carrega adiante uma ocorrência por vez.

​
Passo 3: Veja quais ocorrências não rodaram

Uma ocorrência fica retida quando o motor chega a ela mais de um minuto depois do horário dela e ninguém pediu para aquele horário rodar. Causas comuns são um serviço que estava fora, uma fila que estava atrasada ou um processo que reiniciou. O Flowker nunca roda uma ocorrência retida por conta própria. Ele a segura para a sua decisão, no estado pending-review. Uma ocorrência retida continua disponível para os endpoints de executar e descartar. O Flowker nunca preenche retroativamente um horário que passou. Então a lista de retidas guarda os disparos que o Flowker já tinha registrado e não conseguiu rodar. Ela não guarda uma entrada para cada horário que passou durante uma indisponibilidade. A cadência em si retoma a partir do próximo horário futuro. Uma ocorrência é ignorada quando o motor a pegou e a fechou sem rodar o workflow. O scheduler nunca roda uma ocorrência ignorada de novo. Uma ocorrência ignorada carrega um skipReason, e os endpoints de executar e descartar não a aceitam: As duas classes não se separam pelo tempo. Uma coisa o tempo decide: um horário atrasado que você nunca pediu para rodar cai na lista de retidas, nunca na lista de ignoradas. Depois que você pede para um horário retido rodar, a idade dele para de segurá-lo. O motor então o pega como qualquer outra ocorrência, e as três razões acima podem fechá-lo. Então um scheduledFor muito no passado é normal na lista de ignoradas, e não significa que o horário disparou na hora. O Passo 4 cobre em que a sua própria execução pode terminar. Três leituras cobrem o quadro inteiro:
1

Liste as ocorrências retidas de um workflow

Listar ocorrências agendadas retidas devolve as mais antigas primeiro.
scheduledFor é o horário que a ocorrência representa, e status é o que decide se você pode agir sobre ela.Esta rota não aceita limit nem cursor de página, e devolve no máximo 100 ocorrências. Planeje uma recuperação em lote em torno disso: trabalhe as linhas que você recebe, depois leia a lista de novo.A contagem abaixo reporta o total em pending-review. A lista de retidas pode guardar mais linhas que essa contagem, porque ela também inclui ocorrências missed. O estado missed dura pouco: um horário atrasado o mantém enquanto o motor retém o horário como pending-review. Os endpoints de executar e descartar não aceitam esse estado, então leia a lista de novo e aja quando a linha mostrar pending-review. Descartar a lista inteira também cobre cada ocorrência pendente de revisão, não apenas as 100 que uma única leitura mostra a você.
2

Liste as ocorrências ignoradas

Listar ocorrências agendadas ignoradas devolve as mais antigas primeiro, cada uma com seu skipReason. Quando informado, limit aceita de 1 a 50. Quando omitido, o padrão é 100.
Ocorrências ignoradas com active-run repetidas significam que o workflow demora mais que o intervalo entre dois disparos. Alargue a cadência ou faça o workflow terminar mais rápido.
3

Conte o que está esperando em todos os workflows

Contar ocorrências pendentes de revisão responde pelo tenant inteiro em uma chamada, que é o que você consulta para um indicador de revisão. O mapa é esparso: um workflow sem nada esperando está ausente dele.
Adicione ?workflowIds=<id>,<id> para limitar as contagens aos workflows que interessam a você.
As duas listas respondem 200 com um array occurrences vazio para um id de workflow que seu tenant não possui, então uma lista vazia significa “nada para revisar aqui”. O Flowker expõe os dados de agendamento subjacentes por suas APIs de próximas ocorrências, de retidas e de contagem de pendentes de revisão. Consulte a documentação do Console para orientações de interface.

​
Passo 4: Execute ou descarte uma ocorrência retida

Executar e descartar agem sobre uma ocorrência cujo status é pending-review. Qualquer outro estado responde FLK-0755, o que também torna uma chamada repetida segura: a segunda chamada responde o mesmo erro em vez de agir duas vezes. A sua própria execução coloca a ocorrência em um desses outros estados: ela sai de pending-review na hora. Uma execução que você pede sai da lista de retidas de imediato, e a idade do horário não a segura mais. Isso não promete que o workflow roda:
  • O workflow roda. A execução aparece em Listar execuções para aquele workflow.
  • O motor fecha a ocorrência como ignorada. Ela sai da lista de retidas para a lista de ignoradas com uma das três razões acima. Uma razão active-run significa que outra execução do workflow ainda estava em andamento. Uma razão workflow-gone significa que o workflow não estava ativo quando a sua execução chegou ao motor. Uma razão execution-duplicate significa que o trabalho daquele horário já tinha rodado.
Depois da sua execução, o scheduler nunca roda uma ocorrência ignorada de novo, e os endpoints de executar e descartar não a aceitam. Leia as duas listas antes de concluir qualquer coisa sobre um horário que você tentou recuperar. A linha ignorada pode registrar a recusa da sua recuperação, não a do disparo original. Mantenha o workflow ativo enquanto você trabalha a lista. Uma execução recarrega o workflow, e um workflow que não está ativo fecha a ocorrência como ignorada por workflow-gone em vez de rodá-la.
1

Execute uma ocorrência

Executar uma ocorrência retida a move para queued e enfileira uma execução forçada no mesmo caminho de execução que um disparo agendado usa. O encaminhador de tarefas adiadas confere a cada segundo por padrão. A hora real de início depende da disponibilidade de workers e da capacidade da fila.
A execução cobre aquele único horário. Ela não desloca a cadência: o próximo disparo continua sendo o que o motor já planejou.
2

Descarte uma ocorrência

Descartar uma ocorrência retida a move para discarded, que é terminal. A ocorrência nunca executa e sai da lista de retidas.
3

Limpe toda a lista de retidas de um workflow

Descartar todas as ocorrências retidas descarta, em uma única escrita, cada ocorrência daquele workflow pendente de revisão, e reporta quantas ele moveu.
Sem nada pendente de revisão, ele responde 200 com "discarded": 0, então uma chamada repetida é segura.
Um descarte não pode ser desfeito, e nunca roda nada. Leia a lista de retidas antes de limpá-la.Descartar todas as ocorrências retidas cobre exatamente as ocorrências daquele único workflow, no seu tenant, pendentes de revisão. Isso deixa o agendamento em si rodando e deixa as próximas ocorrências em paz. Não toca nas ocorrências de outro workflow, nem em ocorrências que já rodaram, falharam, foram ignoradas ou foram descartadas antes.

​
Confirme que funcionou

  • A cadência está saudável quando Listar as próximas ocorrências agendadas devolve horários futuros e a lista de retidas continua curta.
  • Uma execução funcionou quando a ocorrência saiu da lista de retidas e a execução aparece em Listar execuções para aquele workflow.
  • Um descarte funcionou quando a ocorrência saiu da lista de retidas e a contagem de pendentes de revisão daquele workflow caiu.

​
Mude ou pause uma cadência

Apenas um workflow em rascunho aceita uma edição, então mudar a cadência são quatro chamadas:
  1. Desativar o workflow. O Flowker para de registrar novas ocorrências para ele.
  2. Mover para rascunho.
  3. Atualizar o workflow com o novo valor de cron, timezone ou enabled.
  4. Ativar. O produtor restrito ao líder faz uma varredura em um intervalo padrão de 60 segundos. Depois de uma varredura bem-sucedida, o Flowker registra e enfileira a próxima ocorrência da nova cadência.
O Flowker não preenche retroativamente os horários que passaram enquanto o workflow estava inativo. As ocorrências retidas sobrevivem aos quatro passos. Elas continuam listadas e continuam acionáveis assim que o workflow estiver ativo de novo.
Uma ocorrência retida que o Flowker registrou antes da mudança continua pendente de revisão. Leia a lista de retidas depois de uma mudança de cadência e limpe o que você não quer mais.

​
Quando algo dá errado

Duas falhas não respondem código de erro:
  • A lista de próximas mostra ocorrências, mas nada nunca roda. A API calcula a cadência por conta própria, enquanto o binário do worker é o que dispara. Confirme que o worker roda e que você definiu SCHEDULER_REDIS_HOST. Veja Variáveis do scheduler.
  • O Flowker não registra nada novo para um workflow ativo. Confira enabled no nó de gatilho: false mantém o workflow ativo e o agendamento dele quieto.

​
O que vem a seguir

Como configurar um gatilho de webhook

Comece o mesmo workflow a partir de uma chamada HTTP de entrada em vez de uma cadência.

Guia de design de workflows

Construa o resto do grafo em que o gatilho entra.