Introduction
CiviPlus can automatically retrieve email from a specified email inbox and file it as an email activity against contacts of type Individual or Organisation corresponding to the sender and recipients of the email.
Depending on configuration, new individual contacts can be created for emails from addresses of individuals or organisations that do not exist in your database.
This integration can cover both:
Inbound email received into your email account
Outbound emails not from CiviPlus, i.e. correspondence that you (a CiviPlus User) have sent from your own mailbox (not from CiviMail)
Example activity created from an inbound email:
Example activity created from an outbound email:
Using “Email-to-activity processing” always requires you to have an email account either in use already or set up specifically for CiviPlus to connect to. CiviPlus will not create any new inboxes in your email system by itself.
This should not be confused with creating FROM email addresses, which can send mail but not receive mail, as they are not an inbox.
Once set up, how does it all work?
There are two routes in which emails exchanged outside of CiviPlus can be processed into CiviPlus via email-to-activity processing. These can be used in isolation or in tandem, depending on your organisation’s preference.
Route 1 -
a special email address that can be used as a ‘bcc’ in correspondence
You can create a specific email address (typically clients choose something like “crm@yourdomain.com” or similar), which you and your team are able to ‘bcc’ when sending any emails that you would like to have automatically filed as activities within the CRM.
Ideally this should be a new email address, and not one that already belongs to a team or team member.
Route 2 -
A dedicated outlook folder into which emails can be moved into for processing
You are able to set up a folder in your IMAP inbox (more detailed instructions on this follow later in this guide) for which you will provide access to relevant staff within your organisation.
Anyone with access to this IMAP folder within your email client (outside of CiviPlus) will be able to simply drag and drop emails into this folder if they would like them to be processed into the CRM as an activity on the relevant contact record(s) in the CRM.
In either route, once the integration has been set up CiviPlus will periodically (usually every 5-6 minutes, but we can make this once per hour/ day if you prefer) check the relevant inbox or folder and will then create activities as relevant.
To help make clear which emails have been processed or not, at the set up of the integration CiviPluswill create the following additional folders:
CiviMail
|
Each time the processing job runs, applicable emails will be moved from their original location into one of the above folders where you can view them if needed.
Case management email processing
If you are using CiviCase, the system is also smart enough to be able to file emails not just against a contact record but also against a case record* if the email subject contains one of the following structures:
[case #123123]
[case #asdasd9a0sdajasd]
The second can be achieved easily by sending an email directly to a contact from within a case in CiviPlus.
Optionally, if you would like to ensure that emails are only filed to the CRM in the context of case management, please do let us know as the integration does have the ability to ‘ignore’ emails that do not contain a valid case ID in the subject line.
*Please note, that if you are using more than one ‘Case Management’ dashboard within CiviPlus, currently this feature is only supported for the original dashboard. We are working on improving this to support logging of emails on cases within any dashboard.
Questions to consider before we begin set up
The integration is able to be adjusted based on your preferences in a number of ways, so it is helpful to consider these questions before we begin the set up:
Do you want the system to create new contact records if it can’t find an existing contact with the same email address?
By default, the system will create a new contact, but we can stop it from doing so if you would prefer (many clients prefer this)
Activity status
By default, the system will set the status of processed email activities to ‘completed’. If this doesn’t suit your internal workflows, we can alternatively set the default to be another of the available activity statuses.
Will you want to set up Route 1 (above), Route 2 (above), or both?
Technical requirements for set up
Before getting started, you will need ensure that you have:
An active Microsoft Exchange Account
Access to the Microsoft Azure Portal
Access to the Azure Active Directory (AD)
You will need to (securely) share the login credentials for the email inbox that you plan to use with the CRM, so that we can test that the integration is working correctly.
There are set up steps that you will need to take within the Microsoft interface, and other steps that we will need to take on the CiviPlus side in order for the integration to function fully.
Steps you will need to take
Azure AD
For Compuco to be able to continue with the setup, please visit your Azure AD account connected to your Microsoft Exchange account to register your site.
You can access the Microsoft Azure home page using the following link: https://portal.azure.com/#home.
Choose the Azure Active Directory from the navigation menu on the left.
New registration
In the Azure AD you need to go to the App Registrations tab and start a New registration.
First, give a name to your App registration and select which account types are supported. The name could be anything but it’s best if it reflects in some way the site you are trying to connect for Oauth.
From the supported account types options choose the second one that allows the Multitenant option.
Ignore for now the Redirect URI optional setting at the bottom of the page and click on Register.
On the App’s summary page, you will see that the Application ID has been already generated. This is the Client ID number CiviPlus will require, so please copy this value to share with us along with the Secret Value that you will read about more below in the Certificates section. NB: As with any sensitive information that needs sharing, please do not send this directly to us via email or basecamp. Our team will advise on the appropriate sharing mechanism.
Certificates
The other data we need to generate is the “Client secret” which is a unique identifier Microsoft will use to authenticate the connection. You can start generating it by clicking on ‘Add certificate or secret'
On the ‘Certificates & Secrets’ tab make sure you are on the Client secrets section and click on ‘New client secret’. This will open a pop up window where you can give a description to your secret and set its expiration date. While the recommended setting is 6 months of validity you may choose different periods depending on your organisation’s security practices.
When you are finished click on ‘Add’ to create the secret.
You will see the newly created secret along with its Value, which is the ‘client secret’ identifier we will need you to share with us. Important: the Client Secret Value is only ever visible at this point, so please save this value as Compuco will need it for CiviPlus configuration. (If you forgot to save, you will just need to create a new certificate clicking the Add button)
Redirect URL
The next step is to set up the required permissions in Azure AD and to add the Redirect URL.
Our team will share the correct Redirect URL with you (please ask for it if it has for any reason not been provided yet).
To add the redirect URL to your app in Azure AD go back to the overview page and click on ‘Add a Redirect URI’.
On the following setup page click on ‘Add a platform’ and choose Web.
Copy and paste the Redirect URL value that Compuco provided you to the Redirect URIs field and click on Configure in the bottom.
This will add the CiviPlus site as a new platform to the App. You can ignore other options on the Authentication tab and the Configure Website pop up.
Permissions
The final step in Azure AD is to set up the App with the correct API permissions. You can do this by navigating to the API permissions tab:
The app will need 6 permissions which can be added by clicking on ‘Microsoft Graph’. It is important to highlight that the additional permissions will not be added by clicking on the ‘Add a permission’ button but by clicking on the Microsoft Graph link to add the permissions to that.
On the Request API Permissions pop up window you can add the required permissions by searching for them in the ‘Select Permissions’ search bar.
Once you have found them you can check the box next to them.
Once all permissions have been checked click on ‘Update permissions’ in the bottom. Here is the list of permissions that need to be added:
IMAP.AccessAsUser.All
email
offline_access
openid
POP.AccessAsUser.All
SMTP.Send
The additional permissions will be listed under Microsoft Graph. You may see a 7th one “User.Read” which is a default permission for Apps in Azure AD. You can leave it there, no need to remove this.
The permissions also need to be consented to - if you are a Global Admin of your organisation in Microsoft Azure, you can click on ‘Grant admin consent’ to approve all permissions.
The approval has to happen before the connection can be established.
With these steps all completed, you just need to securely share the Client ID and the Secret Value with our team if you haven’t already.
We will then proceed with the remaining steps on the CiviPlus side.