Dolibarr ERP CRM Wiki

Changes

Using Dolibarr node in the n8n automation platform (view source)

Revision as of 09:47, 25 May 2023

2,227 bytes added ,  1 year ago
m
no edit summary
Line 1: Line 1: −
== Connecting to n8n ==
+
{{TemplateDocUser}}
−
As explained in previous parts, once you have created your n8n self-hosted instance on your computer and started it with the command :
+
[[Category:No Code Automation]]
−
```bash
  −
n8n start
  −
```
  −
or
  −
```bash
  −
n8n
  −
```
  −
you just have to press `o` on your terminal to open n8n in your browser.
     −
You should arrive to the following connexion screen where you can enter your connexion informations.
+
If you want a developer tutorial to the integration of Dolibarr to the n8n automation platform you can find it [[Integration of Dolibarr to the n8n automation platform|here.]]
   −
![Connecting to n8n](./screenshots/connecting_to_n8n.png)
+
==Prerequisites==
 +
The following tutorial assumes that you have completed the following prerequisites:
   −
== Creating a Workflow using Dolibarr Node ==
+
*You have access to an instance of Dolibarr configured to use SSL encryption (with the HTTPS protocol),
−
When you have signed in, you can create you first Workflow and selected the Dolibarr node.
+
*You have access to a user account with rights to use some specific modules such as Calendar, Project or Documents,
 +
*You have obtained an API key for this user account that you will be used to test your integration (generated by an administrator, or by the user himself if he has permission to modify his user account information).
   −
To do that you just have to click on `Add Workflow` to create one and click on the `+` to add a node to your Workflow. It will open a search bar in which you can search `dolibarr` to find it.
+
When necessary, in this documentation, 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.
 +
<br />
    +
==Connecting to n8n==
 +
As explained in previous parts, once you have created your n8n self-hosted instance on your computer and started it with the command : <code>n8n start</code> or <code>n8n</code>.
   −
![Dolibarr Node](./screenshots/dolibarr_node.png)
+
Then you just have to press '''o''' on your terminal to open n8n in your browser.
   −
== Explanation of the different functionnalities ==
+
You should arrive to the following connexion screen where you can enter your connexion informations.
−
![Different scenarios](./screenshots/different_scenarios.png)
+
<br />
 +
[[File:Connecting to n8n.png|center|thumb|Connecting to n8n]]
   −
Here are the different Dolibarr functionnalities we have implemented in n8n.
     −
=== General informations ===
+
==Creating a Workflow using Dolibarr Node==
 +
When you have signed in, you can create you first Workflow and selected the Dolibarr node.
   −
==== Credentials ====
+
To do that, you just have to click on '''Add Workflow''' to create one and click on the '''+''' to add a node to your Workflow. It will open a search bar in which you can search '''dolibarr''' to find it.
−
For every Dolibarr node you will have to setup up your credentials in order to connect your Dolibarr instance to n8n.
+
[[File:Dolibarr node.png|center|thumb|Dolibarr node]]
   −
You can connect to your Dolibarr from the `Credentials` tab or directly from a Dolibarr node.
     −
![Credentials](./screenshots/credentials.png)
+
==Explanation of the different functionalities==
 +
[[File:Different scenarios.png|center|thumb|Different scenarios]]
   −
You have to indicate you base URL which is your instance URL.
     −
And your API key that you can find in your account parameters when connecting in Dolibarr.
+
Here are the different Dolibarr functionalities we have implemented in n8n.
 +
<br />
   −
==== Fields in every node ====
+
===General informations===
−
![Add event in n8n](./screenshots/add_event_n8n.png)
     −
For every Dolibarr node there will be some fields that will be the same.
+
====Credentials====
 +
A Dolibarr node needs to have set up credentials in order to connect your Dolibarr instance to n8n.
   −
These fiels are the first three one on the picture below :
+
You can connect to your Dolibarr account from the `Credentials` tab or directly from a Dolibarr node.
−
- `Credential` to connect with : this is where you can set your `credentials` as explained just before,
+
[[File:Credentials.png|center|thumb|Credentials]]
−
- `Resource` : this is where you just which module of Dolibarr it will affect, there are 4 options : Calendar, Task, Document and Custom API Call (use this one only if you know what you are doing),
  −
- `Operation` : this is in this field where you select this kind of operation you want to do on this specific resource, for now it only support creation operation
     −
=== Creating a Calendar Event ===
  −
The first node is used to create an event in the calendar in Dolibarr.
     −
![Add event in n8n](./screenshots/add_event_n8n.png)
+
You have to indicate you base URL which is your instance URL.
   −
If you have selected the `Create an Event` and have alreary set your credentials the first three fields will be already completed.
+
And your API key that you can find in your account parameters when connected in Dolibarr.
−
 
+
<br />
−
For the next fields :
  −
- `Event Name` corresponds with the `Label` field in Dolibarr interface (this field is required),
  −
- `Description` corresponds with the `Descriptio` field (this field is optional),
  −
- `Event Type` corresponds with the `Type` type field, three options are available : `Intervention on site`, `Meetings` and `Reception of Email` (this field is required),
  −
- `Beginning Date of Event` corresponds with the left date in the `Date` field (this field is required),
  −
- `End Date of Event` corresponds with the right date in the `Date` field (this field is required),
  −
- `Email From` is not corresponding to any field for now on Dolibarr but since this field is present in Dolibarr AP, it is possible that is the next updates a dedicated Mail Sender field will be available on Dolibarr interface (this field is optional),
  −
- `Email Subject` is also not corresponding to ant field for now on Dolibarr and as the the previous one we can expect to the a dedicated field appears is the next updates (this field is optional).
  −
 
  −
![Add event in Dolibarr](./screenshots/add_event_dolibarr.png)
      +
====Fields in every node====
 
<br />
 
<br />
 +
[[File:Add event n8n.png|center|thumb|Fields in every node]]
   −
==== Creating an event in Calendar when an event is created in Google Calendar ====
  −
To produce this use case you will have to connect a `Google Calendar Trigger node` on the `Dolibarr node`.
     −
The `Google Calendar Trigger node` documentation can be found here https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.googlecalendartrigger/.
+
For every Dolibarr node there will be some fields that will be the same.
   −
Once you have set up the `Google Calendar Trigger node` you can connect it to the `Dolibarr Create an event node`.
+
These fields are the first three one on the picture below:
   −
![Google Calendar Use Case](./screenshots/google_calendar_use_case.png)
+
*'''Credential to connect with''': this is where you can set your '''credentials''' as explained just before,
 +
*'''Resource''': this is where you choose which module of Dolibarr will be affected, there are 4 options : Calendar, Task, Document and Custom API Call (use this one only if you know what you are doing),
 +
*'''Operation''': this is in this field where you select the kind of operation you want to do on this specific resource, for now it only supports creation operation.
   −
One possible configuration to have the wanted informations is to enter to same informations as the screenshot.
+
<br />
   −
Be sure to select `Expression` mode on fields that use the previous node informations.
+
===Creating a Calendar Event===
 +
The first node is used to create an event in the calendar in Dolibarr.
 +
[[File:Add event n8n.png|center|thumb|Add event in n8n]]
   −
You can either type or drag and drop from the left window which field you want to have from the Google Calendar Event.
     −
Here :
+
If you have selected the '''Create an Event''' operation and have alreary set your credentials the first three fields will be already completed.
   −
- `{{$json.summary }}` correspond to the Google Caldendar Name,
+
For the next fields:
   −
- `{{$json.htmlLink }}` correspond to the Google Caldendar URL (doing this is optional, description can be empty as explained before, entering the URL only facilitate the Google Calendar event access from Dolibarr),
+
*'''Event Name''' corresponds with the '''Label''' field in Dolibarr interface (this field is required),
 +
*'''Description''' corresponds with the '''Description''' field (this field is optional),
 +
*'''Event Type''' corresponds with the '''Type''' type field, three options are available : '''Intervention on site''', '''Meetings''' and '''Reception of Email''' (this field is required),
 +
*'''Beginning Date of Event''' corresponds with the left date in the '''Date''' field (this field is required),
 +
*'''End Date of Event''' corresponds with the right date in the '''Date''' field (this field is required),
 +
*'''Email From''' is not corresponding to any field for now on Dolibarr but since this field is present in Dolibarr API, it is possible that is the next updates a dedicated Mail Sender field will be available on the Dolibarr interface (this field is optional),
 +
*'''Email Subject''' is also not corresponding to any field for now on Dolibarr and as the previous one we can expect that a dedicated field appears is the next updates (this field is optional).
   −
- `{{$json.start.dateTime }}` correspond to the starting time of the Google Calendar event,
+
<br />
 +
[[File:Add event dolibarr.png|center|thumb|Add event in Dolibarr]]
 +
<br />
   −
- `{{$json.start.dateTime }}` correspond to the ending time of the Google Calendar event.
+
====Creating an event in Calendar when an event is created in Google Calendar====
 +
To produce this use case you will have to connect a '''Google Calendar Trigger node''' on the '''Dolibarr node'''.
   −
==== Creating an event in Calendar when an email is received ====
+
The '''Google Calendar Trigger node''' documentation can be found [https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.googlecalendartrigger/ here].
−
To produce this use case you will have to connect an `Email Trigger node` on the `Dolibarr node`, for example the `Email Trigger (IMAP) node` or the `Gmail Trigger node`.
     −
The `Email Trigger (IMAP) node` documentation can be found here https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/ and the `Gmail Trigger node` one here https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailtrigger/.
+
Once you have set up the '''Google Calendar Trigger node''' you can connect it to the '''Dolibarr Create an event node'''.
 +
<br />
 +
[[File:Google calendar use case.png|center|thumb|Creating an event in Calendar when an event is created in Google Calendar]]
   −
As before when have set up the trigger node you can connect it to the `Dolibarr Create an event node`. ![Email Use Case Before Update](./screenshots/mail_use_case_before_update.png)
     −
For the example of configuration the `Email Trigger node` case will be presented since it is the more general case. One possible configuration to have the wanted informations is to enter to same informations as the screenshot.
     −
Be sure to select `Expression` mode on fields that use the previous node informations.
+
One possible configuration to have the wanted informations is to enter to same informations as in the screenshot.
   −
You can either type or drag and drop from the INPUT window on the left which field you want to have from the received mail.
+
Be sure to select '''Expression''' mode on fields that use the previous node informations.
   −
Here :
+
You can either type or drag and drop from the left window which field you want to have from the Google Calendar Event.
   −
- `{{$json.subject }}` correspond to the subject of the mail,
+
Here:
   −
- `{{$json.from }}` correspond to the email sender,
+
*<code>$json.summary</code> corresponds to the Google Caldendar Event Name,
 +
*<code>$json.htmlLink</code> corresponds to the Google Caldendar event URL (doing this is optional since description can be empty as explained before, entering the URL only facilitate the Google Calendar event access from Dolibarr),
 +
*<code>$json.start.dateTime</code> corresponds to the starting time of the Google Calendar event,
 +
*<code>$json.end.dateTime</code> corresponds to the ending time of the Google Calendar event.
   −
- `{{$json.date }}` correspond to the date when the email was send,
+
<br />
   −
The `Gmail Trigger node` will be similar, you can find the desired field using the INPUT window on the left in Schema mode to help yourself. ![Email Use Case After Update](./screenshots/mail_use_case_after_update.png)
+
====Creating an event in Calendar when an email is received====
 +
To produce this use case you will have to connect an '''Email Trigger node''' on the '''Dolibarr node''', for example the '''Email Trigger (IMAP) node''' or the '''Gmail Trigger node'''.
   −
The second screenshot correspond to a possible configuration of the `Dolibarr Create an event Node` with the `Email Trigger (IMAP) node` when the `Email From` and `Email Subject` fields will be implemented in the Dolibarr interface in future updates.
+
The '''Email Trigger (IMAP) node''' documentation can be found [https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/ here] and the '''Gmail Trigger node''' one [https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailtrigger/). here].
   −
=== Creating a document ===
+
As before, when you have set up the trigger node you can connect it to the '''Dolibarr Create an event node'''.  
−
The second node is used to create create a document on a specific Dolibarr module. ![Add event in n8n](./screenshots/add_document_n8n.png)
+
<br />
 +
[[File:Mail use case before update.png|center|thumb|Creating an event in Calendar when an email is received before update]]
   −
If you have selected the `Create a document` and have alreary set your credentials the first two fields will be already completed.
     −
For the next fields :
+
For the example of configuration, this is the '''Email Trigger node''' case that will be presented since it is the more general case. One possible configuration to have the wanted informations is to enter to same informations as the screenshot.
   −
- `File Name` correspond to the file name is Dolibarr, it is important not to forget the file extension if you want it to have one (this field is required),
+
Be sure to select '''Expression''' mode on fields that use the previous node informations.
   −
- `Module Name` correspond to the Dolibarr module where the file will be created (this field is required),
+
You can either type or drag and drop from the '''INPUT''' window on the left which field you want to have from the received mail.
   −
- `Reference` correspond to the `Ref.` of the object to which the file with will linked (this field is required),
+
Here:
   −
- `File content` correspond to the content that will be written in the file (this field is optional),
+
*<code>$json.subject</code> corresponds to the subject of the mail,
 +
*<code>$json.textPlain</code> corresponds to the email sender,
 +
*<code>$json.from</code> corresponds to the body of the email,
 +
*<code>$json.date</code> corresponds to the date when the email was sent.
   −
- `File Encoding` is an additionnal field that needs to be activated if you want to add file with formatting like pdf which needs to be encoded in base64 (this field is optional),
+
The '''Gmail Trigger node''' will be similar, you can find the desired field using the '''INPUT''' window on the left in '''Schema''' mode to help yourself.
 +
<br />
 +
[[File:Mail use case after update.png|center|thumb|Creating an event in Calendar when an email is received after update]]
   −
- `Overwrite File if It Already Exists ?` is an additionnal field than when activated will allowed file overwriting if the File Name entered already exists (this field is optional),
     −
- `Create Subdirectories if Necessary ?` is an additionnal field that when activated creates a Subdirectory for your file if this is necessery (this field is optional).
+
The second screenshot correspond to a possible configuration of the `Dolibarr Create an event Node` with the `Email Trigger (IMAP) node` when the `Email From` and `Email Subject` fields will be implemented in the Dolibarr interface in future updates.
 +
<br />
   −
==== Add a document in Dolibarr Document Gestion containing Zoom meeting information ====
+
===Creating a document===
−
To produce this use case you will have to connect an `Zoom Get Meeting node` on the `Dolibarr node` with a `n8n Trigger node` at the beggining og the workflow.
+
The second node is used to create a document on a specific Dolibarr module.
 +
<br />
 +
[[File:Add document n8n.png|center|thumb|Add a document in n8n]]
   −
The `Zoom node` documentation can be found here https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.zoom/.
     −
As before when have set up the node you can connect it to the `Dolibarr Create an event node`. ![Add a document in Dolibarr](./screenshots/zoom_use_case.png)
+
If you have selected '''Create a document''' and have alreary set your credentials the first two fields will be already completed.
   −
One possible configuration to have a Zoom meeting informations is to enter to same informations as the screenshot.
+
For the next fields:
   −
Be sure to select `Expression` mode on fields that use the previous node informations.
+
*'''File Name''' corresponds to the file name is Dolibarr, it is important not to forget the file extension if you want it to have one (this field is required),
 +
*'''Module Name''' corresponds to the Dolibarr module where the file will be created (this field is required),
 +
*'''Reference''' corresponds to the `Ref.` of the object to which the file will be linked (this field is required),
 +
*'''File Content''' corresponds to the content that will be written in the file (this field is optional),
 +
*'''File Encoding''' is an additionnal field that needs to be activated if you want to add file with formatting, like pdf which needs to be encoded in base64 (this field is optional),
 +
*'''Overwrite File if It Already Exists ?''' is an additionnal field that when activated will allow file overwriting if the File Name entered already exists (this field is optional),
 +
*'''Create Subdirectories if Necessary ?''' is an additionnal field that when activated creates a Subdirectory for your file if this is necessery (this field is optional).
   −
You can either type or drag and drop from the INPUT window on the left which field you want to have from the received mail.
+
<br />
   −
Here :
+
====Add a document in Dolibarr Document Gestion containing Zoom meeting information====
 +
To produce this use case you will have to connect an '''Zoom Get Meeting node''' on the '''Dolibarr node''' with a '''n8n Trigger node''' at the beggining of the workflow.
   −
- `{{$json.topic }}` correspond to the topic of the Zoom meeting,
+
The '''Zoom node''' documentation can be found [https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.zoom/). here].
   −
- `{{$json.host_email }}` correspond to the email of the person who host the Zoom meeting,
+
As before when have set up the node you can connect it to the '''Dolibarr Create an event node'''.
 +
<br />
 +
[[File:Zoom use case.png|center|thumb|Add a document in Dolibarr Document Gestion containing Zoom meeting information]]
   −
- `{{$json.duration }}` correspond to the duration of the Zoom metting,
     −
- `{{$json.timezone }}` correspond to the time zone where was done the Zoom metting.
+
One possible configuration to have a Zoom meeting informations is to enter to same informations as on the screenshot.
   −
Besides, some a .docx file extension is added to generate a file compatible with LibreOffice Write, this format does not need File Encodind.
+
Be sure to select '''Expression''' mode on fields that use the previous node informations.
   −
This file will be addded to the Agenda Evend associated with the Zoom meeting, in the example this is the event with eht reference n°33.
+
You can either type or drag and drop from the '''INPUT''' window on the left which field you want to have from the received mail.
   −
Finally, the additional Field `Overwrite File If Already Exists` is activated to be able ot overwrite the file with more or different informations  from the Zoom meeting if wanted.
+
Here:
   −
=== Creating a Project Task ===
+
*<code>$json.topic</code> corresponds to the topic of the Zoom meeting,
−
![Add task on n8n](./screenshots/add_task_n8n.png)
+
*<code>$json.host_email</code> corresponds to the email of the person who host the Zoom meeting,
 +
*<code>$json.duration</code> corresponds to the duration of the Zoom metting,
 +
*<code>$json.timezone</code> corresponds to the time zone where was done the Zoom metting.
   −
The third node is used to create a task in the project module of Dolibarr.
+
Besides, a .docx file extension is added to generate a file compatible with LibreOffice Writer, this format does not need '''File Encoding'''.
   −
If you have selected the `Create a Task` and have alreary set your credentials the first three fields will be already completed.
+
This file will be added to the Agenda Event associated with the Zoom meeting, in the example this is the event with the '''Reference''' n°33.
   −
For the next fields :
+
Finally, the additional Field '''Overwrite File If Already Exists ?''' is activated to be able ot overwrite the file with more or different informations  from the Zoom meeting if wanted.
 +
<br />
   −
- `Task Reference` corresponds with the `Ref.` field in Dolibarr interface, the `Task Reference` is a `string` that must be unique, (this field is required),
+
===Creating a Project Task===
 +
The third node is used to create a task in the project module of Dolibarr.
 +
<br />
 +
[[File:Add task n8n.png|center|thumb|Add task in n8n]]
   −
- `Project ID` corresponds with the `Child of project` field, this is a number corresponding to the id of the project from which the task will be a child (this field is required),
     −
- `Task Name` corresponds with the `Label` field (this field is required),
+
If you have selected '''Create a Task''' and have alreary set your credentials the first three fields will be already completed.
   −
- `Description` corresponds with the `Description` field (this field is optional),
+
For the next fields:
   −
- `Starting Date` corresponds with the left date in the `Date` field (this field is required),
+
*'''Task Reference''' corresponds with the '''Ref.''' field in Dolibarr interface, the '''Task Reference''' is a '''string''' that must be unique, (this field is required),
 +
*'''Project ID''' corresponds with the '''Child of project''' field, this is a number corresponding to the id of the project from which the task will be a child (this field is required),
 +
*'''Task Name''' corresponds with the '''Label''' field (this field is required),
 +
*'''Description''' corresponds with the '''Description''' field (this field is optional),
 +
*'''Starting Date''' corresponds with the left date in the '''Date''' field (this field is required),
 +
*'''Ending Date''' corresponds with the right date in the '''Date''' field (this field is optional).
   −
- `Ending Date` corresponds with the right date in the `Date` field (this field is optional), ![Add task on Dolibarr](./screenshots/add_task_dolibarr.png)
+
<br />
 +
[[File:Add task dolibarr.png|center|thumb|Add task in Dolibarr]]
 +
<br />
   −
A possible configuration for creating a document having zoom meeting inf
+
====Creating a Task in Dolibarr when a Github issue is received====
 +
To produce this use case you will have to connect a '''Github Trigger node''' on the '''Dolibarr node'''.
   −
==== Creating a Task in Dolibarr when a Github issue is received ====
+
It is important here if you are using a self-hosted instance of n8n to start it in tunnel mode. To do so, just run the following command: <code>n8n start --tunnel</code>.
−
To produce this use case you will have to connect a `Github Trigger node` on the `Dolibarr node`.
     −
It is important here if you are using a self-hosted instance of n8n to start it in tunnel mode. To do so, just run the following command :
+
To trigger on receiving issues select the type '''Issues''' in the '''Events''' field.
   −
```bash
+
The '''Github Trigger node''' documentation can be found [https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.githubtrigger/ here].
   −
n8n start --tunnel
+
Once you have set up the '''Github Trigger node''' you can connect it to the '''Dolibarr Create a task node'''.
−
 
+
<br />
−
```
+
[[File:Github use case.png|center|thumb|Creating a Task in Dolibarr when a Github issue is received]]
   −
To trigger on receiving issues select the type `Issues` in the `Events` field.
     −
The `Github Trigger node` documentation can be found here https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.githubtrigger/.
+
One possible configuration to have the wanted informations is to enter to same informations as on the screenshot.
   −
Once you have set up the `Github Trigger node` you can connect it to the `Dolibarr Create a task node`. ![Google Calendar Use Case](./screenshots/github_use_case.png)
+
Be sure to select '''Expression''' mode on fields that use the previous node informations.
−
 
  −
One possible configuration to have the wanted informations is to enter to same informations as the screenshot.
  −
 
  −
Be sure to select `Expression` mode on fields that use the previous node informations.
      
You can either type or drag and drop from the left window which field you want to have from the Github Issue.
 
You can either type or drag and drop from the left window which field you want to have from the Github Issue.
   −
Here :
+
Here:
−
 
  −
- `{{$json.body.repository.name }}` correspond to the name of the Github reposity,
  −
 
  −
- `{{$json.body.issue.title }}` correspond to the title of the issue,
     −
- `{{$json.body.issue.body }}` correspond to comment leave on the issue,
+
*<code>$json.body.repository.name</code> corresponds to the name of the Github repository,
 +
*<code>$json.body.issue.title</code> corresponds to the title of the issue,
 +
*<code>$json.body.issue.body</code> corresponds to comment leave on the issue,
 +
*<code>$json.body.issue.created_at</code> corresponds to the creation date of the issue.
   −
- `{{$json.body.issue.created_at }}` correspond to creation date of the issue.
+
==Conclusion==
 +
This tutorial helped you understand how to configure a Dolibarr node in n8n and how they work in order to make you build the example use cases or custom use cases using already existing Dolibarr node functionalities.
   −
=== Conclusion ===
+
==Credits==
−
This tutorial helped you understand how to configure a Dolibarr node in n8n and how they work in order to make you build the example use cases or custom use cases using already existing Dolibarr node functionnalities.
+
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].
Retrieved from "https://wiki.dolibarr.org/index.php?title=Special:MobileDiff/56420...56600"