Skip to main content
Um trigger de schedule inicia 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 no horário não é perdido: ele espera em uma lista de ocorrências retidas até que você o execute ou o descarte. Use esta página para escrever o trigger, confirmar a cadência e trabalhar a lista de ocorrências retidas.

​
Antes de começar

  • Um workflow em status draft. Somente um workflow em draft aceita uma edição, portanto escreva o trigger antes de ativá-lo. Veja Primeiros passos com o Flowker para o caminho de criação e ativação.
  • O binário worker em execução com o scheduler habilitado. SCHEDULER_ENABLED é resolvido como true a menos que você o defina como false, e a fila precisa de SCHEDULER_REDIS_HOST: sem host, o binário worker não inicia e nenhum workflow agendado dispara. Verifique essa variável primeiro quando os seus agendamentos nunca disparam. Veja Variáveis do scheduler.
  • A permissão read sobre o recurso workflows para listar ocorrências e contagens, e update sobre o mesmo recurso para executar ou descartar uma.

​
Passo 1: Escreva o node do trigger de schedule

Os triggers já vêm incluídos. Você os descobre no catálogo e nunca cria um. Obter um trigger do catálogo retorna o JSON Schema do trigger de schedule direto da instância em execução:
O trigger de schedule é um node 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, e 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 satisfaz qualquer um dos dois campos: 0 9 13 * 5 dispara no dia 13 e em todas as sextas-feiras. Um minuto é a cadência mais fina que uma expressão de 5 campos consegue expressar. Para algo mais rápido, atenda a chamada no momento em que ela chega com um trigger de webhook. O Flowker verifica a expressão quando você salva o workflow e novamente quando você o ativa, e responde FLK-0117 quando ela não se sustenta. Estas formas não se sustentam:
  • Uma expressão de seis campos, como */30 * * * * *.
  • Uma macro, como @daily ou @every 5m.
  • Um dia ou um mês com 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 fuso horário funciona

Os campos do cron são hora de relógio de parede no fuso que você nomeia, e toda hora que a API retorna é UTC. Um agendamento 0 9 * * * em America/Sao_Paulo reporta 12:00Z. Um fuso que observa horário de verão mantém a hora de relógio de parede na virada: 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 node com o resto do seu workflow para Criar um workflow, ou para Atualizar um workflow se o draft já existir. O Flowker valida o cron aqui.
2

Confira a cadência antes de assumi-la

Listar próximas ocorrências agendadas calcula os próximos disparos direto do trigger, então você pode lê-los enquanto o workflow ainda é um draft.
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. Em menos de um minuto o engine registra a próxima ocorrência e a enfileira para o horário dela.
O Flowker registra apenas o próximo disparo, nunca um calendário de disparos futuros. Quando essa ocorrência é executada, o engine registra o disparo seguinte, então a cadência se sustenta sozinha, uma ocorrência por vez.

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

Uma ocorrência fica retida quando o engine chega até ela mais de um minuto depois do horário dela e ninguém pediu que aquele horário fosse executado: o serviço estava fora, a fila estava atrasada, o processo reiniciou. O Flowker nunca executa uma ocorrência retida por conta própria — ele a guarda para a sua decisão, no estado pending-review. Reter é o único resultado que não é terminal: uma ocorrência retida continua acionável até você executá-la ou descartá-la. O Flowker nunca preenche um horário que passou. Então a lista de retidas guarda os disparos que o Flowker já havia registrado e não conseguiu executar — não uma entrada para cada horário que passou durante uma indisponibilidade — e a cadência em si retoma a partir do próximo horário futuro. Uma ocorrência é ignorada quando o engine a assumiu e a encerrou sem executar o workflow. Uma ocorrência ignorada é terminal e carrega um skipReason: As duas classes não se separam pelo momento do disparo. Uma coisa esse momento decide: um horário atrasado que você nunca pediu para executar aparece na lista de retidas, nunca na de ignoradas. Depois que você pede que um horário retido seja executado, a idade dele para de segurá-lo. O engine então o assume como qualquer outra ocorrência, e os três motivos acima podem encerrá-lo. Então um scheduledFor bem antigo é normal na lista de ignoradas, e não significa que o horário disparou em tempo. O Passo 4 cobre em que a sua própria execução pode terminar. Três leituras cobrem o quadro completo:
1

Liste as ocorrências retidas de um workflow

Listar ocorrências agendadas retidas retorna da mais antiga para a mais recente.
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 paginação, e retorna no máximo 100 ocorrências. Planeje uma recuperação em massa com isso em mente: trabalhe as linhas que você recebe e leia a lista novamente. A contagem mais abaixo informa o total real. Descartar a lista inteira também cobre todas as ocorrências pendentes de revisão, não apenas as 100 que uma única leitura mostra.
2

Liste as ocorrências ignoradas

Listar ocorrências agendadas ignoradas retorna da mais antiga para a mais recente, cada uma com o seu skipReason. limit aceita de 1 a 50.
Uma sequência de omissões active-run significa que o workflow demora mais do 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 por todo o tenant em uma única chamada, que é o que você consulta para um badge de revisão. O mapa é esparso: um workflow sem nada esperando não aparece nele.
Acrescente ?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 o seu tenant não possui, então uma lista vazia significa “nada a revisar aqui”.
O Console mostra as mesmas três leituras. Abra o painel Agendamento a partir da lista de workflows para ver o status do agendamento, as próximas execuções e as execuções pendentes de revisão. Veja Visão geral de workflows.

​
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 segura uma chamada repetida: a segunda é recusada em vez de agir duas vezes. A sua própria execução deixa 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. Ela não promete que o workflow execute:
  • O workflow executa. A execução aparece em Listar execuções para aquele workflow.
  • O engine encerra a ocorrência como ignorada. Ela sai da lista de retidas para a de ignoradas com um dos três motivos acima. active-run significa que outra execução do workflow ainda estava em andamento. workflow-gone significa que o workflow não estava ativo quando a sua execução chegou ao engine. execution-duplicate significa que o trabalho daquele horário já havia sido executado.
Uma omissão vinda da sua própria execução é tão terminal quanto qualquer outra, então uma segunda execução ou um descarte sobre ela respondem FLK-0755. Leia as duas listas antes de concluir algo 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 encerra a ocorrência como uma omissão workflow-gone em vez de executá-la.
1

Execute uma ocorrência

Executar uma ocorrência retida a move para queued e a entrega ao mesmo caminho de execução que um disparo agendado usa. Ela começa em um ou dois segundos.
A execução cobre aquele único horário. Ela não desloca a cadência: o próximo disparo continua sendo o que o engine já planejou.
2

Descarte uma ocorrência

Descartar uma ocorrência retida a move para discarded, que é terminal. A ocorrência nunca é executada 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, todas as ocorrências daquele workflow que estão pendentes de revisão, e informa quantas foram movidas.
Sem nada pendente de revisão, ela responde 200 com "discarded": 0, então uma chamada repetida é segura.
Um descarte não pode ser desfeito e nunca executa 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, que estão pendentes de revisão. Ele deixa o agendamento funcionando, deixa as próximas ocorrências intactas e não toca nas ocorrências de outro workflow nem nas que já foram executadas, falharam, foram ignoradas ou foram descartadas antes.

​
Confirme que funcionou

  • A cadência está saudável quando Listar próximas ocorrências agendadas retorna horários futuros e a lista de retidas se mantém 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

Somente um workflow em draft aceita uma edição, então mudar a cadência são quatro chamadas:
  1. Desative o workflow. O Flowker para de registrar novas ocorrências para ele.
  2. Mova-o para draft.
  3. Atualize o workflow com o novo valor de cron, timezone ou enabled.
  4. Ative-o. Em menos de um minuto o engine registra a próxima ocorrência da nova cadência.
O Flowker não preenche os horários que passaram enquanto o workflow esteve inativo, e as ocorrências retidas sobrevivem aos quatro passos: elas continuam listadas e continuam acionáveis quando o workflow está ativo de novo.
Uma ocorrência que o Flowker registrou antes da mudança continua pendente. Leia a lista de retidas depois de mudar a cadência e limpe o que você não quiser mais.

​
Quando algo falha

Duas falhas não respondem nenhum código de erro:
  • As próximas ocorrências são listadas, mas nada nunca é executado. A API calcula a cadência por conta própria, enquanto o binário worker é quem a dispara. Confirme que o worker está em execução e que SCHEDULER_REDIS_HOST está definido. Veja Variáveis do scheduler.
  • Nada de novo é registrado para um workflow ativo. Verifique enabled no node trigger: false mantém o workflow ativo e o agendamento dele em silêncio.

​
Próximos passos

Configurando um trigger de webhook

Inicie o mesmo workflow a partir de uma chamada HTTP recebida em vez de uma cadência.

Guia de design de workflows

Construa o resto do grafo em que o trigger entra.