Configurer une application via son propre assistant

Une application peut remplacer l'assistant de configuration du bureau par sa propre interface. Sur un site neuf, le bureau redirige alors l'utilisateur vers cette interface. L'application termine ensuite la configuration par un appel à complete_app_setup.

Prérequis

• Une application avec un fichier hooks.py.
• Une page de l'application servie hors du bureau (pas sous /app/ ni /desk/), par exemple une page Vue sous /suite/setup.
• Un utilisateur avec le rôle System Manager pour terminer la configuration.
• Aucune application active ne déclare setup_wizard_stages ni setup_wizard_complete (voir la section « Choix de l’assistant »).

1. Déclarer le hook setup_wizard_url

Le hook est une chaîne (une route), pas une fonction :

# hooks.py
setup_wizard_url = "/suite/setup"

Le modèle d'application généré par bench new-app contient cette ligne en commentaire.

2. Choix de l'assistant

frappe.desk.page.setup_wizard.setup_wizard.get_setup_wizard_url() choisit la route. Le résultat est placé dans frappe.boot.setup_wizard_url.

Tant que la configuration n'est pas terminée, le routeur du bureau redirige vers setup_wizard_url avec window.location.replace. Une route qui commence par /app/ ou /desk/ ne déclenche pas cette redirection : le bureau ouvre alors son propre assistant.

      
flowchart TD
    A[Site non configuré] --> B{Une application active déclare
    

3. Terminer la configuration avec complete_app_setup

POST /api/method/frappe.desk.page.setup_wizard.setup_wizard.complete_app_setup

La méthode exécute le moteur de configuration (process_setup_stages) sans les étapes de saisie du bureau : enregistrement de la langue et de la région, puis les étapes de fin.

Tous les paramètres sont facultatifs. La méthode n'accepte pas d'autres arguments : créez l'entreprise, les utilisateurs ou les autres données de l'application avec vos propres méthodes.

Comportement :

• La méthode accepte uniquement POST et exige le rôle System Manager (frappe.only_for).
• Si le site exige l'assistant du bureau, elle lève l'erreur « This site's setup must run through the built-in wizard. ».
• Si la configuration est déjà terminée, elle retourne {"status": "ok"} sans rien refaire. Un deuxième appel est donc sans effet.
• Si une autre configuration est en cours, elle lève l'erreur « Setup is already in progress. Please try again in a moment. ».

Exemple

Depuis une application Vue avec frappe-ui :

import { createResource } from "frappe-ui";

const completeSetup = createResource({
    url: "frappe.desk.page.setup_wizard.setup_wizard.complete_app_setup",
    method: "POST",
    onSuccess() {
        window.location.href = "/suite";
    },
});

completeSetup.submit({
    country: "France",
    currency: "EUR",
    timezone: "Europe/Paris",
    language: "fr",
});

Dépannage