Scripts serveur Python
Scripts serveur Python
Un Script Serveur (Python) est un code Python enregistré dans un document, sans application personnalisée. Dodock l'exécute sur le serveur, à un événement de document, à un appel d'API ou à une heure planifiée.
Prérequis
- Les scripts serveur sont activés sur le bench. Lancez cette commande depuis le dossier du bench :
bench set-config -g server_script_enabled 1
La commande ajoute la cléserver_script_enabledau fichiercommon_site_config.json. - Vous avez le rôle « Gestionnaire de script ».
Créer un script serveur
- Ouvrez la liste Script Serveur (Python) et cliquez sur Ajouter.
- Choisissez le « Type de script ».
- Remplissez les champs propres à ce type (voir le tableau ci-dessous).
- Écrivez le code dans le champ « Script ».
- Enregistrez.
| Type de script | Champs à remplir | Déclenchement |
|---|---|---|
« Evénement déclencheur » (DocType Event) | « Type de document de référence » et « Evénement déclencheur » | Un événement d'un document de ce type. Le document est dans la variable doc. |
| « API » | « Méthode d'API » | Un appel à /api/method/<méthode>. |
« Événement programmé » (Scheduler Event) | « Fréquence de l'événement » | Le planificateur, à la fréquence choisie (horaire, quotidienne, cron…). |
« Requête d'autorisation » (Permission Query) | « Type de document de référence » | Chaque liste de ce type. Le script renvoie une condition SQL dans la variable conditions. |
« Tâche de workflow » (Workflow Task) | Une transition de workflow. |
Événements de document
Les principaux événements sont :
| Événement | Moment |
|---|---|
| « Avant la création » | Avant le premier enregistrement du document. |
| « Avant vérification » | Avant les contrôles du document, à chaque enregistrement. |
| « Avant l'enregistrement » | Après les contrôles, avant l'écriture en base. |
| « Après l'insertion » | Après le premier enregistrement. |
| « Après l'enregistrement » | Après chaque enregistrement. |
| « Avant la validation » / « Après la validation » | Autour de la validation d'un document soumissible. |
| « Avant l'annulation » / « Après l'annulation » | Autour de l'annulation. |
| « Avant la suppression » / « Après la suppression » | Autour de la suppression. |
| « Avant le renommage » / « Après le renommage » | Autour du renommage. |
| « Avant enregistrement (Document validé) » / « Après enregistrement (Document validé) » | Modification d'un champ autorisé après validation. |
La liste contient aussi des événements de paiement (« On Payment Authorization », « On Payment Paid »…).
Scripts API
Le nom saisi dans « Méthode d'API » devient l'adresse /api/method/<méthode>. Pour un appel sans connexion, cochez « Autoriser les utilisateurs invités ». Pour limiter le nombre d'appels, cochez « Activer la limite d'usage ».
Le script place sa réponse dans frappe.response["message"].
Ce qu'un script peut utiliser
Un script serveur s'exécute dans un environnement restreint (RestrictedPython). Il n'a pas accès à import ni aux fichiers du serveur. Il peut utiliser un ensemble de fonctions de Dodock : frappe.get_doc, frappe.new_doc, frappe.get_all, frappe.get_list, frappe.db.get_value, frappe.db.count, frappe.db.exists, frappe.throw, frappe.msgprint, frappe.utils, frappe.qb, etc.
Pour la liste complète, voir Exécution sécurisée.
Exemples
Changer une valeur avant l'enregistrement
Événement : « Avant l'enregistrement » sur ToDo.
if "urgent" in (doc.description or "").lower():
doc.priority = "High"
Bloquer un enregistrement
Événement : « Avant vérification ».
if doc.description and "interdit" in doc.description:
frappe.throw("La description contient un mot interdit.")
frappe.throw affiche le message et annule l'enregistrement.
Créer une tâche après l'enregistrement
Événement : « Après l'insertion ». Le type de document de référence a un champ allocated_to (lien vers Utilisateur) et un champ subject. Ce sont des champs personnalisés de l'exemple.
if doc.allocated_to:
frappe.get_doc({
"doctype": "ToDo",
"allocated_to": doc.allocated_to,
"description": doc.subject,
"reference_type": doc.doctype,
"reference_name": doc.name,
}).insert()
Créer une API
- Type de script : « API »
- Méthode d'API :
bonjour
nom = frappe.form_dict.get("nom") or "inconnu"
frappe.response["message"] = f"Bonjour {nom}"
Appel : GET /api/method/bonjour?nom=Camille renvoie {"message": "Bonjour Camille"}.
Bloquer le coworking quand les deux salles sont réservées
Exemple fictif. Un tiers-lieu loue deux salles de réunion. Une troisième ressource, « Salle de coworking », n'est disponible que si une des deux salles est libre.
Événement : « Avant vérification » sur Resource Booking (application Bookings).
salles = ["Salle réunion 1", "Salle réunion 2"]
coworking = "Salle de coworking"
if doc.booking_resource == coworking and doc.status == "Confirmed":
salles_occupees = 0
for salle in salles:
chevauchements = frappe.db.count("Resource Booking", {
"booking_resource": salle,
"status": "Confirmed",
"starts_on": ["<", doc.ends_on],
"ends_on": [">", doc.starts_on],
})
if chevauchements:
salles_occupees += 1
if salles_occupees == len(salles):
frappe.throw("Les deux salles de réunion sont réservées sur ce créneau : le coworking n'est pas disponible.")
Le script cherche les réservations confirmées de chaque salle qui chevauchent le créneau demandé. Si les deux salles sont occupées, il refuse la réservation du coworking.