From Bright Pattern Documentation
Jump to: navigation, search
(Updated via BpDeleteTranslateTags script)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<translate>
+
 
 
= Integration Configuration =
 
= Integration Configuration =
This procedure describes how to configure the Microsoft Dynamics 365 CRM and Microsoft Azure for integration with Bright Pattern Contact Center.
+
This procedure describes how to configure the Microsoft Dynamics 365 CRM and Microsoft Azure to enable [https://www.brightpattern.com/integrations/microsoft-dynamics-365/ MS Dynamics integration with Bright Pattern Contact Center software]. Part of this procedure includes enabling (i.e., authenticating and authorizing) Bright Pattern scenario blocks for use with Dynamics 365 data via the Web API.
  
 
== Step 1: Sign in to Microsoft Dynamics 365 ==
 
== Step 1: Sign in to Microsoft Dynamics 365 ==
Line 13: Line 13:
 
## '''Application ID''' - The Client ID<br /><br>
 
## '''Application ID''' - The Client ID<br /><br>
 
## '''Object ID''' - This ID will be filled in for the registered app<br /><br>
 
## '''Object ID''' - This ID will be filled in for the registered app<br /><br>
## '''Home page''' - http://localhost [Note: use exactly this value as it also will be hardcoded in the Azure Portal]<br /><br />[IMAGE]<br /><br>
+
## '''Home page''' - http://localhost [Note: use exactly this value as it also will be hardcoded in the Azure Portal]<br /><br />[[File:MS365-11-53.png|800px|thumbnail|center|App registration fields]]<br /><br>
# In the newly created app, go to ''equired Permissions > APIs > Add'' to add API access.<br /><br>[IMAGE]<br /><br>
+
# In the newly created app, go to ''Required Permissions > APIs > Add'' to add API access.<br /><br>[[File:MS365-12-53.png|800px|thumbnail|center|Add API access]]<br /><br>
 
# In ''Add API access'', make the following selections:<br /><br>
 
# In ''Add API access'', make the following selections:<br /><br>
 
## In ''Select an API'', select '''Dynamics CRM Online API'''.<br /><br>
 
## In ''Select an API'', select '''Dynamics CRM Online API'''.<br /><br>
Line 23: Line 23:
 
## In ''Expires'', set '''Never expires'''.<br /><br>
 
## In ''Expires'', set '''Never expires'''.<br /><br>
 
## Click '''Save'''. Once saved, the key value will be shown. The key value is the ''Client Secret'', which you need for later configuration steps.<br /><br>
 
## Click '''Save'''. Once saved, the key value will be shown. The key value is the ''Client Secret'', which you need for later configuration steps.<br /><br>
## '''Copy the key value now''' because this is the only moment you can see the actual key.<br /><br>[IMAGE]<br /><br>
+
## '''Copy the key value now''' because this is the only moment you can see the actual key.<br /><br>[[File:MS365-13-53.png|800px|thumbnail|center|The key is the Client Secret]]<br /><br>
# Go to ''App Registrations > Endpoints'' and copy the '''OAUTH 2.0 Authorization Endpoint''' and '''OAUTH 2.0 Token Endpoint''' values.<br /><br>[IMAGE]<br /><br>
+
# Go to ''App Registrations > Endpoints'' and copy the '''OAUTH 2.0 Authorization Endpoint''' and '''OAUTH 2.0 Token Endpoint''' values.<br /><br>[[File:MS365-14-53.png|800px|thumbnail|center|OAUTH 2.0 endpoint values]]<br /><br>
 
# Open the Dynamics 365 CRM (not Azure) application, and go to ''Settings > Security > Security Roles''.<br /><br>
 
# Open the Dynamics 365 CRM (not Azure) application, and go to ''Settings > Security > Security Roles''.<br /><br>
 
## Add new role (or copy existing role).<br /><br>
 
## Add new role (or copy existing role).<br /><br>
## Make sure the role has required privileges (the screenshot shown only grants access to the Account CRM object).<br /><br>[IMAGE]<br /><br>
+
## Make sure the role has required privileges (the screenshot shown only grants access to the Account CRM object).<br /><br>[[File:MS365-15-53.png|800px|thumbnail|center|Role assignment]]<br /><br>
 
# Go to ''Settings > Security > Users''.<br /><br>
 
# Go to ''Settings > Security > Users''.<br /><br>
## Switch view to '''Application Users'''.<br /><br>[IMAGE]<br /><br>
+
## Switch view to '''Application Users'''.<br /><br>[[File:MS365-16-53.png|800px|thumbnail|center|Application Users view]]<br /><br>
 
# Add new user.<br /><br>
 
# Add new user.<br /><br>
## Once new user form is shown, change it to '''Application User'''.<br /><br>[IMAGE]<br /><br>
+
## Once new user form is shown, change it to '''Application User'''.<br /><br>[[File:MS365-17-53.png|800px|thumbnail|center|User account information]]<br /><br>
 
# In ''Account Information'', fill in the following:<br /><br>
 
# In ''Account Information'', fill in the following:<br /><br>
 
## '''User Name'''<br /><br>
 
## '''User Name'''<br /><br>
Line 37: Line 37:
 
# In ''User Information'', fill in the following:<br /><br>
 
# In ''User Information'', fill in the following:<br /><br>
 
## '''Full Name''' - User's first name and last name<br /><br>
 
## '''Full Name''' - User's first name and last name<br /><br>
## '''Primary Email''' - User's email address<br /><br>[IMAGE]<br /><br>
+
## '''Primary Email''' - User's email address<br /><br>[[File:MS365-18-53.png|800px|thumbnail|center|Completed New User record]]<br /><br>
# Save the record. At this time, the '''Application ID URI''' and '''Azure AD Object ID''' fields are filled in.<br /><br>[IMAGE]<br /><br>
+
# Save the record. At this time, the '''Application ID URI''' and '''Azure AD Object ID''' fields are filled in.<br /><br>[[File:MS365-19-53.png|800px|thumbnail|center|Save user record]]<br /><br>
 
# Click '''Manage Roles'''.<br /><br>
 
# Click '''Manage Roles'''.<br /><br>
## In ''Manage User Roles'', add the custom role created on step 2.7 to that user.<br /><br>[IMAGE]<br /><br>
+
## In ''Manage User Roles'', add the custom role created on step 2.7 to that user.<br /><br>[[File:MS365-20-53.png|800px|thumbnail|center|Manage User Roles]]<br /><br>
  
 
This completes Microsoft Dynamics 365 CRM and Azure configuration.
 
This completes Microsoft Dynamics 365 CRM and Azure configuration.
Line 63: Line 63:
  
 
== Step 4: Get refresh token for Web API access by adding integration account ==
 
== Step 4: Get refresh token for Web API access by adding integration account ==
A refresh token can be obtained only after you provide your credentials to access the CRM Web API. These credentials are placed in the Microsoft Dynamics 365 integration account properties.
+
A refresh token can be obtained only after you provide your credentials to access the CRM Web API. These credentials are placed in the Microsoft Dynamics 365 [[Contact-center-administrator-guide/IntegrationAccounts/MicrosoftDynamics365 |  integration account properties]].
  
# In ''Contact Center Administrator > Integration Accounts'', add an integration account of type '''Microsoft Dynamics 365'''.<br /><br>[IMAGE]<br /><br>
+
# In ''Contact Center Administrator > Integration Accounts'', add an integration account of type '''Microsoft Dynamics 365'''.<br /><br>[[File:MS365-5-53.PNG|800px|thumbnail|center|Select integration account type]]<br /><br>
 
# Edit properties:<br /><br>
 
# Edit properties:<br /><br>
 
## '''Type''' - By default, “Microsoft Dynamics 365” because this is the type of integration account you are creating<br /><br>
 
## '''Type''' - By default, “Microsoft Dynamics 365” because this is the type of integration account you are creating<br /><br>
Line 72: Line 72:
 
## '''Authorization URL''' - The authorization code (see “How to Get Authorization URL”)<br /><br>
 
## '''Authorization URL''' - The authorization code (see “How to Get Authorization URL”)<br /><br>
 
## '''Token URL''' - The “Home page” value (i.e., “http://localhost”) you entered in step 2.2 of this procedure<br /><br>
 
## '''Token URL''' - The “Home page” value (i.e., “http://localhost”) you entered in step 2.2 of this procedure<br /><br>
## '''API URL''' - The API's URL with your instance name (e.g., “https://brightpatterndev.crm.dynamics.com/api/data/v9.0”)<br /><br>
+
## '''API URL''' - The API's URL with your instance name (e.g., “https://example.crm.dynamics.com/api/data/v9.0”)<br /><br>
 
## '''Client ID''' - The application ID you got from step 2.2 of this procedure<br /><br>
 
## '''Client ID''' - The application ID you got from step 2.2 of this procedure<br /><br>
 
## '''Client Secret''' - The key you got from step 2.2 of this procedure<br /><br>
 
## '''Client Secret''' - The key you got from step 2.2 of this procedure<br /><br>
## '''Refresh token''' - The refresh token you got from requesting the authorization URL (see “How to Get Authorization URL”). Click '''Request token''' to get a new one. <br /><br>
+
## '''Request token''' - Uses the credentials you've provided to access Microsoft's Web API and request a refresh token. When clicked, the token will appear in the ''Refresh token'' field<br /><br>
## '''Test connection''' - Tests the connection between Bright Pattern and Microsoft<br /><br>
+
## '''Refresh token''' - The refresh token you got from requesting the authorization URL (see “How to Get Authorization URL”). <br /><br>
 +
## '''Test connection''' - Tests the credentials and confirms whether the connection between Bright Pattern and Microsoft is valid.<br /><br>
  
 
=== How to Get Authorization URL ===
 
=== How to Get Authorization URL ===
Get one-time authorization code using AUTHORIZATION as base URL, client ID (i.e., the application ID), client secret (i.e., key), redirect URL (i.e., “http://localhost”), and API_URL (e.g., “https://brightpatterndev.crm.dynamics.com/api/data/v9.0”).
+
Get a one-time authorization code using AUTHORIZATION as base URL, client ID (i.e., the application ID), client secret (i.e., key), redirect URL (i.e., “http://localhost”), and API_URL (e.g., “https://brightpatterndev.crm.dynamics.com/api/data/v9.0”).
  
 
Like this:
 
Like this:
Line 87: Line 88:
 
  https://login.microsoftonline.com/7f3b7d01-a049-4dfd-9dbd-d394e711c3a0/oauth2/authorize? grant_type=client_credentials&client_id=dc40e7c1-86fa-484e-a38b-bec0d31c945a&client_secret=uxjgDon7fWbis1ijuCDwPifHooG4BV2lVTUFRGVttt4%3D&response_type=code&redirect_url=http://localhost&scope=offline_access&resource=https://brightpatterndev.crm.dynamics.com
 
  https://login.microsoftonline.com/7f3b7d01-a049-4dfd-9dbd-d394e711c3a0/oauth2/authorize? grant_type=client_credentials&client_id=dc40e7c1-86fa-484e-a38b-bec0d31c945a&client_secret=uxjgDon7fWbis1ijuCDwPifHooG4BV2lVTUFRGVttt4%3D&response_type=code&redirect_url=http://localhost&scope=offline_access&resource=https://brightpatterndev.crm.dynamics.com
  
This will return a one-time-use code at redirect url. This code should not be saved in DB; it is only used once to obtain a refresh token:
+
This will return a one-time-use code at redirect URL. This code should not be saved in the database; it is only used once to obtain a refresh token:
 
  http://localhost/?code=<CODE>&session_state=XXX
 
  http://localhost/?code=<CODE>&session_state=XXX
  
Line 127: Line 128:
 
  "expires_on":"1548192804",
 
  "expires_on":"1548192804",
 
  "not_before":"1548188904",
 
  "not_before":"1548188904",
  "resource":"https://brightpatterndev.crm.dynamics.com",
+
  "resource":"https://example.crm.dynamics.com",
 
  "access_token":"XXX",
 
  "access_token":"XXX",
 
  "refresh_token":"YYY"
 
  "refresh_token":"YYY"
Line 138: Line 139:
  
 
Once the access token expires, repeat step 1 to get a new access token.
 
Once the access token expires, repeat step 1 to get a new access token.
 
 
 
 
 
 
 
 
 
 
 
 
</translate>
 

Latest revision as of 04:02, 29 May 2024

• 5.19 • 5.3 • 5.8


Integration Configuration

This procedure describes how to configure the Microsoft Dynamics 365 CRM and Microsoft Azure to enable MS Dynamics integration with Bright Pattern Contact Center software. Part of this procedure includes enabling (i.e., authenticating and authorizing) Bright Pattern scenario blocks for use with Dynamics 365 data via the Web API.

Step 1: Sign in to Microsoft Dynamics 365

If you haven't already done so, get a Microsoft Dynamics 365 account and create a user ID. Get a trial organization of Microsoft Dynamics 365 or sign in to your instance.

Step 2: Configure Microsoft Azure and Dynamics 365 CRM for Web API access

  1. In the Azure Portal > Azure Active Directory > App Registrations, click Add New to add a new registered app.

  2. Edit the registered app fields with the following values:

    1. Application type - Web app / API

    2. Application ID - The Client ID

    3. Object ID - This ID will be filled in for the registered app

    4. Home page - http://localhost [Note: use exactly this value as it also will be hardcoded in the Azure Portal]

      App registration fields


  3. In the newly created app, go to Required Permissions > APIs > Add to add API access.

    Add API access


  4. In Add API access, make the following selections:

    1. In Select an API, select Dynamics CRM Online API.

    2. Select the checkbox for Delegated Permissions.

    3. When done, click Grant Permissions.

  5. In the newly created app, go to Keys and:

    1. In Description, name the app key.

    2. In Expires, set Never expires.

    3. Click Save. Once saved, the key value will be shown. The key value is the Client Secret, which you need for later configuration steps.

    4. Copy the key value now because this is the only moment you can see the actual key.

      The key is the Client Secret


  6. Go to App Registrations > Endpoints and copy the OAUTH 2.0 Authorization Endpoint and OAUTH 2.0 Token Endpoint values.

    OAUTH 2.0 endpoint values


  7. Open the Dynamics 365 CRM (not Azure) application, and go to Settings > Security > Security Roles.

    1. Add new role (or copy existing role).

    2. Make sure the role has required privileges (the screenshot shown only grants access to the Account CRM object).

      Role assignment


  8. Go to Settings > Security > Users.

    1. Switch view to Application Users.

      Application Users view


  9. Add new user.

    1. Once new user form is shown, change it to Application User.

      User account information


  10. In Account Information, fill in the following:

    1. User Name

    2. Application ID - Your application ID (i.e., the Client ID) that you got from step 2

  11. In User Information, fill in the following:

    1. Full Name - User's first name and last name

    2. Primary Email - User's email address

      Completed New User record


  12. Save the record. At this time, the Application ID URI and Azure AD Object ID fields are filled in.

    Save user record


  13. Click Manage Roles.

    1. In Manage User Roles, add the custom role created on step 2.7 to that user.

      Manage User Roles


This completes Microsoft Dynamics 365 CRM and Azure configuration.

Step 3: Get configuration values for access to CRM Web API

The following configuration (Configuration DB table) will be needed by the Bright Pattern Scenario Engine in order to use the CRM Web API. These configuration values should be provided by the Azure portal.

CREATE TABLE 'ms_dynamics_365_data' (
 'ID' varchar(255) NOT NULL,
 'VERSION' bigint(20) DEFAULT NULL,
 'DEFAULT_ACCOUNT' tinyint(1) NOT NULL DEFAULT '0',
 'TENANT_ID' varchar(255) NOT NULL,
 'NAME' varchar(255) NOT NULL,
 'CLIENT_ID' varchar(255) NOT NULL,
 'CLIENT_SECRET' varchar(255) DEFAULT NULL,
 'REFRESH_TOKEN' longtext NOT NULL, (encrypted)
 'AUTHORIZATION_URL' varchar(255) NOT NULL,
 'TOKEN_URL' varchar(255) NOT NULL,
 'API_URL' varchar(255) NOT NULL,
PRIMARY KEY ('ID')
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Step 4: Get refresh token for Web API access by adding integration account

A refresh token can be obtained only after you provide your credentials to access the CRM Web API. These credentials are placed in the Microsoft Dynamics 365 integration account properties.

  1. In Contact Center Administrator > Integration Accounts, add an integration account of type Microsoft Dynamics 365.

    Select integration account type


  2. Edit properties:

    1. Type - By default, “Microsoft Dynamics 365” because this is the type of integration account you are creating

    2. Name - The unique name (any) of the account

    3. Default account - Because it is possible to have multiple integration accounts of this type, select this checkbox to enable this account as the default

    4. Authorization URL - The authorization code (see “How to Get Authorization URL”)

    5. Token URL - The “Home page” value (i.e., “http://localhost”) you entered in step 2.2 of this procedure

    6. API URL - The API's URL with your instance name (e.g., “https://example.crm.dynamics.com/api/data/v9.0”)

    7. Client ID - The application ID you got from step 2.2 of this procedure

    8. Client Secret - The key you got from step 2.2 of this procedure

    9. Request token - Uses the credentials you've provided to access Microsoft's Web API and request a refresh token. When clicked, the token will appear in the Refresh token field

    10. Refresh token - The refresh token you got from requesting the authorization URL (see “How to Get Authorization URL”).

    11. Test connection - Tests the credentials and confirms whether the connection between Bright Pattern and Microsoft is valid.

How to Get Authorization URL

Get a one-time authorization code using AUTHORIZATION as base URL, client ID (i.e., the application ID), client secret (i.e., key), redirect URL (i.e., “http://localhost”), and API_URL (e.g., “https://brightpatterndev.crm.dynamics.com/api/data/v9.0”).

Like this:

<base_url>?grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&response_type=code&redirect_url=http://localhost& scope=offline_access&resource=<API_URL>

For example:

https://login.microsoftonline.com/7f3b7d01-a049-4dfd-9dbd-d394e711c3a0/oauth2/authorize? grant_type=client_credentials&client_id=dc40e7c1-86fa-484e-a38b-bec0d31c945a&client_secret=uxjgDon7fWbis1ijuCDwPifHooG4BV2lVTUFRGVttt4%3D&response_type=code&redirect_url=http://localhost&scope=offline_access&resource=https://brightpatterndev.crm.dynamics.com

This will return a one-time-use code at redirect URL. This code should not be saved in the database; it is only used once to obtain a refresh token:

http://localhost/?code=&session_state=XXX

Now use this code to obtain access and refresh tokens by issuing HTTP POST request to the token URL (i.e., “http://localhost”) with the following body:

redirect_uri=http://localhost&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=authorization_code&code=

In response, the token service will return the following JSON encoded data:

{
	"token_type":"Bearer",
	"scope":"user_impersonation",
	"expires_in":"3599",
	"ext_expires_in":"3599",
	"expires_on":"1548192804",
	"not_before":"1548188904",
	"resource":"https://<your.instance.name>.crm.dynamics.com",
	"access_token":"XXX",
	"refresh_token":"YYY",
	"id_token":"ZZZ"
}

You only need refresh_token. Store it to the REFRESH_TOKEN field in the Configuration DB table.

Step 5: Get access token to let Scenario Engine and Workflow Engine use CRM Web API

The server components will use refresh token from configuration to obtain an access token first. Access tokens typically expire within 1 hour by default.

Issue HTTP POST request to the <TOKEN_URL> with the following body:

client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>

In response, the token service will return the following JSON encoded data:

{
	"token_type":"Bearer",
	"scope":"user_impersonation",
	"expires_in":"3599",
	"ext_expires_in":"3599",
	"expires_on":"1548192804",
	"not_before":"1548188904",
	"resource":"https://example.crm.dynamics.com",
	"access_token":"XXX",
	"refresh_token":"YYY"
}

Use the access token from the previous step to work with 'API_URL by adding an Authorization HTTP header with the following value:

Authorization: Bearer <access_token>


Once the access token expires, repeat step 1 to get a new access token.

< Previous | Next >