Pianificazioni

Una pianificazione (cron) mette uno script a funzionare da solo: tutti i giorni alle 7:00, ogni 15 minuti, l'ultimo venerdì del mese, oppure ogni 5 minuti in una finestra notturna finché il lavoro del giorno non è fatto. Uno script può avere più pianificazioni, ciascuna con il suo orario, fuso orario e argomenti.

In questa pagina usiamo la pianificazione Indicadores diários dell'app Gestione Clienti, che esegue lo script atualizar_indicadores tutti i giorni alle 7:00 (fuso Europe/Lisbon).

#Creare e aprire pianificazioni

Nell'albero laterale, espandi il nodo dello script. La riga Pianificazioni mostra quante ne esistono; sotto di essa, ogni pianificazione compare con il nome, l'orario in sintesi e, quando è spenta, la marca (disattivato).

• Per crearla: clicca sul + della riga Pianificazioni (Nuova pianificazione). Si apre l'editor in una nuova scheda.
• Per modificarla: clicca sul nome della pianificazione.
• Nel menu ⋮ di ogni pianificazione trovi Attiva/Disattiva ed Elimina. Eliminare ferma la pianificazione per sempre, ma la cronologia delle esecuzioni dello script resta.

L'editor ha il modulo a sinistra e il pannello Esecuzioni a destra (solo dopo il salvataggio — vedi la fine della pagina). In alto, l'interruttore Attivo accende e spegne la pianificazione, e Salva salva tutto.

#Scegliere la frequenza

Il campo Frequenza offre tre schede — tre nature di pianificazione:

Scheda	Serve per
Ripetere	"Ogni N minuti o ore, senza sosta." Sondaggi, sincronizzazioni continue.
In momenti precisi	"A un'ora del giorno, nei giorni che scegli." Il classico: giornaliero, settimanale, mensile.
Finestra di sorveglianza	"Sonda ogni N minuti fra due orari e si ferma quando il lavoro del giorno è fatto."

Sotto le schede, la scorciatoia Scrivere l'espressione a mano sostituisce i controlli con un campo di Espressione cron libera — per chi ne ha già una. Accetta 5 campi o 6 (con i secondi), es.: 0 9 * * 1-5. Torna ai controlli annulla lo scambio.

#Ripetere

1. Scegli la scheda Ripetere.
2. In Unità, scegli minuti o ore.
3. Con i minuti, definisci Ogni quanti minuti? (es.: 15). Con le ore, definisci Al minuto — il minuto di ogni ora in cui scatta (es.: 0 esegue alle 9:00, 10:00, 11:00…).

#In momenti precisi

1. Scegli la scheda In momenti precisi.

2. In Ripete, scegli la variante:

   Opzione	Campi che compaiono
   Tutti i giorni (nei giorni scelti)	All'ora + Giorni — sette pulsanti (Lun…Dom) con le scorciatoie Tutti, Feriali e Fine settimana. Va bene qualunque combinazione: lunedì, mercoledì e venerdì, per esempio.
   Una volta alla settimana	All'ora + Giorno della settimana.
   Una volta al mese	All'ora + Nel mese, esegue (vedi sotto).

3. Per il mensile, Nel mese, esegue ha tre forme:

   Opzione	Esempio
   In un giorno fisso	Il giorno 1, il giorno 15… Con Giorno del mese sopra il 28, l'editor avvisa: "Nei mesi senza quel giorno non viene eseguito. Per «l'ultimo giorno», usa l'opzione dedicata."
   In una posizione (es.: ultimo venerdì)	Posizione (1º, 2º, 3º, 4º, 5º o ultimo) + Giorno della settimana — es.: l'ultimo venerdì del mese.
   L'ultimo giorno del mese	31, 30, 28 o 29 — quello che il mese ha.

#Il fuso orario

Ogni pianificazione ha un Fuso orario — le ore che definisci sono ore di quel fuso, non del server. Il selettore elenca tutti i fusi IANA, con ricerca (es.: Lisbon, Sao_Paulo). Una pianificazione alle 9:00 in America/Sao_Paulo viene eseguita alle 9:00 di São Paulo, anche con il server in Europa — e i cambi dell'ora legale restano a carico della piattaforma.

#Se un'esecuzione viene persa

A volte l'ora prevista passa senza esecuzione: il server era spento, si è riavviato a metà, o l'esecuzione precedente era ancora in corso. La sezione Se un'esecuzione viene persa decide cosa fare di quelle occorrenze:

Opzione	Conseguenza
Ignora	Non recupera. Resta registrato che è andata persa (stato Persa nel pannello Esecuzioni).
Solo la più recente	Recupera l'ultima rimasta da fare; le precedenti restano registrate come perse.
Tutte	Recupera tutte quelle rimaste da fare, nell'ordine in cui erano previste.

Le esecuzioni recuperate compaiono nella cronologia dello script con l'origine Recupero.

#Finestra di sorveglianza

La terza scheda risolve uno schema che il cron classico non esprime: "a partire dalle 18:00, prova ogni 5 minuti; quando ci riesci, esegui una volta e fermati fino a domani". Tipico per aspettare che arrivi un file, che una chiusura di giornata finisca in un altro sistema, o che una tabella si riempia.

I campi:

Campo	Cosa definisce
Ogni	L'intervallo di sondaggio: 1, 2, 3, 5, 10, 15, 20 o 30 minuti.
Dalle / Alle	Gli orari in cui la finestra apre e chiude, nel fuso scelto.
Giorni	I giorni della settimana in cui la finestra esiste (gli stessi sette pulsanti e scorciatoie).
Se uno script dà errore, fermare per il resto della giornata	Acceso, un errore chiude la finestra fino al giorno dopo invece di continuare a provare.

Senza nient'altro, la finestra esegue lo script al primo scatto di ogni giorno e chiude fino al giorno dopo. Il vero potere sta nella convalida:

#Lo script di convalida

La sezione Script di convalida accetta un piccolo codice Python che decide, a ogni sondaggio, se si può già eseguire:

1. Clicca su Aggiungi convalida. Si apre un editor in una finestra.
2. Scrivi una funzione main(input) che restituisce True (pronto — il principale viene eseguito una volta e la finestra chiude fino a domani) o False (non ancora — aspetta e riprova all'intervallo successivo).
3. Usa Prova convalida per eseguirla subito, con gli argomenti della pianificazione: vedi il verdetto (Può essere eseguito (esegue 1×) o Non ancora — attende), la durata e i log.
4. Chiudi la finestra e clicca su Salva nell'editor della pianificazione.

# Restituisce True quando il file del giorno è già arrivato all'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)

La convalida viene eseguita nello stesso ambiente dello script principale: riceve lo stesso input (argomenti e contesto), e ha gli stessi file, lo stesso ambiente Python e lo stesso SDK (db, http, log, …).

#Argomenti della pianificazione

La sezione Argomenti definisce coppie nome/valore che arrivano allo script in input["args"] in tutte le esecuzioni di questa pianificazione — proprio come nell'esecuzione manuale, i valori arrivano come testo. È così che lo stesso script serve due pianificazioni diverse: un exportar giornaliero con {"ambito": "dia"} e uno mensile con {"ambito": "mes"}, per esempio.

#Salvare, attivare, seguire

• Salva crea (o aggiorna) la pianificazione. Il pulsante si attiva solo quando il nome è compilato e l'orario è valido.
• L'interruttore Attivo in alto accende e spegne senza cancellare nulla — nell'albero, una pianificazione spenta mostra (disattivato).
• Una pianificazione attiva di uno script in Bozza non viene eseguita: le occorrenze restano Saltata, con la nota "Lo script è in bozza".

#Il pannello Esecuzioni

Dopo il salvataggio, il lato destro dell'editor mostra il pannello Esecuzioni — la pianificazione vista da fuori, aggiornata in diretta:

• La prima riga dice se il motore delle pianificazioni dell'installazione è vivo ("Pianificatore attivo · ultimo controllo Ns fa"). Se non è in esecuzione, compare un avviso chiaro — gli orari previsti esistono, ma nessuno li rispetterà finché il pianificatore non parte. In quel caso, parla con chi amministra l'installazione.
• Sotto, l'elenco delle occorrenze — ogni ora prevista e il suo stato:

Stato	Significa
Da fare	Ora futura, ancora da rispettare.
In corso	L'esecuzione è in corso adesso.
Fatta	È stata eseguita.
Persa	È rimasta da eseguire e la politica è Ignora (o non era più recuperabile). Il motivo compare nella riga.
Saltata	Non è mai partita — es.: script in bozza, o sovrapposizione con l'esecuzione precedente.

In una pianificazione con convalida, cliccare su un'occorrenza apre i Tentativi della convalida: ogni sondaggio con il verdetto (pronto, non ancora o errore) e il messaggio. Le sequenze di "non ancora" compaiono ripiegate — "12 tentativi senza novità" — perché le tre righe che contano non si perdano in mezzo alle altre.

#Domande frequenti

Ho impostato il giorno 31 e ci sono mesi in cui non viene eseguito. È il comportamento di In un giorno fisso: nei mesi senza quel giorno non viene eseguito — l'editor avvisa quando scegli 29, 30 o 31. Per "la fine del mese", usa L'ultimo giorno del mese.

L'esecuzione delle 9:00 è comparsa come Saltato (sovrapposizione). L'esecuzione precedente era ancora in corso quando è arrivata la nuova ora. La piattaforma non esegue mai la stessa pianificazione due volte allo stesso tempo. Se succede spesso, allarga l'intervallo o riduci il lavoro per esecuzione.

La convalida ha restituito True ma il principale è stato eseguito una volta sola — la condizione è ancora vera. È voluto: quando la convalida restituisce True, il principale viene eseguito una volta e la finestra chiude fino al giorno dopo. Senza questo, una condizione che restasse vera metterebbe lo script a girare in ciclo fino alla fine della finestra.

È cambiata l'ora (legale/solare) — devo aggiustare le pianificazioni? No. Le ore sono interpretate nel Fuso orario della pianificazione; il cambio dell'ora è gestito dalla piattaforma.