Triggers-acciones

Dolibarr proporciona un mecanismo sencillo para poder actuar en una aplicación externa en un evento interno de Dolibarr (Para obtener información sobre el caso inverso y permitir que un sistema externo actúe sobre Dolibarr, consulte la página Interfaces del Exterior hacia Dolibarr).

= Añadir su código en un evento Dolibarr =

Para ayudar a desencadenar código personalizado en respuesta a un evento Dolibarr (creación/modificación /eliminación de una empresa/factura/producto/usuario u otro), Dolibarr propone un mecanismo de triggers. Este mecanismo le permite personalizar un flujo de trabajo a fin de que los eventos de gestión Dolibarr sean enviados a otra aplicación, por ejemplo. Nada impide que también sean utilizados para cambiar el comportamiento de Dolibarr mismo: por ejemplo, para que la validación de una factura provoque la creación de un contrato automáticamente.

Entonces, para añadir su propio código que será desencadenado por un trigger, el procedimiento es el siguiente:

1) Copiar el fichero htdocs/core/triggers/interface_20_all_Demo.class.php bajo el nombre: o bien donde Xxx es una cadena a vuestro gusto que empieza por una mayúscula y MonModule es el nombre del módulo si su trigger debe activarse solamente si el módulo MonModule está activo. Si queremos que el trigger esté siempre activo, pondremos all en lugar de modMonModule. Debemos dejar que este nuevo archivo en la misma carpeta. Nota: Los valores a utilizar de modMonModule son visibles en la carpeta htdocs/includes/modules.
 * interface_99_all_Xxx.class.php
 * interface_99_modMonModule_Xxx.class.php

Por ejemplo, podemos llamar a nuestro nuevo trigger: htdocs/includes/triggers/interface_99_modFacture_Monworkflow.class.php

Al crear un archivo de nombre como en este ejemplo, el nuevo trigger se activará en cada evento Dolibarr, siempre que el módulo factura esté activo.

Nota: Con Dolibarr 3.2+, es posible tener los archivos triggers en un subdirectorio del módulo. Ej: si el módulo se encuentra en htdocs/mimodulo/, podemos tener los triggers en htdocs/mimodulo/core/triggers/.

En este caso, el trigger no se encontrará si no lo declara en el archivo descriptor de su módulo. Para ello añada triggers->1 en la tabla module_parts (ej: /mimodulo/core/modules/modMiModulo.class.php): Seguidamente desactive y reactive el módulo. Esto añadirá una línea en la tabla Table llx_const que le indicará a Dolibarr que hace falta buscar un trigger en el directorio de su módulo htdocs/mimodulo/core/triggers.

2) Editar el fichero interface_99_modMonModule_Monworkflow.class.php renombrando la clase InterfaceDemo por InterfaceMonworkflow

A continuación, Acceder a la página Inicio-> Info Sistema -> Dolibarr -> Triggers. Su fichero trigger debe aparecer en la lista sin error indicaando que las operaciones anteriores se han realizado con éxito.

3) Volvamos a editar el fichero triggur para añadir nuestro código en la función run_trigger. Esta función es llamada en cada evento Dolibarr. Pongamos nuestro código en función de los eventos sobre los que queramos actuar, cada evento se identifica mediante un código (ver los capítulos siguientes para ver el listado de códigos), podemos actuar o en un evento determinado por una prueba en la variable $action:

Puede hacer lo que desee en esta parte del código, siempre que la función run_trigger devuelva un código de retorno basándose en el principio siguiente:

<0 si error, 0 si no se realiza ninguna acción, >0 si ok

También puede utilizar en esta función los siguientes objetos:
 * $object es el objeto sobre el que se lleva la acción (véase la sección siguiente)
 * $user es el objeto del usuario Dolibarr que realiza la acción
 * $langs es el objeto que contiene el idioma del usuario Dolibarr
 * $conf es el objeto que contiene toda la configuración de Dolibarr.

4) Una vez que el código esté realizado, sólo tiene que probarlo, provocando el evento desencadenante en Dolibarr. Atención, la llamada a  run_trigger está encapsulado en una transacción. Si el trigger devuelve un código ko, la función que lo ha llamado puede cancelar la transacción (esto depende de la función que realiza la llamada).

Añadir traces en un fichero en la función run_trigger para asegurarse que el código se ejecuta correctamente. Para ello, si lo desea, puede usar la función dol_syslog("mi texto de trace", LOG_DEBUG);

= Listado de los eventos conocidos =

Los eventos Dolibarr que provocan una llamada de triggers son, a día de hoy, identificados por los códigos $action los siguientes eventos:

= Gestionar nuevos eventos =

Para la gestión de otros eventos como los anteriores, es necesario modificar el código Dolibarr para añadir la secuencia siguiente en los métodos de negociado destinados a la gestión de eventos:

Aquí, $this debe de ser el objeto de la clase de negociado que contiene toda la información a pasar al trigger. Reemplazar, de paso, el 'XXXXX_YYYYY' por un código de evento no utilizado. Entonces será posible añadir en el método run_trigger, un if que permita la gestión de ese código. El método run_trigger tomaría esta forma :

= Conclusión = Puede en pocos minutos, agregar una interfaz Dolibarr al exterior sin riesgos ya que no toca código Dolibarr, se limita a poner una nuevo archivo trigger en la carpeta de triggers. Si esta interfaz puede ser útil a otros, no dude en empaquetarla en tgz (véase Desarrollo_de_un_módulo) y enviarlo al área de descarga de las contribuciones en el sitio Dolibarr.

= Vea también =
 * El sistema Hooks
 * Interfaces Dolibarr hacia el exterior
 * Interfaces del Exterior hacia Dolibarr