Dolibarr ERP CRM Wiki - User contributions [en]

Developer documentation

2023-05-15T08:43:06Z

IPazu:

<seo metak="developer, development, documentation, guide, doc, tutorial, usage, help, api, coding, standard, rules" />


[[fr:Documentation_Développeur]]
[[es:Documentación_Desarrolladores]]
[[de:Entwickler_Dokumentation]]
[[zh:开发文档]]


This page is main index of documents relating to developer documentation. For user documentation [[User documentation|see here]].

=Development organization and tools=
This chapter contains global information that must be read before starting any development on Dolibarr.

#[[Dolibarr Project|Organization of project]]
#[[To known before to start|To be known before starting to develop]]
#[[Environment and development tools]]
#[[Dependencies and external libraries]]
#[[FAQ_Get,update_project_sources|Get or update sources of a development version]]

=Coding rules and best practices=

#[[Prerequisite|Prerequisites]]
#[[Language and development rules|Language and development rules (PHP, SQL, HTML)]]
#[[:Category:Table SQL|List of tables]]
#Tree structure of files and classes are available in the [http://doxygen.dolibarr.org/ doxygen generated documentation]

=List of modules=
Technical documentation on standard business modules is available in each module's developer documentation pages. Choose the appropriate page you are interested in:

*[[:Category:List of Modules (developer)‎|List of standard modules]]
*[[:Category:Complementary modules|List of complementary modules]]

=To develop a new module/addon for GUI=
This section describes how to develop a new module changing the Dolibarr user interface. This can be screens, themes, data, its own CSS stylesheet, source code or all of this.

Script development is not included in this section (this is described in the next chapter).

To develop your own module, check the [[Module development]] tutorial.

=To develop a batch or command line script=
This chapter describes how to develop command line scripts to execute tasks in Dolibarr (read, update data...).

Making modifications to the graphical user interface (GUI) is not included in this chapter. See the previous chapter for this.

To develop a script, like a cron script or a command line import tool to import data from an external source, you can have a look at the [[Script development]] page.

=Technical components of Dolibarr=
==Tree structure==
The path hierarchy of the current version files is available from the [http://doxygen.dolibarr.org/ doxygen generated documentation] (similar to generated "javadoc" documentation).

Paths to use to add new files by a new module are defined in the documentation to develop a new module (see [[Module development]]).

==Setup storage==
There are 3 places for Dolibarr setup parameters.

*Dolibarr technical setup parameters (authentication mode, database logins and storage area for files) are defined in only one setup file: <code>/conf/conf.php</code> .

:See [[Configuration file]] for more information.

*Global features parameters are stored in [[Table llx_const]].

:See the [[Constants]] page for more information.

*Feature parameters specific to a user are stored in [[Table llx_user_param]].

==Business objects==
See [[Business Objects]]

==Menus system==
See [[Menus system]]

==Tabs system==
See [[Tabs system]]

==Skins system==
See [[Skins]]

==Widget system==
See [[Widget system]]

==Authentication system==
See [[Authentication]]

==Permission system==
See [[Permissions En|Permissions]]

==Translation system==
See [[Translation system]]

==Error management==
See [[Error reporting|Error reporting]]

==Canvas system==
Canvas is a developer feature to replace screens to create, update or view a record (products, thirdparties, contacts, ...). For example, you can replace the input form used to create a new third party, or its editing form, or replace its viewing template.

See [[Canvas development]]

==Triggers system==
Triggers are a development feature to execute personalized code during a Dolibarr "business event" (creation of an invoice, deleting a user, update of third party, etc...), and only for a business event. To personalize code for other contexts, see the '''Hooks system''' chapter instead.

For triggers usage, see [[Interfaces Dolibarr toward foreign systems|this page]].

==Hooks system==
See [[Hooks system]]

==Variable substitution system==
See [[Variable substitution system]]

==Web services==
Dolibarr can be setup to provide some services.

See [[Module Web Services API REST (developer)]]

Note: The [[Module Web Services API SOAP (developer)]] is deprecated.

==Files/Documents storage management==
See [[Generated documents]]

==Numbering modules==
For each entity created in the application, Dolibarr assigns a reference. In order to adapt the reference to any use, Dolibarr use modules to define the reference generation rule. Several standard modules are supplied. Some are generic and are used to define the numbering mask (number on x characters, with or without prefix, including the date or not, etc.), which can meet most needs. However, there are still cases where the modules provided don't meet the needs. In this case it is necessary to develop a custom numbering module.

For more information, see [[Create numeration module|Create numbering module]].

==Document templates and documents generation==

More documentation about document generation from templates is available to [[Create a PDF document template]] or [[Create an ODT document template]].

==Extrafields==
See [[Extrafields]]

==Online payment system==
See [[Online payment system]]

==Other internal function==
There are many internal libraries your code can use.
You may find a lot of generic functions in the functions.lib.php, functions2.lib.php or admin.lib.php. Any function found in htdocs/core/lib/*.lib files can be used.

'''To specify a requirement based on Dolibarr version number'''

For example, to make a condition based on requiring Dolibarr version > 3.5, you can use versioncompare and versiondolibarrarray found in admin.lib.php:

<syntaxhighlight lang="PHP">
if (versioncompare(versiondolibarrarray(), array(3,5,0)) > 0)
{
...
}
</syntaxhighlight>

=Mass exports/imports=

#[[Mass imports]]
#[[Module Exports En|Mass exports]]

=Interfaces and links with other applications=

#[[Interfaces Dolibarr toward foreign systems]] or Dolibarr toward Dolibarr (Dolibarr Triggers or Hooks)
#[[Interfaces from foreign systems toward Dolibarr]]

Integrate Dolibarr to automation platforms:

#[[Integration of Dolibarr to the Zapier automation platform]]
#[[Integration of Dolibarr to the n8n automation platform]]
#[[Integration of Dolibarr to the Make automation platform]]

=FAQ=
All FAQs are available through the FAQ index page [[:Category:FAQ EN|FAQ EN]]
[[Category:Development]]

Developer documentation

2023-05-14T20:39:40Z

IPazu: /* Interfaces and links with other applications */

<seo metak="developer, development, documentation, guide, doc, tutorial, usage, help, api, coding, standard, rules" />


[[fr:Documentation_Développeur]]
[[es:Documentación_Desarrolladores]]
[[de:Entwickler_Dokumentation]]
[[zh:开发文档]]


This page is main index of documents relating to developer documentation. For user documentation [[User documentation|see here]].

=Development organization and tools=
This chapter contains global information that must be read before starting any development on Dolibarr.

#[[Dolibarr Project|Organization of project]]
#[[To known before to start|To be known before starting to develop]]
#[[Environment and development tools]]
#[[Dependencies and external libraries]]
#[[FAQ_Get,update_project_sources|Get or update sources of a development version]]

=Coding rules and best practices=

#[[Prerequisite|Prerequisites]]
#[[Language and development rules|Language and development rules (PHP, SQL, HTML)]]
#[[:Category:Table SQL|List of tables]]
#Tree structure of files and classes are available in the [http://doxygen.dolibarr.org/ doxygen generated documentation]

=List of modules=
Technical documentation on standard business modules is available in each module's developer documentation pages. Choose the appropriate page you are interested in:

*[[:Category:List of Modules (developer)‎|List of standard modules]]
*[[:Category:Complementary modules|List of complementary modules]]

=To develop a new module/addon for GUI=
This section describes how to develop a new module changing the Dolibarr user interface. This can be screens, themes, data, its own CSS stylesheet, source code or all of this.

Script development is not included in this section (this is described in the next chapter).

To develop your own module, check the [[Module development]] tutorial.

=To develop a batch or command line script=
This chapter describes how to develop command line scripts to execute tasks in Dolibarr (read, update data...).

Making modifications to the graphical user interface (GUI) is not included in this chapter. See the previous chapter for this.

To develop a script, like a cron script or a command line import tool to import data from an external source, you can have a look at the [[Script development]] page.

=Technical components of Dolibarr=
==Tree structure==
The path hierarchy of the current version files is available from the [http://doxygen.dolibarr.org/ doxygen generated documentation] (similar to generated "javadoc" documentation).

Paths to use to add new files by a new module are defined in the documentation to develop a new module (see [[Module development]]).

==Setup storage==
There are 3 places for Dolibarr setup parameters.

*Dolibarr technical setup parameters (authentication mode, database logins and storage area for files) are defined in only one setup file: <code>/conf/conf.php</code> .

:See [[Configuration file]] for more information.

*Global features parameters are stored in [[Table llx_const]].

:See the [[Constants]] page for more information.

*Feature parameters specific to a user are stored in [[Table llx_user_param]].

==Business objects==
See [[Business Objects]]

==Menus system==
See [[Menus system]]

==Tabs system==
See [[Tabs system]]

==Skins system==
See [[Skins]]

==Widget system==
See [[Widget system]]

==Authentication system==
See [[Authentication]]

==Permission system==
See [[Permissions En|Permissions]]

==Translation system==
See [[Translation system]]

==Error management==
See [[Error reporting|Error reporting]]

==Canvas system==
Canvas is a developer feature to replace screens to create, update or view a record (products, thirdparties, contacts, ...). For example, you can replace the input form used to create a new third party, or its editing form, or replace its viewing template.

See [[Canvas development]]

==Triggers system==
Triggers are a development feature to execute personalized code during a Dolibarr "business event" (creation of an invoice, deleting a user, update of third party, etc...), and only for a business event. To personalize code for other contexts, see the '''Hooks system''' chapter instead.

For triggers usage, see [[Interfaces Dolibarr toward foreign systems|this page]].

==Hooks system==
See [[Hooks system]]

==Variable substitution system==
See [[Variable substitution system]]

==Web services==
Dolibarr can be setup to provide some services.

See [[Module Web Services API REST (developer)]]

Note: The [[Module Web Services API SOAP (developer)]] is deprecated.

==Files/Documents storage management==
See [[Generated documents]]

==Numbering modules==
For each entity created in the application, Dolibarr assigns a reference. In order to adapt the reference to any use, Dolibarr use modules to define the reference generation rule. Several standard modules are supplied. Some are generic and are used to define the numbering mask (number on x characters, with or without prefix, including the date or not, etc.), which can meet most needs. However, there are still cases where the modules provided don't meet the needs. In this case it is necessary to develop a custom numbering module.

For more information, see [[Create numeration module|Create numbering module]].

==Document templates and documents generation==

More documentation about document generation from templates is available to [[Create a PDF document template]] or [[Create an ODT document template]].

==Extrafields==
See [[Extrafields]]

==Online payment system==
See [[Online payment system]]

==Other internal function==
There are many internal libraries your code can use.
You may find a lot of generic functions in the functions.lib.php, functions2.lib.php or admin.lib.php. Any function found in htdocs/core/lib/*.lib files can be used.

'''To specify a requirement based on Dolibarr version number'''

For example, to make a condition based on requiring Dolibarr version > 3.5, you can use versioncompare and versiondolibarrarray found in admin.lib.php:

<syntaxhighlight lang="PHP">
if (versioncompare(versiondolibarrarray(), array(3,5,0)) > 0)
{
...
}
</syntaxhighlight>

=Mass exports/imports=

#[[Mass imports]]
#[[Module Exports En|Mass exports]]

=Interfaces and links with other applications=

#[[Interfaces Dolibarr toward foreign systems]] or Dolibarr toward Dolibarr (Dolibarr Triggers or Hooks)
#[[Interfaces from foreign systems toward Dolibarr]]

Integrate Dolibarr to automation platforms:

#[[Integration of Dolibarr to the Zapier automation platform]]
#[[Using Dolibarr node in the n8n automation platform]]
#[[Integration of Dolibarr to the Make automation platform]]

=FAQ=
All FAQs are available through the FAQ index page [[:Category:FAQ EN|FAQ EN]]
[[Category:Development]]

Developer documentation

2023-05-14T20:39:20Z

IPazu: /* Interfaces and links with other applications */

<seo metak="developer, development, documentation, guide, doc, tutorial, usage, help, api, coding, standard, rules" />


[[fr:Documentation_Développeur]]
[[es:Documentación_Desarrolladores]]
[[de:Entwickler_Dokumentation]]
[[zh:开发文档]]


This page is main index of documents relating to developer documentation. For user documentation [[User documentation|see here]].

=Development organization and tools=
This chapter contains global information that must be read before starting any development on Dolibarr.

#[[Dolibarr Project|Organization of project]]
#[[To known before to start|To be known before starting to develop]]
#[[Environment and development tools]]
#[[Dependencies and external libraries]]
#[[FAQ_Get,update_project_sources|Get or update sources of a development version]]

=Coding rules and best practices=

#[[Prerequisite|Prerequisites]]
#[[Language and development rules|Language and development rules (PHP, SQL, HTML)]]
#[[:Category:Table SQL|List of tables]]
#Tree structure of files and classes are available in the [http://doxygen.dolibarr.org/ doxygen generated documentation]

=List of modules=
Technical documentation on standard business modules is available in each module's developer documentation pages. Choose the appropriate page you are interested in:

*[[:Category:List of Modules (developer)‎|List of standard modules]]
*[[:Category:Complementary modules|List of complementary modules]]

=To develop a new module/addon for GUI=
This section describes how to develop a new module changing the Dolibarr user interface. This can be screens, themes, data, its own CSS stylesheet, source code or all of this.

Script development is not included in this section (this is described in the next chapter).

To develop your own module, check the [[Module development]] tutorial.

=To develop a batch or command line script=
This chapter describes how to develop command line scripts to execute tasks in Dolibarr (read, update data...).

Making modifications to the graphical user interface (GUI) is not included in this chapter. See the previous chapter for this.

To develop a script, like a cron script or a command line import tool to import data from an external source, you can have a look at the [[Script development]] page.

=Technical components of Dolibarr=
==Tree structure==
The path hierarchy of the current version files is available from the [http://doxygen.dolibarr.org/ doxygen generated documentation] (similar to generated "javadoc" documentation).

Paths to use to add new files by a new module are defined in the documentation to develop a new module (see [[Module development]]).

==Setup storage==
There are 3 places for Dolibarr setup parameters.

*Dolibarr technical setup parameters (authentication mode, database logins and storage area for files) are defined in only one setup file: <code>/conf/conf.php</code> .

:See [[Configuration file]] for more information.

*Global features parameters are stored in [[Table llx_const]].

:See the [[Constants]] page for more information.

*Feature parameters specific to a user are stored in [[Table llx_user_param]].

==Business objects==
See [[Business Objects]]

==Menus system==
See [[Menus system]]

==Tabs system==
See [[Tabs system]]

==Skins system==
See [[Skins]]

==Widget system==
See [[Widget system]]

==Authentication system==
See [[Authentication]]

==Permission system==
See [[Permissions En|Permissions]]

==Translation system==
See [[Translation system]]

==Error management==
See [[Error reporting|Error reporting]]

==Canvas system==
Canvas is a developer feature to replace screens to create, update or view a record (products, thirdparties, contacts, ...). For example, you can replace the input form used to create a new third party, or its editing form, or replace its viewing template.

See [[Canvas development]]

==Triggers system==
Triggers are a development feature to execute personalized code during a Dolibarr "business event" (creation of an invoice, deleting a user, update of third party, etc...), and only for a business event. To personalize code for other contexts, see the '''Hooks system''' chapter instead.

For triggers usage, see [[Interfaces Dolibarr toward foreign systems|this page]].

==Hooks system==
See [[Hooks system]]

==Variable substitution system==
See [[Variable substitution system]]

==Web services==
Dolibarr can be setup to provide some services.

See [[Module Web Services API REST (developer)]]

Note: The [[Module Web Services API SOAP (developer)]] is deprecated.

==Files/Documents storage management==
See [[Generated documents]]

==Numbering modules==
For each entity created in the application, Dolibarr assigns a reference. In order to adapt the reference to any use, Dolibarr use modules to define the reference generation rule. Several standard modules are supplied. Some are generic and are used to define the numbering mask (number on x characters, with or without prefix, including the date or not, etc.), which can meet most needs. However, there are still cases where the modules provided don't meet the needs. In this case it is necessary to develop a custom numbering module.

For more information, see [[Create numeration module|Create numbering module]].

==Document templates and documents generation==

More documentation about document generation from templates is available to [[Create a PDF document template]] or [[Create an ODT document template]].

==Extrafields==
See [[Extrafields]]

==Online payment system==
See [[Online payment system]]

==Other internal function==
There are many internal libraries your code can use.
You may find a lot of generic functions in the functions.lib.php, functions2.lib.php or admin.lib.php. Any function found in htdocs/core/lib/*.lib files can be used.

'''To specify a requirement based on Dolibarr version number'''

For example, to make a condition based on requiring Dolibarr version > 3.5, you can use versioncompare and versiondolibarrarray found in admin.lib.php:

<syntaxhighlight lang="PHP">
if (versioncompare(versiondolibarrarray(), array(3,5,0)) > 0)
{
...
}
</syntaxhighlight>

=Mass exports/imports=

#[[Mass imports]]
#[[Module Exports En|Mass exports]]

=Interfaces and links with other applications=

#[[Interfaces Dolibarr toward foreign systems]] or Dolibarr toward Dolibarr (Dolibarr Triggers or Hooks)
#[[Interfaces from foreign systems toward Dolibarr]]

Integrate Dolibarr to automation platforms

#[[Integration of Dolibarr to the Zapier automation platform]]
#[[Using Dolibarr node in the n8n automation platform]]
#[[Integration of Dolibarr to the Make automation platform]]

=FAQ=
All FAQs are available through the FAQ index page [[:Category:FAQ EN|FAQ EN]]
[[Category:Development]]

Developer documentation

2023-05-14T20:38:59Z

IPazu: /* Interfaces and links with other applications */

<seo metak="developer, development, documentation, guide, doc, tutorial, usage, help, api, coding, standard, rules" />


[[fr:Documentation_Développeur]]
[[es:Documentación_Desarrolladores]]
[[de:Entwickler_Dokumentation]]
[[zh:开发文档]]


This page is main index of documents relating to developer documentation. For user documentation [[User documentation|see here]].

=Development organization and tools=
This chapter contains global information that must be read before starting any development on Dolibarr.

#[[Dolibarr Project|Organization of project]]
#[[To known before to start|To be known before starting to develop]]
#[[Environment and development tools]]
#[[Dependencies and external libraries]]
#[[FAQ_Get,update_project_sources|Get or update sources of a development version]]

=Coding rules and best practices=

#[[Prerequisite|Prerequisites]]
#[[Language and development rules|Language and development rules (PHP, SQL, HTML)]]
#[[:Category:Table SQL|List of tables]]
#Tree structure of files and classes are available in the [http://doxygen.dolibarr.org/ doxygen generated documentation]

=List of modules=
Technical documentation on standard business modules is available in each module's developer documentation pages. Choose the appropriate page you are interested in:

*[[:Category:List of Modules (developer)‎|List of standard modules]]
*[[:Category:Complementary modules|List of complementary modules]]

=To develop a new module/addon for GUI=
This section describes how to develop a new module changing the Dolibarr user interface. This can be screens, themes, data, its own CSS stylesheet, source code or all of this.

Script development is not included in this section (this is described in the next chapter).

To develop your own module, check the [[Module development]] tutorial.

=To develop a batch or command line script=
This chapter describes how to develop command line scripts to execute tasks in Dolibarr (read, update data...).

Making modifications to the graphical user interface (GUI) is not included in this chapter. See the previous chapter for this.

To develop a script, like a cron script or a command line import tool to import data from an external source, you can have a look at the [[Script development]] page.

=Technical components of Dolibarr=
==Tree structure==
The path hierarchy of the current version files is available from the [http://doxygen.dolibarr.org/ doxygen generated documentation] (similar to generated "javadoc" documentation).

Paths to use to add new files by a new module are defined in the documentation to develop a new module (see [[Module development]]).

==Setup storage==
There are 3 places for Dolibarr setup parameters.

*Dolibarr technical setup parameters (authentication mode, database logins and storage area for files) are defined in only one setup file: <code>/conf/conf.php</code> .

:See [[Configuration file]] for more information.

*Global features parameters are stored in [[Table llx_const]].

:See the [[Constants]] page for more information.

*Feature parameters specific to a user are stored in [[Table llx_user_param]].

==Business objects==
See [[Business Objects]]

==Menus system==
See [[Menus system]]

==Tabs system==
See [[Tabs system]]

==Skins system==
See [[Skins]]

==Widget system==
See [[Widget system]]

==Authentication system==
See [[Authentication]]

==Permission system==
See [[Permissions En|Permissions]]

==Translation system==
See [[Translation system]]

==Error management==
See [[Error reporting|Error reporting]]

==Canvas system==
Canvas is a developer feature to replace screens to create, update or view a record (products, thirdparties, contacts, ...). For example, you can replace the input form used to create a new third party, or its editing form, or replace its viewing template.

See [[Canvas development]]

==Triggers system==
Triggers are a development feature to execute personalized code during a Dolibarr "business event" (creation of an invoice, deleting a user, update of third party, etc...), and only for a business event. To personalize code for other contexts, see the '''Hooks system''' chapter instead.

For triggers usage, see [[Interfaces Dolibarr toward foreign systems|this page]].

==Hooks system==
See [[Hooks system]]

==Variable substitution system==
See [[Variable substitution system]]

==Web services==
Dolibarr can be setup to provide some services.

See [[Module Web Services API REST (developer)]]

Note: The [[Module Web Services API SOAP (developer)]] is deprecated.

==Files/Documents storage management==
See [[Generated documents]]

==Numbering modules==
For each entity created in the application, Dolibarr assigns a reference. In order to adapt the reference to any use, Dolibarr use modules to define the reference generation rule. Several standard modules are supplied. Some are generic and are used to define the numbering mask (number on x characters, with or without prefix, including the date or not, etc.), which can meet most needs. However, there are still cases where the modules provided don't meet the needs. In this case it is necessary to develop a custom numbering module.

For more information, see [[Create numeration module|Create numbering module]].

==Document templates and documents generation==

More documentation about document generation from templates is available to [[Create a PDF document template]] or [[Create an ODT document template]].

==Extrafields==
See [[Extrafields]]

==Online payment system==
See [[Online payment system]]

==Other internal function==
There are many internal libraries your code can use.
You may find a lot of generic functions in the functions.lib.php, functions2.lib.php or admin.lib.php. Any function found in htdocs/core/lib/*.lib files can be used.

'''To specify a requirement based on Dolibarr version number'''

For example, to make a condition based on requiring Dolibarr version > 3.5, you can use versioncompare and versiondolibarrarray found in admin.lib.php:

<syntaxhighlight lang="PHP">
if (versioncompare(versiondolibarrarray(), array(3,5,0)) > 0)
{
...
}
</syntaxhighlight>

=Mass exports/imports=

#[[Mass imports]]
#[[Module Exports En|Mass exports]]

=Interfaces and links with other applications=

#[[Interfaces Dolibarr toward foreign systems]] or Dolibarr toward Dolibarr (Dolibarr Triggers or Hooks)
#[[Interfaces from foreign systems toward Dolibarr]]

===Integrate Dolibarr to automation platforms===

#[[Integration of Dolibarr to the Zapier automation platform]]
#[[Using Dolibarr node in the n8n automation platform]]
#[[Integration of Dolibarr to the Make automation platform]]

=FAQ=
All FAQs are available through the FAQ index page [[:Category:FAQ EN|FAQ EN]]
[[Category:Development]]

Developer documentation

2023-05-14T20:38:32Z

IPazu: /* Interfaces and links with other applications */

<seo metak="developer, development, documentation, guide, doc, tutorial, usage, help, api, coding, standard, rules" />


[[fr:Documentation_Développeur]]
[[es:Documentación_Desarrolladores]]
[[de:Entwickler_Dokumentation]]
[[zh:开发文档]]


This page is main index of documents relating to developer documentation. For user documentation [[User documentation|see here]].

=Development organization and tools=
This chapter contains global information that must be read before starting any development on Dolibarr.

#[[Dolibarr Project|Organization of project]]
#[[To known before to start|To be known before starting to develop]]
#[[Environment and development tools]]
#[[Dependencies and external libraries]]
#[[FAQ_Get,update_project_sources|Get or update sources of a development version]]

=Coding rules and best practices=

#[[Prerequisite|Prerequisites]]
#[[Language and development rules|Language and development rules (PHP, SQL, HTML)]]
#[[:Category:Table SQL|List of tables]]
#Tree structure of files and classes are available in the [http://doxygen.dolibarr.org/ doxygen generated documentation]

=List of modules=
Technical documentation on standard business modules is available in each module's developer documentation pages. Choose the appropriate page you are interested in:

*[[:Category:List of Modules (developer)‎|List of standard modules]]
*[[:Category:Complementary modules|List of complementary modules]]

=To develop a new module/addon for GUI=
This section describes how to develop a new module changing the Dolibarr user interface. This can be screens, themes, data, its own CSS stylesheet, source code or all of this.

Script development is not included in this section (this is described in the next chapter).

To develop your own module, check the [[Module development]] tutorial.

=To develop a batch or command line script=
This chapter describes how to develop command line scripts to execute tasks in Dolibarr (read, update data...).

Making modifications to the graphical user interface (GUI) is not included in this chapter. See the previous chapter for this.

To develop a script, like a cron script or a command line import tool to import data from an external source, you can have a look at the [[Script development]] page.

=Technical components of Dolibarr=
==Tree structure==
The path hierarchy of the current version files is available from the [http://doxygen.dolibarr.org/ doxygen generated documentation] (similar to generated "javadoc" documentation).

Paths to use to add new files by a new module are defined in the documentation to develop a new module (see [[Module development]]).

==Setup storage==
There are 3 places for Dolibarr setup parameters.

*Dolibarr technical setup parameters (authentication mode, database logins and storage area for files) are defined in only one setup file: <code>/conf/conf.php</code> .

:See [[Configuration file]] for more information.

*Global features parameters are stored in [[Table llx_const]].

:See the [[Constants]] page for more information.

*Feature parameters specific to a user are stored in [[Table llx_user_param]].

==Business objects==
See [[Business Objects]]

==Menus system==
See [[Menus system]]

==Tabs system==
See [[Tabs system]]

==Skins system==
See [[Skins]]

==Widget system==
See [[Widget system]]

==Authentication system==
See [[Authentication]]

==Permission system==
See [[Permissions En|Permissions]]

==Translation system==
See [[Translation system]]

==Error management==
See [[Error reporting|Error reporting]]

==Canvas system==
Canvas is a developer feature to replace screens to create, update or view a record (products, thirdparties, contacts, ...). For example, you can replace the input form used to create a new third party, or its editing form, or replace its viewing template.

See [[Canvas development]]

==Triggers system==
Triggers are a development feature to execute personalized code during a Dolibarr "business event" (creation of an invoice, deleting a user, update of third party, etc...), and only for a business event. To personalize code for other contexts, see the '''Hooks system''' chapter instead.

For triggers usage, see [[Interfaces Dolibarr toward foreign systems|this page]].

==Hooks system==
See [[Hooks system]]

==Variable substitution system==
See [[Variable substitution system]]

==Web services==
Dolibarr can be setup to provide some services.

See [[Module Web Services API REST (developer)]]

Note: The [[Module Web Services API SOAP (developer)]] is deprecated.

==Files/Documents storage management==
See [[Generated documents]]

==Numbering modules==
For each entity created in the application, Dolibarr assigns a reference. In order to adapt the reference to any use, Dolibarr use modules to define the reference generation rule. Several standard modules are supplied. Some are generic and are used to define the numbering mask (number on x characters, with or without prefix, including the date or not, etc.), which can meet most needs. However, there are still cases where the modules provided don't meet the needs. In this case it is necessary to develop a custom numbering module.

For more information, see [[Create numeration module|Create numbering module]].

==Document templates and documents generation==

More documentation about document generation from templates is available to [[Create a PDF document template]] or [[Create an ODT document template]].

==Extrafields==
See [[Extrafields]]

==Online payment system==
See [[Online payment system]]

==Other internal function==
There are many internal libraries your code can use.
You may find a lot of generic functions in the functions.lib.php, functions2.lib.php or admin.lib.php. Any function found in htdocs/core/lib/*.lib files can be used.

'''To specify a requirement based on Dolibarr version number'''

For example, to make a condition based on requiring Dolibarr version > 3.5, you can use versioncompare and versiondolibarrarray found in admin.lib.php:

<syntaxhighlight lang="PHP">
if (versioncompare(versiondolibarrarray(), array(3,5,0)) > 0)
{
...
}
</syntaxhighlight>

=Mass exports/imports=

#[[Mass imports]]
#[[Module Exports En|Mass exports]]

=Interfaces and links with other applications=

#[[Interfaces Dolibarr toward foreign systems]] or Dolibarr toward Dolibarr (Dolibarr Triggers or Hooks)
#[[Interfaces from foreign systems toward Dolibarr]]

== Integrate Dolibarr to automation platforms ==

# [[Integration of Dolibarr to the Zapier automation platform]]
# [[Using Dolibarr node in the n8n automation platform]]
# [[Integration of Dolibarr to the Make automation platform]]

=FAQ=
All FAQs are available through the FAQ index page [[:Category:FAQ EN|FAQ EN]]
[[Category:Development]]

Integration of Dolibarr to the Make automation platform

2023-05-14T20:34:51Z

IPazu: /* Example of module to create events in the Dolibarr calendar */

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.
==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

*You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
*You have access to a user account with administrator rights
*You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
*You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Make application=

#Go to https://eu1.make.com and log into your user account
#Go to the <code>My Apps</code> tab
#Click on <code>Create a new app</code>. You can call it <code>Dolibarr</code>. This instance will contain a connection and several modules that will implement specific features such as '''creation of a task''' or '''creation of an event''' for instance.

In the <code>Base</code> tab, you just have to write

<syntaxhighlight lang="json">{}</syntaxhighlight>

=Configure authentication=

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the <code>connection</code> tab of the Make application.

This tab has two sub-tabs : <code>Parameters</code> tab and <code>Communication</code> tab.

''NB : The applications that a user can create on Make are written in <code>json</code>.''


==a) <code>Parameters</code> tab==

There are three required parameters for the connection : the ''Dolibarr API key'', the ''URL of the Dolibarr instance'' (<code>https://yourdolibarrurl</code> for instance) and your ''user ID''. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

<syntaxhighlight lang="json">[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


==b) <code>Communication</code> tab==

The following code specifies the account validation process.

<syntaxhighlight lang="json">{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=Create an action module=


==Example of module to create events in the Dolibarr calendar==

As a reminder, the goal is to implement the following use case : ''As soon as you receive a mail on an Email box, report it in Dolibarr events''

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call <code>Creation of an event</code>. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.


===a) <code>Communication</code> tab===

This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Explanation of the different required fields :'''

{| class="wikitable"
|-
!API field
!Description
!Type
!Possible value
|-
|type
|Event type
|text
|Email reception
|-
|label
|Event label
|text
|New emails received
|-
|type_code
|Dolibarr event type code
|number
|'''6'''
|-
|userownerid
|Dolibarr user that create the event
|number
|7
|-
|email_sender
|Login of the sender
|text
|jdoe
|-
|email_from
|Email address of the sender
|text
|john@doe.org
|-
|status
|
|number
|0
|-
|percentage
|Event progress
|number between -1 (N/A) and 100
| -1
|-
|date_creation
|Date of creation of the event
|date
|2023-03-12T18:25:43-05:00
|-
|datep
|Start date of the event
|date
|2023-03-12T18:25:43-05:00
|-
|datef
|End date of the event
|date
|2023-03-12T18:25:43-05:00
|}

The type_code “6” corresponds to the event type “Email reception”.

NB : Bold parameters are compulsory for this scenario

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


===b) <code>Static parameters</code> tab===

<syntaxhighlight lang="json">[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


===c) <code>Mappable parameters</code> tab===

The following parameters are mappable, that means it must be completed by the user.

<syntaxhighlight lang="json">[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


===d) <code>Interface</code> tab===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>

Your integration is now ready to be used.


==1st scenario : Report an email in Dolibarr events==


===1) Create a new scenario===

#Click on the <code>Scenarios</code> tab of the left-hand menu
#Click on the <code>Create a new scenario</code> button at the top right


===2) Email scenario configuration===


====2.a) Email scenario initialization====

#Click on the <code>+</code> symbol to add a module
#Select the <code>Email</code> module, that you can search it at the bottom of the drop-down list.
#Select the <code>Watch Emails</code> trigger of this module. To set up the Email module, you should click on it. A configuration window will appear.


====2.b) Email module configuration====

#First, choose the '''connection''' : select the IMAP connection that you configured (named ''My others IMAP connection'')
#Select the <code>/INBOX</code> '''folder'''
#Select the <code>Only unread mails</code> '''criteria'''
#Click on <code>No</code> for <code>Mark message(s) as read when fetched</code> unless you want to mark messages as read.
#Don’t forget to click on <code>OK</code> at the bottom right of the window.


====2.c) Dolibarr module configuration====

Add the Dolibarr application by selecting the <code>Create an event</code> action that you created previously.

In the end, your screen should look like this :

<div class="figure">

[[File:Make mail.png|thumb]]
 

</div>
Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

#Select the right '''connection'''
#Select the '''Email address''' with <code>1. Sender Email Address</code>
#Select the '''Name''' with <code>1. Sender Email Name</code>
#Select the '''Mail label''' with <code>"1. Sender Email Name" : "1. Subject"</code>
#Select the '''Received on''' field : <code>1.Date</code>
#Choose the '''Type''' : 1

<div class="figure">

[[File:Email parameters.png|thumb|Make email parameters]]
 

</div>
<ol start="7" style="list-style-type: decimal;">
<li>Click on <code>OK</code></li></ol>

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


==Example of a module implementation to create a project task on Dolibarr==

As a reminder, the goal is to implement the following use case :

<blockquote>“Creation of a project task in Dolibarr once an issue is created on Github”
</blockquote>
In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (<code>Projects</code> tab, <code>Tasks/Activities</code> section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module <code>Projects</code> of Dolibarr.

'''Required fields :''' There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the <code>Task list</code> columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

{| class="wikitable"
|-
!API field
!Description
!Type
!Possible value
|-
|ref
|Task reference
|text
|K2304-0005
|-
|label
|Task label
|text
|
|-
|fk_project
|Project reference
|number
|2
|-
|date_start
|Start date
|date
|2023-03-12T18:25:43-05:00
|-
|date_end
|End date
|date
|2023-03-12T18:25:43-05:00
|-
|date_creation
|Date of creation
|date
|
|-
|user_creation
|User that created the task
|text
|
|-
|planned_workload
|Estimated completion time (in seconds)
|number
|8400
|-
|duration_effective
|Percentage of actual progress
|number
|0
|-
|fk_user_creat
|ID of the user that created the event
|number
|7
|-
|progress
|Progress of the project (in %)
|number between 0 and 100
|50
|}

Complete the following tabs as follows :


===a) <code>Communication</code> tab===

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Setting up the Github OAuth connection :'''

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

#Click the <code>Add button</code> next to the <code>Connection</code> field. Select the '''Connection type''' as OAuth.
#Optional: In the '''Connection name''' field, enter a name for the connection.
#Click on <code>Save</code>.
#a Github window should open. Confirm the access by clicking Authorize.

'''NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.'''

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


===b) <code>Static parameters</code> tab===

<syntaxhighlight lang="json"> {}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


===c) <code>Mappable parameters</code> tab===

<syntaxhighlight lang="json">[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


===d) <code>Interface</code> tab===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

-----


==2nd scenario : Create a task in Dolibarr when a new issue is created on Github==


===1) Create a new scenario===

#Click on the <code>Scenarios</code> tab of the left-hand menu
#Click on the <code>Create a new scenario</code> button at the top right


===2) Github scenario configuration===


====2.a) Github scenario initialization====

#Click on the <code>+</code> symbol to add a module
#Select the <code>Github</code> module, that you can search it at the bottom of the drop-down list.
#Select the <code>Watch issues</code> trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.


====2.b) Github module configuration====

#First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
#Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the '''I want to watch''' field.
#Select the repository from which we want to launch the scenario on the '''repository''' field. All the repositories of the Github account will be displayed in a drop-down list.
#Choose the '''maximum number of returned issues''' : 10 for example
#Fill the '''watch''' field : select <code>only new issues</code>
#Then, select the '''filter''' : <code>all issues</code>(for example)
#Finally, select the '''state''' : <code>only opened issues</code>

In the end, your screen should look like this :

<div class="figure">

[[File:Make github.png|thumb]]
 

</div>

====2.c) Dolibarr module configuration====

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

#'''Task created by''' : <code>1.Creator</code>
#'''Name of task''' : <code>1.Title</code>
#'''Date of creation''' : <code>Date created</code>
#'''Date of start''' : <code>Date created</code>
#'''Project ID''' : <code>1</code>
#'''Date of end''' : <code>Date updated</code>

In the end, the window should look like :

<div class="figure">

[[File:Make github parameters.png|thumb|Make github parameters]]
 

</div>
Click on <code>OK</code>.

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


==3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar==

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select <code>Watch Events</code> among the several propositions. After, in the <code>Connection</code> section, add a connection with your Google account and accept the terms. In the <code>Calendar</code> section, choose your calendar account. Then, in the <code>Watch Events</code> section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

*'''Event name''' : <code>1. Summary</code>
*'''Start time''' : <code>1. Start</code>
*'''End time''' : <code>1. End</code>
*'''Location''' : <code>1. Location</code>
*'''Description''' : <code>1. Description</code>
*'''Email adress''' : <code>1. Organizer: Email</code>

You normally have the sections filled as follows :

<div class="figure">

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

</div>
The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


=Help for developpers=


==Viewing the code on VSCode==

To view the code written on the Make website on VScode, it is possible to install the <code>Make Apps SDK</code> extension. More details can be found on the [https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code extension configuration page].

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].

Integration of Dolibarr to the Zapier automation platform

2023-05-14T20:25:46Z

IPazu: minor changes

{{TemplateDocDevEn}}


==Preamble==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Zapier integration=

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin. You will be asked for different information:

* A name for your integration
* A description
* A website URL
* A logo
* The audience targeted by your integration (public or private)
* Your role in the development of the integration (employee, hired, independent)
* The category of your integration
<div class="figure">

[[File:01-new-integration.png|thumb|Form in the Zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


=Configure authentication=

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

==Step 1: Configuring Authentication Fields==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>Instance URL</code>
|-
|Key
|<code>host</code>
|-
|Required
|✅ Yes
|-
|Type
|String
|-
|Help Text
|<code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>API Key</code>
|-
|Key
|<code>api_key</code>
|-
|Required
|✅ Yes
|-
|Type
|Password
|-
|Help Text
|<code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


==Step 2: Configuring the token exchange request==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


==Step 3: Configuring the test request==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <syntaxhighlight>
{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}}
</syntaxhighlight> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


==Step 4: Testing the connection==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in Zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index</code> endpoint. <code>php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


=Create a trigger=

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


=Create an action=

*'''Example case:''' Create an event in the Dolibarr calendar
*'''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


==Step 1: Configuring the action==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
!Field
!Value
|-
|Type
|Create
|-
|Key
|<code>create_event</code>
|-
|Name
|<code>Create an event</code>
|-
|Noun
|<code>Event</code>
|-
|Description
|<code>Create an event in the Dolibarr calendar</code>
|-
|Visibility Options
|Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


==Step 2: Configuring the fields==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
!Field
!Label
!Key
!Type
!Required
|-
|Name
|<code>Event name</code>
|<code>label</code>
|String
|✅ Yes
|-
|Start date
|<code>Start date</code>
|<code>datep</code>
|DateTime
|✅ Yes
|-
|End date
|<code>End date</code>
|<code>datef</code>
|DateTime
|❌ No
|-
|Location
|<code>Location</code>
|<code>location</code>
|String
|❌ No
|-
|Description
|<code>Description</code>
|<code>note_private</code>
|Text
|❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

==Step 3: API configuration==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


===API request configuration===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

===Testing the request to the API===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
!Field
!Value
|-
|label
|<code>Test event</code>
|-
|datep
|<code>2023-05-01T16:00:00.000Z</code>
|-
|datef
|<code>2023-05-01T18:00:00.000Z</code>
|-
|location
|<code>Test room</code>
|-
|note_private
|<code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

===Configuration of the data returned by the API===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


==Step 4: Testing the action in a “Zap”==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


===Trigger setup===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


===Action Setup===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
!Field
!Google Calendar field
|-
|Event name
|Summary
|-
|Start date
|Event begins (pretty)
|-
|End date
|Event ends (pretty)
|-
|Location
|Location
|-
|Description
|Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in Zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


=Validate and publish the integration=

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


=Go further=

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


=Conclusion=

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].

Integration of Dolibarr to the Make automation platform

2023-05-14T19:35:13Z

IPazu: removing title and fixing lists

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.
==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Make application=

#Go to https://eu1.make.com and log into your user account
#Go to the <code>My Apps</code> tab
#Click on <code>Create a new app</code>. You can call it <code>Dolibarr</code>. This instance will contain a connection and several modules that will implement specific features such as '''creation of a task''' or '''creation of an event''' for instance.

In the <code>Base</code> tab, you just have to write

<syntaxhighlight lang="json">{}</syntaxhighlight>

=Configure authentication=

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the <code>connection</code> tab of the Make application.

This tab has two sub-tabs : <code>Parameters</code> tab and <code>Communication</code> tab.

''NB : The applications that a user can create on Make are written in <code>json</code>.''


==a) <code>Parameters</code> tab==

There are three required parameters for the connection : the ''Dolibarr API key'', the ''URL of the Dolibarr instance'' (<code>https://yourdolibarrurl</code> for instance) and your ''user ID''. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

<syntaxhighlight lang="json">[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


==b) <code>Communication</code> tab==

The following code specifies the account validation process.

<syntaxhighlight lang="json">{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=Create an action module=


==Example of module to create events in the Dolibarr calendar==

As a reminder, the goal is to implement the following use case : >“As soon as you receive a mail on an Email box, report it in Dolibarr events”

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call <code>Creation of an event</code>. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.


===a) <code>Communication</code> tab===

This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Explanation of the different required fields :'''

{| class="wikitable"
|-
!API field
!Description
!Type
!Possible value
|-
|type
|Event type
|text
|Email reception
|-
|label
|Event label
|text
|New emails received
|-
|type_code
|Dolibarr event type code
|number
|'''6'''
|-
|userownerid
|Dolibarr user that create the event
|number
|7
|-
|email_sender
|Login of the sender
|text
|jdoe
|-
|email_from
|Email address of the sender
|text
|john@doe.org
|-
|status
|
|number
|0
|-
|percentage
|Event progress
|number between -1 (N/A) and 100
| -1
|-
|date_creation
|Date of creation of the event
|date
|2023-03-12T18:25:43-05:00
|-
|datep
|Start date of the event
|date
|2023-03-12T18:25:43-05:00
|-
|datef
|End date of the event
|date
|2023-03-12T18:25:43-05:00
|}

The type_code “6” corresponds to the event type “Email reception”.

NB : Bold parameters are compulsory for this scenario

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


===b) <code>Static parameters</code> tab===

<syntaxhighlight lang="json">[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


===c) <code>Mappable parameters</code> tab===

The following parameters are mappable, that means it must be completed by the user.

<syntaxhighlight lang="json">[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


===d) <code>Interface</code> tab===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>

Your integration is now ready to be used.


==1st scenario : Report an email in Dolibarr events==


===1) Create a new scenario===

#Click on the <code>Scenarios</code> tab of the left-hand menu
#Click on the <code>Create a new scenario</code> button at the top right


===2) Email scenario configuration===


====2.a) Email scenario initialization====

#Click on the <code>+</code> symbol to add a module
#Select the <code>Email</code> module, that you can search it at the bottom of the drop-down list.
#Select the <code>Watch Emails</code> trigger of this module. To set up the Email module, you should click on it. A configuration window will appear.


====2.b) Email module configuration====

#First, choose the '''connection''' : select the IMAP connection that you configured (named ''My others IMAP connection'')
#Select the <code>/INBOX</code> '''folder'''
#Select the <code>Only unread mails</code> '''criteria'''
#Click on <code>No</code> for <code>Mark message(s) as read when fetched</code> unless you want to mark messages as read.
#Don’t forget to click on <code>OK</code> at the bottom right of the window.


====2.c) Dolibarr module configuration====

Add the Dolibarr application by selecting the <code>Create an event</code> action that you created previously.

In the end, your screen should look like this :

<div class="figure">

[[File:Make mail.png|thumb]]
 

</div>
Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

#Select the right '''connection'''
#Select the '''Email address''' with <code>1. Sender Email Address</code>
#Select the '''Name''' with <code>1. Sender Email Name</code>
#Select the '''Mail label''' with <code>"1. Sender Email Name" : "1. Subject"</code>
#Select the '''Received on''' field : <code>1.Date</code>
#Choose the '''Type''' : 1

<div class="figure">

[[File:Email parameters.png|thumb|Make email parameters]]
 

</div>
<ol start="7" style="list-style-type: decimal;">
<li>Click on <code>OK</code></li></ol>

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


==Example of a module implementation to create a project task on Dolibarr==

As a reminder, the goal is to implement the following use case :

<blockquote>“Creation of a project task in Dolibarr once an issue is created on Github”
</blockquote>
In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (<code>Projects</code> tab, <code>Tasks/Activities</code> section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module <code>Projects</code> of Dolibarr.

'''Required fields :''' There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the <code>Task list</code> columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

{| class="wikitable"
|-
!API field
!Description
!Type
!Possible value
|-
|ref
|Task reference
|text
|K2304-0005
|-
|label
|Task label
|text
|
|-
|fk_project
|Project reference
|number
|2
|-
|date_start
|Start date
|date
|2023-03-12T18:25:43-05:00
|-
|date_end
|End date
|date
|2023-03-12T18:25:43-05:00
|-
|date_creation
|Date of creation
|date
|
|-
|user_creation
|User that created the task
|text
|
|-
|planned_workload
|Estimated completion time (in seconds)
|number
|8400
|-
|duration_effective
|Percentage of actual progress
|number
|0
|-
|fk_user_creat
|ID of the user that created the event
|number
|7
|-
|progress
|Progress of the project (in %)
|number between 0 and 100
|50
|}

Complete the following tabs as follows :


===a) <code>Communication</code> tab===

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Setting up the Github OAuth connection :'''

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

#Click the <code>Add button</code> next to the <code>Connection</code> field. Select the '''Connection type''' as OAuth.
#Optional: In the '''Connection name''' field, enter a name for the connection.
#Click on <code>Save</code>.
#a Github window should open. Confirm the access by clicking Authorize.

'''NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.'''

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


===b) <code>Static parameters</code> tab===

<syntaxhighlight lang="json"> {}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


===c) <code>Mappable parameters</code> tab===

<syntaxhighlight lang="json">[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


===d) <code>Interface</code> tab===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

-----


==2nd scenario : Create a task in Dolibarr when a new issue is created on Github==


===1) Create a new scenario===

#Click on the <code>Scenarios</code> tab of the left-hand menu
#Click on the <code>Create a new scenario</code> button at the top right


===2) Github scenario configuration===


====2.a) Github scenario initialization====

#Click on the <code>+</code> symbol to add a module
#Select the <code>Github</code> module, that you can search it at the bottom of the drop-down list.
#Select the <code>Watch issues</code> trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.


====2.b) Github module configuration====

#First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
#Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the '''I want to watch''' field.
#Select the repository from which we want to launch the scenario on the '''repository''' field. All the repositories of the Github account will be displayed in a drop-down list.
#Choose the '''maximum number of returned issues''' : 10 for example
#Fill the '''watch''' field : select <code>only new issues</code>
#Then, select the '''filter''' : <code>all issues</code>(for example)
#Finally, select the '''state''' : <code>only opened issues</code>

In the end, your screen should look like this :

<div class="figure">

[[File:Make github.png|thumb]]
 

</div>

====2.c) Dolibarr module configuration====

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

#'''Task created by''' : <code>1.Creator</code>
#'''Name of task''' : <code>1.Title</code>
#'''Date of creation''' : <code>Date created</code>
#'''Date of start''' : <code>Date created</code>
#'''Project ID''' : <code>1</code>
#'''Date of end''' : <code>Date updated</code>

In the end, the window should look like :

<div class="figure">

[[File:Make github parameters.png|thumb|Make github parameters]]
 

</div>
Click on <code>OK</code>.

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


==3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar==

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select <code>Watch Events</code> among the several propositions. After, in the <code>Connection</code> section, add a connection with your Google account and accept the terms. In the <code>Calendar</code> section, choose your calendar account. Then, in the <code>Watch Events</code> section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

*'''Event name''' : <code>1. Summary</code>
*'''Start time''' : <code>1. Start</code>
*'''End time''' : <code>1. End</code>
*'''Location''' : <code>1. Location</code>
*'''Description''' : <code>1. Description</code>
*'''Email adress''' : <code>1. Organizer: Email</code>

You normally have the sections filled as follows :

<div class="figure">

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

</div>
The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


=Help for developpers=


==Viewing the code on VSCode==

To view the code written on the Make website on VScode, it is possible to install the <code>Make Apps SDK</code> extension. More details can be found on the [https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code extension configuration page].

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].

Integration of Dolibarr to the Zapier automation platform

2023-05-14T19:33:29Z

IPazu: removing title

{{TemplateDocDevEn}}


==Preamble==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Zapier integration=

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin. You will be asked for different information:

* A name for your integration
* A description
* A website URL
* A logo
* The audience targeted by your integration (public or private)
* Your role in the development of the integration (employee, hired, independent)
* The category of your integration
<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


=Configure authentication=

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

==Step 1: Configuring Authentication Fields==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>Instance URL</code>
|-
|Key
|<code>host</code>
|-
|Required
|✅ Yes
|-
|Type
|String
|-
|Help Text
|<code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>API Key</code>
|-
|Key
|<code>api_key</code>
|-
|Required
|✅ Yes
|-
|Type
|Password
|-
|Help Text
|<code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


==Step 2: Configuring the token exchange request==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


==Step 3: Configuring the test request==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: {{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}}) which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


==Step 4: Testing the connection==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index</code> endpoint. <code>php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


=Create a trigger=

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


=Create an action=

*'''Example case:''' Create an event in the Dolibarr calendar
*'''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


==Step 1: Configuring the action==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
!Field
!Value
|-
|Type
|Create
|-
|Key
|<code>create_event</code>
|-
|Name
|<code>Create an event</code>
|-
|Noun
|<code>Event</code>
|-
|Description
|<code>Create an event in the Dolibarr calendar</code>
|-
|Visibility Options
|Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


==Step 2: Configuring the fields==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
!Field
!Label
!Key
!Type
!Required
|-
|Name
|<code>Event name</code>
|<code>label</code>
|String
|✅ Yes
|-
|Start date
|<code>Start date</code>
|<code>datep</code>
|DateTime
|✅ Yes
|-
|End date
|<code>End date</code>
|<code>datef</code>
|DateTime
|❌ No
|-
|Location
|<code>Location</code>
|<code>location</code>
|String
|❌ No
|-
|Description
|<code>Description</code>
|<code>note_private</code>
|Text
|❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

==Step 3: API configuration==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


===API request configuration===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

===Testing the request to the API===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
!Field
!Value
|-
|label
|<code>Test event</code>
|-
|datep
|<code>2023-05-01T16:00:00.000Z</code>
|-
|datef
|<code>2023-05-01T18:00:00.000Z</code>
|-
|location
|<code>Test room</code>
|-
|note_private
|<code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

===Configuration of the data returned by the API===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


==Step 4: Testing the action in a “Zap”==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


===Trigger setup===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


===Action Setup===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
!Field
!Google Calendar field
|-
|Event name
|Summary
|-
|Start date
|Event begins (pretty)
|-
|End date
|Event ends (pretty)
|-
|Location
|Location
|-
|Description
|Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


=Validate and publish the integration=

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


=Go further=

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


=Conclusion=

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].

Integration of Dolibarr to the Zapier automation platform

2023-05-14T19:32:40Z

IPazu: fixing bundle and some minor changes

{{TemplateDocDevEn}}


=Integration of Dolibarr to the Zapier automation platform=


==Preamble==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Zapier integration=

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin. You will be asked for different information:

* A name for your integration
* A description
* A website URL
* A logo
* The audience targeted by your integration (public or private)
* Your role in the development of the integration (employee, hired, independent)
* The category of your integration
<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


=Configure authentication=

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

==Step 1: Configuring Authentication Fields==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>Instance URL</code>
|-
|Key
|<code>host</code>
|-
|Required
|✅ Yes
|-
|Type
|String
|-
|Help Text
|<code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>API Key</code>
|-
|Key
|<code>api_key</code>
|-
|Required
|✅ Yes
|-
|Type
|Password
|-
|Help Text
|<code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


==Step 2: Configuring the token exchange request==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


==Step 3: Configuring the test request==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: {{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}}) which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


==Step 4: Testing the connection==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index</code> endpoint. <code>php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


=Create a trigger=

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


=Create an action=

*'''Example case:''' Create an event in the Dolibarr calendar
*'''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


==Step 1: Configuring the action==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
!Field
!Value
|-
|Type
|Create
|-
|Key
|<code>create_event</code>
|-
|Name
|<code>Create an event</code>
|-
|Noun
|<code>Event</code>
|-
|Description
|<code>Create an event in the Dolibarr calendar</code>
|-
|Visibility Options
|Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


==Step 2: Configuring the fields==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
!Field
!Label
!Key
!Type
!Required
|-
|Name
|<code>Event name</code>
|<code>label</code>
|String
|✅ Yes
|-
|Start date
|<code>Start date</code>
|<code>datep</code>
|DateTime
|✅ Yes
|-
|End date
|<code>End date</code>
|<code>datef</code>
|DateTime
|❌ No
|-
|Location
|<code>Location</code>
|<code>location</code>
|String
|❌ No
|-
|Description
|<code>Description</code>
|<code>note_private</code>
|Text
|❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

==Step 3: API configuration==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


===API request configuration===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

===Testing the request to the API===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
!Field
!Value
|-
|label
|<code>Test event</code>
|-
|datep
|<code>2023-05-01T16:00:00.000Z</code>
|-
|datef
|<code>2023-05-01T18:00:00.000Z</code>
|-
|location
|<code>Test room</code>
|-
|note_private
|<code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

===Configuration of the data returned by the API===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


==Step 4: Testing the action in a “Zap”==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


===Trigger setup===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


===Action Setup===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
!Field
!Google Calendar field
|-
|Event name
|Summary
|-
|Start date
|Event begins (pretty)
|-
|End date
|Event ends (pretty)
|-
|Location
|Location
|-
|Description
|Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


=Validate and publish the integration=

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


=Go further=

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


=Conclusion=

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


=Licence=

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

Integration of Dolibarr to the Zapier automation platform

2023-05-14T19:29:09Z

IPazu: fixing list format

{{TemplateDocDevEn}}


=Integration of Dolibarr to the Zapier automation platform=

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]


==Preamble==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


==Prerequisites==

The following tutorial assumes that you have completed the following prerequisites:

* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation])
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


=Create the Zapier integration=

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin. You will be asked for different information:

* A name for your integration
* A description
* A website URL
* A logo
* The audience targeted by your integration (public or private)
* Your role in the development of the integration (employee, hired, independent)
* The category of your integration
<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


=Configure authentication=

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

==Step 1: Configuring Authentication Fields==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>Instance URL</code>
|-
|Key
|<code>host</code>
|-
|Required
|✅ Yes
|-
|Type
|String
|-
|Help Text
|<code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
!Field
!Value
|-
|Field Type
|<code>Field</code>
|-
|Label
|<code>API Key</code>
|-
|Key
|<code>api_key</code>
|-
|Required
|✅ Yes
|-
|Type
|Password
|-
|Help Text
|<code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


==Step 2: Configuring the token exchange request==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


==Step 3: Configuring the test request==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <code>{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}})</code> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


==Step 4: Testing the connection==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index endpoint. php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


=Create a trigger=

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


=Create an action=

*'''Example case:''' Create an event in the Dolibarr calendar
*'''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


==Step 1: Configuring the action==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
!Field
!Value
|-
|Type
|Create
|-
|Key
|<code>create_event</code>
|-
|Name
|<code>Create an event</code>
|-
|Noun
|<code>Event</code>
|-
|Description
|<code>Create an event in the Dolibarr calendar</code>
|-
|Visibility Options
|Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


==Step 2: Configuring the fields==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
!Field
!Label
!Key
!Type
!Required
|-
|Name
|<code>Event name</code>
|<code>label</code>
|String
|✅ Yes
|-
|Start date
|<code>Start date</code>
|<code>datep</code>
|DateTime
|✅ Yes
|-
|End date
|<code>End date</code>
|<code>datef</code>
|DateTime
|❌ No
|-
|Location
|<code>Location</code>
|<code>location</code>
|String
|❌ No
|-
|Description
|<code>Description</code>
|<code>note_private</code>
|Text
|❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

==Step 3: API configuration==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


===API request configuration===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

===Testing the request to the API===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
!Field
!Value
|-
|label
|<code>Test event</code>
|-
|datep
|<code>2023-05-01T16:00:00.000Z</code>
|-
|datef
|<code>2023-05-01T18:00:00.000Z</code>
|-
|location
|<code>Test room</code>
|-
|note_private
|<code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

===Configuration of the data returned by the API===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


==Step 4: Testing the action in a “Zap”==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


===Trigger setup===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


===Action Setup===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
!Field
!Google Calendar field
|-
|Event name
|Summary
|-
|Start date
|Event begins (pretty)
|-
|End date
|Event ends (pretty)
|-
|Location
|Location
|-
|Description
|Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


=Validate and publish the integration=

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


=Go further=

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


=Conclusion=

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


=Credits=

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


=Licence=

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

Integration of Dolibarr to the Zapier automation platform

2023-05-14T19:28:14Z

IPazu: fixing bundle and lists

{{TemplateDocDevEn}}


== Preamble ==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Zapier integration =

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin.

You will be asked for different information: * a name for your integration * a description * a website URL * a logo * the audience targeted by your integration (public or private) * your role in the development of the integration (employee, hired, independent) * the category of your integration

<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


= Configure authentication =

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

== Step 1: Configuring Authentication Fields ==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>Instance URL</code>
|-
| Key
| <code>host</code>
|-
| Required
| ✅ Yes
|-
| Type
| String
|-
| Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>API Key</code>
|-
| Key
| <code>api_key</code>
|-
| Required
| ✅ Yes
|-
| Type
| Password
|-
| Help Text
| <code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


== Step 2: Configuring the token exchange request ==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


== Step 3: Configuring the test request ==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>

You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: {{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}}) which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


== Step 4: Testing the connection ==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index</code> endpoint. <code>php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


= Create a trigger =

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


= Create an action =

* '''Example case:''' Create an event in the Dolibarr calendar
* '''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


== Step 1: Configuring the action ==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
! Field
! Value
|-
| Type
| Create
|-
| Key
| <code>create_event</code>
|-
| Name
| <code>Create an event</code>
|-
| Noun
| <code>Event</code>
|-
| Description
| <code>Create an event in the Dolibarr calendar</code>
|-
| Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


== Step 2: Configuring the fields ==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
! Field
! Label
! Key
! Type
! Required
|-
| Name
| <code>Event name</code>
| <code>label</code>
| String
| ✅ Yes
|-
| Start date
| <code>Start date</code>
| <code>datep</code>
| DateTime
| ✅ Yes
|-
| End date
| <code>End date</code>
| <code>datef</code>
| DateTime
| ❌ No
|-
| Location
| <code>Location</code>
| <code>location</code>
| String
| ❌ No
|-
| Description
| <code>Description</code>
| <code>note_private</code>
| Text
| ❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

== Step 3: API configuration ==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


=== API request configuration ===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

=== Testing the request to the API ===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
! Field
! Value
|-
| label
| <code>Test event</code>
|-
| datep
| <code>2023-05-01T16:00:00.000Z</code>
|-
| datef
| <code>2023-05-01T18:00:00.000Z</code>
|-
| location
| <code>Test room</code>
|-
| note_private
| <code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

=== Configuration of the data returned by the API ===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


== Step 4: Testing the action in a “Zap” ==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


=== Trigger setup ===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


=== Action Setup ===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
! Field
! Google Calendar field
|-
| Event name
| Summary
|-
| Start date
| Event begins (pretty)
|-
| End date
| Event ends (pretty)
|-
| Location
| Location
|-
| Description
| Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


= Validate and publish the integration =

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


= Go further =

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


= Conclusion =

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

Integration of Dolibarr to the Make automation platform

2023-05-14T19:06:24Z

IPazu: IPazu moved page Integration of Dolibarr to the make automation platform to Integration of Dolibarr to the Make automation platform

{{TemplateDocDevEn}}


= Integration of Dolibarr to the Make automation platform =

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Make application =

# Go to https://eu1.make.com and log into your user account
# Go to the <code>My Apps</code> tab
# Click on <code>Create a new app</code>. You can call it <code>Dolibarr</code>. This instance will contain a connection and several modules that will implement specific features such as '''creation of a task''' or '''creation of an event''' for instance.

In the <code>Base</code> tab, you just have to write

<syntaxhighlight lang="json">{}</syntaxhighlight>

= Configure authentication =

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the <code>connection</code> tab of the Make application.

This tab has two sub-tabs : <code>Parameters</code> tab and <code>Communication</code> tab.

''NB : The applications that a user can create on Make are written in <code>json</code>.''


== a) <code>Parameters</code> tab ==

There are three required parameters for the connection : the ''Dolibarr API key'', the ''URL of the Dolibarr instance'' (<code>https://yourdolibarrurl</code> for instance) and your ''user ID''. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

<syntaxhighlight lang="json">[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


== b) <code>Communication</code> tab ==

The following code specifies the account validation process.

<syntaxhighlight lang="json">{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


= Create an action module =


== Example of module to create events in the Dolibarr calendar ==

As a reminder, the goal is to implement the following use case : >“As soon as you receive a mail on an Email box, report it in Dolibarr events”

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call <code>Creation of an event</code>. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.


=== a) <code>Communication</code> tab ===

This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Explanation of the different required fields :'''

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| type
| Event type
| text
| Email reception
|-
| label
| Event label
| text
| New emails received
|-
| type_code
| Dolibarr event type code
| number
| '''6'''
|-
| userownerid
| Dolibarr user that create the event
| number
| 7
|-
| email_sender
| Login of the sender
| text
| jdoe
|-
| email_from
| Email address of the sender
| text
| john@doe.org
|-
| status
|
| number
| 0
|-
| percentage
| Event progress
| number between -1 (N/A) and 100
| -1
|-
| date_creation
| Date of creation of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datep
| Start date of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datef
| End date of the event
| date
| 2023-03-12T18:25:43-05:00
|}

The type_code “6” corresponds to the event type “Email reception”.

NB : Bold parameters are compulsory for this scenario

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

The following parameters are mappable, that means it must be completed by the user.

<syntaxhighlight lang="json">[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>

Your integration is now ready to be used.


== 1st scenario : Report an email in Dolibarr events ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Email scenario configuration ===


==== 2.a) Email scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Email</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch Emails</code> trigger of this module. To set up the Email module, you should click on it. A configuration window will appear.


==== 2.b) Email module configuration ====

# First, choose the '''connection''' : select the IMAP connection that you configured (named ''My others IMAP connection'')
# Select the <code>/INBOX</code> '''folder'''
# Select the <code>Only unread mails</code> '''criteria'''
# Click on <code>No</code> for <code>Mark message(s) as read when fetched</code> unless you want to mark messages as read.
# Don’t forget to click on <code>OK</code> at the bottom right of the window.


==== 2.c) Dolibarr module configuration ====

Add the Dolibarr application by selecting the <code>Create an event</code> action that you created previously.

In the end, your screen should look like this :

<div class="figure">

[[File:Make mail.png|thumb]]
 

</div>
Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

# Select the right '''connection'''
# Select the '''Email address''' with <code>1. Sender Email Address</code>
# Select the '''Name''' with <code>1. Sender Email Name</code>
# Select the '''Mail label''' with <code>"1. Sender Email Name" : "1. Subject"</code>
# Select the '''Received on''' field : <code>1.Date</code>
# Choose the '''Type''' : 1

<div class="figure">

[[File:Email parameters.png|thumb|Make email parameters]]
 

</div>
<ol start="7" style="list-style-type: decimal;">
<li>Click on <code>OK</code></li></ol>

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== Example of a module implementation to create a project task on Dolibarr ==

As a reminder, the goal is to implement the following use case :

<blockquote>“Creation of a project task in Dolibarr once an issue is created on Github”
</blockquote>
In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (<code>Projects</code> tab, <code>Tasks/Activities</code> section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module <code>Projects</code> of Dolibarr.

'''Required fields :''' There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the <code>Task list</code> columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| ref
| Task reference
| text
| K2304-0005
|-
| label
| Task label
| text
|
|-
| fk_project
| Project reference
| number
| 2
|-
| date_start
| Start date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_end
| End date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_creation
| Date of creation
| date
|
|-
| user_creation
| User that created the task
| text
|
|-
| planned_workload
| Estimated completion time (in seconds)
| number
| 8400
|-
| duration_effective
| Percentage of actual progress
| number
| 0
|-
| fk_user_creat
| ID of the user that created the event
| number
| 7
|-
| progress
| Progress of the project (in %)
| number between 0 and 100
| 50
|}

Complete the following tabs as follows :


=== a) <code>Communication</code> tab ===

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Setting up the Github OAuth connection :'''

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

# Click the <code>Add button</code> next to the <code>Connection</code> field. Select the '''Connection type''' as OAuth.
# Optional: In the '''Connection name''' field, enter a name for the connection.
# Click on <code>Save</code>.
# a Github window should open. Confirm the access by clicking Authorize.

'''NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.'''

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json"> {}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

-----


== 2nd scenario : Create a task in Dolibarr when a new issue is created on Github ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Github scenario configuration ===


==== 2.a) Github scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Github</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch issues</code> trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.


==== 2.b) Github module configuration ====

# First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
# Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the '''I want to watch''' field.
# Select the repository from which we want to launch the scenario on the '''repository''' field. All the repositories of the Github account will be displayed in a drop-down list.
# Choose the '''maximum number of returned issues''' : 10 for example
# Fill the '''watch''' field : select <code>only new issues</code>
# Then, select the '''filter''' : <code>all issues</code>(for example)
# Finally, select the '''state''' : <code>only opened issues</code>

In the end, your screen should look like this :

<div class="figure">

[[File:Make github.png|thumb]]
 

</div>

==== 2.c) Dolibarr module configuration ====

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

# '''Task created by''' : <code>1.Creator</code>
# '''Name of task''' : <code>1.Title</code>
# '''Date of creation''' : <code>Date created</code>
# '''Date of start''' : <code>Date created</code>
# '''Project ID''' : <code>1</code>
# '''Date of end''' : <code>Date updated</code>

In the end, the window should look like :

<div class="figure">

[[File:Make github parameters.png|thumb|Make github parameters]]
 

</div>
Click on <code>OK</code>.

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== 3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar ==

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select <code>Watch Events</code> among the several propositions. After, in the <code>Connection</code> section, add a connection with your Google account and accept the terms. In the <code>Calendar</code> section, choose your calendar account. Then, in the <code>Watch Events</code> section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

* '''Event name''' : <code>1. Summary</code>
* '''Start time''' : <code>1. Start</code>
* '''End time''' : <code>1. End</code>
* '''Location''' : <code>1. Location</code>
* '''Description''' : <code>1. Description</code>
* '''Email adress''' : <code>1. Organizer: Email</code>

You normally have the sections filled as follows :

<div class="figure">

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

</div>
The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


= Help for developpers =


== Viewing the code on VSCode ==

To view the code written on the Make website on VScode, it is possible to install the <code>Make Apps SDK</code> extension. More details can be found on the [https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code extension configuration page].

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

Integration of Dolibarr to the Zapier automation platform

2023-05-14T19:06:02Z

IPazu: IPazu moved page Integration of Dolibarr to the zapier automation platform to Integration of Dolibarr to the Zapier automation platform

{{TemplateDocDevEn}}


= Integration of Dolibarr to the Zapier automation platform =

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]


== Preamble ==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Zapier integration =

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin.

You will be asked for different information: * a name for your integration * a description * a website URL * a logo * the audience targeted by your integration (public or private) * your role in the development of the integration (employee, hired, independent) * the category of your integration

<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


= Configure authentication =

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

== Step 1: Configuring Authentication Fields ==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>Instance URL</code>
|-
| Key
| <code>host</code>
|-
| Required
| ✅ Yes
|-
| Type
| String
|-
| Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>API Key</code>
|-
| Key
| <code>api_key</code>
|-
| Required
| ✅ Yes
|-
| Type
| Password
|-
| Help Text
| <code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


== Step 2: Configuring the token exchange request ==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


== Step 3: Configuring the test request ==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <code>{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}})</code> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


== Step 4: Testing the connection ==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index endpoint. php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


= Create a trigger =

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


= Create an action =

* '''Example case:''' Create an event in the Dolibarr calendar
* '''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


== Step 1: Configuring the action ==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
! Field
! Value
|-
| Type
| Create
|-
| Key
| <code>create_event</code>
|-
| Name
| <code>Create an event</code>
|-
| Noun
| <code>Event</code>
|-
| Description
| <code>Create an event in the Dolibarr calendar</code>
|-
| Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


== Step 2: Configuring the fields ==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
! Field
! Label
! Key
! Type
! Required
|-
| Name
| <code>Event name</code>
| <code>label</code>
| String
| ✅ Yes
|-
| Start date
| <code>Start date</code>
| <code>datep</code>
| DateTime
| ✅ Yes
|-
| End date
| <code>End date</code>
| <code>datef</code>
| DateTime
| ❌ No
|-
| Location
| <code>Location</code>
| <code>location</code>
| String
| ❌ No
|-
| Description
| <code>Description</code>
| <code>note_private</code>
| Text
| ❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

== Step 3: API configuration ==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


=== API request configuration ===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

=== Testing the request to the API ===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
! Field
! Value
|-
| label
| <code>Test event</code>
|-
| datep
| <code>2023-05-01T16:00:00.000Z</code>
|-
| datef
| <code>2023-05-01T18:00:00.000Z</code>
|-
| location
| <code>Test room</code>
|-
| note_private
| <code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

=== Configuration of the data returned by the API ===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


== Step 4: Testing the action in a “Zap” ==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


=== Trigger setup ===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


=== Action Setup ===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
! Field
! Google Calendar field
|-
| Event name
| Summary
|-
| Start date
| Event begins (pretty)
|-
| End date
| Event ends (pretty)
|-
| Location
| Location
|-
| Description
| Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


= Validate and publish the integration =

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


= Go further =

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


= Conclusion =

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

Integration of Dolibarr to the Make automation platform

2023-05-14T10:19:39Z

IPazu: fixing license

= Integration of Dolibarr to the Make automation platform =

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Make application =

# Go to https://eu1.make.com and log into your user account
# Go to the <code>My Apps</code> tab
# Click on <code>Create a new app</code>. You can call it <code>Dolibarr</code>. This instance will contain a connection and several modules that will implement specific features such as '''creation of a task''' or '''creation of an event''' for instance.

In the <code>Base</code> tab, you just have to write

<syntaxhighlight lang="json">{}</syntaxhighlight>

= Configure authentication =

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the <code>connection</code> tab of the Make application.

This tab has two sub-tabs : <code>Parameters</code> tab and <code>Communication</code> tab.

''NB : The applications that a user can create on Make are written in <code>json</code>.''


== a) <code>Parameters</code> tab ==

There are three required parameters for the connection : the ''Dolibarr API key'', the ''URL of the Dolibarr instance'' (<code>https://yourdolibarrurl</code> for instance) and your ''user ID''. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

<syntaxhighlight lang="json">[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


== b) <code>Communication</code> tab ==

The following code specifies the account validation process.

<syntaxhighlight lang="json">{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


= Create an action module =


== Example of module to create events in the Dolibarr calendar ==

As a reminder, the goal is to implement the following use case : >“As soon as you receive a mail on an Email box, report it in Dolibarr events”

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call <code>Creation of an event</code>. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.


=== a) <code>Communication</code> tab ===

This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Explanation of the different required fields :'''

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| type
| Event type
| text
| Email reception
|-
| label
| Event label
| text
| New emails received
|-
| type_code
| Dolibarr event type code
| number
| '''6'''
|-
| userownerid
| Dolibarr user that create the event
| number
| 7
|-
| email_sender
| Login of the sender
| text
| jdoe
|-
| email_from
| Email address of the sender
| text
| john@doe.org
|-
| status
|
| number
| 0
|-
| percentage
| Event progress
| number between -1 (N/A) and 100
| -1
|-
| date_creation
| Date of creation of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datep
| Start date of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datef
| End date of the event
| date
| 2023-03-12T18:25:43-05:00
|}

The type_code “6” corresponds to the event type “Email reception”.

NB : Bold parameters are compulsory for this scenario

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

The following parameters are mappable, that means it must be completed by the user.

<syntaxhighlight lang="json">[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>

Your integration is now ready to be used.


== 1st scenario : Report an email in Dolibarr events ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Email scenario configuration ===


==== 2.a) Email scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Email</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch Emails</code> trigger of this module. To set up the Email module, you should click on it. A configuration window will appear.


==== 2.b) Email module configuration ====

# First, choose the '''connection''' : select the IMAP connection that you configured (named ''My others IMAP connection'')
# Select the <code>/INBOX</code> '''folder'''
# Select the <code>Only unread mails</code> '''criteria'''
# Click on <code>No</code> for <code>Mark message(s) as read when fetched</code> unless you want to mark messages as read.
# Don’t forget to click on <code>OK</code> at the bottom right of the window.


==== 2.c) Dolibarr module configuration ====

Add the Dolibarr application by selecting the <code>Create an event</code> action that you created previously.

In the end, your screen should look like this :

<div class="figure">

[[File:Make mail.png|thumb]]
 

</div>
Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

# Select the right '''connection'''
# Select the '''Email address''' with <code>1. Sender Email Address</code>
# Select the '''Name''' with <code>1. Sender Email Name</code>
# Select the '''Mail label''' with <code>"1. Sender Email Name" : "1. Subject"</code>
# Select the '''Received on''' field : <code>1.Date</code>
# Choose the '''Type''' : 1

<div class="figure">

[[File:Email parameters.png|thumb|Make email parameters]]
 

</div>
<ol start="7" style="list-style-type: decimal;">
<li>Click on <code>OK</code></li></ol>

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== Example of a module implementation to create a project task on Dolibarr ==

As a reminder, the goal is to implement the following use case :

<blockquote>“Creation of a project task in Dolibarr once an issue is created on Github”
</blockquote>
In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (<code>Projects</code> tab, <code>Tasks/Activities</code> section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module <code>Projects</code> of Dolibarr.

'''Required fields :''' There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the <code>Task list</code> columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| ref
| Task reference
| text
| K2304-0005
|-
| label
| Task label
| text
|
|-
| fk_project
| Project reference
| number
| 2
|-
| date_start
| Start date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_end
| End date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_creation
| Date of creation
| date
|
|-
| user_creation
| User that created the task
| text
|
|-
| planned_workload
| Estimated completion time (in seconds)
| number
| 8400
|-
| duration_effective
| Percentage of actual progress
| number
| 0
|-
| fk_user_creat
| ID of the user that created the event
| number
| 7
|-
| progress
| Progress of the project (in %)
| number between 0 and 100
| 50
|}

Complete the following tabs as follows :


=== a) <code>Communication</code> tab ===

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Setting up the Github OAuth connection :'''

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

# Click the <code>Add button</code> next to the <code>Connection</code> field. Select the '''Connection type''' as OAuth.
# Optional: In the '''Connection name''' field, enter a name for the connection.
# Click on <code>Save</code>.
# a Github window should open. Confirm the access by clicking Authorize.

'''NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.'''

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json"> {}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

-----


== 2nd scenario : Create a task in Dolibarr when a new issue is created on Github ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Github scenario configuration ===


==== 2.a) Github scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Github</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch issues</code> trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.


==== 2.b) Github module configuration ====

# First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
# Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the '''I want to watch''' field.
# Select the repository from which we want to launch the scenario on the '''repository''' field. All the repositories of the Github account will be displayed in a drop-down list.
# Choose the '''maximum number of returned issues''' : 10 for example
# Fill the '''watch''' field : select <code>only new issues</code>
# Then, select the '''filter''' : <code>all issues</code>(for example)
# Finally, select the '''state''' : <code>only opened issues</code>

In the end, your screen should look like this :

<div class="figure">

[[File:Make github.png|thumb]]
 

</div>

==== 2.c) Dolibarr module configuration ====

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

# '''Task created by''' : <code>1.Creator</code>
# '''Name of task''' : <code>1.Title</code>
# '''Date of creation''' : <code>Date created</code>
# '''Date of start''' : <code>Date created</code>
# '''Project ID''' : <code>1</code>
# '''Date of end''' : <code>Date updated</code>

In the end, the window should look like :

<div class="figure">

[[File:Make github parameters.png|thumb|Make github parameters]]
 

</div>
Click on <code>OK</code>.

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== 3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar ==

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select <code>Watch Events</code> among the several propositions. After, in the <code>Connection</code> section, add a connection with your Google account and accept the terms. In the <code>Calendar</code> section, choose your calendar account. Then, in the <code>Watch Events</code> section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

* '''Event name''' : <code>1. Summary</code>
* '''Start time''' : <code>1. Start</code>
* '''End time''' : <code>1. End</code>
* '''Location''' : <code>1. Location</code>
* '''Description''' : <code>1. Description</code>
* '''Email adress''' : <code>1. Organizer: Email</code>

You normally have the sections filled as follows :

<div class="figure">

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

</div>
The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


= Help for developpers =


== Viewing the code on VSCode ==

To view the code written on the Make website on VScode, it is possible to install the <code>Make Apps SDK</code> extension. More details can be found on the [https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code extension configuration page].

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

Integration of Dolibarr to the Make automation platform

2023-05-14T10:19:05Z

IPazu: Fixing images and structure

= Integration of Dolibarr to the Make automation platform =

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Make application =

# Go to https://eu1.make.com and log into your user account
# Go to the <code>My Apps</code> tab
# Click on <code>Create a new app</code>. You can call it <code>Dolibarr</code>. This instance will contain a connection and several modules that will implement specific features such as '''creation of a task''' or '''creation of an event''' for instance.

In the <code>Base</code> tab, you just have to write

<syntaxhighlight lang="json">{}</syntaxhighlight>

= Configure authentication =

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the <code>connection</code> tab of the Make application.

This tab has two sub-tabs : <code>Parameters</code> tab and <code>Communication</code> tab.

''NB : The applications that a user can create on Make are written in <code>json</code>.''


== a) <code>Parameters</code> tab ==

There are three required parameters for the connection : the ''Dolibarr API key'', the ''URL of the Dolibarr instance'' (<code>https://yourdolibarrurl</code> for instance) and your ''user ID''. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

<syntaxhighlight lang="json">[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


== b) <code>Communication</code> tab ==

The following code specifies the account validation process.

<syntaxhighlight lang="json">{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


= Create an action module =


== Example of module to create events in the Dolibarr calendar ==

As a reminder, the goal is to implement the following use case : >“As soon as you receive a mail on an Email box, report it in Dolibarr events”

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call <code>Creation of an event</code>. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.


=== a) <code>Communication</code> tab ===

This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Explanation of the different required fields :'''

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| type
| Event type
| text
| Email reception
|-
| label
| Event label
| text
| New emails received
|-
| type_code
| Dolibarr event type code
| number
| '''6'''
|-
| userownerid
| Dolibarr user that create the event
| number
| 7
|-
| email_sender
| Login of the sender
| text
| jdoe
|-
| email_from
| Email address of the sender
| text
| john@doe.org
|-
| status
|
| number
| 0
|-
| percentage
| Event progress
| number between -1 (N/A) and 100
| -1
|-
| date_creation
| Date of creation of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datep
| Start date of the event
| date
| 2023-03-12T18:25:43-05:00
|-
| datef
| End date of the event
| date
| 2023-03-12T18:25:43-05:00
|}

The type_code “6” corresponds to the event type “Email reception”.

NB : Bold parameters are compulsory for this scenario

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

The following parameters are mappable, that means it must be completed by the user.

<syntaxhighlight lang="json">[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save the written code with <code>Ctrl+S</code>

Your integration is now ready to be used.


== 1st scenario : Report an email in Dolibarr events ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Email scenario configuration ===


==== 2.a) Email scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Email</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch Emails</code> trigger of this module. To set up the Email module, you should click on it. A configuration window will appear.


==== 2.b) Email module configuration ====

# First, choose the '''connection''' : select the IMAP connection that you configured (named ''My others IMAP connection'')
# Select the <code>/INBOX</code> '''folder'''
# Select the <code>Only unread mails</code> '''criteria'''
# Click on <code>No</code> for <code>Mark message(s) as read when fetched</code> unless you want to mark messages as read.
# Don’t forget to click on <code>OK</code> at the bottom right of the window.


==== 2.c) Dolibarr module configuration ====

Add the Dolibarr application by selecting the <code>Create an event</code> action that you created previously.

In the end, your screen should look like this :

<div class="figure">

[[File:Make mail.png|thumb]]
 

</div>
Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

# Select the right '''connection'''
# Select the '''Email address''' with <code>1. Sender Email Address</code>
# Select the '''Name''' with <code>1. Sender Email Name</code>
# Select the '''Mail label''' with <code>"1. Sender Email Name" : "1. Subject"</code>
# Select the '''Received on''' field : <code>1.Date</code>
# Choose the '''Type''' : 1

<div class="figure">

[[File:Email parameters.png|thumb|Make email parameters]]
 

</div>
<ol start="7" style="list-style-type: decimal;">
<li>Click on <code>OK</code></li></ol>

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== Example of a module implementation to create a project task on Dolibarr ==

As a reminder, the goal is to implement the following use case :

<blockquote>“Creation of a project task in Dolibarr once an issue is created on Github”
</blockquote>
In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (<code>Projects</code> tab, <code>Tasks/Activities</code> section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module <code>Projects</code> of Dolibarr.

'''Required fields :''' There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the <code>Task list</code> columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

{| class="wikitable"
|-
! API field
! Description
! Type
! Possible value
|-
| ref
| Task reference
| text
| K2304-0005
|-
| label
| Task label
| text
|
|-
| fk_project
| Project reference
| number
| 2
|-
| date_start
| Start date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_end
| End date
| date
| 2023-03-12T18:25:43-05:00
|-
| date_creation
| Date of creation
| date
|
|-
| user_creation
| User that created the task
| text
|
|-
| planned_workload
| Estimated completion time (in seconds)
| number
| 8400
|-
| duration_effective
| Percentage of actual progress
| number
| 0
|-
| fk_user_creat
| ID of the user that created the event
| number
| 7
|-
| progress
| Progress of the project (in %)
| number between 0 and 100
| 50
|}

Complete the following tabs as follows :


=== a) <code>Communication</code> tab ===

<syntaxhighlight lang="json">{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

'''Setting up the Github OAuth connection :'''

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

# Click the <code>Add button</code> next to the <code>Connection</code> field. Select the '''Connection type''' as OAuth.
# Optional: In the '''Connection name''' field, enter a name for the connection.
# Click on <code>Save</code>.
# a Github window should open. Confirm the access by clicking Authorize.

'''NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.'''

'''Select a connection :''' Under the previous code block, you have to select a connection. Select the <code>Dolibarr connection</code> that you created previously.


=== b) <code>Static parameters</code> tab ===

<syntaxhighlight lang="json"> {}</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== c) <code>Mappable parameters</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>


=== d) <code>Interface</code> tab ===

<syntaxhighlight lang="json">[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]</syntaxhighlight>
NB : In each tab, save your code with <code>Ctrl+S</code>

-----


== 2nd scenario : Create a task in Dolibarr when a new issue is created on Github ==


=== 1) Create a new scenario ===

# Click on the <code>Scenarios</code> tab of the left-hand menu
# Click on the <code>Create a new scenario</code> button at the top right


=== 2) Github scenario configuration ===


==== 2.a) Github scenario initialization ====

# Click on the <code>+</code> symbol to add a module
# Select the <code>Github</code> module, that you can search it at the bottom of the drop-down list.
# Select the <code>Watch issues</code> trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.


==== 2.b) Github module configuration ====

# First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
# Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the '''I want to watch''' field.
# Select the repository from which we want to launch the scenario on the '''repository''' field. All the repositories of the Github account will be displayed in a drop-down list.
# Choose the '''maximum number of returned issues''' : 10 for example
# Fill the '''watch''' field : select <code>only new issues</code>
# Then, select the '''filter''' : <code>all issues</code>(for example)
# Finally, select the '''state''' : <code>only opened issues</code>

In the end, your screen should look like this :

<div class="figure">

[[File:Make github.png|thumb]]
 

</div>

==== 2.c) Dolibarr module configuration ====

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

# '''Task created by''' : <code>1.Creator</code>
# '''Name of task''' : <code>1.Title</code>
# '''Date of creation''' : <code>Date created</code>
# '''Date of start''' : <code>Date created</code>
# '''Project ID''' : <code>1</code>
# '''Date of end''' : <code>Date updated</code>

In the end, the window should look like :

<div class="figure">

[[File:Make github parameters.png|thumb|Make github parameters]]
 

</div>
Click on <code>OK</code>.

The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


== 3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar ==

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select <code>Watch Events</code> among the several propositions. After, in the <code>Connection</code> section, add a connection with your Google account and accept the terms. In the <code>Calendar</code> section, choose your calendar account. Then, in the <code>Watch Events</code> section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

* '''Event name''' : <code>1. Summary</code>
* '''Start time''' : <code>1. Start</code>
* '''End time''' : <code>1. End</code>
* '''Location''' : <code>1. Location</code>
* '''Description''' : <code>1. Description</code>
* '''Email adress''' : <code>1. Organizer: Email</code>

You normally have the sections filled as follows :

<div class="figure">

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

</div>
The scenario can now be executed. For this, click on the <code>Run</code> button at the bottom left of the screen.


= Help for developpers =


== Viewing the code on VSCode ==

To view the code written on the Make website on VScode, it is possible to install the <code>Make Apps SDK</code> extension. More details can be found on the [https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code extension configuration page].

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[http://creativecommons.org/licenses/by-sa/4.0/ [[File:https://licensebuttons.net/l/by-sa/4.0/88x31.png|CC BY-SA 4.0]]]

Integration of Dolibarr to the Make automation platform

2023-05-14T10:14:51Z

IPazu: Adding make integration documention

# Integration of Dolibarr to the Make automation platform
[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

This tutorial explains how to create a Make integration for Dolibarr using an integration that creates events in the agenda module as an example.

## Prerequisites

The following tutorial assumes that you have completed the following prerequisites:
* You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol)
* You have access to a user account with administrator rights
* You have activated the "Web Services API REST" module (if it is not already the case, follow the [official documentation](https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer)))
* You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: `https://yourdolibarrurl`. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.

# Create the Make application

1. Go to <https://eu1.make.com> and log into your user account
2. Go to the `My Apps` tab
3. Click on `Create a new app`. You can call it `Dolibarr`. This instance will contain a connection and several modules that will implement specific features such as **creation of a task** or **creation of an event** for instance.

In the `Base` tab, you just have to write
```json
{}
```

# Configure authentication

It is essential to link the Make application (i.e Dolibarr) to the external application via a connection, which can be set in the `connection` tab of the Make application.

This tab has two sub-tabs : `Parameters` tab and `Communication` tab.

*NB : The applications that a user can create on Make are written in `json`.*

## a) `Parameters` tab
There are three required parameters for the connection : the *Dolibarr API key*, the *URL of the Dolibarr instance* (`https://yourdolibarrurl` for instance) and your *user ID*. It means these parameters require some values in order to create a connection. Thus, you can write the following code :

```json
[
{
"name": "apiKey",
"type": "text",
"label": "Dolibarr API key",
"required": true
},
{
"name": "hostname",
"type": "text",
"label": "Dolibarr instance URL",
"required": true
},
{
"name": "userownerid",
"type": "number",
"label": "User ID",
"required": true
}
]
```
NB : In each tab, save the written code with `Ctrl+S`

## b) `Communication` tab
The following code specifies the account validation process.
```json
{
"url":"{{parameters.hostname}}/api/index.php/users/info",
"headers": {
"DOLAPIKEY": "{{parameters.apiKey}}"
},
"log": {
"sanitize": ["request.headers.DOLAPIKEY"]
}
}
```
NB : In each tab, save the written code with `Ctrl+S`

# Create an action module
## Example of module to create events in the Dolibarr calendar
As a reminder, the goal is to implement the following use case :
>"As soon as you receive a mail on an Email box, report it in Dolibarr events"

In this case, the Dolibarr instance receives information from the Email application. In this case, the Email application is a trigger generating an action in Dolibarr.

On the Dolibarr side, the module to implement is an action module, that we can call `Creation of an event`. This module can be configured in different tabs which are detailed below. The different tabs are connected so that some parameters can be used in a tab that is different from itself.

### a) `Communication` tab
This tab contains the different required parameters that will be transmitted from the Email application to Dolibarr. The required parameters are the one required by the API.

You have to fill the code block of this tab as follows :
```json
{
"url": "{{connection.hostname}}/api/index.php/agendaevents",
"method": "POST",
"qs": {},
"body": {
"type": "Email reception",
"label": "{{parameters.label}}",
"type_code": 6,
"userownerid": "{{connection.userownerid}}",
"email_sender": "{{parameters.name}}",
"email_from": "{{lower(parameters.email)}}",
"percentage": "-1",
"status": "0",
"date_creation": "{{parameters.date}}",
"datep": "{{parameters.date}}",
"datef": "{{parameters.date}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
}
```
NB : In each tab, save your code with `Ctrl+S`

**Explanation of the different required fields :**

| API field | Description | Type | Possible value |
|---------------|-------------------------------------|---------------------------------|---------------------------|
| type | Event type | text | Email reception |
| label | Event label | text | New emails received |
| type_code | Dolibarr event type code | number | **6** |
| userownerid | Dolibarr user that create the event | number | 7 |
| email_sender | Login of the sender | text | jdoe |
| email_from | Email address of the sender | text | john@doe.org |
| status | | number | 0 |
| percentage | Event progress | number between -1 (N/A) and 100 | -1 |
| date_creation | Date of creation of the event | date | 2023-03-12T18:25:43-05:00 |
| datep | Start date of the event | date | 2023-03-12T18:25:43-05:00 |
| datef | End date of the event | date | 2023-03-12T18:25:43-05:00 |

The type_code "6" corresponds to the event type "Email reception".

NB : Bold parameters are compulsory for this scenario

**Select a connection :**
Under the previous code block, you have to select a connection. Select the `Dolibarr connection` that you created previously.

### b) `Static parameters` tab
```json
[
{
"name": "type",
"type": "text",
"label": "Type",
"value": "Email reception"
}
]
```
NB : In each tab, save the written code with `Ctrl+S`

### c) `Mappable parameters` tab
The following parameters are mappable, that means it must be completed by the user.
```json
[
{
"name": "email",
"type": "email",
"label": "Email address",
"required": true
},
{
"name": "name",
"type": "text",
"label": "Name",
"required": true
},
{
"name":"label",
"type":"text",
"label":"Mail label",
"required": true
},
{
"name":"date",
"type":"date",
"label":"Received on",
"required": true
}
]
```
NB : In each tab, save the written code with `Ctrl+S`

### d) `Interface` tab
```json
[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]
```
NB : In each tab, save the written code with `Ctrl+S`

Your integration is now ready to be used.

## 1st scenario : Report an email in Dolibarr events

### 1) Create a new scenario

1) Click on the `Scenarios` tab of the left-hand menu
2) Click on the `Create a new scenario` button at the top right

### 2) Email scenario configuration
#### 2.a) Email scenario initialization
1) Click on the `+` symbol to add a module
2) Select the `Email` module, that you can search it at the bottom of the drop-down list.
3) Select the `Watch Emails` trigger of this module.
To set up the Email module, you should click on it. A configuration window will appear.

#### 2.b) Email module configuration

1. First, choose the **connection** : select the IMAP connection that you configured (named *My others IMAP connection*)
2. Select the `/INBOX` **folder**
3. Select the `Only unread mails` **criteria**
4. Click on `No` for `Mark message(s) as read when fetched` unless you want to mark messages as read.
5. Don't forget to click on `OK` at the bottom right of the window.

#### 2.c) Dolibarr module configuration

Add the Dolibarr application by selecting the `Create an event` action that you created previously.

In the end, your screen should look like this :

![[File:Make mail.png|thumb]]
 

Once you have your scenario is set up, you should fill the Dolibarr module fields with some Email fields, by following the steps below :

1. Select the right **connection**
2. Select the **Email address** with `1. Sender Email Address`
3. Select the **Name** with `1. Sender Email Name`
4. Select the **Mail label** with `"1. Sender Email Name" : "1. Subject"`
5. Select the **Received on** field : `1.Date`
6. Choose the **Type** : 1

![[File:Email parameters.png|thumb|Make email parameters]]
 

7. Click on `OK`

The scenario can now be executed. For this, click on the `Run` button at the bottom left of the screen.

## Example of a module implementation to create a project task on Dolibarr

As a reminder, the goal is to implement the following use case :

>"Creation of a project task in Dolibarr once an issue is created on Github"

In this case, the Dolibarr instance receives information from Github. Github is a trigger that generates an action in Dolibarr, of creating a project task (`Projects` tab, `Tasks/Activities` section).

Here is the code that must be implemented on Make, to realize the scenario of creation of a project task in the module `Projects` of Dolibarr.

**Required fields :**
There are two types of required fields, the ones which are required to create a valid task that can be accepted by Dolibarr and the fields that give information in the tasks list.

Fields corresponding to the `Task list` columns : task reference, task label, start date (type : date), end date (type : date), project reference, project status, expected workload, time consumed, consumption progress, actual progress declared (percentage), task progress

Mapping between API fields and their labels :

| API field | Description | Type | Possible value |
|--------------------|----------------------------------------|--------------------------|---------------------------|
| ref | Task reference | text | K2304-0005 |
| label | Task label | text | |
| fk_project | Project reference | number | 2 |
| date_start | Start date | date | 2023-03-12T18:25:43-05:00 |
| date_end | End date | date | 2023-03-12T18:25:43-05:00 |
| date_creation | Date of creation | date | |
| user_creation | User that created the task | text | |
| planned_workload | Estimated completion time (in seconds) | number | 8400 |
| duration_effective | Percentage of actual progress | number | 0 |
| fk_user_creat | ID of the user that created the event | number | 7 |
| progress | Progress of the project (in %) | number between 0 and 100 | 50 |

Complete the following tabs as follows :

### a) `Communication` tab

```json
{
"url": "{{connection.hostname}}/api/index.php/tasks",
"method": "POST",
"qs": {},
"body": {
"label": "{{parameters.taskName}}",
"fk_project": "{{parameters.projectID}}",
"date_start": "{{parameters.date_start)}}",
"date_end": "{{parameters.date_end)}}",
"user_creation": "{{parameters.creator)}}",
"date_creation": "{{parameters.date_creation)}}",
"fk_user_creat": "{{connection.userownerid}}",
"ref": "{{parameters.taskref}}"
},
"headers": {
"DOLAPIKEY": "{{connection.apiKey}}"
},
"response": {
"output": "{{body}}"
}
```
NB : In each tab, save your code with `Ctrl+S`

**Setting up the Github OAuth connection :**

(Source : https://www.make.com/en/help/app/github?_ga=2.85846297.1242178067.1682759655-390117518.1678356777)

1) Click the `Add button` next to the `Connection` field. Select the **Connection type** as OAuth.
2) Optional: In the **Connection name** field, enter a name for the connection.
3) Click on `Save`.
4) a Github window should open. Confirm the access by clicking Authorize.

**NB : You may have to reauthorize the connection to avoid some problems. On Make, in the left-side bar menu, select Connection. in the list of the connections, you may find (my Others IMAP connection). Click on Reauthorize.**

**Select a connection :**
Under the previous code block, you have to select a connection. Select the `Dolibarr connection` that you created previously.

### b) `Static parameters` tab

```json
{}
```
NB : In each tab, save your code with `Ctrl+S`

### c) `Mappable parameters` tab
```json
[
{
"name": "creator",
"type": "text",
"label": "Task created by:",
"required": true
},

{
"name": "taskName",
"type": "text",
"label": "Name of task",
"required": true
},
{
"name": "date_creation",
"type": "date",
"label": "Date of creation",
"required": true
},
{
"name": "date_start",
"type": "date",
"label": "Date of start",
"required": true
},
{
"name": "projectID",
"type": "text",
"label": "Project ID",
"required": true
},
{
"name": "date_end",
"type": "date",
"label": "Date of end",
"required": true
},
{
"name": "taskref",
"type": "text",
"label": "Reference of task",
"required": true
}
]
```
NB : In each tab, save your code with `Ctrl+S`

### d) `Interface` tab
```json
[
{
"name": "id",
"type": "uinteger",
"label": "User ID"
}
]
```
NB : In each tab, save your code with `Ctrl+S`

---

## 2nd scenario : Create a task in Dolibarr when a new issue is created on Github

### 1) Create a new scenario

1) Click on the `Scenarios` tab of the left-hand menu
2) Click on the `Create a new scenario` button at the top right

### 2) Github scenario configuration
#### 2.a) Github scenario initialization
1) Click on the `+` symbol to add a module
2) Select the `Github` module, that you can search it at the bottom of the drop-down list.
3) Select the `Watch issues` trigger of this module.

To set up the Github module, you should click on it. A configuration window will appear.

#### 2.b) Github module configuration

1) First, you will need to associate the Github account from which you want to retrieve the issues created, through an OAuth connection.
2) Then, you should choose if you want to watch all the repositories or only one repository of your linked Github account in the **I want to watch** field.
3) Select the repository from which we want to launch the scenario on the **repository** field. All the repositories of the Github account will be displayed in a drop-down list.

4) Choose the **maximum number of returned issues** : 10 for example
5) Fill the **watch** field : select `only new issues`
6) Then, select the **filter** : `all issues `(for example)
7) Finally, select the **state** : `only opened issues`

In the end, your screen should look like this :

[[File:Make github.png|thumb]]
 

#### 2.c) Dolibarr module configuration

Once your scenario is set up, you should fill the Dolibarr module fields with the available Github fields :

1) **Task created by** : `1.Creator`
2) **Name of task** : `1.Title`
3) **Date of creation** : `Date created`
4) **Date of start** : `Date created`
5) **Project ID** : `1`
6) **Date of end** : `Date updated`

In the end, the window should look like :

[[File:Make github parameters.png|thumb|Make github parameters]]
 

Click on `OK`.

The scenario can now be executed. For this, click on the `Run` button at the bottom left of the screen.

## 3rd scenario : Create a new event in the Dolibarr calendar when creating one in Google Calendar

This scenario involves to automatically add a new event in the Dolibarr calendar when creating one in Google Calendar.

First, when creating your scenario on Make, you need to find the Google Calendar application in the list. Then select `Watch Events` among the several propositions. After, in the `Connection` section, add a connection with your Google account and accept the terms. In the `Calendar` section, choose your calendar account. Then, in the `Watch Events` section, select what interest you in particular. Finally, let the other sections by default.

Secondly, add the Dolibarr module at the right of the Google Calendar one, and fill its sections as follows :

* **Event name** : `1. Summary`
* **Start time** : `1. Start`
* **End time** : `1. End`
* **Location** : `1. Location`
* **Description** : `1. Description`
* **Email adress** : `1. Organizer: Email`

You normally have the sections filled as follows :

[[File:Create event dolibarr module.png|thumb|Dolibarr module sections]]
 

The scenario can now be executed. For this, click on the `Run` button at the bottom left of the screen.

# Help for developpers

## Viewing the code on VSCode

To view the code written on the Make website on VScode, it is possible to install the `Make Apps SDK` extension. More details can be found on the [extension configuration page](https://docs.integromat.com/apps/apps-sdk/configuration-of-vs-code).

NB: The code viewed under VScode is stored in a local temporary repository on your computer, and it is synchronized with the code visible on Make.

On the other hand, it is only possible to export the code in .zip, which is annoying to put it on a Github repository for example.

# Credits

This tutorial was produced by the [AuTEAMation](https://github.com/AuTEAMation) team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [DoliCloud ](https://www.dolicloud.com/). This study was carried out as part of the PFA, a 2nd year group project at [ENSEIRB-MATMECA](https://enseirb-matmeca.bordeaux-inp.fr).

# Licence

This tutorial is licensed under a
[Creative Commons Attribution-ShareAlike 4.0 International License][cc-by-sa].

[![CC BY-SA 4.0][cc-by-sa-image]][cc-by-sa]

[cc-by-sa]: http://creativecommons.org/licenses/by-sa/4.0/
[cc-by-sa-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png
[cc-by-sa-shield]: https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg

File:Make github.png

2023-05-14T10:12:49Z

IPazu:

Make github

File:Create event dolibarr module.png

2023-05-14T10:12:23Z

IPazu:

Dolibarr module sections

File:Make github parameters.png

2023-05-14T10:11:39Z

IPazu:

Make github parameters

File:Email parameters.png

2023-05-14T10:11:07Z

IPazu:

Make email parameters

File:Make mail.png

2023-05-14T10:10:36Z

IPazu:

Make mail

Integration of Dolibarr to the Zapier automation platform

2023-05-14T10:05:20Z

IPazu: Fixing code files and licence

= Integration of Dolibarr to the Zapier automation platform =

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]


== Preamble ==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Zapier integration =

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin.

You will be asked for different information: * a name for your integration * a description * a website URL * a logo * the audience targeted by your integration (public or private) * your role in the development of the integration (employee, hired, independent) * the category of your integration

<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


= Configure authentication =

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

== Step 1: Configuring Authentication Fields ==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>Instance URL</code>
|-
| Key
| <code>host</code>
|-
| Required
| ✅ Yes
|-
| Type
| String
|-
| Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>API Key</code>
|-
| Key
| <code>api_key</code>
|-
| Required
| ✅ Yes
|-
| Type
| Password
|-
| Help Text
| <code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


== Step 2: Configuring the token exchange request ==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


== Step 3: Configuring the test request ==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <code>{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}})</code> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


== Step 4: Testing the connection ==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index endpoint. php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/authentication.js code/authentication.js], exported from Zapier CLI.


= Create a trigger =

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


= Create an action =

* '''Example case:''' Create an event in the Dolibarr calendar
* '''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


== Step 1: Configuring the action ==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
! Field
! Value
|-
| Type
| Create
|-
| Key
| <code>create_event</code>
|-
| Name
| <code>Create an event</code>
|-
| Noun
| <code>Event</code>
|-
| Description
| <code>Create an event in the Dolibarr calendar</code>
|-
| Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


== Step 2: Configuring the fields ==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
! Field
! Label
! Key
! Type
! Required
|-
| Name
| <code>Event name</code>
| <code>label</code>
| String
| ✅ Yes
|-
| Start date
| <code>Start date</code>
| <code>datep</code>
| DateTime
| ✅ Yes
|-
| End date
| <code>End date</code>
| <code>datef</code>
| DateTime
| ❌ No
|-
| Location
| <code>Location</code>
| <code>location</code>
| String
| ❌ No
|-
| Description
| <code>Description</code>
| <code>note_private</code>
| Text
| ❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

== Step 3: API configuration ==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


=== API request configuration ===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

=== Testing the request to the API ===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
! Field
! Value
|-
| label
| <code>Test event</code>
|-
| datep
| <code>2023-05-01T16:00:00.000Z</code>
|-
| datef
| <code>2023-05-01T18:00:00.000Z</code>
|-
| location
| <code>Test room</code>
|-
| note_private
| <code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

=== Configuration of the data returned by the API ===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


== Step 4: Testing the action in a “Zap” ==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


=== Trigger setup ===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


=== Action Setup ===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
! Field
! Google Calendar field
|-
| Event name
| Summary
|-
| Start date
| Event begins (pretty)
|-
| End date
| Event ends (pretty)
|-
| Location
| Location
|-
| Description
| Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [https://github.com/Dolibarr/dolibarr-integration-resources/blob/main/zapier/code/creates/create_event.js code/creates/create_event.js], exported from Zapier CLI. Similarly, you will find other sample actions in the [https://github.com/Dolibarr/dolibarr-integration-resources/tree/main/zapier/code/creates code/creates] folder.


= Validate and publish the integration =

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


= Go further =

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


= Conclusion =

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[https://creativecommons.org/licenses/by-sa/4.0/ License CC-BY-SA 4.0]

Integration of Dolibarr to the Zapier automation platform

2023-05-14T09:56:52Z

IPazu: Fixing images

= Integration of Dolibarr to the Zapier automation platform =

[http://creativecommons.org/licenses/by-sa/4.0/ [[File:https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg|CC BY-SA 4.0]]]


== Preamble ==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Zapier integration =

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin.

You will be asked for different information: * a name for your integration * a description * a website URL * a logo * the audience targeted by your integration (public or private) * your role in the development of the integration (employee, hired, independent) * the category of your integration

<div class="figure">

[[File:01-new-integration.png|thumb|Form in the zapier interface when adding the dolibarr integration]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


= Configure authentication =

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

== Step 1: Configuring Authentication Fields ==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>Instance URL</code>
|-
| Key
| <code>host</code>
|-
| Required
| ✅ Yes
|-
| Type
| String
|-
| Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>API Key</code>
|-
| Key
| <code>api_key</code>
|-
| Required
| ✅ Yes
|-
| Type
| Password
|-
| Help Text
| <code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


== Step 2: Configuring the token exchange request ==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


== Step 3: Configuring the test request ==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <code>{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}})</code> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


== Step 4: Testing the connection ==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:02-authentication-test.png|thumb|Testing dolibarr connection in zapier]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index endpoint. php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [[./code/authentication.js|code/authentication.js]], exported from Zapier CLI.


= Create a trigger =

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


= Create an action =

* '''Example case:''' Create an event in the Dolibarr calendar
* '''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


== Step 1: Configuring the action ==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
! Field
! Value
|-
| Type
| Create
|-
| Key
| <code>create_event</code>
|-
| Name
| <code>Create an event</code>
|-
| Noun
| <code>Event</code>
|-
| Description
| <code>Create an event in the Dolibarr calendar</code>
|-
| Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


== Step 2: Configuring the fields ==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
! Field
! Label
! Key
! Type
! Required
|-
| Name
| <code>Event name</code>
| <code>label</code>
| String
| ✅ Yes
|-
| Start date
| <code>Start date</code>
| <code>datep</code>
| DateTime
| ✅ Yes
|-
| End date
| <code>End date</code>
| <code>datef</code>
| DateTime
| ❌ No
|-
| Location
| <code>Location</code>
| <code>location</code>
| String
| ❌ No
|-
| Description
| <code>Description</code>
| <code>note_private</code>
| Text
| ❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:03-create-event-input-designer.png|thumb|Example of action for dolibar in Zapier]]

</div>

== Step 3: API configuration ==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


=== API request configuration ===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

=== Testing the request to the API ===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
! Field
! Value
|-
| label
| <code>Test event</code>
|-
| datep
| <code>2023-05-01T16:00:00.000Z</code>
|-
| datef
| <code>2023-05-01T18:00:00.000Z</code>
|-
| location
| <code>Test room</code>
|-
| note_private
| <code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

=== Configuration of the data returned by the API ===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


== Step 4: Testing the action in a “Zap” ==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


=== Trigger setup ===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


=== Action Setup ===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
! Field
! Google Calendar field
|-
| Event name
| Summary
|-
| Start date
| Event begins (pretty)
|-
| End date
| Event ends (pretty)
|-
| Location
| Location
|-
| Description
| Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:04-test-zap.png|thumb|Testing actions created for dolibarr in zapier]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [[./code/creates/create_event.js|code/creates/create_event.js]], exported from Zapier CLI. Similarly, you will find other sample actions in the [[./code/creates|code/creates]] folder.


= Validate and publish the integration =

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


= Go further =

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


= Conclusion =

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[http://creativecommons.org/licenses/by-sa/4.0/ [[File:https://licensebuttons.net/l/by-sa/4.0/88x31.png|CC BY-SA 4.0]]]

File:04-test-zap.png

2023-05-14T09:51:41Z

IPazu:

Testing actions created in zapier for dolibarr

File:03-create-event-input-designer.png

2023-05-14T09:50:09Z

IPazu:

Example of action for dolibarr in zapier

File:02-authentication-test.png

2023-05-14T09:48:00Z

IPazu:

Testing dolibarr conection in zapier

File:01-new-integration.png

2023-05-14T09:46:36Z

IPazu:

Adding dolibarr integration in zapier interface

Integration of Dolibarr to the Zapier automation platform

2023-05-14T09:39:43Z

IPazu: Adding zapier doc for dolibarr

= Integration of Dolibarr to the Zapier automation platform =

[http://creativecommons.org/licenses/by-sa/4.0/ [[File:https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg|CC BY-SA 4.0]]]


== Preamble ==

There are two ways to create an integration for Zapier: using the Zapier CLI or using the Zapier Platform Visual Builder. By starting to create an integration with the Zapier Platform Visual Builder, you can then export your integration and import it into the Zapier CLI for editing and publishing. But once you start using the Zapier CLI, you will no longer be able to use the Zapier Platform Visual Builder to modify your integration. In this tutorial, we will start by using the Zapier Platform Visual Builder, but the project was exported in the Zapier CLI and you can find it in the [[./code|code]] folder.


== Prerequisites ==

The following tutorial assumes that you have completed the following prerequisites: * You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol) * You have access to a user account with administrator rights * You have activated the “Web Services API REST” module (if it is not already the case, follow the [https://wiki.dolibarr.org/index.php/Module_Web_Services_API_REST_(developer) official documentation]) * You have obtained an API key for your user account that you will use to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information)

When necessary, we will use the following URL to refer to your Dolibarr instance: <code>https://yourdolibarrurl</code>. You will have to replace it with the URL of your own Dolibarr instance, without trailing slash.


= Create the Zapier integration =

Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.

If you don’t already have a Zapier account, you’ll need to create one. Once logged in, you should land on the Zapier Platform Visual Builder home page. Click the “Start a Zapier Integration” button to begin.

You will be asked for different information: * a name for your integration * a description * a website URL * a logo * the audience targeted by your integration (public or private) * your role in the development of the integration (employee, hired, independent) * the category of your integration

<div class="figure">

[[File:./screenshots/01-new-integration.png|Integration creation form]]

</div>
You can find more information on the [https://platform.zapier.com/quickstart/create-integration official documentation].


= Configure authentication =

Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.

You will be offered several authentication methods (API Key, OAuth v2, Session Auth, Basic Auth, Digest Auth…). In our case, we will use the “Session Auth” method.

<blockquote>'''Note:''' Although the “API Key” method seems to correspond better to the use of the Dolibarr API (since it requires an API key), the connection data is fixed and would require the user specifies its user ID in the Dolibarr database upstream, so that it can then be used in other actions. With the “Session Auth” method, we simply retrieve the user’s identifier at the first connection, which can then be used in other actions.
</blockquote>

== Step 1: Configuring Authentication Fields ==

In the first step, click on the “Add Field” button to add a first field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>Instance URL</code>
|-
| Key
| <code>host</code>
|-
| Required
| ✅ Yes
|-
| Type
| String
|-
| Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have "/" at the end and must start with https://.</code>
|}

Leave the other fields blank.

Then add a second field with the following information:

{| class="wikitable"
|-
! Field
! Value
|-
| Field Type
| <code>Field</code>
|-
| Label
| <code>API Key</code>
|-
| Key
| <code>api_key</code>
|-
| Required
| ✅ Yes
|-
| Type
| Password
|-
| Help Text
| <code>Specify the API key associated with the Dolibarr account to use through the integration.</code>
|}

Leave the other fields blank.


== Step 2: Configuring the token exchange request ==

In the second step, you need to configure the token exchange request. In the case of Dolibarr, there is no notion of token, but we will use this request to retrieve the identifier of the user who connects (see note above) as well as his first and last name (for display in Zapier).

The Zapier interface offers a “simple” mode where all you have to do is enter the URL of the request and the parameters to send, but that is not enough in our case. We will use the “advanced” mode by clicking on the “Switch to Code Mode” button.

Paste the following code in it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {
'id': results.id,
'firstname': results.firstname,
'lastname': results.lastname,
};
});</syntaxhighlight>
<blockquote>'''Note:''' From the data that will be entered by the user in the authentication fields (<code>host</code> and <code>api_key</code>) and accessible via <code>bundle.authData</code>, we build the URL of the Dolibarr API, then we make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key. We then retrieve the user’s data (his identifier, first name and last name) and send them back to Zapier to make them available in other actions.
</blockquote>
Once the code has been pasted, click on the “Save & Continue” button to go to the next step.


== Step 3: Configuring the test request ==

In the third step, you need to configure the test query. This request is used by Zapier to verify that the information entered by the user is correct. In our case, we will simply make a GET request on the URL <code>/api/index.php/users/info</code> with the header <code>DOLAPIKEY</code> containing the API key.

As before, click on the “Switch to Code Mode” button and paste the following code into it:

<syntaxhighlight lang="javascript">const options = {
url: `${bundle.authData.host}/api/index.php/users/info`,
method: 'GET',
headers: {
'DOLAPIKEY': bundle.authData.api_key
}
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return results;
});</syntaxhighlight>
You will then have to specify a “Connection Label”, which will be displayed to the user when he connects to his Dolibarr account from Zapier. For example, you can use the first and last name of the user, or the name of the Dolibarr instance. By imagining that the user is called “John Doe” and that the Dolibarr instance is available at the address <code>https://yourdolibarrurl</code>, you can use the following value: <code>{{bundle.authData.firstname}} {{bundle.authData.lastname}}({{bundle.authData.host}})</code> which will show <code>John Doe (https://yourdolibarrurl)</code>.

Then click on the “Save & Continue” button to go to the next step.


== Step 4: Testing the connection ==

In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.

A window will open and ask you to enter the authentication information configured in step 1, i.e. the URL of the Dolibarr instance and the API key of the user.

<div class="figure">

[[File:./screenshots/02-authentication-test.png|Authentication information input window]]

</div>
Once the information has been entered, click on the “Yes, Continue to …” button.

If all went well, you should see your account appear in the list of available accounts.

Then click on the “Test Authentication” button to check that the connection is working properly. If everything went well, you should see the result of the test query configured in step 3, i.e. the user information returned by the <code>/api/index endpoint. php/users/info</code>:

<syntaxhighlight lang="json">{
"id": "10",
"login": "jdoe",
"lastname": "Doe",
"firstname": "John",
// And many more...
}</syntaxhighlight>
All you have to do is click on the “Save & Finish” button to complete the authentication configuration.

The different authentication configuration data is available in the file [[./code/authentication.js|code/authentication.js]], exported from Zapier CLI.


= Create a trigger =

Creating a trigger is more complex than creating an action. Indeed, a trigger must be able to retrieve data from an event that occurs in Dolibarr and send it to Zapier.

Dolibarr offers a “webhook” system that allows data to be sent to a given URL when an event occurs, but it is not yet fully adapted to setting up a trigger in Zapier. So we won’t cover in this part in the tutorial, but all contributions about it are welcome.


= Create an action =

* '''Example case:''' Create an event in the Dolibarr calendar
* '''Prerequisites:''' Have activated the “Events/Agenda” module in Dolibarr and given the necessary permissions to the user to create an event in his name

Actions allow to perform operations in Dolibarr, in reaction to an event that occurs in another application. For example, you can create an action that allows to create an event in the Dolibarr calendar when an event is created in Google Calendar. It is this use case that we will cover in this part of the tutorial.

From the integration dashboard on Zapier, click on the “Add Action” button in the “Actions” section.


== Step 1: Configuring the action ==

In the first step, you need to configure the action. To do this, you must give it a name and a description. This information will be displayed to the user when they use the action in a zap. Fill in the fields as follows (you can of course use the values of your choice depending on the action you want to create):

{| class="wikitable"
|-
! Field
! Value
|-
| Type
| Create
|-
| Key
| <code>create_event</code>
|-
| Name
| <code>Create an event</code>
|-
| Noun
| <code>Event</code>
|-
| Description
| <code>Create an event in the Dolibarr calendar</code>
|-
| Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|}

Once the fields are filled in, click on the “Save” button and go to the next step.


== Step 2: Configuring the fields ==

In the second step, you need to configure the action fields. These fields allow the user to enter the information needed to perform the action. In our case, we are going to create an action which allows to create an event in the Dolibarr calendar. We will therefore need the following fields: a name, a start date, an end date, a place and a description. Many other fields are available, but we will limit ourselves to these 5 fields for this example.

Click the “Add” > “Input Field” button to add a field. Fill in the fields as follows, then click the “Save” button:

{| class="wikitable"
|-
! Field
! Label
! Key
! Type
! Required
|-
| Name
| <code>Event name</code>
| <code>label</code>
| String
| ✅ Yes
|-
| Start date
| <code>Start date</code>
| <code>datep</code>
| DateTime
| ✅ Yes
|-
| End date
| <code>End date</code>
| <code>datef</code>
| DateTime
| ❌ No
|-
| Location
| <code>Location</code>
| <code>location</code>
| String
| ❌ No
|-
| Description
| <code>Description</code>
| <code>note_private</code>
| Text
| ❌ No
|}

<blockquote>'''Note:''' The field keys are deliberately the same as the keys used by the Dolibarr API to identify the fields. Often poorly documented, they can be found in the source code of Dolibarr, or directly in the database. You can also create a resource from Dolibarr then retrieve it via the API (use the API explorer at https://yourdolibarrurl/api/index.php/explorer/ or a tool like Postman to test the requests to the API) to identify the field keys based on the data you entered.
</blockquote>
Once all the fields have been created, you should see a summary table of the action fields and a preview of the data entry form similar to this:

<div class="figure">

[[File:./screenshots/03-create-event-input-designer.png|Summary table of action fields]]

</div>

== Step 3: API configuration ==

In the third step, you need to configure the request to the Dolibarr API, in three substeps:


=== API request configuration ===

In the first sub-step, you need to fill in the basic request information to the API. As for the authentication configuration, switch to “code” mode by clicking on the “Switch to Code Mode” button, then paste the following code:

<syntaxhighlight lang="js">const options = {
url: `${bundle.authData.host}/api/index.php/agendaevents`,
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'DOLAPIKEY': bundle.authData.api_key
},
body: JSON.stringify({
'type_id': "50",
'userownerid': bundle.authData.id,
'label': bundle.inputData.label,
'datep': Date.parse(bundle.inputData.datep) / 1000,
'datef': Date.parse(bundle.inputData.datef) / 1000,
'location': bundle.inputData.location,
'note_private': bundle.inputData.note_private
})
}

return z.request(options)
.then((response) => {
response.throwForStatus();
const results = response.json;

return {id: results};
});</syntaxhighlight>
<blockquote>'''Note:''' The code above is to be adapted according to the fields you created in the previous step. For strings, you can directly use user-entered values via <code>bundle.inputData</code>. For dates, you need to use <code>Date.parse()</code> to convert the date entered by the user into timestamp (in milliseconds in JavaScript), then divide by 1000 to get a timestamp in seconds (Dolibarr API expects a timestamp in seconds). Some fields take “hard” numeric values, such as <code>type_id</code>, which will then have to be discovered by exploring the Dolibarr API. Finally, for the <code>userownerid</code> field, we use <code>bundle.authData.id</code>, which was automatically populated by Zapier with the user ID when the user configured their Dolibarr account in Zapier.
</blockquote>

=== Testing the request to the API ===

In the second sub-step, you need to test the request to the API. To do this, choose the Dolibarr account to use (like the one connected when configuring authentication) or add a new one. Then fill in the fields with test values, then click the “Test Your Request” button:

{| class="wikitable"
|-
! Field
! Value
|-
| label
| <code>Test event</code>
|-
| datep
| <code>2023-05-01T16:00:00.000Z</code>
|-
| datef
| <code>2023-05-01T18:00:00.000Z</code>
|-
| location
| <code>Test room</code>
|-
| note_private
| <code>This is a test event</code>
|}

<blockquote>'''Note:''' When testing or creating a “Zap” (user scenario), Zapier only offers text fields, nothing more. For dates, you must therefore enter a date in one of the supported formats ([https://help.zapier.com/hc/en-us/articles/8496259603341#date-time-fields-0-0 see here]), for example in ISO 8601 format (<code>2023-05-01T16:00:00.000Z</code> for May 1, 2023 at 4:00 PM UTC). When using your action in a workflow, Zapier will also offer data fields from the triggering application, more often suited to the data types you defined in the previous step.
</blockquote>
If everything goes well, you should see a success message and a preview of the data returned by the Dolibarr API, in this case, the identifier of the event created:

<syntaxhighlight lang="json">{
"id": 86
}</syntaxhighlight>

=== Configuration of the data returned by the API ===

In the third substep, you need to configure the data returned by the API. This is to tell Zapier what the data returned by the API corresponds to, to then possibly be reused in other scenarios. In our case, we will simply indicate that the identifier of the created event corresponds to the identifier of the event created by the Dolibarr API. To do this, simply click on the “Use Response from Test Data” button, then “Generate Output Field Definitions”. You should then see an <code>id</code> field appear in the list of output fields, give it the description <code>ID of the event created</code>.

All you have to do is click on the “Save Output & Finish” button to complete the configuration of your action.


== Step 4: Testing the action in a “Zap” ==

Now that your action is configured, you can use it in a “Zap” (user scenario). To do this, go to the [https://zapier.com/app/zaps Zapier user dashboard] and click on the “Create” > “New Zap” button.


=== Trigger setup ===

In the first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” > “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.

In the second step, you need to configure the Google account to use. Click the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Google Calendar account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the Google Calendar to monitor. Click the “Continue” button.

In the fourth and last step, you can test the trigger by clicking on the “Test trigger” button. This will look for an event in the selected Google Calendar and use it to test the rest of the scenario. If all goes well, you should see a success message and a preview of the data returned by the trigger. Click the “Continue” button.


=== Action Setup ===

In the first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” > “Create Event” action, which we created earlier. This will appear with the mention “By invite”, because it is not yet published. If you don’t see it, make sure you’re using the same Zapier account you used to create the action. If you want to use an action created but not published by another Zapier account, you can invite that account to collaborate on your Zapier app (see [https://platform.zapier.com/private_integrations/share-your-private-integration here]). Click the “Continue” button.

In the second step, you need to configure the Dolibarr account to use. Click on the “Connect a new account” button (or select an existing account), then follow the instructions to connect your Dolibarr account to Zapier. Once the account is connected, click on the “Continue” button.

In the third step, you need to configure the data to provide to the action. To do this, you can use the data returned by the trigger, by clicking on a field and selecting the corresponding field in the list of data. In our case, we will use the following data:

{| class="wikitable"
|-
! Field
! Google Calendar field
|-
| Event name
| Summary
|-
| Start date
| Event begins (pretty)
|-
| End date
| Event ends (pretty)
|-
| Location
| Location
|-
| Description
| Description
|}

Click the “Continue” button.

In the fourth step, you can test the action by clicking the “Test action” button. This will create an event in Dolibarr, with a copy of the Google Calendar event data. If all goes well, you should see a success message and a preview of the created event ID.

<div class="figure">

[[File:./screenshots/04-test-zap.png|Example of Zap test]]

</div>
All you have to do is click on the “Publish” button and “Turn Zap on” to activate your scenario.

<blockquote>'''Note:''' Some services like Gmail or Google Drive cannot be used in a Zapier scenario until the integration is published and validated. So you will be able to test your scenario, but when publishing you will get an error message. To work around this problem, you can for example use the “Code by Zapier” > “Run Javascript” action before the Dolibarr action, simply returning the trigger data to make it available in the Dolibarr action. Alternatively, you can publish your integration and have it validated.
</blockquote>
The different action configuration data is available in the file [[./code/creates/create_event.js|code/creates/create_event.js]], exported from Zapier CLI. Similarly, you will find other sample actions in the [[./code/creates|code/creates]] folder.


= Validate and publish the integration =

The final step is to validate and publish the integration. This step is necessary to be able to use the integration with other accounts than the one used to create it without having to invite them to collaborate on the Zapier application.

This part will not be covered in this tutorial, because it requires having the rights to the Dolibarr application or to the domain name of the organization (more information [https://platform.zapier.com/partners/integration-review-guidelines#21-integration-ownership here]).


= Go further =

Many other features are available in Zapier, such as the “search” actions, which allow you to list data in a third-party application in order to use it in a programmed scenario or executed via an external trigger. As seen above, it is possible to create triggers, but this will probably have to wait for better management of webhooks in Dolibarr. Finally, although Dolibarr already offers many APIs, some features are not yet available.


= Conclusion =

Zapier is a very powerful tool that allows you to create integrations between many third-party applications without having to write a single line of code. It also allows to create complex scenarios, using conditions and loops. Finally, it allows creating private integrations, which are not available to other Zapier users, but only to accounts invited to collaborate on the Zapier app. Dolibarr is a very complete application, which already offers many APIs, but which can be further improved. Its integration into Zapier will allow it to be used with many other applications, and to create complex scenarios, without having to write a single line of code.


= Credits =

This tutorial was produced by the [https://github.com/AuTEAMation AuTEAMation] team as part of the design of interfacing prototypes between the Dolibarr ERP/CRM and several automation platforms for [https://www.dolicloud.com/ DoliCloud]. This study was carried out as part of the PFA, a 2nd year group project at [https://enseirb-matmeca.bordeaux-inp.fr ENSEIRB-MATMECA].


= Licence =

This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].

[http://creativecommons.org/licenses/by-sa/4.0/ [[File:https://licensebuttons.net/l/by-sa/4.0/88x31.png|CC BY-SA 4.0]]]