Workflows d'approbation

À quoi ça sert

Ce module fournit un moteur d'approbation générique et configurable : au lieu d'un circuit de validation figé pour chaque fonctionnalité, un administrateur conçoit visuellement, module par module, le circuit d'étapes d'approbation applicable à un type d'objet métier (demande de congé, demande de personnel, réservation de salle, etc.).

Prérequis

Prérequis

• Modules sous licence : HR
• Permissions : config.manage
• Rôles : ORG_ADMIN, HR_MANAGER

Comment ça marche

1. Consulter les workflows existants

Ouvrez Administration → Workflows (/dashboard/admin/workflows) : la liste affiche tous les circuits configurés dans le tenant, avec le type d'entité auquel chacun s'applique et son statut actif/inactif.

2. Concevoir un nouveau circuit dans l'éditeur visuel

1. Cliquez sur Nouveau workflow, donnez-lui un nom et choisissez le type d'entité auquel il s'applique. Les types réellement déclenchés par l'application aujourd'hui sont :

   Type d'entité	Déclenché par
   LEAVE_REQUEST	Soumission d'une demande de congé
   JOB_REQUISITION	Soumission d'une demande de personnel
   OFFER_LETTER	Émission d'une lettre d'offre (si un workflow actif existe)
   EMPLOYEE_ONBOARDING	Démarrage d'un parcours d'intégration
   EMPLOYEE_OFFBOARDING	Démarrage d'un parcours de sortie
   RESOURCE_BOOKING	Réservation d'une salle/ressource nécessitant validation
   PURCHASE_REQUEST	Soumission d'une demande d'achat
   OBJECTIVE	Soumission d'un objectif proposé

2. Ouvrez l'écran de conception (/dashboard/admin/workflows/{id}/designer) : glissez-déposez des nœuds sur le canevas et reliez-les par des flèches pour représenter le circuit.

3. Trois types de nœuds sont disponibles (NodeType) :

   • Approbation (APPROVAL) : une étape où un approbateur doit valider ou rejeter.
   • Condition (CONDITION) : un embranchement selon une règle (ex. montant, département).
   • Notification (NOTIFICATION) : un point du circuit qui se contente d'informer, sans bloquer.

4. Pour chaque nœud d'approbation, choisissez le type d'approbateur (ApproverType) : DIRECT_MANAGER (le manager direct du demandeur), HR_MANAGER, DEPARTMENT_HEAD, un rôle spécifique (ROLE), ou un utilisateur nommé (SPECIFIC_USER).

5. Définissez le comportement en cas de rejet (OnRejection) : arrêter le circuit (STOP), ignorer l'étape et continuer (SKIP), ou renvoyer au demandeur pour correction (RETURN_TO_SUBMITTER).
6. L'éditeur dispose d'un historique annuler/rétablir ; enregistrez puis activez le workflow pour qu'il soit utilisé par les nouvelles instances de ce type d'entité.

3. Suivre une instance de workflow en cours

Chaque fois qu'une demande soumise déclenche un circuit configuré, une instance de workflow (WorkflowInstance) est créée et progresse étape par étape (WorkflowStepInstance). Son statut global (WorkflowStatus) évolue parmi PENDING, IN_PROGRESS, APPROVED, REJECTED, CANCELLED, RETURNED ; chaque étape individuelle a son propre statut (StepStatus) : PENDING, APPROVED, REJECTED, SKIPPED, TIMED_OUT, NOTIFIED.

4. Désactiver ou remplacer un workflow

Un workflow peut être désactivé sans être supprimé (les instances déjà en cours continuent de suivre la version de circuit qui les a créées) ; créez un nouveau workflow actif pour le même type d'entité afin de faire évoluer le circuit sans perturber les demandes déjà engagées.

Qui peut faire quoi

Permission requise	Rôles concernés
config.manage	ORG_ADMIN, HR_MANAGER

Permission	Donne accès à
config.manage	Créer, modifier, activer/désactiver et supprimer un workflow d'approbation

Rôle système	Accès
ORG_ADMIN	Toutes les actions (permission globale)
HR_MANAGER	config.manage

Approuver une étape n'exige pas config.manage

La configuration du circuit (ce document) est réservée à config.manage. Approuver une étape en tant qu'approbateur désigné (manager direct, RH, rôle ciblé…) ne nécessite pas cette permission — elle dépend du type d'approbateur défini sur l'étape, pas d'un droit de configuration global. Voir le guide correspondant à chaque module métier (ex. Congés — administration, Recrutement) pour le détail des permissions d'approbation.

Détails techniques

Entités : WorkflowDefinition (entityType est une chaîne libre, pas une énumération Java — sa valeur doit correspondre exactement à ce que le service métier concerné transmet au moteur ; config en JSONB stocke la définition des nœuds/arêtes), WorkflowStepDefinition, WorkflowStepEdge, WorkflowInstance, WorkflowStepInstance (package app.jigi.workflow.*).

Endpoints (WorkflowAdminController, base /admin/workflows, tous gated config.manage) : CRUD complet sur les définitions de workflow et leur structure de nœuds/arêtes.

Moteur : WorkflowEngine.initiateWorkflow(entityType, entityId, definitionId, initiatorId, tenantId) est appelé par chaque service métier concerné dès qu'une demande de ce type est soumise ; le moteur résout la définition active pour ce type d'entité (au niveau du tenant, ou globale à défaut), instancie le circuit, et notifie le ou les premiers approbateurs. Il bloque explicitement l'auto-approbation par le demandeur.

Anti-auto-approbation : le moteur refuse qu'un utilisateur approuve ou rejette une étape sur une instance qu'il a lui-même initiée.

Écart identifié entre l'éditeur visuel et les déclencheurs réels

L'écran de conception propose également, dans son sélecteur de type d'entité, les options PAYROLL_RUN, APPRAISAL, RECRUITMENT_OFFER et EMPLOYMENT_CONTRACT. À ce jour, aucun service métier du backend n'appelle initiateWorkflow(...) avec l'une de ces quatre valeurs : un workflow configuré sur l'un de ces types peut être créé et activé sans erreur, mais ne sera jamais déclenché automatiquement tant qu'aucun code métier ne l'invoque. Ne configurez pas de circuit sur ces types en attendant une confirmation de l'équipe produit, ou vérifiez auprès de l'équipe technique si le déclenchement a été ajouté depuis la rédaction de cette page.

Cas d'erreur et FAQ

Comment savoir quel type d'entité correspond à quel module métier ? Reportez-vous au tableau de l'étape 2 ci-dessus : chaque type d'entité correspond à un seul module (congés, recrutement, réservation, etc.), documenté dans le guide de ce module.

J'ai configuré un workflow sur APPRAISAL mais rien ne se déclenche à la soumission d'une évaluation, pourquoi ? Ce type d'entité est proposé dans l'éditeur mais n'est actuellement invoqué par aucun service métier — voir l'avertissement dans les détails techniques ci-dessus. Le sign-off des évaluations de performance utilise un mécanisme dédié (PerformanceWorkflowCallback), documenté dans Performance — administration.

Peut-on avoir plusieurs workflows actifs pour le même type d'entité ? Non, un seul workflow doit rester actif à la fois par type d'entité et par tenant — le moteur résout la définition active la plus récente au niveau du tenant, ou globale à défaut.

Que se passe-t-il si l'approbateur désigné (ex. manager direct) n'existe pas pour un demandeur donné ? Le comportement dépend de la configuration de l'étape (OnRejection ou logique de secours définie côté service métier) ; en général, il est recommandé de toujours prévoir un approbateur de repli (ex. HR_MANAGER) pour éviter qu'une instance reste bloquée sans destinataire.

Peut-on modifier un workflow déjà utilisé par des demandes en cours ? Les instances déjà créées continuent de suivre la structure du circuit telle qu'elle était au moment de leur création ; modifier ou désactiver le workflow n'affecte que les nouvelles demandes soumises après le changement.

Voir aussi

• Employés & contrats
• Utilisateurs, rôles & permissions
• Parcours Recruter
• Parcours Départ
• Guide RH