Concepts

Scripts serveur Python

Écrire un script serveur en Python déclenché par un événement de document, un appel à l'API web ou le planificateur, et l'activer sur le bench.

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_enabled au fichier common_site_config.json.
  • Vous avez le rôle « Gestionnaire de script ».

Créer un script serveur

  1. Ouvrez la liste Script Serveur (Python) et cliquez sur Ajouter.
  2. Choisissez le « Type de script ».
  3. Remplissez les champs propres à ce type (voir le tableau ci-dessous).
  4. Écrivez le code dans le champ « Script ».
  5. Enregistrez.
Type de scriptChamps à remplirDé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énementMoment
« 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.