Agendamentos

Um agendamento (cron) põe um script a correr sozinho: todos os dias às 7h00, de 15 em 15 minutos, na última sexta-feira do mês, ou de 5 em 5 minutos numa janela nocturna até o trabalho do dia estar feito. Um script pode ter vários agendamentos, cada um com o seu horário, fuso horário e argumentos.

Nesta página usamos o agendamento Indicadores diários da app Gestão de Clientes, que corre o script atualizar_indicadores todos os dias às 7h00 (fuso Europe/Lisbon).

#Criar e abrir agendamentos

Na árvore lateral, expande o nó do script. A linha Agendamentos mostra quantos existem; por baixo dela, cada agendamento aparece com o nome, o horário resumido e, quando desligado, a marca (desactivado).

• Para criar: clica no + da linha Agendamentos (Novo agendamento). Abre-se o editor num separador novo.
• Para editar: clica no nome do agendamento.
• No menu ⋮ de cada agendamento tens Activar/Desactivar e Eliminar. Eliminar pára o agendamento de vez, mas o histórico de execuções do script mantém-se.

O editor tem o formulário à esquerda e o painel Execuções à direita (só depois de gravado — ver o fim da página). No topo, o interruptor Activo liga e desliga o agendamento, e Gravar grava tudo.

#Escolher a frequência

O campo Frequência oferece três cartões — três naturezas de agendamento:

Cartão	Serve para
Repetir	"A cada N minutos ou horas, sem parar." Sondagens, sincronizações contínuas.
Em momentos certos	"Numa hora do dia, nos dias que escolheres." O clássico: diário, semanal, mensal.
Janela de vigilância	"Sonda de N em N minutos entre duas horas e pára quando o trabalho do dia estiver feito."

Por baixo dos cartões, o atalho Escrever a expressão à mão troca os controlos por um campo de Expressão cron livre — para quem já traz uma. Aceita 5 campos ou 6 (com segundos), ex.: 0 9 * * 1-5. Voltar aos controlos desfaz a troca.

#Repetir

1. Escolhe o cartão Repetir.
2. Em Unidade, escolhe minutos ou horas.
3. Com minutos, define A cada quantos minutos? (ex.: 15). Com horas, define Ao minuto — o minuto de cada hora em que dispara (ex.: 0 corre às 9h00, 10h00, 11h00…).

#Em momentos certos

1. Escolhe o cartão Em momentos certos.

2. Em Repete, escolhe a variante:

   Opção	Campos que aparecem
   Todos os dias (nos dias escolhidos)	À hora + Dias — sete botões (Seg…Dom) com os atalhos Todos, Úteis e Fim-de-semana. Qualquer combinação serve: segunda, quarta e sexta, por exemplo.
   Uma vez por semana	À hora + Dia da semana.
   Uma vez por mês	À hora + No mês, corre (ver abaixo).

3. Para o mensal, No mês, corre tem três formas:

   Opção	Exemplo
   Num dia fixo	Dia 1, dia 15… Com Dia do mês acima de 28, o editor avisa: "Nos meses sem esse dia não corre. Para «o último dia», usa a opção própria."
   Numa posição (ex.: última sexta)	Posição (1ª, 2ª, 3ª, 4ª, 5ª ou última) + Dia da semana — ex.: a última sexta-feira do mês.
   No último dia do mês	31, 30, 28 ou 29 — o que o mês tiver.

#O fuso horário

Todo o agendamento tem um Fuso horário — as horas que defines são horas desse fuso, não do servidor. O selector lista todos os fusos IANA, com pesquisa (ex.: Lisbon, Sao_Paulo). Um agendamento às 9h00 em America/Sao_Paulo corre às 9h00 de São Paulo, mesmo com o servidor na Europa — e as mudanças de hora de Verão ficam por conta da plataforma.

#Se ficar por correr

Às vezes a hora marcada passa sem execução: o servidor estava desligado, reiniciou a meio, ou a execução anterior ainda decorria. A secção Se ficar por correr decide o que fazer a essas ocorrências:

Opção	Consequência
Ignorar	Não recupera. Fica registado que se perdeu (estado Perdida no painel Execuções).
Só a mais recente	Recupera a última que ficou por fazer; as anteriores ficam registadas como perdidas.
Todas	Recupera todas as que ficaram por fazer, pela ordem em que estavam marcadas.

As execuções recuperadas aparecem no histórico do script com a origem Recuperação.

#Janela de vigilância

O terceiro cartão resolve um padrão que o cron clássico não exprime: "a partir das 18h00, tenta de 5 em 5 minutos; quando conseguires, corre uma vez e pára até amanhã". Típico para esperar que um ficheiro chegue, que um fecho de dia termine noutro sistema, ou que uma tabela fique preenchida.

Os campos:

Campo	O que define
A cada	O intervalo de sondagem: 1, 2, 3, 5, 10, 15, 20 ou 30 minutos.
Das / Até	As horas em que a janela abre e fecha, no fuso escolhido.
Dias	Os dias da semana em que a janela existe (os mesmos sete botões e atalhos).
Se algum script der erro, parar o resto do dia	Ligado, um erro fecha a janela até ao dia seguinte em vez de continuar a tentar.

Sem mais nada, a janela corre o script no primeiro disparo de cada dia e fecha até ao dia seguinte. O poder verdadeiro está na validação:

#O script de validação

A secção Script de validação aceita um pequeno código Python que decide, a cada sondagem, se já se pode executar:

1. Clica em Adicionar validação. Abre-se um editor num modal.
2. Escreve uma função main(input) que devolve True (pronto — o principal corre uma vez e a janela fecha até amanhã) ou False (ainda não — espera e tenta no próximo intervalo).
3. Usa Testar validação para a correr já, com os argumentos do agendamento: vês o veredicto (Pode executar (corre 1×) ou Ainda não — espera), a duração e os logs.
4. Fecha o modal e clica em Gravar no editor do agendamento.

# Devolve True quando o ficheiro do dia já chegou ao FTP interno.
from api_manager import db


def main(input):
    linha = db("Dados CRM").query_one(
        "select count(*) as n from cargas_diarias where dia = date('now')"
    )
    return bool(linha and linha["n"] > 0)

A validação corre no mesmo ambiente do script principal: recebe o mesmo input (argumentos e contexto), e tem os mesmos ficheiros, o mesmo ambiente Python e o mesmo SDK (db, http, log, …).

#Argumentos do agendamento

A secção Argumentos define pares nome/valor que chegam ao script em input["args"] em todas as execuções deste agendamento — tal como na execução manual, os valores chegam como texto. É assim que o mesmo script serve dois agendamentos diferentes: um exportar diário com {"ambito": "dia"} e um mensal com {"ambito": "mes"}, por exemplo.

#Gravar, activar, acompanhar

• Gravar cria (ou actualiza) o agendamento. O botão só activa quando o nome está preenchido e o horário é válido.
• O interruptor Activo no topo liga e desliga sem apagar nada — na árvore, um agendamento desligado mostra (desactivado).
• Um agendamento activo de um script em Rascunho não corre: as ocorrências ficam Saltada, com a nota "O script está em rascunho".

#O painel Execuções

Depois de gravado, o lado direito do editor mostra o painel Execuções — o agendamento visto de fora, actualizado ao vivo:

• A primeira linha diz se o motor de agendamentos da instalação está vivo ("Agendador activo · última verificação há Ns"). Se não estiver a correr, aparece um aviso claro — as horas previstas existem, mas ninguém as vai cumprir até o agendador arrancar. Nesse caso, fala com quem administra a instalação.
• Por baixo, a lista de ocorrências — cada hora marcada e o estado dela:

Estado	Significa
Por fazer	Hora futura, ainda por cumprir.
A correr	A execução está a decorrer agora.
Feita	Correu.
Perdida	Ficou por correr e a política é Ignorar (ou já não era recuperável). O motivo aparece na linha.
Saltada	Não chegou a correr — ex.: script em rascunho, ou sobreposição com a execução anterior.

Num agendamento com validação, clicar numa ocorrência abre as Tentativas da validação: cada sondagem com o veredicto (pronto, ainda não ou erro) e a mensagem. As sequências de "ainda não" aparecem colapsadas — "12 tentativas sem novidade" — para as três linhas que interessam não se perderem no meio.

#Perguntas frequentes

Marquei para o dia 31 e há meses em que não corre. É o comportamento de Num dia fixo: nos meses sem esse dia, não corre — o editor avisa quando escolhes 29, 30 ou 31. Para "o fim do mês", usa No último dia do mês.

A execução das 9h00 apareceu como Saltado (sobreposição). A execução anterior ainda estava a decorrer quando a nova hora chegou. A plataforma nunca corre o mesmo agendamento duas vezes ao mesmo tempo. Se acontece com frequência, alarga o intervalo ou reduz o trabalho por execução.

A validação devolveu True mas o principal correu só uma vez — a condição continua verdadeira. É de propósito: quando a validação devolve True, o principal corre uma vez e a janela fecha até ao dia seguinte. Sem isso, uma condição que ficasse verdadeira punha o script a correr em ciclo até ao fim da janela.

Mudou a hora (Verão/Inverno) — tenho de ajustar os agendamentos? Não. As horas são interpretadas no Fuso horário do agendamento; a mudança de hora é tratada pela plataforma.