|
|
| Line 1: |
Line 1: |
| {{TemplateDocDev}} | | {{TemplateDocDev}} |
| Dolibarr fournit un mécanisme simple pour permettre d'agir dans un application extérieur suite à un évênement interne de Dolibarr (Pour des informations sur l'autre sens et permettre à un système extérieur de faire agir Dolibarr, voir plutôt la page [[Interfaces Exterieur vers Dolibarr]]). | | Dolibarr fournit deux mécanismes simples pour permettre d'interfacer Dolibarr avec une application tierce: |
|
| |
|
| = Ajouter son code sur un événement Dolibarr =
| | * Les [[Triggers]] - active votre code suite à un évênement-action interne |
| | * Le [[système de Hooks]] - active votre code dans un point d'entrée de Dolibarr (un point d'entrée peut être n'importe où contrairement aux actions-triggers). |
|
| |
|
| 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. | | Pour des informations sur l'autre sens et permettre à un système extérieur de faire agir Dolibarr, voir plutôt la page [[Interfaces Exterieur vers Dolibarr]]. |
| 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.
| |
| | |
| Donc, pour ajouter son propre code qui sera déclenché par trigger, la procédure est la suivante:
| |
| | |
| | |
| 1) Copier le fichier '''htdocs/includes/triggers/interface_all_Demo.class.php''' sous le nom:
| |
| * '''interface_all_''Xxx''.class.php'''
| |
| ou bien
| |
| * '''interface_mod''MonModule_Xxx''.class.php'''
| |
| où ''Xxx'' est une chaine de votre choix commençant par une majuscule et ''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 utilisable pour modMonModule sont visibles dans le répertoire
| |
| ''htdocs/includes/modules''.
| |
| | |
| Par exemple, on pourra nommer notre nouveau trigger:
| |
| ''htdocs/includes/triggers/interface_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.
| |
| | |
| | |
| 2) Editer ce fichier ''interface_modMonModule_Monworkflow.class.php'' afin de renommer la classe ''InterfaceDemo'' par ''InterfaceMonworkflow''
| |
| | |
| | |
| Ensuite, accéder à la page Accueil-> Infos Systèmes -> Dolibarr -> Triggers.
| |
| Votre fichier trigger doit apparaitre 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 ''run_trigger''.
| |
| 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ée par un test sur la variable '''$action''':
| |
| | |
| <source lang="php">
| |
| function run_trigger($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')
| |
| ...
| |
| }
| |
| </source>
| |
| | |
| Vous pouvez faire ce que vous voulez dans cette portion de code du moment que la fonction run_trigger renvoi 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 '''run_trigger''' 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 '''run_trigger''' 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 =
| |
| La liste de tous les évênements qui provoque un déclenchement de trigger sont disponibles dans la table [[Table llx c action trigger]]. Voici un vue rapide des evênements identifiés par la valeur suivante au code '''$action''':
| |
| | |
| * USER_CREATE
| |
| * USER_MODIFY
| |
| * USER_DISABLE
| |
| Dans ces 3 cas, la variable $object contient un objet de type user.class.php
| |
| | |
| * COMPANY_CREATE
| |
| * COMPANY_MODIFY
| |
| * COMPANY_DELETE
| |
| Dans ces 3 cas, la variable $object contient un objet de type societe.class.php
| |
| | |
| * PRODUCT_CREATE
| |
| * PRODUCT_MODIFY
| |
| * PRODUCT_DELETE
| |
| Dans ces 3 cas, la variable $object contient un objet de type product.class.php
| |
| | |
| * ORDER_CREATE
| |
| * ORDER_VALIDATE
| |
| * ORDER_DELETE
| |
| Dans ces 3 cas, la variable $object contient un objet de type commande.class.php
| |
| | |
| * ORDER_SUPPLIER_CREATE
| |
| * ORDER_SUPPLIER_VALIDATE
| |
| Dans ces 2 cas, la variable $object contient un objet de type fournisseur.commande.class.php
| |
| | |
| * PROPAL_CREATE
| |
| * PROPAL_MODIFY
| |
| * PROPAL_VALIDATE
| |
| * PROPAL_CLOSE_SIGNED
| |
| * PROPAL_CLOSE_REFUSED
| |
| Dans ces 5 cas, la variable $object contient un objet de type societe.class.php
| |
| | |
| * CONTRACT_CREATE
| |
| * CONTRACT_MODIFY
| |
| * CONTRACT_ACTIVATE
| |
| * CONTRACT_CANCEL
| |
| * CONTRACT_CLOSE
| |
| * CONTRACT_DELETE
| |
| Dans ces 6 cas, la variable $object contient un objet de type contract.class.php
| |
| | |
| * BILL_CREATE
| |
| * BILL_MODIFY
| |
| * BILL_VALIDATE
| |
| * BILL_CANCEL
| |
| * BILL_DELETE
| |
| Dans ces 5 cas, la variable $object contient un objet de type facture.class.php
| |
| | |
| * PAYMENT_CUSTOMER_CREATE
| |
| Dans ce cas, la variable $object contient un objet de type paiement.class.php
| |
| | |
| * PAYMENT_SUPPLIER_CREATE
| |
| Dans ce cas, la variable $object contient un objet de type paiementfourn.class.php
| |
| | |
| * FICHEINTER_VALIDATE
| |
| Dans ce cas, la variable $object contient un objet de type ficheinter.class.php
| |
| | |
| * MEMBER_CREATE
| |
| * MEMBER_VALIDATE
| |
| * MEMBER_SUBSCRIPTION
| |
| * MEMBER_MODIFY
| |
| * MEMBER_RESILIATE
| |
| * MEMBER_DELETE
| |
| Dans ces 6 cas, la variable $object contient un objet de type adherent.class.php
| |
| | |
| * CATEGORY_CREATE
| |
| * CATEGORY_MODIFY
| |
| * CATEGORY_DELETE
| |
| Dans ces 3 cas, la variable $object contient un objet de type category.class.php
| |
| | |
| * SHIPPING_VALIDATE
| |
| * SHIPPING_MODIFY
| |
| Dans ce cas, la variable $object contient un objet de type expedition.class.php
| |
| | |
| = Gérer de nouveau évènements =
| |
| | |
| Pour gérer d'autre é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 utilisées pour gérer les évenements:
| |
| | |
| <source lang="php">
| |
| // Appel des triggers
| |
| include_once(DOL_DOCUMENT_ROOT . "/core/class/interfaces.class.php");
| |
| $interface=new Interfaces($this->db);
| |
| $result=$interface->run_triggers('XXXXX_YYYYY',$this,$user,$langs,$conf);
| |
| if ($result < 0) { $error++; $this->errors=$interface->errors; }
| |
| // Fin appel triggers
| |
| </source>
| |
| | |
| Ici, $this doit être l'objet de la classe métier qui contient toutes les informations à passer au trigger. Remplacer, de plus, le 'XXXXX_YYYYY' par un code évènement non déjà utilisé.
| |
| Il sera alors possible d'ajouter dans la méthode run_trigger, un if qui permet de gérer ce code. La méthode run_trigger serait alors de la forme :
| |
| | |
| <source lang="php">
| |
| 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
| |
| <b>
| |
| if ($action == 'XXXXX_YYYYY')
| |
| {
| |
| dol_syslog("Trigger for action '$action' launched. id=".$object->id);
| |
| }
| |
| </b>
| |
| 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')
| |
| ...
| |
| }
| |
| </source>
| |
| | |
| = 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.C3.A9er_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.
| |
