Module EMail Collector: Difference between revisions

Jump to navigation Jump to search

Module EMail Collector (view source)

Revision as of 11:23, 10 November 2026

10,357 bytes added ,  15 hours ago
Add Office 366 configuration
VisualWikitext
Tag: 2017 source edit
(Add Office 366 configuration)
 
Line 58: Line 58:


Choose the action to do on collected emails.
Choose the action to do on collected emails.
==Configuring Microsoft 365 / Office 365 (Exchange Online)==
This procedure uses IMAP with delegated OAuth 2.0 and initial browser authorization. It is based on Dolibarr 24's native mechanisms; available providers and labels can differ between installed versions. It does not describe app-only authentication using IMAP.AccessAsApp.
===Prerequisites===


*An Exchange Online mailbox accessible to the account authorizing the connection.
*Dolibarr administrator access and a Microsoft Entra / Exchange administrator for the required permissions.
*A valid HTTPS Dolibarr URL, including any installation subdirectory.
*From the Dolibarr hosting server: DNS resolution and outbound TCP connections to outlook.office365.com:993 and Microsoft OAuth HTTPS endpoints on port 443. A successful connection from a user's workstation does not verify the server's connectivity.


===Dolibarr: collect the information needed for Microsoft registration===
#Enable the '''Email Collector''' module in Setup → Modules/Applications.
#Open Setup → OAuth services, or <code>/admin/oauth.php</code>.
#Create a dedicated service and, where available, select '''Microsoft Exchange Online [SMTP/IMAP]'''. This provider can be used for incoming mail only.
#Copy the '''redirect URL displayed by Dolibarr'''. For this provider, it ends with <code>/core/modules/oauth/microsoft3_oauthcallback.php</code>. Example: <code>https://erp.example.org/core/modules/oauth/microsoft3_oauthcallback.php</code>.
#When using another native or generic provider, use its displayed URL: microsoft, microsoft2 and generic callbacks are different. Do not substitute an arbitrary path.
===Microsoft 365 setup===
====1. Register the application====
In the [https://entra.microsoft.com/ Microsoft Entra admin center], open '''Identity → App registrations → New registration'''.
*Use a clear application name, such as “Dolibarr – IMAP collection”.
*For an organization's internal installation, select accounts in this organizational directory only.
*Add a '''Web''' platform and enter exactly the redirect URL copied from Dolibarr.
*Record the '''Application (client) ID''' and '''Directory (tenant) ID'''.
See [https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app app registration] and [https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-redirect-uri redirect URIs].
====2. Application credential====
For the Dolibarr provider using a client secret, open '''Certificates & secrets → Client secrets → New client secret'''. Copy its '''Value''', not its secret ID. Record the expiry date and arrange its replacement in Dolibarr. The value cannot be displayed again later. Do not publish it in documentation, logs or email.
See [https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials application credentials].
====3. Permissions and consent====
Configure the '''delegated''' permissions required for this flow: <code>IMAP.AccessAsUser.All</code> and <code>offline_access</code>. These are available in the Microsoft Graph delegated permission catalogue. '''Mail.Read alone does not replace IMAP permission.'''
Have an administrator grant consent when tenant policy requires it, then verify the status. Merely adding permissions to the app registration does not grant consent. Administrator approval does not replace the subsequent mailbox authorization from Dolibarr.
Collector filters do not restrict the token's mailbox permissions.
See [https://learn.microsoft.com/en-us/graph/permissions-reference#imapaccessasuserall IMAP permission] and [https://learn.microsoft.com/en-us/troubleshoot/entra/entra-id/app-integration/troubleshoot-consent-issues consent troubleshooting].
====4. Enable mailbox IMAP access====
In the Exchange admin center, open '''Recipients → Mailboxes → select the mailbox → Email apps → Manage''', then enable IMAP if necessary.
After connecting to Exchange Online PowerShell, an Exchange administrator can also run: <syntaxhighlight lang="powershell">
Get-CASMailbox -Identity "collector@example.org" | Select-Object ImapEnabled
Set-CASMailbox -Identity "collector@example.org" -ImapEnabled $true
</syntaxhighlight>
Security and Conditional Access policies must permit the OAuth flow. Do not disable MFA or tenant-wide protections to work around a refusal.
See [https://learn.microsoft.com/en-us/Exchange/recipients-in-exchange-online/manage-user-mailboxes/managing-email-apps-for-user-mailboxes protocol management] and [https://learn.microsoft.com/en-us/powershell/module/exchangepowershell/set-casmailbox?view=exchange-ps Set-CASMailbox].
===Dolibarr: complete OAuth authorization===
Complete the service created earlier:
{| class="wikitable"
!Field!!Value
|-
|Client ID||Microsoft Application ID
|-
|Client secret||Secret Value
|-
|Tenant / directory||Microsoft tenant ID
|-
|IMAP scope||https://outlook.office.com/IMAP.AccessAsUser.All
|-
|Token renewal||offline_access
|}For incoming mail only, do not select SMTP.Send or add Graph mail-reading scopes to the IMAP token.
Save, then use the authorization / token-generation action. Sign in with the account for the mailbox to collect, complete MFA, and return to Dolibarr. Check that the token is stored and renewal is available. Consent granted using an administrator account does not mean that a token for the target mailbox exists.
The native Microsoft provider manages the endpoints. When identifying the settings for a configurable provider, these are:<pre>
Authorization: https://login.microsoftonline.com/&lt;TENANT_ID&gt;/oauth2/v2.0/authorize
Token: https://login.microsoftonline.com/&lt;TENANT_ID&gt;/oauth2/v2.0/token
</pre>See [https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth IMAP OAuth] and [https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow the authorization code flow].
===Configure the collector===
On versions where collector OAuth depends on PHP-IMAP/Webklex, enable the native engine by setting <code>MAIN_IMAP_USE_PHPIMAP</code> to <code>1</code> in Setup → Other setup. Check that the required components are available in the distribution; this engine is different from the PHP ext-imap extension.
{| class="wikitable"
!Setting!!Value / choice
|-
|IMAP server||outlook.office365.com
|-
|Port||993
|-
|Encryption||Implicit SSL/TLS; generally labelled “SSL” in Dolibarr
|-
|Authentication||OAuth token / OAuth2
|-
|Login||Full mailbox address
|-
|OAuth service||Service authorized for this mailbox
|-
|Mailbox password||Not used with OAuth; keep the client secret in the OAuth service
|-
|Source folder||INBOX, or the folder's exact IMAP name
|-
|Initial maximum messages||1, to limit the first test
|}Collection uses port 993; SMTP port 587 is not used to read mail. See [https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/pop3-and-imap4/pop3-and-imap4 Exchange Online connection settings].
Next, configure filters and operations. For example, combine the expected sender and recipient to select messages from a website form. A business-object creation operation and its permissions are separate from IMAP access.
With Multicompany, configure the collector, OAuth service and operations in the intended entity, then check their permissions and availability. Successful Microsoft authentication does not validate business-object creation.
===Testing, scheduling and maintenance===
#Keep the collector inactive while configuring it. Check connectivity and folders first.
#Test message selection with a small limit and read the report.
#Standard test mode avoids IMAP message moves and rolls back the intended SQL writes. External effects triggered by extensions, such as outgoing emails, may not be reversible: review operations before testing.
#Perform a controlled real collection, verify the created objects and message handling, then enable the collector.
#Enable the corresponding native job in '''Scheduled jobs''' and verify that the server actually invokes the Dolibarr scheduler. Monitor the last result and errors.
Plan client-secret replacement, monitor failures, and authorize again if the refresh token is revoked. Manually pasting a temporary access token is not a permanent configuration. See [https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens refresh tokens].
===Troubleshooting===
{| class="wikitable"
!Symptom!!Check
|-
|Administrator approval required, including AADSTS90094||Correct application and tenant, actual delegated permissions requested, and consent
|-
|Redirect URI error||Exact HTTPS URL, installation subdirectory and selected provider's callback
|-
|Token accepted but IMAP authentication fails||Authorized account, collector login, Exchange IMAP scope and enabled protocol
|-
|Timeout / inaccessible port 993||Hosting server DNS and outbound firewall, including hosting-provider restrictions
|-
|No messages selected||Folder, sender, recipient, other filters and collection limit
|-
|Messages read but no object created||Operations, rights, entity and business-module compatibility
|-
|Collection stops after previously working||Expired client secret, revoked token or changed sign-in policy
|}'''Shared mailboxes:''' this guide targets a user mailbox. Shared mailbox access uses an authorized delegated user with the required mailbox permissions; check support in the installed Dolibarr version. Do not assume interactive sign-in directly as the shared mailbox.
'''Outgoing mail:''' SMTP is configured separately. Add SMTP.Send and configure SMTP AUTH only when sending is required.
===Dolibarr references and verification scope===
*[https://github.com/Dolibarr/dolibarr/blob/769c7db907099643558e77d7002c109cfda919e5/htdocs/core/lib/oauth.lib.php OAuth providers, Dolibarr 24 reference]
*[https://github.com/Dolibarr/dolibarr/blob/769c7db907099643558e77d7002c109cfda919e5/htdocs/emailcollector/class/emailcollector.class.php Collector fields and processing, same reference]
*[https://github.com/Dolibarr/dolibarr/blob/769c7db907099643558e77d7002c109cfda919e5/htdocs/admin/emailcollector_card.php Collector card and actions]
Prepared on 10 November 2026, without screenshots. Based on source inspection and Microsoft documentation; this is not acceptance testing of every version or tenant.
=Usage=
=Usage=
Let the job scheduler ([[Module Scheduled jobs]]) being executed automatically to run the Email collectore and see your data being recorded into Dolibarr.
Let the job scheduler ([[Module Scheduled jobs]]) being executed automatically to run the Email collectore and see your data being recorded into Dolibarr.
Line 67: Line 200:
A test mode is available (button '''Test'''). This mode does not cause any modification of your mailbox (just reading) nor modification in Dolibarr. On the other hand, it allows you to see the different stages of the selection of qualified email, the filter and the processing of the actions that would be applied if we were not in test mode. This is an important feature to fine-tune the configuration of the collector.
A test mode is available (button '''Test'''). This mode does not cause any modification of your mailbox (just reading) nor modification in Dolibarr. On the other hand, it allows you to see the different stages of the selection of qualified email, the filter and the processing of the actions that would be applied if we were not in test mode. This is an important feature to fine-tune the configuration of the collector.


== Trouble shooting ==
==Trouble shooting==
If you got the error "connection setup failed - authenticate" with Google OAuth and your OAuth token + refresh works, check the Login (email) in your Emailcollector setup.
If you got the error "connection setup failed - authenticate" with Google OAuth and your OAuth token + refresh works, check the Login (email) in your Emailcollector setup.


== Example of use case: Using Emailcollector for a support center ==
==Example of use case: Using Emailcollector for a support center==
You have a support center with n employees. The email of your support center is support@mycompany.com (an independant email or a mailing-list that dispatch any input email to the n employees).  
You have a support center with n employees. The email of your support center is support@mycompany.com (an independant email or a mailing-list that dispatch any input email to the n employees).  


You must:
You must:
* Declare/Allow the email support@mycompany.com as a possible sender email for each employee (Example on Gmail: click on the menu wheel "Parameters", See All parameters, tab "Accounts and import", in section "Send email as", click on "Add another email", enter the email support@mycompany.com but uncheck the checkbox "alias", then click on link received by email to validate the new sender profile, go back in section "Send email as" and check the option "Reply from the same address the message was sent to").  
 
*Declare/Allow the email support@mycompany.com as a possible sender email for each employee (Example on Gmail: click on the menu wheel "Parameters", See All parameters, tab "Accounts and import", in section "Send email as", click on "Add another email", enter the email support@mycompany.com but uncheck the checkbox "alias", then click on link received by email to validate the new sender profile, go back in section "Send email as" and check the option "Reply from the same address the message was sent to").
 
So it will be possible for every employee to send/answer emails as the  sender support@mycompany.com. So if the customer answer email of any employee, the answer will be sent to support@mycompany.com (so the n employees will also receive it).
So it will be possible for every employee to send/answer emails as the  sender support@mycompany.com. So if the customer answer email of any employee, the answer will be sent to support@mycompany.com (so the n employees will also receive it).
* Once this is done, if the email support@mycompany.com is a Mailing-List, it is recommended to create another email account, for exemple *followsupport@mycompany.com* and include it as another member of the mailing list support@mycompany.com. So followsupport@mycompany.com will receive any emails and answers inside the Inbox.
 
* Enable the [[Module EMail Collector]] and the [[Module Ticket]].
*Once this is done, if the email support@mycompany.com is a Mailing-List, it is recommended to create another email account, for exemple *followsupport@mycompany.com* and include it as another member of the mailing list support@mycompany.com. So followsupport@mycompany.com will receive any emails and answers inside the Inbox.
* In the setup of the ticket module, set the field "Force an email as CC recipient to all messages send from ticket page" to support@mycompany.com, so any email send from a ticket in Dolibarr backoffice will aslo be sent to support@mycompany.com.
*Enable the [[Module EMail Collector]] and the [[Module Ticket]].
* In the setup of the ticket module, create one EmailCollector entry with credentials (IMAP login or OAuth) of the "followsupport" user as the user to connect to IMAP, and "Inbox" as the input directory. You can set the output directoy as "Processed emails" (you must create the directory or label before the first run). As the inbox is dedicated to followsupport@mycompany.com email, no need to set filters.  
*In the setup of the ticket module, set the field "Force an email as CC recipient to all messages send from ticket page" to support@mycompany.com, so any email send from a ticket in Dolibarr backoffice will aslo be sent to support@mycompany.com.
*In the setup of the ticket module, create one EmailCollector entry with credentials (IMAP login or OAuth) of the "followsupport" user as the user to connect to IMAP, and "Inbox" as the input directory. You can set the output directoy as "Processed emails" (you must create the directory or label before the first run). As the inbox is dedicated to followsupport@mycompany.com email, no need to set filters.


Imagine that the received emails are formated by a web form and has this content:
Imagine that the received emails are formated by a web form and has this content:
Line 97: Line 233:
So each time an email is received to support@mycompany.com, or an answer is done, the user follow@mycompany.com receive the email and the collector will use it, trying to guess if it is a input or output email and will record a help desk ticket or complete a ticket..
So each time an email is received to support@mycompany.com, or an answer is done, the user follow@mycompany.com receive the email and the collector will use it, trying to guess if it is a input or output email and will record a help desk ticket or complete a ticket..


== Example of use case: Create an opportunity for a team of sales ==
==Example of use case: Create an opportunity for a team of sales==
You have a sale team with n employees. The email of your team is sales@mycompany.com (an independant email or a mailing-list that dispatched any input email to the n employees).
You have a sale team with n employees. The email of your team is sales@mycompany.com (an independant email or a mailing-list that dispatched any input email to the n employees).


You must:
You must:


* Declare the email sales@mycompany.com as a possible sender email for each employee (but uncheck the checkbox "alias" if using Gmail). So it will be possible for every employee to send/answer emails as the  sender sales@mycompany.com. So if the customer answer email of any employee, the answer will be sent to sales@mycompany.com (so the n employee will also receive it).
*Declare the email sales@mycompany.com as a possible sender email for each employee (but uncheck the checkbox "alias" if using Gmail). So it will be possible for every employee to send/answer emails as the  sender sales@mycompany.com. So if the customer answer email of any employee, the answer will be sent to sales@mycompany.com (so the n employee will also receive it).


* Once this is done, if the email sales@mycompany.com is a Mailing-List, it is recommended to create another email account, for exemple *followsales@mycompany.com* and include it as another member of the mailing list sales@mycompany.com. So followsales@mycompany.com will receive any emails and answers inside its Inbox.
*Once this is done, if the email sales@mycompany.com is a Mailing-List, it is recommended to create another email account, for exemple *followsales@mycompany.com* and include it as another member of the mailing list sales@mycompany.com. So followsales@mycompany.com will receive any emails and answers inside its Inbox.
* Enable the [[Module EMail Collector]] and the [[Module Projects]] with option "Allow opportunity management" to On.
*Enable the [[Module EMail Collector]] and the [[Module Projects]] with option "Allow opportunity management" to On.
* Create one EmailCollector entry with credentials (IMAP login or OAuth) of the sales mailbox. You can set the output directoy as "Processed emails" (you must create the directory or label before the first run). As the Inbox is dedicated to followsales@mycompany.com email, no need to set filters.  
*Create one EmailCollector entry with credentials (IMAP login or OAuth) of the sales mailbox. You can set the output directoy as "Processed emails" (you must create the directory or label before the first run). As the Inbox is dedicated to followsales@mycompany.com email, no need to set filters.


Imagine that the received emails are formated by a web form and has this content:
Imagine that the received emails are formated by a web form and has this content:
Mapiolca
84

edits

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

Navigation menu