28,936
edits
Changes
Interfaces Dolibarr toward foreign systems (view source)
Revision as of 15:15, 14 August 2024
, 7 months agono edit summary
Line 1:
Line 1:
+
−= Execute your own code on a Dolibarr event =
−To execute personalized code after a Dolibarr event (create/modify/remove a third party/invoice/product or other), Dolibarr offers a mechanism of business triggers. This mechanism allows you to personalize a work-flow to have Dolibarr business events being synchronized into another application for example.
−You can also use triggers to modify the behavior of Dolibarr itself: for example, to create automatically a contract when an invoice is validated.
−
−So, to add your own code that will be triggered by a Dolibarr trigger, this is the way to process:
−
−
−1) Copy file '''htdocs/includes/triggers/interface_all_Demo.class.php''' under the new name:
−* '''interface_all_''Xxx''.class.php'''
−or
−* '''interface_mod''MyModule_Xxx''.class.php'''
−where ''Xxx'' is a string of your choice startint with uppercase character and ''MyModule'' is the name of a module if you want that trigger is activated only if module MyModyle is activated. If you want the trigger to be always active, use ''all'' instead of modMyModule.
−This new file must be saved inside same directory.
−Note: Value you can use for modMyModule are values found in directory
−''htdocs/includes/modules''.
−
−For example, you can name your new trigger file:
−''htdocs/includes/triggers/interface_modFacture_Myworkflow.class.php''
−
−By creating such a file with name as in the example, your new trigger file will be executed each time a Dolibarr business event occurs but only if the module Facture is enabled.
−
−
−2) Edit the file ''interface_modMyModule_Myworkflow.class.php'' to rename class ''InterfaceDemo'' by ''InterfaceMyworkflow''
−
−
−Then go on page Home-> System Infos -> Dolibarr -> Triggers.
−Your new trigger file must appears in the list without any error message. This means preceding actions have been done successfully.
−
−
−3) Return now to edition of file to add your own code inside function ''run_trigger''.
−This function is called at each Dolibarr business event. Put your code according to events on which you want to run. Each event is identified by a code (see following chapter to get full list of codes). So you can react or no after an event by doing just a test on variable '''$action''':
−
−<source lang="php">
− function run_trigger($action,$object,$user,$lang,$conf)
− {
− // Put here code to execute after an action
− // The type of Dolibarr business event is stored into $action
− // Data of action are stored into object $object
− // Setup, user and language are saved into $conf, $user and $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>
−
−You can do what you want into this coding part, if you check that function run_trigger returns a return code according to following rule:
−
−<0 if KO, 0 if nothing is done, >0 if OK
−
−You can also use in this function the preinitialized following variables:
−* '''$object''' is the object on which action is done (see next chapter)
−* '''$user''' is the object containing all information of Dolibarr user that realizes the business event.
−* '''$langs''' is the object that contains the user language and translations strings
−* '''$conf''' is the object that contains all the Dolibarr configuration.
−
−4) Once your trigger file has been developed, last action is to test by using Dolibarr to execute the business event that should trigger your code. Warning, call of function '''run_trigger''' is encapsulated into a transaction. If your code return a KO code, the calling function may rollback the transaction (this depends on calling function).
−Add log information inside your function '''run_trigger''' to know if your code is correctly triggered and runs correctly. For this, you can use the function
−dol_syslog("my log message", LOG_DEBUG);
−
−= List of known events =
−
−Dolibarr events that launch triggers are identified by an event code '''$action'''. Existing codes are:
−
−* USER_CREATE
−* USER_MODIFY
−* USER_DISABLE
−In such cases, the variable $object contains an object of type user.class.php
−
−* COMPANY_CREATE
−* COMPANY_MODIFY
−* COMPANY_DELETE
−In such cases, the variable $object contains an object of type societe.class.php
−
−* PRODUCT_CREATE
−* PRODUCT_MODIFY
−* PRODUCT_DELETE
−In such cases, the variable $object contains an object of type product.class.php
−
−* ORDER_CREATE
−* ORDER_VALIDATE
−* ORDER_DELETE
−In such cases, the variable $object contains an object of type commande.class.php
−
−* ORDER_SUPPLIER_CREATE
−* ORDER_SUPPLIER_VALIDATE
−In such cases, the variable $object contains an object of type fournisseur.commande.class.php
−
−* PROPAL_CREATE
−* PROPAL_MODIFY
−* PROPAL_VALIDATE
−* PROPAL_CLOSE_SIGNED
−* PROPAL_CLOSE_REFUSED
−In such cases, the variable $object contains an object of type societe.class.php
−
−* CONTRACT_CREATE
−* CONTRACT_MODIFY
−* CONTRACT_ACTIVATE
−* CONTRACT_CANCEL
−* CONTRACT_CLOSE
−* CONTRACT_DELETE
−In such cases, the variable $object contains an object of type contract.class.php
−
−* BILL_CREATE
−* BILL_MODIFY
−* BILL_VALIDATE
−* BILL_CANCEL
−* BILL_DELETE
−In such cases, the variable $object contains an object of type facture.class.php
−
−* PAYMENT_CUSTOMER_CREATE
−In such cases, the variable $object contains an object of type paiement.class.php
−
−* PAYMENT_SUPPLIER_CREATE
−In such cases, the variable $object contains an object of type paiementfourn.class.php
−
−* FICHEINTER_VALIDATE
−In such cases, the variable $object contains an object of type ficheinter.class.php
−
−* MEMBER_CREATE
−* MEMBER_VALIDATE
−* MEMBER_SUBSCRIPTION
−* MEMBER_MODIFY
−* MEMBER_RESILIATE
−* MEMBER_DELETE
−In such cases, the variable $object contains an object of type adherent.class.php
−
−* CATEGORY_CREATE
−* CATEGORY_MODIFY
−* CATEGORY_DELETE
−In such cases, the variable $object contains an object of type category.class.php
−
−= Manage new events =
−
−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 . "/interfaces.class.php");
−$interface=new Interfaces($this->db);
−$interface->run_triggers('XXXXX_YYYYYY',$this,$user,$lang,$conf);
−// 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_YYYYYY' 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 les wiki sur la diffusion de modules) et de la soumettre dans l'espace des téléchargement-contributions sur le site de Dolibarr.
<!-- BEGIN origin interlang links -->
+<!-- You can edit this section but do NOT remove these comments
+ Links below will be automatically replicated on translated pages by PolyglotBot -->
+[[fr:Interfaces_Dolibarr_vers_exterieur]]
+[[es:Interfaces_Dolibarr_hacia_el_exterior]]
+[[zh:Dolibarr到外部系统的接口]]
+<!-- END interlang links -->
+
{{TemplateDocDevEn}}
{{TemplateDocDevEn}}
−Dolibarr provides a simple mecanism to make Dolibarr act into an external system on a Dolibarr event (For more inforation on the other direction and allow an external system to act into Dolibarr system, see page [[Interfaces from foreign systems toward Dolibarr]]).
+Dolibarr provides several mechanisms to interface Dolibarr with an external system on the behave of a Dolibarr event :
−* [[Triggers system]] - a mechanism to activate your own code when Dolibarr executes an action (for example, creation of invoice, edit of a user, delete of an order, ...)
−* [[Hooks system]] - an interface to integrate your own code in an entry point of Dolibarr
−* [[Module Webhook]] - a module to send a JSON message on a Dolibarr triggered event.
−For more information on the opposite mechanism (allow an external system to interface with the Dolibarr system and use the Dolibarr's datas), see [[Interfaces from foreign systems toward Dolibarr]].
−