Triggers

= Execute your own code on a Dolibarr's action = 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 the trigger file htdocs/core/triggers/interface_90_all_Demo.class.php-NORUN under the new name: or where Xxx is a string of your choice starting with uppercase character, 99 is the priority number for the execution of your trigger (1 being the top priority) 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.
 * interface_99_all_Xxx.class.php
 * interface_99_modMyModule_Xxx.class.php

Note: Value you can use for modMyModule are values found in directory htdocs/includes/modules.

WARNING: All those parameters are necessary for the trigger to be detected and executed! Eg: if you forget the priority number, your trigger won't be detected!

For example, you can name your new trigger file: htdocs/includes/triggers/interface_99_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.

Note: With Dolibarr 3.2+, you can also place the triggers in your own module's subdirectly. Eg: if your module resides in htdocs/mymodule/, then you can place your triggers inside htdocs/mymodule/core/triggers/. But for this, you must declare the trigger into your module descriptor file (eg: /mymodule/core/modules/modMyModule.class.php). For this, add into this file triggers->1 into module_parts array: Then disable and reenable your module. This will add a record into Table llx_const to say Dolibarr a trigger file must be searched into module directory htdocs/mymodule/core/triggers/

2) Edit the file interface_99_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:

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, inside this function, the following preinitialized 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 triggers actions = List of all events that launch triggers are available in Table llx c action trigger. This is a quick list of those events, identified by value of variable $action into trigger code and type of variable $object for each code:

This list may be not complete.

= Manage and create a new trigger's action =

To manage other events on objects than the one defined before, you must edit the Dolibarr code to add the following code inside the business method of the class file of the object:

Here, $this contains the business class with all information to send to the trigger functions. Replace 'XXXXX_YYYYY' by an event code not already used. Then you will be able to add inside the run_trigger method, a "if" to manage this code. The run_trigger method will contains a part of code like this :

= Conclusion = You can in few minutes, add an interface from Dolibarr towards another system (or why not towards Dolibarr itself), with no risk since you don't touch anything to Dolibarr files. You only "added" a new trigger file inside the trigger directory. If this new interface can serve a lot of other users, you can package it into a tgz file (see page Module_development) and submit it on the download area in section external contributions on official Dolibarr web site.

= See also =
 * Hooks system
 * Interfaces Dolibarr toward foreign systems
 * Interfaces from foreign systems toward Dolibarr