Integration of Dolibarr to the Zapier automation platform: Difference between revisions

Jump to navigation Jump to search

Integration of Dolibarr to the Zapier automation platform (view source)

Revision as of 19:29, 14 May 2023

144 bytes added ,  3 years ago
fixing list format
VisualWikitext
(fixing bundle and lists)
Tag: 2017 source edit
(fixing list format)
Line 1: Line 1:
{{TemplateDocDevEn}}
{{TemplateDocDevEn}}


<span id="integration-of-dolibarr-to-the-zapier-automation-platform"></span>
=Integration of Dolibarr to the Zapier automation platform=


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


<span id="preamble"></span>
<span id="preamble"></span>
== Preamble ==
==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.
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.


<span id="prerequisites"></span>
<span id="prerequisites"></span>
== Prerequisites ==
==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)
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.
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.


<span id="create-the-zapier-integration"></span>
<span id="create-the-zapier-integration"></span>
= Create the Zapier integration =
=Create the Zapier integration=


Start by accessing the Zapier Platform Visual Builder at the following address: https://developer.zapier.com/.
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.
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:  
 
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


* 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">
<div class="figure">


Line 32: Line 45:


<span id="configure-authentication"></span>
<span id="configure-authentication"></span>
= Configure authentication =
=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.
Once you’ve created your integration, you’ll land on its dashboard. In the “Authentication” section, click on the “Set Up Authentication” button.
Line 41: Line 54:
</blockquote>
</blockquote>
<span id="step-1-configuring-authentication-fields"></span>
<span id="step-1-configuring-authentication-fields"></span>
== Step 1: Configuring Authentication Fields ==
==Step 1: Configuring Authentication Fields==


In the first step, click on the “Add Field” button to add a first field with the following information:
In the first step, click on the “Add Field” button to add a first field with the following information:
Line 47: Line 60:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Field
!Field
! Value
!Value
|-
|-
| Field Type
|Field Type
| <code>Field</code>
|<code>Field</code>
|-
|-
| Label
|Label
| <code>Instance URL</code>
|<code>Instance URL</code>
|-
|-
| Key
|Key
| <code>host</code>
|<code>host</code>
|-
|-
| Required
|Required
| ✅ Yes
|✅ Yes
|-
|-
| Type
|Type
| String
|String
|-
|-
| Help Text
|Help Text
| <code>Specify the base address of the Dolibarr instance, it must not have &quot;/&quot; at the end and must start with https://.</code>
|<code>Specify the base address of the Dolibarr instance, it must not have &quot;/&quot; at the end and must start with https://.</code>
|}
|}


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


Line 100: Line 113:


<span id="step-2-configuring-the-token-exchange-request"></span>
<span id="step-2-configuring-the-token-exchange-request"></span>
== Step 2: Configuring the token exchange request ==
==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).
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).
Line 132: Line 145:


<span id="step-3-configuring-the-test-request"></span>
<span id="step-3-configuring-the-test-request"></span>
== Step 3: Configuring the test request ==
==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.
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:
As before, click on the “Switch to Code Mode” button and paste the following code into it:


<syntaxhighlight lang="javascript">const options = {
<syntaxhighlight lang="javascript">const options = {
Line 153: Line 167:
     return results;
     return results;
   });</syntaxhighlight>
   });</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>.
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 &amp; Continue” button to go to the next step.
Then click on the “Save &amp; Continue” button to go to the next step.


<span id="step-4-testing-the-connection"></span>
<span id="step-4-testing-the-connection"></span>
== Step 4: Testing the connection ==
==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.
In the fourth step, you need to test the connection to Dolibarr. Click on the “Add a New Account” button.
Line 174: Line 187:
If all went well, you should see your account appear in the list of available accounts.
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>:
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">{
<syntaxhighlight lang="json">{
Line 188: Line 201:


<span id="create-a-trigger"></span>
<span id="create-a-trigger"></span>
= Create a trigger =
=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.
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.
Line 195: Line 208:


<span id="create-an-action"></span>
<span id="create-an-action"></span>
= Create an action =
=Create an action=


* '''Example case:''' Create an event in the Dolibarr calendar
*'''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
*'''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.
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.
Line 205: Line 218:


<span id="step-1-configuring-the-action"></span>
<span id="step-1-configuring-the-action"></span>
== Step 1: Configuring the action ==
==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):
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):
Line 211: Line 224:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Field
!Field
! Value
!Value
|-
|-
| Type
|Type
| Create
|Create
|-
|-
| Key
|Key
| <code>create_event</code>
|<code>create_event</code>
|-
|-
| Name
|Name
| <code>Create an event</code>
|<code>Create an event</code>
|-
|-
| Noun
|Noun
| <code>Event</code>
|<code>Event</code>
|-
|-
| Description
|Description
| <code>Create an event in the Dolibarr calendar</code>
|<code>Create an event in the Dolibarr calendar</code>
|-
|-
| Visibility Options
|Visibility Options
| Important (Displayed above the fold in the Zap Editor)
|Important (Displayed above the fold in the Zap Editor)
|}
|}


Line 236: Line 249:


<span id="step-2-configuring-the-fields"></span>
<span id="step-2-configuring-the-fields"></span>
== Step 2: Configuring the fields ==
==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.
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.
Line 244: Line 257:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Field
!Field
! Label
!Label
! Key
!Key
! Type
!Type
! Required
!Required
|-
|-
| Name
|Name
| <code>Event name</code>
|<code>Event name</code>
| <code>label</code>
|<code>label</code>
| String
|String
| ✅ Yes
|✅ Yes
|-
|-
| Start date
|Start date
| <code>Start date</code>
|<code>Start date</code>
| <code>datep</code>
|<code>datep</code>
| DateTime
|DateTime
| ✅ Yes
|✅ Yes
|-
|-
| End date
|End date
| <code>End date</code>
|<code>End date</code>
| <code>datef</code>
|<code>datef</code>
| DateTime
|DateTime
| ❌ No
|❌ No
|-
|-
| Location
|Location
| <code>Location</code>
|<code>Location</code>
| <code>location</code>
|<code>location</code>
| String
|String
| ❌ No
|❌ No
|-
|-
| Description
|Description
| <code>Description</code>
|<code>Description</code>
| <code>note_private</code>
|<code>note_private</code>
| Text
|Text
| ❌ No
|❌ No
|}
|}


Line 292: Line 305:
</div>
</div>
<span id="step-3-api-configuration"></span>
<span id="step-3-api-configuration"></span>
== Step 3: API configuration ==
==Step 3: API configuration==


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


<span id="api-request-configuration"></span>
<span id="api-request-configuration"></span>
=== API request configuration ===
===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:
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:
Line 330: Line 343:
</blockquote>
</blockquote>
<span id="testing-the-request-to-the-api"></span>
<span id="testing-the-request-to-the-api"></span>
=== Testing the request to the API ===
===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:
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:
Line 336: Line 349:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Field
!Field
! Value
!Value
|-
|-
| label
|label
| <code>Test event</code>
|<code>Test event</code>
|-
|-
| datep
|datep
| <code>2023-05-01T16:00:00.000Z</code>
|<code>2023-05-01T16:00:00.000Z</code>
|-
|-
| datef
|datef
| <code>2023-05-01T18:00:00.000Z</code>
|<code>2023-05-01T18:00:00.000Z</code>
|-
|-
| location
|location
| <code>Test room</code>
|<code>Test room</code>
|-
|-
| note_private
|note_private
| <code>This is a test event</code>
|<code>This is a test event</code>
|}
|}


Line 363: Line 376:
}</syntaxhighlight>
}</syntaxhighlight>
<span id="configuration-of-the-data-returned-by-the-api"></span>
<span id="configuration-of-the-data-returned-by-the-api"></span>
=== Configuration of the data returned by the API ===
===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>.
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>.
Line 370: Line 383:


<span id="step-4-testing-the-action-in-a-zap"></span>
<span id="step-4-testing-the-action-in-a-zap"></span>
== Step 4: Testing the action in a “Zap” ==
==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” &gt; “New Zap” button.
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” &gt; “New Zap” button.


<span id="trigger-setup"></span>
<span id="trigger-setup"></span>
=== Trigger setup ===
===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” &gt; “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 first step, you must configure the “trigger” of your scenario. In our case, we are going to use the “Google Calendar” &gt; “New Event” trigger, which lets you trigger the scenario when a new event is created in a Google Calendar. Click the “Continue” button.
Line 386: Line 399:


<span id="action-setup"></span>
<span id="action-setup"></span>
=== Action Setup ===
===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” &gt; “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 first step, you need to configure the action of your scenario. In our case, we are going to use the “Dolibarr” &gt; “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.
Line 396: Line 409:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Field
!Field
! Google Calendar field
!Google Calendar field
|-
|-
| Event name
|Event name
| Summary
|Summary
|-
|-
| Start date
|Start date
| Event begins (pretty)
|Event begins (pretty)
|-
|-
| End date
|End date
| Event ends (pretty)
|Event ends (pretty)
|-
|-
| Location
|Location
| Location
|Location
|-
|-
| Description
|Description
| Description
|Description
|}
|}


Line 433: Line 446:


<span id="validate-and-publish-the-integration"></span>
<span id="validate-and-publish-the-integration"></span>
= Validate and publish the integration =
=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.
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.
Line 440: Line 453:


<span id="go-further"></span>
<span id="go-further"></span>
= Go further =
=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.
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.


<span id="conclusion"></span>
<span id="conclusion"></span>
= Conclusion =
=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.
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.


<span id="credits"></span>
<span id="credits"></span>
= Credits =
=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].
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].


<span id="licence"></span>
<span id="licence"></span>
= Licence =
=Licence=


This tutorial is licensed under a [http://creativecommons.org/licenses/by-sa/4.0/ Creative Commons Attribution-ShareAlike 4.0 International License].
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]
IPazu
29

edits

Retrieved from "https://wiki.dolibarr.org/index.php/Special:MobileDiff/56532"

Navigation menu