Contents

1 Microsoft Dynamics 365 tenant level configuration

The guide applies to Voice for Dynamics 365 version 1.0 onwards.

Voice for D365 is suitable for three different scenarios from the viewpoint of how Dynamics is configured, depending on what capabilities of Dynamics 365 the customer wants to use.

These are:

• Used in a classic model driven app (CIF1)

• Used in a multisession app (CIF2)

• Used in a multisession app with Omnichannel (CIF2)

The way how Dynamics must be configured and what components need to be installed or provisioned are different.

The following table visualizes the steps that need to be carried out.

1.1 Installation Prerequisites

• A functioning Microsoft Dynamics 365 tenant with the needed Dynamics 365 target instances (environments) for installation.

• Microsoft Dynamics 365 Unified Interface (Online version).

• Required suitable Microsoft Dynamics 365 licenses for single-session Customer service Apps (CIF 1.0) or multi-session e.g. Omnichannel for Customer Service and Customer Service Workspace App use (CIF 2.0).

https://dynamics.microsoft.com/en-us/pricing/customer-service/#plans

• Install Channel Integration Framework in your target environment, or

• Provision Omnichannel

Note: Please send your Microsoft Dynamics 365 environment URL-information to your Enreach contact before installation.

1.1.1 Setting up Channel Integration Framework

• This setup is used for customers who are using

  • a single-session Dynamics 365 model-driven apps, such as:

Dynamics 365 Customer Service

Dynamics 365 Sales

Dynamics 365 Project Service

Dynamics 365 Field Service, or

have Dynamics 365 Enterprise license and want to use Customer Service Workspace multi-session app without Omnichannel capabilities

Install Channel Integration Framework in your target environment. The following documentation from Microsoft describes the steps which need to be carried out, in addition a few screenshots help to guide the installation.

https://docs.microsoft.com/en-us/dynamics365/customer-service/channel-integration-framework/get-channel-integration-framework

Figure 1 AppSource Dynamics 365 Channel Integration Framework

Figure 2 Agree to Terms

Figure 3 Install Channel Integration API

1.1.2 Provision Omnichannel

This section applies to customers that use Omnichannel capabilities in Dynamics 365, have Digital Messaging or Chat licenses and want to use Voice for D365 in a multi-session app, like:

• Omnichannel for Customer Service

• Customer Service Workspace

To provision Omnichannel please follow the material provided by Microsoft:

https://docs.microsoft.com/en-us/dynamics365/omnichannel/administrator/omnichannel-provision-license

1.2 Configure Azure app registration

For Voice for Dynamics 365 to work, an Azure App registration is needed for authentication purposes. Giving access to your D365 though an Azure App registration does not consume D365 licenses.

Configuring Azure App registrations is done by the following steps:

Sign in to Azure portal (https://portal.azure.com) From the navigation menu, choose Azure Active Directory and Application registration Choose New Registration from top of the page

Figure 4 Create App Registration

Fill in a name, for example Voice for Dynamics 365 for the app registration. All the other settings can be left as default. Choose Register.

Figure 5 Register an Application

Once deployment is done, you should see a similar window than below:

Figure 6 Registration done

App registration needs API permissions to be able to authenticate to your Dynamics 365 environment. Choose API permissions from the navigation panel

Figure 7 Select API Permissions

• Choose Add a permission

• Select Dynamics CRM from the pop-up window

Figure 8 API permissions

Tick user_impersonation selection and choose Add permissions

Figure 9 Add permissions

For authentication purposes, a client secret is needed.

Since Microsoft limits the expiration of secret keys created on the user interface to 2 years, the client secret must be added using a script.

• Navigate to main properties of App Registration by clicking Overview on the left

• Copy the value of Object ID attribute to clipboard

Figure 10 Copy Object ID

Replace OBJECT_ID in the following script with the copied value

Connect-AzureAD

$startDate = Get-Date

$endDate = $startDate.AddYears(100)

$aadAppsecret01 = New-AzureADApplicationPasswordCredential `

-ObjectId OBJECT_ID `

-CustomKeyIdentifier 'Voice' `

-StartDate $startDate `

-EndDate $endDate

Write-Output $aadAppsecret01

Open Cloud Shell by clicking the icon on top menu bar

Figure 11 Open Cloud Shell

• Paste the script and hit Enter. A client secret is created with 100 years expiration.

• Save the secret key value into a secure place as it is not visible afterwards.

Figure 12 Run Script

Once secret key is created, send the following details to Enreach:

• secret key value

• application id

• directory id (from overview page)

Enreach will then deploy back-end components for integrations to work.

After the Azure App registration is completed, next step is to Install Voice for Dynamics 365 package and set up an application user in Dynamics 365.

1.3 Install Voice for Dynamics 365 package to Dynamics 365 Instance

Install Voice for D365 managed package provided by Enreach and login to appropriate Microsoft Dynamics 365 organization with System Administrator credentials.

VoiceForD365Package contains the following:

• The package contains solutions with base entities, configuration data and settings, links for the Azure apps/functions.

• Voice channel provider

• Multisession configuration data (session, notification templates) are to be installed within the solution package automatically. Note: for the Channel Integration Framework v2.0 only

1.3.1 The installation process for the customer’s administrator

Incoming zip package should be unpacked

Figure 12 Deployment Package properties

• Right-click on DeploymentPackage.dll and verify that the file is not blocked. If it is, unblock and then apply. Otherwise, might an error message might occur during the deployment (no solution found).

• Then run PackageDeployer.exe and go through the standard wizard.

• Wizard will guide the user through all the needed steps for installation.

Figure 13 Package Deployer Wizard

Figure 14 Insert your company information

Figure 15 Company information example

Figure16 Connect to Microsoft Dynamics CRM

Figure 17 Voice for D365 Package

Figure 18 Ready to Install

Figure 19 Installer Configuration

Figure 20 Executing Install Actions

Figure 21 Installation Complete

PLEASE NOTE: All future updates after the first installation are also done with the Package Deployer / Wizard!

1.4 Configure application user in D365

Please complete Azure App registration before proceeding to configuring the application user in Dynamics 365.

• Navigate to Power Platform admin center and sign in as System Adminstrator

• Click Environment on the top-left and select the environment from the list.

• Click Settings on the top ribbon.

• 

  Click Users + permissions, and then select Application users.

• Click New app user on top ribbon.

  

• Click Add an app and select the application created in chapter 1.2 Configure Azure app registration.

• Select a Business Unit from the drop-down list. It is recommended to select the root business unit.

• Click

  

  next to Security roles.

• Select Voice ApiUser role.

• Click Save to select the role.

• Click Create to create the application user.

1.5 Voice for D365 Configuration

Configuration settings are divided on the following parts

1.5.1 Channel Provider Configuration

1.5.1.1 Configuration for Channel Integration Framework 1.0

Open Dynamics and open Channel Integration Framework App:

Figure 26 Channel Integration Framework App

This configuration is used for customers not using the multisession capabilities and do not use Omnichannel licensing in their Dynamics 365 environment.

Figure 27 Active Channel Providers

Figure 28 Voice Channel Provider Configuration

Channel integration configuration record with settings is to be created with deployment package during the installation but needs to fill in access-based settings:

Select which Apps and User Roles will have access to the channel provider.

See more about Channel Integration Framework configuration:

https://docs.microsoft.com/en-us/dynamics365/customer-service/channel-integration-framework/configure-channel-provider-channel-integration-framework

1.5.1.2 Configuration for Channel Integration Framework 2.0

Channel configuration for CIF2 is maintained by the Deployment Package. However, the channel itself must be added to an Application Profile.

To do it,

• Sign in to the Power Apps portal.

• In top-righ corner, select the environment you are adding the channel to.

• Select Apps on the left menu.

• Select the ellipses next to Omnichannel for Customer Service or Customer Service workspace.

• On the menu that appears, select App profile manager.

• Select App profiles on the left menu, and then select your app profile (or create a new one if you don’t have any custom app profile yet).

• On the app profile select the Channels tab.

• 

  Click Add channel providers.

• In the search box, type “voice”.

• From search results, select Voice for Dynamics 365 by Enreach.

1.5.2 Users

1.5.2.1 Update enreach Cloud User ID

Open Voice Configurator App

Figure 29 Voice Configurator App

Changing any of the followings automatically triggers Enreach user ID update:

• Setting Enreach Cloud User Email

• Assigning Voice User role

User IDs can be updated manually as well:

Navigate to Users Settings and choose Update Enreach User Ids –button (at the top of the page)

Figure 30 Update Enreach User Ids

Wait couple of seconds and Enreach User Ids should appear on the user list for the users that have same email address than in Enreach Cloud.

Figure 31 Enreach Cloud User Id

After updating the ids, if some user is missing the Enreach User id, then you need to manually update the correct Enreach Cloud Email to Enreach User Email field on the user record:

Figure 6 User record Voice for Dynamics 365 settings

• Enreach User Id – unique identifier of the user in Enreach Cloud

• Enreach User Email (optional) - should be filled in if email user in D365 differ from Enreach Cloud

1.5.2.2 Assign users to Application Profile (CIF2)

After creating the Application Profile and Channel Provider in PowerApps Portal according to Microsoft’s instructions (see chapter 1.5.1.2 Configuration for Channel Integration Framework 2.0), users who will be authorized to use the phone widget need to be assigned to the newly created Application Profile.

To do this, click Assign Users on the top menu on Application Profile editor.

A view will open in Dynamics Unified Interface. Click Add Existing User and select the user(s) to be added

.

1.5.3 Phonecall sync settings (Enterprise Calls)

Phone Call Synchronization settings are in General Settings -> Phone Call sync settings view:

Figure 33 Phonecall Sync Settings

Figure 34 DefaultCRMAssignee

• CallDurationLimit - Minimum duration of calls (in seconds). If the duration of a call is below this limit then the call is not synchronised to Dynamics.

• CallStartMargin - value in seconds, used to set a range of searching existing phone calls, to avoid creating duplicates.

• DefaultCrmAssignee - Enreach user id, which is set as the owner of a phone call, in case user Enreach user was not found in D365. Current value e.g. fbc423f5-74f9-e911-80e0-…

The value can be any Enreach user id chosen by the customer organization.

• EnableAudit - boolean value, which defines to set in Enreach Api Audit field of a phone call in D365. In case it is false, the field will be set as CallId is {Enreach call id}, in other cases, all the values retrieved from the Enreach regarding this phone call will be set.

• EnableMultipleMatchCreate - boolean value, which defines if service calls should be created when multiple contacts/accounts/leads found.

• ExecutionInterval - value in minutes, which is taken from execution start and set into start date for phone calls retrieval from Enreach API.

• IncomingDirectCallSubject - string value, defines the subject of a direct phone call.

• IncomingQueueCallSubject - string value, defines the subject for service phone calls.

• MultipleMatchPhoneCallStatus - int value, which should exist as status reason value of phone call in D365. Set when multiple contacts/leads/accounts found and EnableMultipleMatchCreate is true.

• NumbersToCut - int value, defines the number of characters to be cut off from the start of the phone number, before searching in D365.

• OutgoingDirectCallSubject - string value, subject for outgoing phone calls.

• ProcessDirectCalls - boolean value, defines whether direct answered calls should be retrieved and processed.

• ProcessServiceCalls - boolean value, defines weather service answered calls should be retrieved and processed.

• ProcessServiceCallsUnanswered - boolean value, defines weather service unanswered calls should be retrieved and processed.

• RunInDebugMode- boolean value. When set true, the start date of phone calls retrieved from Enreach API is execution date - 45 days and the end date is now.

• MultipleMatchesPickFirst – Boolean value, default: False. When set to true, the first account or contact is picked by Enterprise Call Sync and Callback Sync, if multiple accounts/contacts found. This way calls created by back-end synchronization will more likely point to an actual customer.

Phone call synchronization Azure WebJob runs continuously. After executing the business logic, it sleeps for 60 seconds. It means that in practice synchronization runs nearly every minute.

Important to note that to make call synchronization work, DefaultCrmAssignee setting must be set properly (see in the list above).

When synchronizing phone calls, the following fields are set based on the identity of the user who made or answered the call within the organization:

• Owner

• Activity party (Call From/Call To, based on call direction)

If the user who made the phone call is not a Dynamics user, a fallback (default) user is set to the fields above. The value of DefaultCrmAssignee setting determines this fallback user.

The value of this setting must be the Enreach Id (NOT Dynamics CRM Id) of the fallback user. It can be any user with an Enreach Id - either a real or a technical user. To avoid any confusion to the users (because of a different user appearing on a call than who actually made that call) it is recommended to set the Id of API user (or any other technical user):

• Open Voice for D365 Configurator app

• Navigate to User Settings

• From the list, find your API user (see 1.2 Configure Azure app registration)

• Open the user record and set the Enreach email of API user to Enreach Cloud User Email (e.g. mycompany.apiuser@mycompany.com). Enreach support can help you to have this value.

• After saving the record, Enreach Cloud User Id of the user gets populated

• Copy the id

• Navigate to General Settings -> Phone call Sync Settings -> DefaultCrmAssigneet

• Paste the id to Value field and save the record

At night, between 10:00PM and 11:30PM UTC a so-called retroactive call synchronization is carried out. The exact time of execution is picked randomly to avoid overloading the back-end infrastructure by executing simultaneously for multiple environments.

Retroactive sync retrieves all calls from Enreach API wich were made in the past 24 hours. Then tries to create the calls in CRM. As a result, if a user adds a contact or account with identical phone number to CRM after the call was made but before retroactive sync kicks in, such calls will be synced at night.

Note: Users mobile number needs to be saved to User form in Dynamics 365 for all users that are going to need their phonecalls to be synced from mobile to Dynamics 365. By default calls that are classified as Work calls (Call information Privacy setting in Voice Center side) are synchronized. Unclassified and Private calls are not Synced to D365.

1.5.4 Callbacks

Callbacks can be configured only after you get a confirmation from Enreach.

Callbacks are synchronized from Enreach API into Dynamics 365 by an Azure WebJob, hosted in Enreach’s Microsoft Azure tenant, maintained by Enreach. Application retrieves callback requests from Enreach API, transforms data into corresponding D365 format, maps to D365 contact/account/lead, and creates corresponding phone call records in D365.

Callback synchronization Azure WebJob runs continuously, similarly to call synchrnonization. After executing the business logic, it sleeps for 60 seconds. It means that in practice synchronization runs nearly every minute.

Callback functionality can be configured for organizations that receive callback requests e.g. for Sales or Customer Service purposes to reconnect with the customer at a more suitable time.

1.5.4.1 Basic configuration

By going to General Settings area within Voice for D365 Configurator app and selecting Callback Sync Settings view, the default subject of callback request phone call activities can be adjusted by amending the value of CallbackRequestDefaultSubject setting.

Besides the global setting, a subject can be specified on callback profile-level as well (see below), which overrides the global setting.

To configure callbacks in Dynamics 365, at least one callback profile needs to be added with the following (example) settings:

Figure 35 Callback Profile Example Settings

• Callback List: lookup to a virtual entity, which is retrieved from Enreach API.

• Queue: lookup to OOB D365 entity Queue. Defines to which queue callbacks should be assigned to.

• Ownership Rule: controls how callback requests are assigned to users:

  • API User: callback requests will be owned by the API user (application user)

  • Owner of Queue: owner of callback requests will be identical to owner of target queue

• Phone Call Subject: the subject set to phone calls created by the integration. It can optionally be specified here, on callback profile level. If no value is given here then the global setting is used (see above).

• Duplicate Handling Rule: specifies how multiple callback requests from the same number are handled

  • Bundle calls: All callback requests are synced to Dynamics. If at the same time more than one open callback requests exist, the calls are linked to each other and can be seen on Phone Call form.

  • Ignore additional calls: Additional callback requests from the same number within the same call queue are ignored, only one callback request is created in Dynamics

• Synchronization method: See chapter 1.5.4.1 Synchronization methods.

• Age Time Unit: A unit of the time-period, can be Days, Hours or Minutes. Controls the size of time window when querying callbacks from Enreach API. Visible in case of certain synchronization methods only. See chapter 1.5.4.1 Synchronization methods.

• Callback Age: Number value of defined periods in the previous field. Visible in case of certain synchronization methods only. See chapter 1.5.4.1 Synchronization methods.

All active callback profiles will be proceeded during execution of the callback synchronization job.

Global callback settings configurable within Voice for D365 Configurator app’s General Settings -> Callback Sync Settings:

• CallbackRequestDefaultSubject: Default subject of callback requests. Can be amended freely

• CallbackRequestRecipientRule: Defines if the recipient (“to” field) of callback requests should be the referenced queue or the owner of that queue. Valid values:

  • QueueOwner: “to” field points to the owner of queue

  • Any other value: “to” field points to the queue referenced by the callback profile

1.5.4.1 Synchronization methods

Callback integration supports two ways to bring callbacks to Dynamics: polling (Dynamics reaches out to Enreach API on a regular basis to fetch callbacks) and webhook (Enreach API pushes callbacks right after creation).

Synchronization Method field of callback profile controls how the callbacks are getting synchronized.

• Polling: Dynamics fetches callbacks from Enreach API every minute. The age of callbacks retrieved is specified by Age Time Unit and Callback Age fields.

• Webhook: Enreach API pushes callbacks to the webhook listener web service of Voice for Dynamics 365. Provides more efficient operation in case of large number of callbacks.

• Webhook backed with polling: Same as webhook, but polling on a regular basis is also active as a backup. If callbacks are for any reason left behind by webhook sync, the service executed on a regular basis will still synchronize those.

Setting up polling sync

This section applies to synchronization methods Polling and Webhook backed with polling.

The value of Age Time Unit and Callback Age have an influence on performance; the wider the time window, the more data the component will have to handle on each execution. Callback synchronization is triggered every minute, therefore, in a production environment (where it is likely to have more calls) doesn’t make sense to set the value to more than one hour. In QA and DEV environments it may be longer, several hours or even days.

Callback Synchronizer service caches the settings, refreshing the cached data every 60 minutes. It means that any change to callback configuration (activating-deactivating callback profiles, creating new ones, amending any detail) will take place at the next refresh (within max. 60 minutes).

No other actions are needed to set up polling sync. After the callback profile has been created and the service picked up the new settings, synchronization starts automatically.

Setting up webhook sync

Webhook synchronization is not enabled on the back-end services by default. To make webhook sync work, additional actions must be taken by Enreach staff to configure integration through webhook listener.

If you would like to utilize this synchronization method, please contact Enreach support.

1.5.5 Dynamics 365 apply Phone call form

Voice for D365 – Phone Call form should be chosen as the main form for the Phone Call entity. Please consider if your organization has done customizations to the phone call forms.

• Navigate to customize the Unified Interface App (one or many) that your organization uses in your Dynamics 365 environment.

• Open in App Designer (click the three dots on the right-side corner of the App)

Figure 36 Open in App Designer

• Add Phone Call table to the list of pages, if it is not already included

• Change the Main form to Voice for D365 – Phone Call

• Include Quick View and Quick Create Forms to the app solution.

Figure 37 Change the forms to Voice - Phone Call

Save and Publish

1.5.6 Dynamics 365 Click-to-Dial configuration

Click-to-Dial gives the possibility to make a phone call directly by clicking a button in Dynamics 365 Phone number /mobile number field.

Customize the forms where you want to enable the Click2Dial functionality for the phone number fields:

• Go to form customizations, then target form

• Select the field properties for the field.

• Choose Controls tab and add a new control, choose Channel Communication Control.

• Select the radio buttons to Channel Communication Control

Figure 38 Channel Communication Control

Do the same steps for all the phone fields you want to enable.

1.6. Smart Routing in Voice for Dynamics 365

There are multiple ways to enable smart routing for Voice for Dynamics 365. Smart Routing setup is always dependant on the specific customer needs and use case scenarios. The best way to plan the smart routing setup is to consult both Enreach deployment team and the Dynamics 365 Integrator partner before the deployment & configuration of Voice for Dynamics 365. In this configuration guide we present the REST API based model for smart routing.

By utilizing Smart Routing capabilities, calls arriving to a voice pool can be redirected to another pool or to a certain agent, based on data in Dynamics 365. For example if the call is coming from a number which is – either directly or indirectly – related to a VIP customer then the call can be redirected to a queue dedicated to such customers.

The following steps have to be carried out by the Dynamics 365 integrator partner to set up Smart Routing:

• Create a JSON REST API, e.g.

  • MS Flow with “When a HTTP request is received” trigger

  • Azure Function App

  • Azure App Service with a REST API

• Receive the data in the API (see below)

• Query Dynamics CRM database according to business needs

• Based on the queried data, return a response to redirect the caller (see below)

• Send the URL of your webhook and authentication key to Enreach, together with the queue(s) where this functionality is needed. Enreach will then set up the queue to call the web hook.

The whole mechanism is visualized on the following diagram:

1.6.1 Receiving data

The API has to accept data in JSON format according to the following schema:

{

  "type": "object",
  "properties": {
    "anum": {
      "type": "string"
    },
    "bnum": {
      "type": "string"
    }
  }
}

Example payload:

{

  "anum": "+35850454564", // phone number of caller
  "bnum": "+35840675644" // phone number of pool the call is in at the moment
}

Business logic will then find the caller in Dynamics CRM based anum and determine the needed action. Phone numbers have to be saved to CRM in the correct format, with no spaces or other characters, and starting with international calling prefix (plus sign). If phone numbers happen to be saved to CRM in local format then by removing first few (3-4) characters of anum, the rest can be matched to CRM data using contains comparison.

1.6.2 Authentication

Besides the payload, Enreach Cloud is sending an X-Benemen-APIKey HTTP header as a means of authentication. The API key must be validated by the business logic and return HTTP 401 Unauthorized if doesn’t match.

1.6.3 Redirecting the call

When the phone number of target queue has been determined by the business logic, it is returned as an HTTP response.

Example payload:

{

  "InitialTarget": "+35853445657", // phone number of target queue or agent
}

Things to notice:

• If no redirection has to be done (e.g. customer not found) then HTTP 204 No Content response must be returned

• Returning the same bnum from the request as InitialTarget is forbidden because it would cause an infinite loop in Enreach cloud. In such a case returning HTTP 204 is recommended.

The implementation of a Power Automate flow can be seen on the screnshot as an example.

Figure 39 Example Power Automate flow

1.6.4 Useful links to technical documentation for Smart Routing scenarios

More detailed technical documentation for developer needs:

https://benemen.atlassian.net/wiki/spaces/PD/pages/1215791782/SmartRouting+HTTP+Integrator+Guide

Azure function App example:

https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-serverless-api

1.7. Omnichannel user presence integration

If the Dynamics environment is running Omnichannel (user status feature is available as in the upper right screenshot), which uses Unified Routing engine to distribute work items to the user, it is essential to keep user status of Omnichannel and Web Phone in sync. If the status of user becomes Do not Disturb – either because of reaching maximum capacity or the user manually changed the status –, the system automatically blocks incoming calls by setting the user DND in Web Phone as well.

There are two basic use cases regarding this feature:

• User status gets changed when a call is not in progress

• User status is changed by call events

When user status is changed when not in a call, status is mirrored between Omnichannel and Web Phone according to the following mappings:

When the agent is receiving or making a call, Omnichannel status is se to Do not Disturb, to prevent Unified Routing from distributing any work item to the user during a call.

When the call ends, Omnichannel status is reset to the value which was active right before the call.

The feature is implemented within the following built-in JavaScript plugins:

All the plugins above are deployed automatically to the system and are by default enabled, no need to configure the feature in any way.

1.8. Test Voice for Dynamics 365 functionality

If everything was set up correctly, you should see the Voice for Dynamics 365 sidebar in the configured applications. Inbound& outbound calls, automatic phone call activity creation, Click-toDial and callback handling (if configured) are now available for the end users.

Figure 40 Voice for Dynamics 365, Customer Service Workspace (CIF2) (On the left side of Dynamics 365 UI)

Figure 41 Voice for Dynamics 365 Model Driven App (CIF1) (on the right side of Dynamics 365 UI)