Dolibarr ERP CRM Wiki

Système de Triggers


Retour index
Documentation développeur

File Doc dev.png

Ajouter son code sur un événement métier

Pour permettre de déclencher du code personnalisé en réaction à un événement Dolibarr (création/modification/suppression d'une société/facture/produit/utilisateur ou autre), Dolibarr propose un mécanisme de triggers métiers. Ce mécanisme vous permet de personnaliser un workflow afin que les événements de gestion Dolibarr soient répercutés dans une autre application par exemple. Rien n'empêche également de l'utiliser pour modifier le comportement de Dolibarr même: par exemple, pour que la validation d'une facture provoque la création d'un contrat automatiquement.

Notez que les Triggers sont une fonctionnalité pour les développeurs, qui est limitée:

  • aux événements métiers CRUD (Créer | Mettre à jour (Update) | Supprimer (Delete)).
  • ou au changement du statut principal d'un objet.

Pour les autres cas, il existe une autre fonctionnalité permettant aux développeurs d'injecter du code personnalisé dans une application appelée le Système de Hooks. Note: Historiquement, l'envoi d'un email génère aussi un appel trigger bien que ne rentrant pas dans le cadre des 2 cas précédents autorisés.


Donc, pour ajouter son propre code qui sera déclenché par trigger, la procédure est la suivante:

1) Copier le fichier modèle htdocs/modulebuilder/template/core/triggers/interface_99_modMyModule_MyModuleTriggers.class.php sous le nom:

  • interface_99_all_Xxx.class.php

ou bien

  • interface_99_modMonModule_Xxx.class.php

où Xxx est une chaîne de votre choix commençant par une majuscule, 99 est le numéro de priorité du trigger (01 étant le plus prioritaire), MonModule est le nom du module si votre trigger ne doit être activé que si le module MonModule est actif. Si on désire que le trigger soit toujours actif, on mettra all à la place de modMonModule. Il faut laisser ce nouveau fichier dans le même répertoire. Rem: Les valeurs utilisables pour modMonModule sont visibles dans le répertoire htdocs/core/modules. ATTENTION: Tous ces paramètres sont nécessaires pour que le trigger soit détecté! Ex: si vous oubliez le numéro de priorité, le module ne sera pas detecté!

Par exemple, on pourra nommer notre nouveau trigger: htdocs/core/triggers/interface_99_modFacture_Monworkflow.class.php

En créant un fichier nommé comme dans cet exemple, notre nouveau trigger sera déclenché à chaque événement métier Dolibarr et à condition que le module Facture soit actif.

Note: Il est aussi possible de placer les fichiers triggers dans un sous-dossier d'un module externe. Ex: si le module réside dans htdocs/custom/mymodule/, alors il est possible de placer les triggers dans htdocs/custom/mymodule/core/triggers/. Mais dans ce cas, le trigger ne sera trouvé que si vous le déclarer dans le fichier descripteur de votre module. Pour cela, ajouter triggers->1 dans le tableau module_parts (ex: /monmodule/core/modules/modMonModule.class.php): 

// Defined all module parts (triggers, login, substitutions, menus, etc...) (0=disable,1=enable)
   $this->module_parts = array('triggers' => 1);
   //$this->module_parts = array('triggers' => 1,
   //              'login' => 0,
   //              'substitutions' => 0,
   //              'menus' => 0);

Puis désactiver et réactiver le module. Ceci aura pour effet d'ajouter une ligne dans la Table llx_const pour indiquer à Dolibarr qu'il faut aussi rechercher les triggers dans le répertoire de votre module htdocs/monmodule/core/triggers.


2) Editer ce fichier interface_99_modMyModule_MyModuleTriggers.class.php afin de renommer la classe InterfaceMyModuleTriggers par InterfaceMonworkflow

Ensuite, accéder à la page Accueil-> Infos Systèmes -> Dolibarr -> Triggers. Votre fichier trigger doit apparaître dans la liste sans erreur indiquant que les opérations précédentes ont été réalisées avec succès.


3) Revenez maintenant à l'édition du fichier trigger afin d'ajouter votre code dans la fonction runTrigger. Cette fonction est appelée à chaque événement Dolibarr. Placer votre code en fonction du ou des événements sur lesquels vous voulez réagir, chaque événement étant identifié par un code (voir chapitres suivant pour la liste des codes), on peut réagir ou non à un événement donné par un test sur la variable $action: 

public function runtrigger($action,$object,$user,$langs,$conf)
{
      // Mettre ici le code à exécuter en réaction de l'action
      // Le type de l'évènement Dolibarr est stocké dans $action
      // Les données de l'action sont stockées dans $object
      // La configuration, utilisateur et langage sont dans $conf,$user et $lang
      if ($action == 'COMPANY_CREATE')
      {
          dol_syslog("Trigger for action '$action' launched. id=".$object->id);
      }
      elseif ($action == 'COMPANY_MODIFY')
      {        
          dol_syslog("Trigger for action '$action' launched. id=".$object->id);
      }
      elseif ($action == 'COMPANY_DELETE')
      ...
}

Vous pouvez faire ce que vous voulez dans cette portion de code du moment que la fonction runTrigger renvoie un code retour sur le principe suivant:

<0 si ko, 0 si aucune action faite, >0 si ok

Vous pouvez de plus dans cette fonction utiliser les objets suivant:

  • $object est l'objet sur lequel porte l'action (voir chapitre suivant)
  • $user est l'objet de l'utilisateur Dolibarr qui réalise l'action
  • $langs est l'objet qui contient la langue de l'utilisateur Dolibarr
  • $conf est l'objet qui contient toute la configuration de Dolibarr.


4) Une fois le code réalisé, il n'y a plus qu'à tester, en provoquant l’événement déclencheur dans Dolibarr. Attention, l'appel au runTrigger et encapsuler dans un transaction. Si votre trigger renvoie un code ko, la fonction appelante peut annuler la transaction (ceci dépend de la fonction appelante). Ajouter des traces dans un fichier dans la fonction runTrigger afin de vous assurer que le code s'exécute bien. Vous pouvez pour cela si vous le désirer, utiliser la fonction dol_syslog("mon texte de trace", LOG_DEBUG);

Liste des événements gérés

Voici un vue rapide des événements qui provoquent une recherche et exécution de triggers. Un événement est caractérisés par la valeur du code $action, avec le type de l'objet reçu dans $object.

Remarque: Le Module Agenda et le Module Notification utilise la table Table llx c action trigger comme liste de triggers connus. Cela évite de scanner le disque pour avoir cette information mais cette table ne contient qu'une liste très limité des triggers.

En général, le code action de trigger commence par le nom du module suivi du caractère _.

Trigger code ($action) Type object ($object)
USER_CREATE user.class.php
USER_MODIFY user.class.php
USER_DELETE user.class.php
USER_LOGIN user.class.php
USER_LOGIN_FAILED user.class.php
USER_LOGOUT user.class.php
USER_ENABLEDISABLE user.class.php
USER_NEW_PASSWORD user.class.php
USER_SETINGROUP user.class.php
USER_REMOVEFROMGROUP user.class.php
USERGROUP_CREATE (>= 12.0.0) usergroup.class.php
USERGROUP_MODIFY(>= 12.0.0) usergroup.class.php
USERGROUP_DELETE(>= 12.0.0) usergroup.class.php
GROUP_CREATE usergroup.class.php
GROUP_MODIFY usergroup.class.php
GROUP_DELETE (>= 3.3.0) usergroup.class.php
COMPANY_CREATE societe.class.php
COMPANY_MODIFY societe.class.php
COMPANY_DELETE societe.class.php
COMPANY_SENTBYMAIL (>= 3.5.0) societe.class.php
CONTACT_CREATE contact.class.php
CONTACT_MODIFY contact.class.php
CONTACT_DELETE contact.class.php
CONTACT_ENABLEDISABLE (>= 3.5.0) contact.class.php
PRODUCT_CREATE product.class.php
PRODUCT_MODIFY product.class.php
PRODUCT_PRICE_MODIFY product.class.php
PRODUCT_DELETE product.class.php
SUPPLIER_PRODUCT_BUYPRICE_MODIFY fournisseur.product.class.php
SUPPLIER_PRODUCT_BUYPRICE_CREATE fournisseur.product.class.php
ORDER_CREATE commande.class.php
ORDER_VALIDATE commande.class.php
ORDER_SENTBYMAIL commande.class.php
ORDER_DELETE commande.class.php
ORDER_MODIFY commande.class.php
ORDER_CLASSIFY_BILLED commande.class.php
ORDER_CLONE commande.class.php
ORDER_CLOSE commande.class.php
ORDER_CANCEL commande.class.php
ORDER_REOPEN (>= 3.3.0) commande.class.php
ORDER_UNVALIDATE commande.class.php
COMMANDE_ADD_CONTACT commande.class.php
COMMANDE_DELETE_CONTACT commande.class.php
COMMANDE_DELETE_RESOURCE (>= 3.6.0) commande.class.php
LINEORDER_INSERT commande.class.php
LINEORDER_UPDATE commande.class.php
LINEORDER_DELETE commande.class.php
LINEORDER_DISPATCH (>= 3.4.0) commande.class.php
ORDER_SUPPLIER_CREATE fournisseur.commande.class.php
ORDER_SUPPLIER_CLONE fournisseur.commande.class.php
ORDER_SUPPLIER_VALIDATE fournisseur.commande.class.php
ORDER_SUPPLIER_SENTBYMAIL fournisseur.commande.class.php
ORDER_SUPPLIER_APPROVE fournisseur.commande.class.php
ORDER_SUPPLIER_REFUSE fournisseur.commande.class.php
ORDER_SUPPLIER_CANCEL fournisseur.commande.class.php
ORDER_SUPPLIER_DELETE fournisseur.commande.class.php
ORDER_SUPPLIER_DISPATCH (>= 3.4.0) fournisseur.commande.class.php
ORDER_SUPPLIER_ADD_CONTACT fournisseur.commande.class.php
ORDER_SUPPLIER_DELETE_CONTACT fournisseur.commande.class.php
ORDER_SUPPLIER_DELETE_RESOURCE (>= 3.6.0) fournisseur.commande.class.php
LINEORDER_SUPPLIER_CREATE fournisseur.commande.class.php
LINEORDER_SUPPLIER_UPDATE fournisseur.commande.class.php
LINEORDER_SUPPLIER_DELETE (>= 3.6.0) fournisseur.commande.class.php
PROPAL_CREATE propal.class.php
PROPAL_DELETE propal.class.php
PROPAL_CLONE propal.class.php
PROPAL_REOPEN (>= 3.5.0) propal.class.php
PROPAL_VALIDATE propal.class.php
PROPAL_CLOSE_SIGNED propal.class.php
PROPAL_CLOSE_REFUSED propal.class.php
PROPAL_SENTBYMAIL propal.class.php
PROPAL_MODIFY propal.class.php
PROPAL_ADD_CONTACT propal.class.php
PROPAL_DELETE_CONTACT propal.class.php
PROPAL_DELETE_RESOURCE (>= 3.6.0) propal.class.php
LINEPROPAL_INSERT propal.class.php
LINEPROPAL_UPDATE propal.class.php
LINEPROPAL_DELETE propal.class.php
CONTRACT_CREATE contrat.class.php
CONTRACT_VALIDATE contrat.class.php
CONTRACT_SERVICE_ACTIVATE contrat.class.php
CONTRACT_SERVICE_CLOSE contrat.class.php
CONTRACT_DELETE contrat.class.php
CONTRAT_ADD_CONTACT contrat.class.php
CONTRAT_DELETE_CONTACT contrat.class.php
CONTRAT_DELETE_RESOURCE (>= 3.6.0) contrat.class.php
LINECONTRACT_INSERT contrat.class.php
LINECONTRACT_MODIFY contrat.class.php
LINECONTRACT_DELETE contrat.class.php
BILL_CREATE facture.class.php
BILL_MODIFY facture.class.php
BILL_CLONE facture.class.php
BILL_VALIDATE facture.class.php
BILL_UNVALIDATE (>= 3.4.0) facture.class.php
BILL_PAYED facture.class.php
BILL_UNPAYED facture.class.php
BILL_CANCEL facture.class.php
BILL_DELETE facture.class.php
BILL_SENTBYMAIL facture.class.php
FACTURE_ADD_CONTACT facture.class.php
FACTURE_DELETE_CONTACT facture.class.php
FACTURE_DELETE_RESOURCE (>= 3.6.0) facture.class.php
LINEBILL_INSERT facture.class.php
LINEBILL_UPDATE facture.class.php
LINEBILL_DELETE facture.class.php
BILL_SUPPLIER_CREATE fournisseur.facture.class.php
BILL_SUPPLIER_MODIFY fournisseur.facture.class.php
BILL_SUPPLIER_DELETE fournisseur.facture.class.php
BILL_SUPPLIER_VALIDATE fournisseur.facture.class.php
BILL_SUPPLIER_PAYED fournisseur.facture.class.php
BILL_SUPPLIER_UNPAYED fournisseur.facture.class.php
BILL_SUPPLIER_SENTBYMAIL fournisseur.facture.class.php
INVOICE_SUPPLIER_ADD_CONTACT fournisseur.facture.class.php
INVOICE_SUPPLIER_DELETE_CONTACT fournisseur.facture.class.php
INVOICE_SUPPLIER_DELETE_RESOURCE (>= 3.6.0) fournisseur.facture.class.php
LINEBILL_SUPPLIER_CREATE fournisseur.facture.class.php
LINEBILL_SUPPLIER_UPDATE fournisseur.facture.class.php
LINEBILL_SUPPLIER_DELETE (>= 3.4.0) fournisseur.facture.class.php
PAYMENT_CUSTOMER_CREATE paiement.class.php
PAYMENT_DELETE (<= 3.8) paiement.class.php
PAYMENT_CUSTOMER_DELETE (>= 3.9) paiement.class.php
PAYMENT_ADD_TO_BANK paiement.class.php
PAYMENT_SUPPLIER_CREATE paiementfourn.class.php
PAYMENT_SUPPLIER_DELETE (>= 3.9) paiement.class.php
PAYMENT_SALARY_CREATE (>= 3.6.0) paymentsalary.class.php
PAYMENT_SALARY_MODIFY (>= 3.6.0) paymentsalary.class.php
PAYMENT_SALARY_DELETE (>= 3.6.0) paymentsalary.class.php
FICHINTER_CREATE fichinter.class.php
FICHINTER_MODIFY fichinter.class.php
FICHINTER_DELETE fichinter.class.php
FICHINTER_VALIDATE fichinter.class.php
FICHINTER_SENTBYMAIL fichinter.class.php
FICHINTER_ADD_CONTACT fichinter.class.php
FICHINTER_DELETE_CONTACT fichinter.class.php
FICHINTER_DELETE_RESOURCE (>= 3.6.0) fichinter.class.php
LINEFICHINTER_CREATE (>= 3.5.0) fichinter.class.php
LINEFICHINTER_UPDATE (>= 3.5.0) fichinter.class.php
LINEFICHINTER_DELETE (>= 3.5.0) fichinter.class.php
MEMBER_CREATE adherent.class.php
MEMBER_VALIDATE adherent.class.php
MEMBER_SUBSCRIPTION adherent.class.php
MEMBER_MODIFY adherent.class.php
MEMBER_RESILIATE adherent.class.php
MEMBER_NEW_PASSWORD adherent.class.php
MEMBER_DELETE adherent.class.php
CATEGORY_CREATE category.class.php
CATEGORY_MODIFY category.class.php
CATEGORY_DELETE category.class.php
CATEGORY_LINK (>= 3.5.0) category.class.php
CATEGORY_UNLINK (>= 3.5.0) category.class.php
SHIPPING_CREATE expedition.class.php
SHIPPING_VALIDATE expedition.class.php
SHIPPING_MODIFY expedition.class.php
SHIPPING_DELETE expedition.class.php
SHIPPING_SENTBYMAIL expedition.class.php
DELIVERY_VALIDATE livraison.class.php
DELIVERY_DELETE livraison.class.php
ACTION_CREATE actioncomm.class.php
ACTION_MODIFY actioncomm.class.php
ACTION_DELETE actioncomm.class.php
ACTION_ADD_CONTACT actioncomm.class.php
ACTION_DELETE_CONTACT actioncomm.class.php
ACTION_DELETE_RESOURCE (>= 3.6.0) actioncomm.class.php
DEPLACEMENT_CREATE deplacement.class.php
DON_CREATE don.class.php
DON_MODIFY (>= 3.7.0) don.class.php
DON_DELETE (>= 3.7.0) don.class.php
LOCALTAX_CREATE localtax.class.php
LOCALTAX_MODIFY localtax.class.php
LOCALTAX_DELETE localtax.class.php
TVA_CREATE tva.class.php
TVA_MODIFY tva.class.php
TVA_DELETE tva.class.php
TVA_ADDPAYMENT tva.class.php
PROJECT_CREATE project.class.php
PROJECT_MODIFY project.class.php
PROJECT_DELETE project.class.php
PROJECT_VALIDATE project.class.php
PROJECT_CLOSE project.class.php
PROJECT_ADD_CONTACT project.class.php
PROJECT_DELETE_CONTACT project.class.php
PROJECT_DELETE_RESOURCE (>= 3.6.0) project.class.php
TASK_CREATE task.class.php
TASK_MODIFY task.class.php
TASK_DELETE task.class.php
TASK_TIMESPENT_CREATE task.class.php
TASK_TIMESPENT_MODIFY task.class.php
TASK_TIMESPENT_DELETE task.class.php
PROJECT_TASK_ADD_CONTACT task.class.php
PROJECT_TASK_DELETE_CONTACT task.class.php
PROJECT_TASK_DELETE_RESOURCE (>= 3.6.0) task.class.php
MYECMDIR_CREATE ecmdirectory.class.php
MYECMDIR_MODIFY ecmdirectory.class.php
MYECMDIR_DELETE ecmdirectory.class.php
STOCK_MOVEMENT mouvementstock.class.php
PAYBOX_PAYMENT_OK
PAYPAL_PAYMENT_OK
LINK_CREATE (>= 3.5.0) link.class.php
LINK_MODIFY (>= 3.5.0) link.class.php
LINK_DELETE (>= 3.5.0) link.class.php
OPENSURVEY_CREATE (>= 3.6.0) opensurveysondage.class.php
OPENSURVEY_DELETE (>= 3.6.0) opensurveysondage.class.php

Liste non exhaustive.

Créer de nouveaux événements Triggers

Pour gérer d'autres événements que ceux ci-dessus, il faut modifier le code Dolibarr pour y ajouter la séquence suivante dans les méthodes métiers des classes des objects manipulés: 

// Call trigger
$result=$this->call_trigger('CODE_TRIGGER',$user);
if ($result < 0) $error++;          
// End call triggers

Pour ajouter des informations de context (par exemple pour dissocier 2 cas différents appelés avec le même code Trigger), il est possible de placer ces informations dans la propriétés ->context de l'object sur lequel porte l'appel du trigger. Exemple: 

// Call trigger
$this->context = array('paramX'=>$valueX, 'anyparamofyourchoice'=>$anyvalue);
$result=$this->call_trigger('CODE_TRIGGER',$user);
if ($result < 0) $error++;          
// End call triggers


Il sera alors possible d'ajouter dans la méthode runTrigger de tout fichier trigger, un if qui permet de gérer ce code. La méthode runTrigger serait alors de la forme : 

function run_trigger($action,$object,$user,$lang,$conf)
{
      // Mettre ici le code à exécuter en réaction de l'action
      // Le type de l'évènement Dolibarr est stocké dans $action
      // Les données de l'action sont stockées dans $object
      // La configuration, utilisateur et langage sont dans $conf,$user et $lang
      if ($action == 'XXXXX_YYYYY')
      {
          dol_syslog("Trigger for action '$action' launched. id=".$object->id);
      }
      elseif ($action == 'COMPANY_CREATE')
      {
          dol_syslog("Trigger for action '$action' launched. id=".$object->id);
      }
      elseif ($action == 'COMPANY_MODIFY')
      {        
          dol_syslog("Trigger for action '$action' launched. id=".$object->id);
      }
      elseif ($action == 'COMPANY_DELETE')
      ...
}

Conclusion

Vous pouvez donc en quelques minutes, ajouter une interface Dolibarr vers exterieur sans risque puisqu'on ne touche pas au code Dolibarr, on s'est contenté de placer un nouveau fichier trigger dans le répertoire des triggers. Si cette interface peut être utile à d'autre, n'hésitez pas à la packager en tgz (voir la page Développement_module#Créer_un_package_pour_livrer_et_installer_votre_module) et de la soumettre dans l'espace des téléchargement-contributions sur le site de Dolibarr.

Voir aussi

Retrieved from "https://wiki.dolibarr.org/index.php?title=Système_de_Triggers&oldid=61845"