Agendamento
Execute processos automaticamente em horários programados: recorrência diária, semanal, mensal, por hora ou expressão Cron customizada.
Como funciona
O Agendador (Job Scheduler) dispara execuções dos seus processos automaticamente na periodicidade configurada, sem intervenção manual. O agendamento roda no servidor da plataforma, então o disparo acontece mesmo com o seu navegador fechado, desde que o Runtime de destino esteja online no horário.
Criar um agendamento
- Em Meus Insights → Control Room, abra a aba Agendamentos e clique em + Novo Agendamento.
- Selecione o Agente. A lista traz cada agente com o processo que ele executa; um agente com vários processos aparece como um grupo, e você escolhe qual deles. Abaixo do seletor aparece quem foi escolhido (avatar, agente e processo).
- Informe um Nome descritivo. Ex.: Execução diária às 8h.
- Em Runtime de Execução, escolha onde este agendamento deve rodar (veja Runtime e ambiente do agendamento). Em branco, vale o runtime e o ambiente do próprio agente.
- Se o processo tiver variáveis da Matrix, elas aparecem em Parâmetros de Inicialização, cada uma com o tipo ao lado do nome, para preenchimento opcional: deixe em branco para manter o valor padrão configurado no processo, ou informe um valor específico para esse agendamento. Variável com regra de uso Fixo aparece bloqueada, com o valor do agente; a de Opções aparece como caixa de seleção (na Lista, marcação dos itens), e a de Opções sem valor padrão precisa de uma escolha para o agendamento ser salvo. A de Formato mostra no campo vazio a ajuda ou o exemplo do formato; valor fora do formato, ou campo vazio quando ela não tem padrão, impede salvar. A variável Obrigatório também não pode ficar em branco; e um agente com parâmetro Secreto obrigatório não pode ser agendado, porque o agendamento não guarda segredo.
- Escolha a Recorrência e o Horário (fuso de Brasília).
- Confira a prévia: a recorrência por extenso (ex.: De segunda a sexta às 08:00), a expressão Cron gerada (ex.:
0 8 * * 1-5) e as três próximas execuções, com a data e quanto falta. Uma expressão que o agendador não aceita aparece em vermelho, com o motivo, e não pode ser salva. Isso inclui um dia que não existe no mês escolhido, como 31 de fevereiro. - Clique em Salvar. Campo obrigatório em branco é apontado embaixo do próprio campo.
{vault.CHAVE}), ou dispare a execução por API, onde o valor é enviado a cada chamada. Veja Dados Sensíveis.
Se você mudar um parâmetro que já tinha valor em agendamentos para o tipo Secreto, esses agendamentos continuam com o valor que tinham gravado. Abra cada um e salve de novo: o campo aparece bloqueado e o valor antigo é apagado do registro.
Runtime e ambiente do agendamento
O campo Runtime de Execução decide em qual runtime e em qual ambiente as execuções do agendamento rodam. Juntos, os dois apontam a instalação que executa e os valores do Cofre que a execução usa.
| Opção | O que fixa |
|---|---|
| A primeira, runtime e ambiente do agente, com o ambiente atual do agente ao lado | Nada. Cada disparo usa o runtime e o ambiente que o agente tiver naquele momento. |
| Nome - mesmo ambiente do agente - LIVE ou OFFLINE | Só o runtime. O ambiente acompanha o do agente: se o agente vai de Homologação para Produção, o agendamento passa a rodar na instalação de Produção do mesmo runtime. Aparece desabilitada, com sem instalação em e o ambiente, quando o runtime não tem instalação no ambiente atual do agente. |
| Nome - Ambiente - LIVE ou OFFLINE, uma por ambiente em que o runtime tem instalação | O runtime e o ambiente. A execução roda na instalação daquele ambiente e usa os valores do cofre desse ambiente, qualquer que seja o ambiente do agente. |
As opções vêm agrupadas por runtime. A lista mostra os seus runtimes e os que um administrador tornou visíveis para a empresa, com - da empresa no nome do grupo. O LIVE ou OFFLINE é o status da instalação no momento da escolha. Um runtime offline continua selecionável, porque o que decide o que acontece no horário do disparo é o estado da instalação naquele momento: ela só recebe a execução na fila se tiver Manter fluxo offline ligado (veja Comportamento de execução).
Ao gravar um agendamento ligado, a tela confere o par que vai valer: o runtime e o ambiente fixados no agendamento, ou, sem nada fixado, os do agente publicado. O Salvar é recusado, com a mesma mensagem que o Router daria no disparo, quando o runtime não existe mais (ou saiu do alcance), quando não tem instalação no ambiente (por exemplo O runtime X não tem instalação em Y. Escolha outro runtime, ou cadastre uma instalação nesse ambiente.) e quando a instalação está suspensa pelo plano. Agendamento gravado desligado não é conferido: a conferência acontece ao religar. A API faz a mesma conferência.
Tipos de recorrência
| Recorrência | Comportamento | Exemplo de Cron |
|---|---|---|
| Diário | Todos os dias no horário escolhido | 0 8 * * * (8h da manhã) |
| Semanal | Nos dias da semana selecionados | 0 8 * * 1-5 (dias úteis, 8h) |
| Mensal | Em um dia fixo do mês | 0 8 1 * * (todo dia 1º, 8h) |
| Por hora | A cada N horas | 0 */2 * * * (a cada 2 horas) |
| Custom | Expressão Cron livre para casos avançados | 30 6,18 * * 1-5 (6h30 e 18h30, dias úteis) |
minuto hora dia-do-mês mês dia-da-semana. O preview no modal sempre mostra a próxima execução calculada. Confira antes de salvar.
Gerenciar agendamentos
A aba Agendamentos lista os agendamentos agrupados pelo agente que executa (avatar, nome do agente e processo), cada um com a recorrência por extenso, a expressão Cron, a próxima execução com a data e quanto falta, o runtime escolhido (no formato Runtime - Ambiente, ou só o runtime quando o agendamento fixa só ele) e a chave de ligar e desligar. Um agendamento desligado mostra Desligado: não dispara; um com expressão que o agendador não aceita aparece marcado como inválido, para ser editado. De lá você pode editar ou remover cada agendamento. Um agendamento novo nasce ligado; editar e salvar não liga nem desliga, ele continua como estava (ligar e desligar é só pela chave do card). Religar confere de novo o par runtime e ambiente que vai valer: sem instalação nele, a chave é recusada com a mensagem do Router, e o agendamento continua desligado. Ao editar, a recorrência reabre no tipo que a descreve (Diário, Semanal com os dias marcados, Mensal, Por hora), e o que não cabe nesses tipos abre em Custom. O dono do processo recebe um e-mail quando o agendamento é ativado e quando é desativado (detalhes em Mensageria Padrão).
O agendamento também pode ser ativado, desativado e consultado programaticamente via API.
Quando o dono do processo perde o acesso
Se o dono do processo for bloqueado pelo administrador da empresa, ou ficar sem acesso ativo porque o plano não comporta mais aquela quantidade de usuários, o agendamento deixa de disparar. Ele não é desativado nem apagado: continua ligado na tela, apenas pula cada horário enquanto durar a situação, e volta a executar sozinho no momento em que o acesso for restabelecido, sem precisar desligar e religar. O mesmo vale para o plano da empresa: perdendo a funcionalidade de agendamento, os disparos param, e voltam com o upgrade. Na volta do plano, cada agendamento é conferido como num religar: o que ficou sem instalação no par runtime e ambiente continua desligado.
Boas práticas
- Confirme o runtime antes do horário. Se a instalação de destino estiver offline no disparo, a execução falha (ou entra na fila, se a instalação tiver Manter fluxo offline ativo).
- Evite sobreposição. Se o processo demora 40 minutos, não agende a cada 30. Use Enfileirar Jobs na instalação ou aumente o intervalo.
- Horários de menor concorrência. Processos pesados rodam melhor fora do horário comercial, quando os sistemas-alvo estão mais rápidos.
- Monitore pela manhã. Agendou de madrugada? Verifique o resultado no Control Room e configure o envio de logs por e-mail em caso de falha.