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 (2025-03-02)​

  • Événements branchés : SESSION_CREATED et SESSION_STATUS_CHANGED (depuis SessionIntegrationService), CONTACT_CREATED (depuis ContactsService après création d’un contact), QUOTE_STATUS_CHANGED (depuis QuotesInvoicesQuotesCrudService après mise à jour du statut d’un devis), INVOICE_STATUS_CHANGED et PAYMENT_RECEIVED (depuis QuotesInvoicesInvoicesCrudService après mise à jour de facture / paid_at). Exécution : seul le type d’entité SESSION exécute réellement un workflow (application à la session) ; pour CONTACT, QUOTE et INVOICE, les triggers sont évalués et enregistrés mais l’exécution est actuellement marquée SKIPPED (workflows sur entités non-session à implémenter ultérieurement). SCHEDULED et FORM_SUBMITTED ne sont pas encore évalués. Voir WORKFLOWS_ARCHITECTURE.md pour le détail.
  • 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 9 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é lors de la soumission d'un formulaire
  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.

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.

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
      }
    ]
  }
}

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.

Statut envoi SMS workflow​

  • Les taches AUTOMATIC_SMS sont executees par WorkflowTasksExecutionService via SmsService.
  • Le numero destinataire provient du contact session (ou du premier contact de session avec telephone).
  • En cas d'echec, la task est marquee FAILED avec la raison dans l'historique.
  • Resolution du message SMS (ordre actuel):
    1. template SMS utilisateur (sms_template_id)
    2. workflow_task_actions[0].config.message
    3. task.action
    4. task.description
    5. fallback systeme
  • Le contenu final SMS est rendu avec remplacement de variables (meme moteur que les templates email/contrats), puis envoye.
  • Metadonnees d'execution enregistrees dans session_workflow_task_runs.metadata:
    • provider, sms_template_id, message_source, recipient_phone, workflow_id, workflow_task_id, session_id.
  • Les templates SMS utilisateurs sont gerables via l'API et l'UI Settings > Data > SMS Templates.
  • Endpoints de creation de defaults SMS (compat):
    • POST /api/sms-templates/create-defaults (canonique)
    • POST /api/sms-templates/defaults
    • POST /api/sms-templates/defaults/create

Intégration​

Dans les services​

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

  • SessionIntegrationService (sessions) : après création et mise à jour de sessions → evaluateTriggersForEvent(SESSION_CREATED | SESSION_STATUS_CHANGED, "SESSION", ...) — exécution du workflow (application à la session) si les conditions sont remplies.
  • ContactsService : après création d’un contact → evaluateTriggersForEvent(CONTACT_CREATED, "CONTACT", ...) — évaluation et enregistrement ; exécution workflow non supportée (SKIPPED).
  • QuotesInvoicesQuotesCrudService : après mise à jour d’un devis avec changement de statut → evaluateTriggersForEvent(QUOTE_STATUS_CHANGED, "QUOTE", ...) — évaluation et enregistrement ; exécution workflow non supportée (SKIPPED).
  • QuotesInvoicesInvoicesCrudService : après mise à jour d’une facture (statut ou paid_at) → evaluateTriggersForEvent(INVOICE_STATUS_CHANGED, "INVOICE", ...) et, si paid_at est renseigné, evaluateTriggersForEvent(PAYMENT_RECEIVED, "INVOICE", ...) — évaluation et enregistrement ; exécution workflow non supportée (SKIPPED).
  • SessionClientInfoService : après enregistrement des renseignements client (putClientInfo ou putClientInfoForClient) → evaluateTriggersForEvent(SESSION_INFO_SUBMITTED, "SESSION", ...) — exécution du workflow (application à la session) si les conditions sont remplies.

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

  • Form submissions : FORM_SUBMITTED
  • Scheduler dédié : SCHEDULED (schedule_config)

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. Exécution des workflows pour non-sessions : Seuls les workflows pour les sessions sont exécutés (application du workflow à la session). Pour CONTACT, QUOTE et INVOICE, les déclencheurs sont évalués et les exécutions enregistrées (statut SKIPPED) ; l’exécution effective de workflows ciblant ces entités n’est pas encore implémentée.

  2. Déclencheurs planifiés : Les déclencheurs SCHEDULED nécessitent un scheduler dédié (à implémenter).

  3. Conditions imbriquées : Les conditions ne supportent pas encore l'imbrication (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