Variables d'environnement des scripts serveur

Lorsqu'un script serveur appelle un service externe (passerelle de paiement, webhook, API tierce), il a souvent besoin d'une clé API ou d'un jeton. Écrire ce secret directement dans le code du script l'expose à toute personne pouvant ouvrir le script, l'exporter ou le lire via l'API.

La table Variables d'environnement (libellé non traduit) d'un script serveur permet de conserver ces secrets à part : chaque ligne associe une clé à une valeur, la valeur est chiffrée au repos, et le script la lit avec frappe.env.CLE.

Prérequis

• Avoir le rôle Gestionnaire de script (Script Manager) : il est obligatoire pour enregistrer un script serveur.
• Les scripts serveur doivent être activés sur le bench (bench set-config -g server_script_enabled 1).

Ajouter une variable d'environnement

1. Ouvrez le script serveur concerné (recherchez « Script Serveur (Python) » avec Ctrl+K).
2. Dans la section Variables d'environnement, ajoutez une ligne à la table :
   • Clé : le nom de la variable ;
   • Valeur : sa valeur (clé API, jeton, mot de passe, etc.).
3. Enregistrez le script serveur.

Une fois enregistrée, la valeur est chiffrée et masquée : elle n'est jamais réaffichée en clair dans le formulaire, les exports ou l'API REST. Pour la modifier, saisissez-la à nouveau dans la ligne. Supprimer une ligne, ou le script serveur lui-même, supprime la valeur chiffrée associée.

Règles de nommage des clés

Une clé doit :

• commencer par une lettre ;
• ne contenir que des lettres, des chiffres et des tirets bas (_) ;
• ne pas être un mot-clé Python (par exemple class) ;
• ne pas être un nom réservé par le bac à sable d'exécution (par exemple format, f_code, co_code, ou tout nom se terminant par __roles__) ;
• être unique dans le script.

Une clé invalide ou en doublon bloque l'enregistrement du script avec une erreur indiquant la ligne concernée.

Lire une variable dans le script

Dans le code du script serveur, lisez la valeur avec frappe.env suivi du nom de la clé :

response = frappe.make_get_request(
    "https://api.example.com/orders",
    headers={"Authorization": f"Bearer {frappe.env.API_TOKEN}"},
)

frappe.env.API_TOKEN renvoie la valeur déchiffrée de la variable API_TOKEN définie dans ce script.

La lecture fonctionne pour tous les types de scripts serveur : événement de document, événement planifié, requête de permission, API et tâche de workflow. Lorsqu'une étape d'automatisation exécute un script serveur lié, ce script s'exécute avec ses propres variables.

Si la clé n'existe pas dans le script, ou si sa valeur chiffrée est absente ou illisible, l'exécution s'interrompt avec une erreur indiquant le nom de la variable concernée.

Sécurité et limites

• Les valeurs sont chiffrées au repos et ne sont jamais affichées en clair dans le formulaire, les exports ou l'API REST.
• Tout code exécuté côté serveur peut néanmoins lire ces valeurs, comme pour n'importe quel champ de type Mot de passe. N'accordez les rôles permettant d'écrire des scripts, comme Gestionnaire de script, qu'à des utilisateurs de confiance.
• La lecture d'une valeur par get_password() sur une ligne de variable est refusée ; utilisez frappe.env.CLE dans le script.
• frappe.env n'est disponible que dans les scripts serveur. Dans les autres contextes d'exécution de code (console système, états de type Script Report, modèles Jinja, scripts inline d'étapes d'automatisation), sa lecture déclenche une erreur indiquant que les variables d'environnement ne sont disponibles que dans les scripts serveur.