Planifications

Une planification (cron) fait tourner un script tout seul : tous les jours à 7h00, toutes les 15 minutes, le dernier vendredi du mois, ou toutes les 5 minutes dans une fenêtre nocturne jusqu'à ce que le travail du jour soit fait. Un script peut avoir plusieurs planifications, chacune avec son horaire, son fuseau horaire et ses arguments.

Sur cette page, nous utilisons la planification Indicadores diários de l'app Gestion des Clients, qui exécute le script atualizar_indicadores tous les jours à 7h00 (fuseau Europe/Lisbon).

#Créer et ouvrir des planifications

Dans l'arborescence latérale, déployez le nœud du script. La ligne Planifications indique combien il en existe ; en dessous, chaque planification apparaît avec son nom, son horaire résumé et, quand elle est éteinte, la marque (désactivé).

• Pour créer : cliquez sur le + de la ligne Planifications (Nouvelle planification). L'éditeur s'ouvre dans un nouvel onglet.
• Pour modifier : cliquez sur le nom de la planification.
• Dans le menu ⋮ de chaque planification, vous avez Activer/Désactiver et Supprimer. Supprimer arrête la planification pour de bon, mais l'historique des exécutions du script est conservé.

L'éditeur a le formulaire à gauche et le panneau Exécutions à droite (seulement une fois enregistré — voir la fin de la page). En haut, l'interrupteur Actif allume et éteint la planification, et Enregistrer enregistre le tout.

#Choisir la fréquence

Le champ Fréquence propose trois cartes — trois natures de planification :

Carte	Sert à
Répéter	« Toutes les N minutes ou heures, sans interruption. » Sondages, synchronisations continues.
À des moments précis	« À une heure du jour, les jours que vous choisissez. » Le classique : quotidien, hebdomadaire, mensuel.
Fenêtre de surveillance	« Sonde toutes les N minutes entre deux heures et s'arrête quand le travail du jour est fait. »

Sous les cartes, le raccourci Écrire l'expression à la main remplace les contrôles par un champ d'Expression cron libre — pour ceux qui en ont déjà une. Il accepte 5 champs ou 6 (avec les secondes), ex. : 0 9 * * 1-5. Retour aux contrôles défait l'échange.

#Répéter

1. Choisissez la carte Répéter.
2. Dans Unité, choisissez minutes ou heures.
3. Avec les minutes, définissez Toutes les combien de minutes ? (ex. : 15). Avec les heures, définissez À la minute — la minute de chaque heure à laquelle elle se déclenche (ex. : 0 s'exécute à 9h00, 10h00, 11h00…).

#À des moments précis

1. Choisissez la carte À des moments précis.

2. Dans Répète, choisissez la variante :

   Option	Champs qui apparaissent
   Tous les jours (les jours choisis)	À l'heure + Jours — sept boutons (Lun…Dim) avec les raccourcis Tous, Ouvrés et Week-end. N'importe quelle combinaison convient : lundi, mercredi et vendredi, par exemple.
   Une fois par semaine	À l'heure + Jour de la semaine.
   Une fois par mois	À l'heure + Dans le mois, s'exécute (voir ci-dessous).

3. Pour le mensuel, Dans le mois, s'exécute a trois formes :

   Option	Exemple
   Un jour fixe	Le 1, le 15… Avec un Jour du mois au-dessus de 28, l'éditeur prévient : « Dans les mois sans ce jour, rien ne s'exécute. Pour « le dernier jour », utilisez l'option dédiée. »
   À une position (ex. : dernier vendredi)	Position (1re, 2e, 3e, 4e, 5e ou dernière) + Jour de la semaine — ex. : le dernier vendredi du mois.
   Le dernier jour du mois	31, 30, 28 ou 29 — ce que le mois a.

#Le fuseau horaire

Toute planification a un Fuseau horaire — les heures que vous définissez sont des heures de ce fuseau, pas de celui du serveur. Le sélecteur liste tous les fuseaux IANA, avec une recherche (ex. : Lisbon, Sao_Paulo). Une planification à 9h00 en America/Sao_Paulo s'exécute à 9h00 de São Paulo, même avec le serveur en Europe — et les changements d'heure d'été sont à la charge de la plateforme.

#Si une exécution est manquée

Parfois l'heure prévue passe sans exécution : le serveur était éteint, il a redémarré en pleine exécution, ou l'exécution précédente était encore en cours. La section Si une exécution est manquée décide quoi faire de ces occurrences :

Option	Conséquence
Ignorer	Ne récupère rien. L'exécution manquée reste enregistrée (état Manquée dans le panneau Exécutions).
Seulement la plus récente	Récupère la dernière exécution manquée ; les précédentes sont enregistrées comme manquées.
Toutes	Récupère toutes les exécutions manquées, dans l'ordre où elles étaient prévues.

Les exécutions rattrapées apparaissent dans l'historique du script avec la source Rattrapage.

#Fenêtre de surveillance

La troisième carte résout un motif que le cron classique n'exprime pas : « à partir de 18h00, essaie toutes les 5 minutes ; quand tu y arrives, exécute une fois et arrête-toi jusqu'à demain ». Typique pour attendre qu'un fichier arrive, qu'une clôture de journée se termine dans un autre système, ou qu'une table soit remplie.

Les champs :

Champ	Ce qu'il définit
Toutes les	L'intervalle de sondage : 1, 2, 3, 5, 10, 15, 20 ou 30 minutes.
De / À	Les heures auxquelles la fenêtre ouvre et ferme, dans le fuseau choisi.
Jours	Les jours de la semaine où la fenêtre existe (les mêmes sept boutons et raccourcis).
Si un script échoue, arrêter pour le reste de la journée	Activé, une erreur ferme la fenêtre jusqu'au lendemain au lieu de continuer d'essayer.

Sans rien de plus, la fenêtre exécute le script au premier déclenchement de chaque jour et ferme jusqu'au lendemain. La vraie puissance est dans la validation :

#Le script de validation

La section Script de validation accepte un petit bout de code Python qui décide, à chaque sondage, si l'on peut déjà exécuter :

1. Cliquez sur Ajouter une validation. Un éditeur s'ouvre dans une fenêtre.
2. Écrivez une fonction main(input) qui renvoie True (prêt — le principal s'exécute une fois et la fenêtre ferme jusqu'à demain) ou False (pas encore — il attend et réessaie à l'intervalle suivant).
3. Utilisez Tester la validation pour l'exécuter tout de suite, avec les arguments de la planification : vous voyez le verdict (Peut s'exécuter (s'exécute 1×) ou Pas encore — en attente), la durée et les logs.
4. Fermez la fenêtre et cliquez sur Enregistrer dans l'éditeur de la planification.

# Renvoie True quand le fichier du jour est arrivé sur le FTP interne.
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 validation s'exécute dans le même environnement que le script principal : elle reçoit le même input (arguments et contexte), et dispose des mêmes fichiers, du même environnement Python et du même SDK (db, http, log, …).

#Arguments de la planification

La section Arguments définit des paires nom/valeur qui arrivent au script dans input["args"] à toutes les exécutions de cette planification — comme dans l'exécution manuelle, les valeurs arrivent sous forme de texte. C'est ainsi qu'un même script sert deux planifications différentes : un exportar quotidien avec {"ambito": "dia"} et un mensuel avec {"ambito": "mes"}, par exemple.

#Enregistrer, activer, suivre

• Enregistrer crée (ou met à jour) la planification. Le bouton ne s'active que lorsque le nom est rempli et l'horaire valide.
• L'interrupteur Actif en haut allume et éteint sans rien supprimer — dans l'arborescence, une planification éteinte affiche (désactivé).
• Une planification active d'un script en Brouillon ne s'exécute pas : les occurrences restent Ignorée, avec la note « Le script est en brouillon ».

#Le panneau Exécutions

Une fois enregistrée, le côté droit de l'éditeur montre le panneau Exécutions — la planification vue de l'extérieur, mise à jour en direct :

• La première ligne dit si le moteur de planifications de l'installation est vivant (« Planificateur actif · dernière vérification il y a Ns »). S'il ne tourne pas, un avertissement clair apparaît — les heures prévues existent, mais personne ne les respectera tant que le planificateur n'aura pas démarré. Dans ce cas, parlez-en à qui administre l'installation.
• En dessous, la liste des occurrences — chaque heure prévue et son état :

État	Signifie
En attente	Heure future, encore à honorer.
En cours	L'exécution est en train de se dérouler.
Effectuée	Elle a tourné.
Manquée	Elle est restée en plan et la politique est Ignorer (ou elle n'était déjà plus rattrapable). Le motif apparaît sur la ligne.
Ignorée	Elle n'a jamais démarré — ex. : script en brouillon, ou chevauchement avec l'exécution précédente.

Dans une planification avec validation, cliquer sur une occurrence ouvre les Tentatives de la validation : chaque sondage avec son verdict (prêt, pas encore ou erreur) et son message. Les séries de « pas encore » apparaissent repliées — « 12 tentatives sans rien de nouveau » — pour que les trois lignes qui comptent ne se perdent pas au milieu.

#Questions fréquentes

J'ai programmé le 31 et il y a des mois où rien ne s'exécute. C'est le comportement d'Un jour fixe : dans les mois sans ce jour, rien ne s'exécute — l'éditeur prévient quand vous choisissez 29, 30 ou 31. Pour « la fin du mois », utilisez Le dernier jour du mois.

L'exécution de 9h00 est apparue comme Ignoré (chevauchement). L'exécution précédente était encore en cours quand la nouvelle heure est arrivée. La plateforme n'exécute jamais la même planification deux fois en même temps. Si cela arrive souvent, élargissez l'intervalle ou réduisez le travail par exécution.

La validation a renvoyé True mais le principal n'a tourné qu'une fois — la condition reste vraie. C'est fait exprès : quand la validation renvoie True, le principal s'exécute une fois et la fenêtre ferme jusqu'au lendemain. Sans cela, une condition qui resterait vraie mettrait le script à tourner en boucle jusqu'à la fin de la fenêtre.

L'heure a changé (été/hiver) — dois-je ajuster les planifications ? Non. Les heures sont interprétées dans le Fuseau horaire de la planification ; le changement d'heure est pris en charge par la plateforme.