28,936
edits
Changes
m
→Execute your own code on a Dolibarr business event
Line 2:
Line 2:
So, to add your own code that will be triggered by a Dolibarr trigger, this is the way to process:
−
+
+
+
+
+
<!-- You can edit this section but do NOT remove these comments
<!-- You can edit this section but do NOT remove these comments
Links below will be automatically replicated on translated pages by PolyglotBot -->
Links below will be automatically replicated on translated pages by PolyglotBot -->
−[[fr:Triggers-actions]]
+[[fr:Système de Triggers]]
[[es:Triggers-acciones]]
[[es:Triggers-acciones]]
+[[zh:触发系统]]
<!-- END interlang links -->
<!-- END interlang links -->
Line 10:
Line 11:
=Execute your own code on a Dolibarr business event=
=Execute your own code on a Dolibarr business 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.
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.
+You can also use triggers to modify the behavior of Dolibarr itself: for example, to create a contract automatically when an invoice is validated, a fill a log file when a record is deleted, ...
−Note that triggers is a feature for developers that is limited to business CRUD events (Create | Read | Update | Delete). There is another features for developers to inject custom code in application called the [[Hooks system]].
+Note that triggers is a feature for developers that is limited to:
+* business CRUD events (Create | Read | Update | Delete).
+* change of the primary status of objects
+There is another feature for developers to inject custom code in the application called the [[Hooks system]]. Note, for historic reason, when you send an email, this generates also a trigger call even if this case is not among the 2 allowed.
−1) Copy the trigger file '''htdocs/core/triggers/interface_90_all_Demo.class.php-NORUN''' under the new name:
+So, to add your own code that will be triggered by a Dolibarr trigger, this is the process:
+1) Copy the template trigger file '''htdocs/modulebuilder/template/core/triggers/interface_99_modMyModule_MyModuleTriggers.class.php''' under the new name:
*'''interface_99_all_''Xxx''.class.php'''
*'''interface_99_all_''Xxx''.class.php'''
Line 24:
Line 29:
*'''interface_99_mod''MyModule_Xxx''.class.php'''
*'''interface_99_mod''MyModule_Xxx''.class.php'''
−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.
+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 MyModule 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.
This new file must be saved inside same directory.
Note: Value you can use for modMyModule are values found in directory
Note: Value you can use for modMyModule are values found in directory
−''htdocs/includes/modules''.
+''htdocs/core/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!
+'''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:
For example, you can name your new trigger file:
−''htdocs/includes/triggers/interface_99_modFacture_Myworkflow.class.php''
+''htdocs/core/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.
+By creating such a file with a name like 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:
+'''Note''': If you develop a full module, you can also place the trigger file in your own module's sub-directory. 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:
−<source lang="php">
+<syntaxhighlight lang="php">
// Defined all module parts (triggers, login, substitutions, menus, etc...) (0=disable,1=enable)
// 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);
Line 45:
Line 50:
// 'substitutions' => 0,
// 'substitutions' => 0,
// 'menus' => 0);
// 'menus' => 0);
−</source>
+</syntaxhighlight>
Then disable and reenable your module. This will add a record into [[Table llx_const]] to tell Dolibarr that a trigger file must be searched in the module directory '''htdocs/mymodule/core/triggers/'''
Then disable and reenable your module. This will add a record into [[Table llx_const]] to tell Dolibarr that a trigger file must be searched in the module directory '''htdocs/mymodule/core/triggers/'''
−2) Edit the file ''interface_99_modMyModule_Myworkflow.class.php'' to rename class ''InterfaceDemo'' by ''InterfaceMyworkflow''
+2) Edit the file ''interface_99_modFacture_Myworkflow.class.php'' to modify its content by changing the class ''InterfaceMyModuleTriggers'' by ''InterfaceMyworkflow:''
Then go on page Home -> Admin Tools -> About Dolibarr ->Triggers.
Then go on page Home -> Admin Tools -> About Dolibarr ->Triggers.
Line 58:
Line 63:
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''':
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">
+<syntaxhighlight lang="php">
function run_trigger($action,$object,$user,$langs,$conf)
function run_trigger($action,$object,$user,$langs,$conf)
{
{
Line 76:
Line 81:
...
...
}
}
−</source>
+</syntaxhighlight>
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:
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:
Line 109:
Line 114:
To manage events other than those above, you must modify the Dolibarr code to add the following sequence in the business methods of the classes of the objects handled:
To manage events other than those above, you must modify the Dolibarr code to add the following sequence in the business methods of the classes of the objects handled:
−<source lang = "php">
+<syntaxhighlight lang="php">
// Call trigger
// Call trigger
−$result = $this->call_trigger('XXXXX_YYYYY', $user);
+$result = $this->call_trigger('CODE_TRIGGER', $user);
if ($result <0) $error++;
if ($result <0) $error++;
// End call triggers
// End call triggers
−</source>
+</syntaxhighlight>
+To add context information (for example to dissociate 2 different cases called with the same Trigger code), it is possible to place this information in the properties ->context of the object on which the trigger is called. Example:
+<syntaxhighlight lang="php">
+// Call trigger
+$this->context = array('paramX'=>$valueX, 'anyparamofyourchoice'=>$anyvalue);
+$result = $this->call_trigger('CODE_TRIGGER',$user);
+if ($result < 0) $error++;
+// End call triggers
+</syntaxhighlight>
It will then be possible to add in the run_trigger method of any trigger file, an if which allows you to manage this code. The run_trigger method would then be of the form:
It will then be possible to add in the run_trigger method of any trigger file, an if which allows you to manage this code. The run_trigger method would then be of the form:
−<source lang="php">
+<syntaxhighlight lang="php">
function run_trigger($action,$object,$user,$lang,$conf)
function run_trigger($action,$object,$user,$lang,$conf)
{
{
Line 140:
Line 155:
...
...
}
}
−</source>
+</syntaxhighlight>
+'''Please note the following before adding additional calls to triggers:'''
+The rule is to have only 1 trigger call per business CRUD event, even when several actions are done in the same transaction.
+As an example: When a new ticket is created with an already assigned user, only the TICKET_CREATE trigger is called, not additionally the TICKET_ASSIGNED trigger. It is the job of the trigger to intercept also this case to scan if an assignment is done directly during creation and to execute its custom code.
+=Conclusion=
=Conclusion=