EWS Integration (Calendar sync & Email send)

Enquire's setup is based on using a service account with Impersonation access, but the Exchange/Outlook integration also supports the use of Delegate access. If you would like to know more about Impersonation vs Delegate access, please reference Microsoft's documentation.

Service Account Setup


Office365 Exchange 2013/2016

 

Creating a user for a service account
  1. Sign in to Office 365 using your credentials.
  2. Navigate to the Office 365 Admin center by clicking the app launcher icon (9 small squares)  in the top left and click Admin.
    admin_button_o365.png
  3. On the left click Users, then click Active users.
    active_users_o365.png
  4. Towards the top of the page, click + Add a user.
  5. Populate the necessary fields and make sure to uncheck the box for Make this user change their password when they first sign in.
Setting up the service account with Application Impersonation

The following steps will add the role of Application Impersonation to the service account user. This will automatically give your Service Account user read and write access to your user's calendar as well as the Send As permissions to send email.

Note: With Application Impersonation, you are not required to manually add permissions for read and write access to a user's calendar or Send As permissions for sending email. Your service account will automatically have these permission for all current and newly added users.

  1. Navigate to https://outlook.office365.com/ecp/
  2. Log in using your Office 365 credentials and you will be taken to the Exchange Admin Center.
  3. Click Permissions, then click admin roles.
  4. Click the plus sign  above the table to create a new Role group.
  5. In the new role group pop up, type in a name in the Name field.
  6. Under the Roles section, click the plus sign .
  7. Select ApplicationImpersonation from the list below DISPLAY NAME, click add ->, then click ok.
    Exchange_Outlook_Application_Impersonation.PNG
  8. Under the Members section, click the plus sign .
  9. Select the user that you created initially as a service account to use with Exchange Sync.
  10. Click add -> and then click ok.

You now have a service account that will impersonate other user's mailboxes that your Enquire Administrator can configure with Enquire Exchange Sync

You will not need to perform the section below if you have already-performed the steps above.

_____________________________________________________________________________

Manually add Read and Write permissions to user calendars and Send As permissions for sending email from Enquire

If you do not want to use the Application Impersonation role, you will need to manually add the read and write and Send As permissions using the methods below.

Note: These permissions will need to be added to current users in your Exchange server as well as any new users added moving forward.

 
Grant Send As permissions via Office365 online portal

This will allow users to send emails from Enquire and display the from email as their own.

  1. Go to Office 365 admin center > Users > Active Users
  2. Choose the user you want, then click Edit next to Mailbox permissions
  3. Click Edit next to Send as.
  4. Click the Add permissions button.
  5. In the search box, type the name of the service account user you created.
  6. Click Save once you've selected the service account user.
Grant Send As permissions via Exchange Online Powershell
  1. Connect to Exchange Online PowerShell.
  2. Connect to your Exchange Online Server.
  3. Run the following cmdlet for each user to add SendAs permissions:
    Add-RecipientPermission -Identity user@company.com -Trustee impersonationuser@company.com -AccessRights SendAs
Grant read/write access to user calendars
  1. Connect to Exchange Online PowerShell.
  2. Connect to your Exchange Online Server.
  3. Run the following cmdlet for each user to add read/write calendar access (update emails for your users):
    Add-MailboxFolderPermission -Identity user@company.com:\Calendar -user impersonationuser@company.com -AccessRights Editor
Grant read/write access to user tasks
  1.  Exchange Online PowerShell.
  2. Connect to your Exchange Online Server.
  3. Run the following cmdlet for each user to add read/write tasks access (update emails for your users):
    Add-MailboxFolderPermission -Identity user@company.com:\Tasks -user impersonationuser@company.com -AccessRights Editor

Enquire OAuth Setup

Follow the instructions below once you have opted in to OAuth for Office.

  1. Login to your Azure Portal (https://portal.azure.com).
  2. Use the search field at the top of your browser screen to search for “App Registrations”: mceclip0.png
    • NOTE: You will select the option under services for App Registrations and continue with the instructions below.
  3. Click “New registration”: mceclip1.png
  4. Give the app any name you would like, and under “Redirect URI” choose “Web” in the dropdown and add the redirect URL: https://account.enquiresolutions.com/integrate/authorizeews, and then click “Register”: mceclip2.png
  5. In the left-hand menu, choose “Certificates & Secrets” and then click “New Client Secret”. Give it a description and time length and then a new client secret will be created.
    • IMPORTANT: Save the client secret and store it somewhere as you will no longer be able to access it after leaving the page. mceclip3.pngmceclip4.png
  6. Next, choose “API permissions” in the left-hand menu. Delete the User.Read scope (under Microsoft Graph) from the API permissions.
    • IMPORTANT: Make sure to delete the User.Read scope before continuing as this may interfere with the EWS synchronization. mceclip5.pngmceclip6.png
  7. Next, click “Add a permission and select the tab “APIs my organization uses”. In the search type in “Office 365 Exchange Online” and select it in the results. In the next screen select “Delegated permissions”: mceclip7.pngmceclip8.png
  8. Expand the group “EWS” and check “EWS.AccessAsUser.All” and click “Add permissions”: mceclip9.png
  9. Click “Add Permission” and you should see the “EWS.AccessAsUser.All” scope listed under “Office 365 Exchange Online”. Choose the option “Grant admin consent for {your organization}: mceclip10.pngIMPORTANT: Ensure the only scope on the API permissions screen is EWS.AccessAsUser.All. There should not be the Users.Read or any other scope from Graph API.
  10. Lastly, choose “Overview” in the left-hand menu to view your Application (Client ID) and Directory ID (Tenant) and record them. These 2 values along with the client secret in step 4 will be the values you will need to provide to Enquire. mceclip11.png
    1. Once you have ensured all these steps are setup correctly, please send an encrypted email to the Integrations Team at enquire.integrations@alineops.com with the below credentials.  (Please include in the subject line the client company name - "EWS Calendar Sync")
  • Service Account Credentials (If not adding yourself) 
    1. Outlook Exchange version
    2. Outlook URL if not O365
    3. Service account Name
    4. Service Account Password
  • OAuth Credentials: 
    1. Client ID
    2. Tenant ID
    3. Client Secret Value

IMPORTANT: The Client Secret Value is NOT the Client Secret ID.

 

 

If you experience any issues, please go here to submit a ticket for assistance.

Enquire Admin Setup


Self Setup

You may use the following steps to setup your company's Exchange server with Enquire.

  1. Navigate to https://account.enquiresolutions.com/integrate/exchange
  2. Log In using the credentials for the impersonation account that was created. 
  3. Click Admin
    Admin_Button.png
  4. Click Exchange
    ExchangeButton.png
  5. Click the Add Exchange Server button
    AddExchangeServerButton.png
  6. Fill out the form with the necessary information:
    • Exchange Version - choose the version of Exchange your company is using. If you are currently setup with Office365, choose Exchange2013.
    • Name - enter a name for the server (i.e. Company Exchange Server).
    • Url - enter your server's EWS Url (if you aren't sure where to find this, you can use Microsoft's Connectivity Tool).

      Note: All Office365 instances have the same EWS Url of https://outlook.office365.com/EWS/Exchange.asmx

    • Username - the User Principal Name (UPN) of your service account.
    • Password - your service account's password (If setting up OAuth, password is not required in this step).
    • Send Email - check this box if you would like your users to send email from Enquire CRM.
    • Delegate - check this if you are using delegate over impersonation.
    • Sync All Day Tasks - leave this checked if you would like your users to sync activities that are marked as All Day in Enquire CRM.
    • Sync Only the Following Activity Types - pick and choose which activities you would like to sync to your user's Outlook. By default, all activities will be synced, but we recommend picking a handful (no more than 5) of activities to keep user calendars from getting overwhelming.
    • Import Calendar Events as - pick the activity type you would like Outlook events to display as when they are synced to Enquire.
  7. Click Save
  8. Validate all users that will be utilizing the Exchange sync have been added to the Exchange Accounts section. All users will be added with a status of Pending in the Calendar Status and Email Status columns.
  9. To the far right of the exchange server you just created, click the red sync icon. This will initiate the sync process, but please allow up to one hour for the sync to complete depending on the number of users and activities.
    SyncExchangeServer.png

  10. Once the sync has finished, the status window will display sync results for each account (these results are only based on the sync from Enquire to Outlook):
    ServerSyncResults.png

    The Calendar status for each user will be updated based on the results of their sync:

    CalendarStatusColumn.png

  11. The Email Status column will display Pending until the user attempts to send an email to an individual or you may test the send email functionality by clicking the blue send test email envelope button to the right of the user's account.
    EmailTestButton.png
    This will send an email to the user with the From and To as themselves and a body with the text: "This is a test email sent from the Enquire CRM to validate your email settings. It was initiated by an administrator or support user. No action or response is required." and update the status in the Email Status column based on the results:
    EmailStatusColumn.png

Enquire Assisted Setup

If you would like Enquire to assist with the setup of your Exchange/Outlook, please follow these steps and send the information to Enquire.

  1. Locate your EWS URL (this URL will end with .asmx):
    • You can use the Microsoft test connectivity tool to auto discover your URL if you do not know it.
    • You can also open Exchange Management Shell on your server and type the following command:
      Get-WebServicesVirtualDirectory |Select name, *url* | fl

    Note: We do not need this EWS URL if you are currently using Office 365.

  2. Once you have finished setting up the impersonation account and you have located your EWS URL, please submit a ticket with our support team with the following information:
    • Your EWS URL.
    • Your current version of Exchange (please specify if you are using Office 365 instead).
    • The user name and password for the Enquire CRM user created on your Exchange server.

User Setup


User self setup

Once the company server is setup, users can setup their own accounts to sync their Exchange accounts with Enquire CRM. You will only need to follow these steps if the user account is added after the Exchange server is setup.

  1. Click Settings at the top left of the left hand menu, and click Email
    email_settings.png
  2. Click Add Account
  3. Choose your company's server from the Server field. Put your email address in the User name field. Leave the Password field blank, your impersonation account will validate your information. Leave the PrimarySync Calendar, and Send Email boxes checked. Click Save.
    UserAddAccountExchangeModal.png

Admin assisted user setup

Admins may setup users to sync with Exchange and edit existing users if updates need to be made.

  1. On the Admin > Exchange page, click the Add Account button.
    AddExchangeAccountButton.png
  2. Choose the Exchange server and user from the specified drop downs. After choosing a user, their email will automatically populate to the Email Address field.
  3. Leave the Is Primary box checked and uncheck the Sync Calendar or Send Email box if you don't want users to use a certain process.
  4. Click Save

To edit a user, click the blue pencil button to the right of the user's Exchange information, make the necessary changes and click Save.

Usage


Enquire to Outlook Calendar Sync

Note: The calendar sync with Enquire will sync events to and from your default Outlook calendar. You can verify or change your default calendar by following Microsoft's Change the default calendar support article.

The calendar sync portion of our Exchange/Outlook integration works in the background and is continually syncing when activities are created. Enquire will sync Timed and All Day activities:

Timed activities - activities with a start and end time will sync to the calendar in Outlook.

When a timed activity is successfully synced to your Outlook calendar, it will display at the date and time specified in Enquire and the subject set to the name of the activity in Enquire. The event notes/detail will contain a link to the activity and individual in Enquire.

EnquireSyncedEvent.png

All day activities - activities marked as All Day will sync to the tasks section in Outlook.

When an all day activity is successfully synced to your Outlook tasks folder, it will display with the date specified in Enquire and the title set to the activity description in Enquire. The task notes/detail will contain a link to the activity and individual in Enquire.

EnquireSyncedTask.png

Outlook to Enquire Calendar Sync

When events from your Outlook calendar are successfully synced to your Enquire calendar, they will display on your calendar at the time specified in Outlook and as the activity type setup by your Admin. Hovering over the activity will display additional information about the activity.

OutlookSyncedEvent.png

Note: All activities synced from your Outlook calendar will display a blank "For" field.

Cancelling Activities/Events

  • Cancel an activity in Enquire: If an activity that was synced to Outlook is cancelled in Enquire, it will be removed from your Enquire and Outlook calendar.
  • Cancel an event in Outlook: If an event that was synced to Enquire is cancelled in Outlook, it will be removed from your Outlook and Enquire calendar.

Rescheduling Activities/Events

  • Reschedule an activity in Enquire: If an activity that was synced to Outlook is rescheduled in Enquire, the original activity will be removed from your Enquire and Outlook calendar and a new activity will be created at the rescheduled date and time.
  • Reschedule an event in Outlook: If an event that was synced to Enquire is rescheduled in Outlook, the original event will be removed from your Enquire and Outlook calendar and a new event will be created at the rescheduled date and time.

Deleting Activities/Events

  • Delete an activity in Enquire: If an activity that was synced to Outlook is deleted in Enquire, it will be removed from your Enquire and Outlook calendar.
  • Delete an event in Outlook: If an event that was synced to Enquire is deleted in Outlook, it will be removed from your Outlook and Enquire calendar.

Send Email

The Send Email functionality allows you to send emails from Enquire using the Send Email tab on the activity box.

  1. Navigate to the individual you would like to send an email to.
  2. Click the Send Email tab along the top of the activity box.
    SendEmailTab.png
    If your account does not have the Send Email functionality setup, you will receive the following warning:
    SendEmailSetupWarning.png
    If the individual you are attempting to send an email to doesn't have an email address entered, you will receive the following warning:
    ProfileWithoutEmailAlert.png
    Enter the individual's name in the For field and choose the suggested individual, choose a template if you have one setup, enter a subject, and body for the email and click Send.

If your email was sent successfully, you will see the following success message:

SendEmailSuccess.png

and a Completed activity with a Description of the email's Subject and a corresponding note with the Email's body will be created:

SendEmailActivity.pngSendEmailNote.pngIf your email was not sent successfully, you will see the following failed message with the red bold text highlighting the error:
SendEmailFailedWarning.pngand a Cancelled activity with "Failed to Send:" appended to the Description will be created:
SendEmailFailedActivity.png

If you don't have the Send Email functionality setup, only a Completed activity with a Description of the email's Subject and a corresponding note with the Email's body will be created.

Note: Enquire does not handle the replies to emails sent from Enquire CRM. Replies to these emails will only be sent to the user's Outlook.

Troubleshooting


Calendar Troubleshooting

If you are getting a large number of notifications in Outlook when logging activities in Enquire CRM, try these steps to avoid this from happening.

When logging activities in Enquire CRM, you have to two options:

  1. Create an activity WITH a specified start and end time
  2. Create an All Day activity WITHOUT a specified start and end time

These two options are very different in regards to how your Outlook or Exchange calendar will handle them once they have synced.

Activities WITH a specified start and end time

If you create an activity with a specified start and end time, your Outlook or Exchange calendar will create a calendar event and notify you per your Outlook or Exchange calendar notification settings (e.g. Remind me 15 minutes before events begin). This will happen regardless of when the activity was created.

Example 1
You just completed a Call Out with John Doe. You navigate to John Doe's profile and create a Call Out activity with a Start and End time of the current time and a Status of Completed.
This will create an event on your Outlook or Exchange calendar once it has finished syncing and notify you immediately because it thinks the event hasn't happened yet.
Example 2
A new lead is entered into your system. You navigate to the new lead profile and create a Call Out activity due 4 hours later.
This will create an event in your Outlook or Exchange calendar once it has finished syncing. It will notify you prior to the event based on your Outlook or Exchange calendar notification settings (e.g. Remind me 15 minutes before events begin).

Activities WITHOUT a specified start and end time (All Day activities)

đź’ˇ Not sure how to create an all day activity? Read our Creating Activities help center article.

If you create an activity without a specified start and end time by checking the activity as an All Day activity, your Outlook or Exchange calendar will not create a calendar event. Outlook or Exchange will instead create a To-Do list item in your Outlook or Exchange.

Some things to be aware of when creating all day activities:

  • If you create an activity with the All Day check box checked AND a Status of Complete, the activity will not show up on your To-Do list in Outlook or Exchange.
  • If you create an activity with the All Day check box checked, but a Status other than Completed, the activity will remain on your To-Do list until it is either Completed or Deleted.
  • Because creating an All Day activity doesn't display a specific start and end time when an activity took place, we suggest noting the time within the description for the activity:

Sync Troubleshooting

If you are having troubles with Syncing your Outlook or Exchange here are some things to try.

    • Check with your Network Administrator to confirm everything has been setup with your company's Exchange Web Services (EWS)
    • Your Network Administrator must authorize your Exchange account to use Exchange Web Services (EWS) with Enquire CRM.
    • Make sure you are using the correct Exchange Network credentials when setting up your Exchange Sync in Enquire CRM.

Note: These are not your Enquire CRM credentials. Please check with your Network Administrator if you are unsure what your credentials are.

  • A green Syncing icon  indicates Enquire CRM is attempting or is currently syncing your Exchange information. This can take some time so please allow at least 30 minutes for your sync to finish.

Sync Statuses

The following is a list of potential statuses an account can have. If Enquire CRM needs to re-sync your Exchange server, it will try four times using your credentials and display a status for each user based on the outcome.

Status Description
Access Denied Calendar/Task Folder Specified folder could not be found in the store. The incorrect permission is chosen, impersonation or delegate.
Denied Access (Forbidden) 403 error (forbidden) or unauthorized client. The service account doesn't have access the user.
Error - Not Syncing General Error Message. Could be caused by a time out or troubles when syncing.
EWS Server giving Internal Server Error An internal server error occurred. Try again later. Potential down time that will often resolve itself after a period of time.
Exchange Version Not Supported Exchange Server doesn't support the requested version.
Impersonation Failed The account does not have permission to impersonate the requested user.
Invalid Calendar or Task folder This property was requested, but it wasn't returned by the server.
Invalid Server URL The remote name could not be resolved. Occurs when the EWS url has been entered incorrectly.
Mailbox Not Setup on EWS The SMTP address has no mailbox associated. Verify that the user's email address is spelled correctly and has the correct domain.
Not Enabled The process (sync calendar or send email) is not currently enabled for the user.
Syncing The process (sync calendar or send email) is correctly enabled and functioning.
Unattempted No Items - no items to sync. The account has been added, but doesn't currently have any activites/calendar events to sync.
Unauthorized (401) Unauthorized. The username or password for the service account is incorrect.

Support Requests

Please include the following in your Support request to receive the best quality service:

Exchange Version:
Name of Server:
URL to Server:
Username:
Password:
Sync the Following Activity Types: <List>
Import Calendar Events as: 

Thank you!  We look forward to working with you on your Exchange integration!

FAQ


Will events synced from my Outlook pull into reports?
No. Outlook events will not display as activities on Standard, Custom, or Enquire Analytics reports.
Can I see activities in the past or future?

The calendar in Enquire will display appointments that have occurred within the last 2 days and scheduled appointments in the next 90 days (3 months).

How do recurring events work?
Because the calendar in Enquire displays 90 days in the future, you will be able to see each occurrence of a recurring Outlook event up till the 90th day.
Created activities aren't showing on my calendar, why?
This can happen for a few reasons, so make sure the following are correct:
  • When scheduling an activity, make sure that the All Day checkbox isn't checked. Remember: all day activities show in the Tasks section of Outlook.
  • Make sure the start time of the activity is prior to the end time.
  • Updates from Enquire to Outlook are not real time, it can take up to 45 minutes for an activity to appear on your Outlook calendar if created in Enquire.
  • If an activity is cancelled or rescheduled, we recommend deleting the activity/invite from your Outlook calendar and create a new activity in Enquire.
How can I verify permissions?

Office365, Exchange 2013, Exchange 2016

First connect to the Exchange Online PowerShell

This cmdlet will return a list of users your impersonation account currently has Send As permissions for.

Get-RecipientPermission -Trustee "impersonationuser@company.com"

This cmdlet will return the calendar permissions the Impersonation User has for the specified user.

Get-MailboxFolderPermission -Identity user@company.com:\Calendar -User impersonationuser@company.com

 

 

Was this article helpful?
0 out of 0 found this helpful