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.

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 13 types de déclencheurs :

  1. SESSION_CREATED : Déclenché lors de la création d'une session
  2. SESSION_UPDATED : Déclenché lors de la mise à jour d'une session
  3. SESSION_STATUS_CHANGED : Déclenché lors du changement de statut d'une session
  4. CONTACT_CREATED : Déclenché lors de la création d'un contact
  5. CONTACT_UPDATED : Déclenché lors de la mise à jour d'un contact
  6. QUOTE_CREATED : Déclenché lors de la création d'un devis
  7. QUOTE_UPDATED : Déclenché lors de la mise à jour d'un devis
  8. QUOTE_STATUS_CHANGED : Déclenché lors du changement de statut d'un devis
  9. INVOICE_CREATED : Déclenché lors de la création d'une facture
  10. INVOICE_UPDATED : Déclenché lors de la mise à jour d'une facture
  11. INVOICE_STATUS_CHANGED : Déclenché lors du changement de statut d'une facture
  12. PAYMENT_RECEIVED : Déclenché lors de la réception d'un paiement
  13. SCHEDULED_TIME : Déclenché à une heure planifiée (cron ou relatif)

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_type": "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_type": "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_type": "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_type": "QUOTE_CREATED",
  "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.

Intégration​

Dans les services​

Les déclencheurs sont automatiquement évalués dans :

  • SessionsService : Après création et mise à jour de sessions
  • ContactsService : Après création et mise à jour de contacts (à implémenter)
  • QuotesService : Après création et mise à jour de devis (à implémenter)
  • InvoicesService : Après création et mise à jour de factures (à implémenter)

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. Workflows pour non-sessions : Seuls les workflows pour les sessions sont actuellement exécutés automatiquement. Les workflows pour contacts, devis et factures nécessitent une implémentation supplémentaire.

  2. Déclencheurs planifiés : Les déclencheurs SCHEDULED_TIME 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