Aller au contenu principal

Système de Déclencheurs de Workflows

Vue d'ensemble​

Le système de déclencheurs permet d'automatiser l'exécution de workflows basés sur des événements et des conditions complexes. Les déclencheurs évaluent automatiquement les conditions lorsqu'un événement se produit (création de session, changement de statut, etc.) et exécutent le workflow associé si les conditions sont remplies.

Changelog récent (2026-08-24)​

  • Événements branchés : SESSION_*, SESSION_INFO_SUBMITTED, SURVEY_SUBMITTED, QUOTE_STATUS_CHANGED, INVOICE_STATUS_CHANGED, PAYMENT_RECEIVED, CONTACT_CREATED, FORM_SUBMITTED.
  • Exécution : SESSION (direct) + QUOTE/INVOICE (via session_id lié) + FORM_SUBMITTED (session créée depuis le lead form) régénèrent les task runs + rappels. CONTACT_CREATED et FORM_SUBMITTED sans session restent SKIPPED. SCHEDULED non évalué. Voir WORKFLOWS_ARCHITECTURE.md.
  • Réponses questionnaire : SURVEY_SUBMITTED et FORM_SUBMITTED exposent answers.<fieldId> / answers.<label_slug> pour les conditions.
  • L'endpoint de simulation workflow a été retiré de l'API (POST /workflows/:id/simulate).
  • Le champ API canonique pour les déclencheurs est trigger_event (et non trigger_type).
  • Les Session Types par defaut sont alignes sur les templates workflows v2 et lies via default_workflow_id.

Architecture​

Tables de base de données​

  • workflow_triggers : Stocke les déclencheurs avec leurs conditions
  • workflow_trigger_executions : Historique des exécutions de déclencheurs

Types de déclencheurs​

Le système supporte 10 types de déclencheurs :

  1. SESSION_CREATED : Déclenché lors de la création d'une session
  2. SESSION_STATUS_CHANGED : Déclenché lors du changement de statut d'une session
  3. CONTACT_CREATED : Déclenché lors de la création d'un contact
  4. QUOTE_STATUS_CHANGED : Déclenché lors du changement de statut d'un devis
  5. INVOICE_STATUS_CHANGED : Déclenché lors du changement de statut d'une facture
  6. PAYMENT_RECEIVED : Déclenché lors de la réception d'un paiement
  7. FORM_SUBMITTED : Déclenché à la soumission d'un lead form (lead-form.submitted). Exécuté si une session a été créée (champ DATE) et a un workflow_id.
  8. SCHEDULED : Déclenché selon une planification (schedule_config)
  9. SESSION_INFO_SUBMITTED : Déclenché lorsque le client a enregistré les renseignements de session (formulaire portail client). Permet d’enchaîner un workflow après réception des renseignements (ex. email de confirmation, tâche de suivi). Voir SESSION_INFO_RENSEIGNEMENTS.md.
  10. SURVEY_SUBMITTED : Déclenché lorsque le client soumet les réponses d'un questionnaire de séance. entityData.answers contient les résultats.

Conditions​

Structure des conditions​

Les conditions sont organisées en groupes avec un opérateur logique (AND/OR) :

{
  "operator": "AND",
  "conditions": [
    {
      "field": "status",
      "operator": "equals",
      "value": "VALIDATED"
    },
    {
      "field": "contact.email",
      "operator": "contains",
      "value": "@example.com"
    }
  ]
}

Opérateurs disponibles​

  • equals : Égalité stricte
  • contains : Contient (pour chaînes de caractères ou tableaux)
  • greater_than : Supérieur à (pour nombres)
  • less_than : Inférieur à (pour nombres)
  • in : Appartient à (pour tableaux de valeurs)
  • not_in : N'appartient pas à (pour tableaux de valeurs)
  • is_null : Est null ou undefined
  • is_not_null : N'est pas null ni undefined

Champs accessibles​

Les champs peuvent être accédés via la notation point pour les relations :

  • Sessions : id, title, status, start_date, end_date, location, contact_id, user_session_type_id, workflow_id, contact.email, etc.
  • Contacts : id, first_name, last_name, email, phone_number, city, country, etc.
  • Quotes : id, title, amount, status, session_id, contact_id, etc.
  • Invoices : id, title, amount, status, session_id, contact_id, etc.
  • Lead forms / questionnaires (FORM_SUBMITTED, SURVEY_SUBMITTED) :
    • answers.<fieldId> — valeur normalisée de la réponse
    • answers.<label_slug> — même valeur, clé = libellé slugifié (Type de séance → type_de_seance)
    • form_id, form_name, submission_id, session_id, contact_id (lead forms)
    • session_survey_id (questionnaires de séance)
    • Les objets { value: "..." } des surveys sont dépliés ; les chaînes numériques ("80") deviennent des nombres.

API​

Endpoints​

Liste des déclencheurs d'un workflow​

GET /api/workflows/:workflowId/triggers

Obtenir un déclencheur​

GET /api/workflows/:workflowId/triggers/:id

Créer un déclencheur​

POST /api/workflows/:workflowId/triggers

Body :

{
  "workflow_id": "uuid",
  "name": "Déclencheur de validation",
  "trigger_event": "SESSION_STATUS_CHANGED",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "status",
        "operator": "equals",
        "value": "VALIDATED"
      }
    ]
  },
  "is_active": true,
  "execution_order": 0
}

Mettre à jour un déclencheur​

PUT /api/workflows/:workflowId/triggers/:id

Supprimer un déclencheur​

DELETE /api/workflows/:workflowId/triggers/:id

Historique d'exécution​

GET /api/workflows/:workflowId/triggers/:id/executions?limit=50

Exemples d'utilisation​

Exemple 1 : Déclencher un workflow quand une session est validée​

{
  "name": "Workflow pour session validée",
  "trigger_event": "SESSION_STATUS_CHANGED",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "status",
        "operator": "equals",
        "value": "VALIDATED"
      }
    ]
  }
}

Exemple 2 : Déclencher un workflow pour les sessions de mariage validées​

{
  "name": "Workflow mariage validé",
  "trigger_event": "SESSION_STATUS_CHANGED",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "status",
        "operator": "equals",
        "value": "VALIDATED"
      },
      {
        "field": "user_session_type.name",
        "operator": "contains",
        "value": "Mariage"
      }
    ]
  }
}

Exemple 3 : Déclencher un workflow pour les devis supérieurs à 2000€​

{
  "name": "Workflow devis premium",
  "trigger_event": "QUOTE_STATUS_CHANGED",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amount",
        "operator": "greater_than",
        "value": 2000
      }
    ]
  }
}

Exemple 4 : Déclencher un workflow selon la réponse d'un questionnaire / lead form​

{
  "name": "Workflow mariage depuis le formulaire",
  "trigger_event": "FORM_SUBMITTED",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "answers.type_de_seance",
        "operator": "equals",
        "value": "Mariage"
      }
    ]
  }
}

Exécution​

Processus d'évaluation​

  1. Événement déclenché : Un événement se produit (création/mise à jour d'entité)
  2. Récupération des déclencheurs : Le système récupère tous les déclencheurs actifs pour ce type d'événement
  3. Évaluation des conditions : Pour chaque déclencheur, les conditions sont évaluées
  4. Exécution du workflow : Si les conditions sont remplies, le workflow associé est exécuté
  5. Enregistrement : L'exécution est enregistrée dans workflow_trigger_executions

Prévention des doublons​

Le système empêche les exécutions multiples pour le même déclencheur + entité via une contrainte unique dans la base de données.

Gestion des erreurs​

Les erreurs lors de l'évaluation ou de l'exécution sont enregistrées dans workflow_trigger_executions avec le statut FAILED et un message d'erreur.

SMS (supprimé)​

Les tâches AUTOMATIC_SMS / SEND_SMS, les templates SMS (sms-templates) et l'envoi Twilio/Vonage ont été supprimés le 2026-09-06 (code, OpenAPI et tables : Liquibase 0279-0281). Voir APP_CLEANUP_MAP.md, Vague E.

Intégration​

Dans les services​

Les déclencheurs sont évalués aux points suivants :

  • SessionIntegrationService (sessions) : après création et mise à jour → exécution sur la session.
  • ContactsService : CONTACT_CREATED — évaluation ; exécution encore SKIPPED.
  • QuotesInvoicesQuotesCrudService : QUOTE_STATUS_CHANGED — exécution via quote.session_id (régénère task runs + rappels de la session liée).
  • QuotesInvoicesInvoicesCrudService : INVOICE_STATUS_CHANGED / PAYMENT_RECEIVED — exécution via invoice.session_id.
  • SessionClientInfoService : SESSION_INFO_SUBMITTED — exécution sur la session.
  • FormSubmittedWorkflowTriggerHandler : FORM_SUBMITTED après soumission lead form. Si une session est créée (champ DATE), lead_forms.workflow_id est passé à sessions.create ; l'exécution régénère les task runs de cette session. Conditions sur answers.*. Sans session → SKIPPED.
  • SurveySubmittedWorkflowTriggerHandler : SURVEY_SUBMITTED — exécution sur la session ; conditions sur answers.*.

À implémenter (évaluation + exécution) :

  • Scheduler dédié : SCHEDULED (schedule_config)
  • CONTACT_CREATED : cible session (ou autre) à définir

Exemple d'intégration​

// Dans SessionsService
const triggersService = this.getWorkflowTriggersService();
if (triggersService) {
  triggersService
    .evaluateTriggersForEvent(
      "SESSION_CREATED",
      "SESSION",
      session.id,
      entityData,
      ownerId
    )
    .catch((error) => {
      // Gestion d'erreur
    });
}

Limitations actuelles​

  1. CONTACT_CREATED : évalué puis SKIPPED (pas de cible session unique).
  2. QUOTE/INVOICE sans session_id (ou session sans workflow_id) : SKIPPED.
  3. FORM_SUBMITTED sans session (pas de champ DATE, ou création de session échouée) : évalué puis SKIPPED. lead_forms.workflow_id ne peut pas s'attacher sans session.
  4. Déclencheurs planifiés : SCHEDULED nécessite un scheduler dédié (à implémenter).
  5. Conditions imbriquées : pas de groupes de groupes.

Améliorations futures​

  1. Éditeur visuel : Interface drag & drop pour créer des déclencheurs
  2. Conditions imbriquées : Support de groupes de conditions complexes
  3. Déclencheurs planifiés : Scheduler pour les déclencheurs basés sur le temps
  4. Webhooks : Intégration avec des services externes
  5. Tests de conditions : Interface pour tester les conditions avant de les sauvegarder
  6. CONTACT_CREATED : définir la cible d’exécution hors session directe