Tâches en arrière-plan

Dokos permet d'exécuter des traitements longs (imports, exports, calculs, etc.) en arrière-plan sans bloquer votre navigation. Grâce aux files d'attente de tâches visibles par l'utilisateur, vous pouvez suivre la progression de ces traitements en temps réel, les annuler si nécessaire, et les relancer en cas d'échec — le tout depuis l'interface.

Pourquoi des tâches en arrière-plan ?

Certaines opérations peuvent prendre plusieurs secondes, voire plusieurs minutes : importation de milliers de lignes, génération de rapports complexes, synchronisation de données, etc. Plutôt que de bloquer votre navigateur le temps du traitement, Dokos délègue ces opérations à une file d'attente et vous notifie de leur avancement.

      
flowchart LR
    A[Utilisateur déclenche une action] --> B[Tâche mise en file d'attente]
    B --> C{Serveur disponible ?}
    C -- Oui --> D[Traitement en cours]
    C -- Non --> B
    D --> E{Résultat}
    E -- Succès --> F[Tâche terminée ✓]
    E -- Échec --> G[Tâche en erreur ✗]
    G --> H[Relance manuelle possible]
    H --> B

    

Suivre vos tâches depuis la barre latérale

Un bouton dédié apparaît dans la barre latérale de Dokos dès qu'une tâche est en cours d'exécution. Il vous donne accès à la liste de toutes vos tâches actives et récentes.

Pour chaque tâche, vous pouvez voir :

• Le nom de la tâche (ex. : « Importation des articles »)
• Son statut : En attente, En cours, Terminé, Annulé, Échec
• La progression en pourcentage (si le développeur a activé cette option)
• L'étape actuelle du traitement (ex. : « Traitement de l'article 150 sur 500 »)

Consulter le détail d'une tâche

Cliquez sur une tâche pour accéder à sa fiche détaillée. Vous y trouverez :

Annuler une tâche

Vous pouvez annuler une tâche qui est en attente ou en cours d'exécution, à condition que le traitement le permette.

• Les tâches en attente sont toujours annulables.
• Les tâches en cours sont annulables uniquement si le développeur a activé cette option (allow_user_cancellation=True).

Pour annuler : ouvrez la fiche de la tâche et cliquez sur le bouton Annuler.

Relancer une tâche en échec

Si une tâche a échoué (par exemple suite à une erreur réseau ou une indisponibilité temporaire), vous pouvez la relancer manuellement depuis sa fiche, via le bouton Réessayer.

Cette option est disponible pour les tâches dont le statut est Échec ou Annulé.

Nettoyage automatique

Les tâches terminées (succès, échec ou annulation) sont automatiquement supprimées après 7 jours. Les fichiers générés par ces tâches sont également nettoyés en même temps.

Pour les développeurs : créer une tâche en arrière-plan

La fonction frappe.enqueue_task permet de lancer n'importe quelle fonction Python en arrière-plan avec un suivi visible par l'utilisateur.

Exemple de base

def traiter_articles(data):
    task = frappe.get_current_task()
    for i, article in enumerate(data):
        # Votre logique de traitement
        traiter(article)

        # Publier la progression tous les 50 éléments
        if i % 50 == 0:
            task.publish_progress(
                percent=(i + 1) / len(data) * 100,
                stage=f"Traitement de l'article {i + 1} sur {len(data)}"
            )

    task.store_result({"articles_traites": len(data)})


frappe.enqueue_task(
    traiter_articles,
    data=liste_articles,
    task_name="Importation des articles",
    queue="long"
)

Paramètres de enqueue_task

Méthodes disponibles dans la tâche

frappe.get_current_task()

Retourne l'objet BackgroundTask courant depuis l'intérieur de la fonction en cours d'exécution.

task.publish_progress(percent, stage)

Publie la progression vers l'interface en temps réel.

task.publish_progress(
    percent=42.5,
    stage="Calcul des totaux"
)

• percent : nombre entre 0 et 100
• stage : texte libre décrivant l'étape en cours (affiché à l'utilisateur)

task.store_result(data)

Sauvegarde le résultat de la tâche, accessible depuis la fiche de la tâche une fois celle-ci terminée.

task.store_result({
    "lignes_importees": 1250,
    "lignes_ignorees": 3
})

Callbacks on_success et on_failure

Vous pouvez définir des fonctions à exécuter automatiquement selon le résultat de la tâche :

def apres_succes(task):
    frappe.sendmail(
        recipients=["gestionnaire@maissonverte.fr"],
        subject="Import terminé",
        message=f"La tâche '{task.task_name}' s'est terminée avec succès."
    )

def apres_echec(task):
    frappe.log_error(title="Échec de l'import", message=task.exception)


frappe.enqueue_task(
    traiter_articles,
    data=liste_articles,
    task_name="Import articles Maison Verte SARL",
    on_success=apres_succes,
    on_failure=apres_echec,
)

Permettre l'annulation pendant l'exécution

Par défaut, seules les tâches en attente peuvent être annulées par l'utilisateur. Pour permettre l'annulation d'une tâche en cours d'exécution, activez allow_user_cancellation :

frappe.enqueue_task(
    traiter_articles,
    data=liste_articles,
    task_name="Import long",
    allow_user_cancellation=True,
)

Joindre des fichiers au résultat

Une tâche peut générer un fichier (export CSV, rapport PDF, etc.) et le joindre automatiquement à sa fiche pour que l'utilisateur puisse le télécharger :

def exporter_clients(filtres):
    task = frappe.get_current_task()
    # ... génération du fichier ...
    contenu_csv = generer_csv(filtres)

    # Attacher le fichier à la tâche
    task.attach_file(
        filename="export_clients.csv",
        content=contenu_csv,
        content_type="text/csv"
    )

Le fichier apparaîtra dans la section Fichiers joints de la fiche de tâche, téléchargeable par l'utilisateur.

Exécution synchrone pour les tests

Pendant le développement ou les tests, vous pouvez forcer l'exécution immédiate (sans file d'attente) avec now=True :

frappe.enqueue_task(
    traiter_articles,
    data=liste_test,
    task_name="Test import",
    now=True  # Exécution synchrone
)

Reprise automatique sur certaines exceptions

Il est possible de configurer une reprise automatique de la tâche lorsqu'une exception spécifique se produit (par exemple, une erreur réseau transitoire). Cette fonctionnalité est configurée au niveau du backend et permet d'éviter des relances manuelles pour des erreurs connues et récupérables.

Permissions

Cas d'usage courants

Import de données volumineuses

Lors d'un import de milliers d'articles ou de contacts, la tâche s'exécute en arrière-plan pendant que vous continuez à travailler. La barre de progression vous indique l'avancement, et un fichier de résultat peut être généré automatiquement.

Génération de rapports préparés

Les rapports préparés (rapports longs mis en cache) utilisent maintenant ce système de tâches. Vous pouvez suivre leur génération depuis la barre latérale et consulter le rapport dès qu'il est prêt.

Synchronisation avec des services externes

Si votre instance Dokos est connectée à un service tiers (ex. : synchronisation avec Bureau Moderne via une API), les synchronisations longues peuvent être déléguées à une tâche en arrière-plan avec notification de succès ou d'échec par email.