Scheduler

Imagine que você administra uma loja de roupas online. Quando um cliente leva a última unidade, o estoque daquele produto chega a 0. Para voltar a vender, você precisa fazer um pedido ao fornecedor. Digamos que o fornecedor mantenha, aberto na internet, um canal que recebe pedidos, e que chamar um endereço definido registre o pedido. E digamos que a tarefa de encontrar os produtos com estoque 0 e chamar esse canal você já tenha deixado pronta como um Script. Ainda assim, resta um problema. É preciso alguém para acionar esse Script uma vez por dia.

O Scheduler faz o papel dessa pessoa. Se você definir uma vez "execute este Script todos os dias no mesmo horário", sempre que esse horário chegar o WEEGLOO executa por conta própria. Ninguém precisa abrir a tela.

Dá para comparar com ajustar um despertador. Se você definir uma vez a que horas ele vai tocar, a partir daí ele toca sozinho naquele horário todos os dias. Nesta página, você verá, com o exemplo da reposição de estoque da loja de roupas, o que se define em um Scheduler, como escrever o horário e com a permissão de quem ele é executado.

As três coisas a definir

Não são muitas as coisas que você define em um Scheduler.

• Nome: serve para você reconhecê-lo depois na lista. Exemplo: Reposição de estoque.
• O Script a executar: você escolhe um Script para executar quando o horário chegar. Um Scheduler executa apenas um Script.
• Quando executar: tratado abaixo em Como escrever o horário.

Há ainda um interruptor para ligar e desligar. Se você o deixar desligado, ele continua salvo e apenas não é executado. Quando precisa pausá-lo por um tempo, como no período em que o fornecedor está fechado, você não precisa apagá-lo.

O Script a executar não pode ser trocado depois. Para rodar outro Script, crie um novo Scheduler. O nome, o horário e o liga-desliga você pode alterar a qualquer momento.

Como escrever o horário

O horário é escrito em cinco posições. Da esquerda para a direita, são minuto, hora, dia, mês e dia da semana, e * significa "todos".

minuto  hora  dia  mês  dia da semana
0       9     *    *    *              → todos os dias às 9h em ponto

Os formatos mais usados são estes.

O horário é lido em tempo universal (UTC). Como não é o horário local, decida a que horas quer executá-lo no horário local e escreva o valor com essa diferença já calculada. Em uma região que está 9 horas à frente do tempo universal, as 9h da manhã de lá são 0 0 * * *. A reposição de estoque roda com esse valor, ou seja, à 0h em tempo universal.

Para horários que incluem uma data ou um dia da semana, esse cálculo pode empurrar até a data, então confira mais uma vez.

Um valor que nunca chega a ser executado não é salvo. Por exemplo, 0 0 30 2 * aponta para 30 de fevereiro, mas esse dia não existe, então, ao tentar salvar, você recebe uma resposta pedindo para verificar o valor novamente.

Com a permissão de quem ele é executado

Quando o Scheduler executa o Script, essa execução é tratada como se quem criou o Scheduler a tivesse feito. O fato de o Script de reposição de estoque ler os produtos e chamar o fornecedor também acontece sob a autoridade de quem o criou.

Por isso, para criar ou alterar um Scheduler, são necessárias duas permissões em conjunto.

• O papel (SpaceRole) precisa ter permissão para configurar Scheduler.
• Você também precisa ter a permissão para executar o Script que aquele Scheduler vai rodar.

A segunda permissão é verificada não só na criação, mas também na alteração. Isso porque mudar o horário em que ele roda é definir quando aquele Script será executado, e ligar o que estava desligado é dar início à execução.

Se quem o criou perder essa permissão depois, o Scheduler é desligado. Se o responsável sai da equipe ou tem seu papel reduzido, no próximo horário de execução o WEEGLOO verifica isso e, sem executar, desliga o interruptor. Mesmo que a permissão volte, o interruptor não se liga automaticamente, então você precisa ligá-lo de novo por conta própria.

Conferir o histórico de execução

Cada vez que o Scheduler roda, fica um registro. Nele consta se aquela execução teve sucesso ou falhou. Se o pedido de ontem à noite realmente saiu, é por esse registro que você confere.

Na lista aparecem o horário de execução e o resultado de cada execução. Ao clicar em uma execução que falhou no meio do caminho, você vê o motivo tal como está, na área de erro do detalhe. Ele aparece junto com o tempo que a execução levou, então esse texto permite distinguir se foi porque o canal do fornecedor não respondeu ou se foi outro problema.

O registro de uma execução bem-sucedida desaparece depois de 1 hora, e o de uma execução com falha, depois de 3 dias. As falhas ficam mais tempo porque são elas que você vai querer examinar mais tarde. Se for um valor que precisa ficar guardado por mais tempo, como o histórico de pedidos, salve-o como Content dentro do Script.

Mesmo que ocorra uma falha, o Scheduler não para. Se a falha foi porque o canal do fornecedor não respondeu por um instante, apenas aquela execução é registrada como falha, e no horário seguinte ele volta a rodar.

Em que difere do Webhook

Ambos coincidem em executar um Script sem que uma pessoa precise acioná-lo. O que os separa é o que dispara a execução.

• O Webhook executa quando algo acontece. Quando um produto é cadastrado, quando um conteúdo é publicado.
• O Scheduler executa quando chega o horário. Todos os dias naquele horário, mesmo que nada aconteça.

À primeira vista, a reposição de estoque parece um caso de Webhook. Afinal, seria só fazer o pedido no exato instante em que o estoque chega a 0. Só que, se, ao longo de um dia, o estoque de um mesmo produto chega a 0, volta por causa de uma devolução e cai a 0 de novo, um pedido sai a cada uma dessas vezes. Se você revisa tudo de uma vez, uma vez por dia, cada produto tem apenas um pedido. O lugar do Scheduler são as tarefas que devem ser "reunidas e feitas de uma vez", e não "feitas toda vez que surgem".

Ao contrário, preencher a descrição no instante em que um produto é cadastrado não tem por que ser adiado, então é caso de Webhook.

O que é bom saber

• Há um limite de quantidade. A quantidade de Scheduler que uma Organization pode ter é definida conforme o plano (Free: 1, Basic: 5, Pro: 30, Enterprise: ilimitado). Ao atingir o limite, não é possível criar novos; ao apagar um que não está em uso, uma vaga se abre novamente.
• O Scheduler e o Script compartilham a contagem de execuções. Como o que o Scheduler faz é executar um Script, cada vez que ele roda consome uma unidade da cota de execuções de Script do plano. Não existe um limite separado só para o Scheduler. Quando essa cota se esgota, os Scheduler cujo horário chegar a partir daí não são executados e ficam desligados. Nesse caso, o motivo pelo qual não conseguiram começar fica registrado no histórico de execução. Mesmo quando vira o mês, eles não voltam a ligar automaticamente, então você precisa ligá-los de novo por conta própria.
• As execuções perdidas não são repostas. Se um dia foi pulado, por causa de uma manutenção, por exemplo, ele não roda duas vezes no dia seguinte. Ele volta a rodar a partir do próximo horário.
• Não dá para excluir um Script que algum Scheduler usa. Isso vale mesmo que esse Scheduler esteja desligado. Exclua antes esse Scheduler e só então exclua o Script.

Gerenciar no estúdio de conteúdo

Você cria e gerencia o Scheduler na tela de Scheduler do estúdio de conteúdo. Na lista, cada Scheduler que você criou aparece em uma linha, junto com o nome, o nome do Script a executar, a expressão cron, a Próxima execução, o estado, a hora da modificação e quem modificou.

A tela também informa qual relógio corresponde a cada uma das duas colunas. No cabeçalho da coluna que traz a expressão cron aparece UTC, e no cabeçalho da coluna Próxima execução aparece o fuso horário de quem está vendo, como UTC±N. Assim, você vê na mesma linha o valor salvo e a que horas ele corresponde no seu horário. Em fusos horários atrasados em relação ao tempo universal, a Próxima execução pode aparecer como o dia anterior.

Um novo Scheduler é criado com o botão Criar no canto superior direito da lista.

1. Pressione o botão Criar no canto superior direito da lista.
2. No campo de nome, digite Reposição de estoque.
3. Deixe Ativo ligado. Se você deixar desligado, ele é salvo, mas não é executado.
4. Em Script a executar, escolha o Script de reposição de estoque.
5. Em Agendamento, escolha Entrada manual.
6. Nas cinco posições, digite 0 0 * * *.
7. Pressione o botão Criar no canto superior direito para salvar.

A tela também mostra na hora quando a expressão que você digitou realmente vai rodar. Junto com o aviso de que a expressão digitada por você é salva em tempo universal (UTC), aparece uma prévia do valor de cron que será salvo e do horário da próxima execução.

Ao clicar em um Scheduler na lista, abre-se a tela de detalhes desse Scheduler. A tela de detalhes se divide em duas abas, Log de execução e Definições, e ao abrir pela primeira vez aparece o Log de execução. Na aba Log de execução, cada execução realizada até agora aparece em uma linha, e em cada linha você vê Executado em, Resultado e o ID da requisição que aponta aquela execução. Com a coluna Resultado você pode ver separadamente só as execuções bem-sucedidas ou só as que falharam, e, ao pressionar Atualizar Logs, as execuções realizadas há instantes também são lidas de novo.

Ao clicar em uma execução, abre-se o detalhe daquela execução. Aqui aparecem o Resultado junto com o Código de status, o tempo que levou (Duração) e com que identidade aquela execução rodou (Run as) e, se for uma execução com falha, o motivo aparece tal como está na área Erro. Na parte de cima há insígnias que informam de qual Scheduler é esta execução e qual Script ela rodou, e junto delas ficam o link que leva a esse Script e o link Ver no log do Script, que mostra a mesma execução no registro do lado do Script.

O que fazer em seguida

• Script: trata de como criar o Script que o Scheduler vai executar e de como incluir ações que chamam serviços externos, como o canal do fornecedor.
• Webhook: trata de como fazer a execução acontecer quando ocorre uma mudança definida, e não em um horário definido.
• Papéis e permissões: trata de como incluir em um papel a permissão para configurar Scheduler e a permissão para executar Script.