Microsoft Dynamics 365 in cooperation with the Cognigy Extension provides the maintenance of Contacts and Accounts. This tutorial will explain how to integrate an organization's Dynamics instance to a Cognigy.AI virtual agent and create and retrieve an entity in Dynamics 365.
Table of Contents
- Install the Microsoft Dynamics Extension
- Create a Microsoft Online Connection
- Get an Access Token - Authenticate the user
- Search for Contacts or Accounts
- Retrieve an Entity by Primary Key
- Create a new Contact
Install the Microsoft Dynamics Extension
The first step is to install the required integration. In this case, a so-called Extension is uploaded to Cognigy.AI. Thus, open the Extensions Library in another tab and download the Microsoft Dynamics Extension by clicking on the Download button. Now follow this installation guide and upload the Extension to Cognigy, where it will be displayed as the following:
Congrats! The installation of the Extension is finished!
Create a Microsoft Online Connection
In this step, a so-called Connection will be created. If one, in Cognigy.AI, clicks on the previously uploaded Extension, the following details can be observed:
The red-marked part in the above figure shows, that there are two Connections required. Therefore, both need to be created and filled with the Dynamics 365 instance information. In order to do so, one initial Dynamics Flow Node needs to be added to a Flow:
- Create a new Flow in Cognigy.AI
- Inside of the Flow Chart, click on + and navigate to the Microsoft Dynamics Extension:
- Add the Get Access Token Flow Node by clicking on it:
- In order to edit the Flow Node and create the Connection, please click on it. An Edit Node menu will be opened on the right side of the screen:
- Right next to the Connection field (the first one at the top), one needs to click on the + button. The Connection menu will be opened at the center of the screen:
- Insert the related Microsoft Online log-in credentials/information of the organization to the fields.
- The Client ID of the Microsoft Dynamics 365 application
- The Client Secret of this Dynamics 365 application. It could be the case that an administrator within your organization needs to provide this.
- The ID of your Microsoft tenant.
- How to find the ID
- Go to portal.azure.com
- Click on Azure Active Directory
- Click Properties under the Manage section
- Your tenant is the Directory ID.
- The defined scope of the application in Azure.
- Example: https://company.crm.dynamics.com/.default
- Click on the Create button
Get an Access Token - Authenticate the user
This recently created Connection is required in order to get an access token for the current chat conversation. Without this token, none of the upcoming Dynamics functionalities could be used. Therefore, please test the Get Access Token Flow Node and check if the so-called "Bearer" token information is stored in the Context:
If the Connection is correct, the required access token is stored in the Context. By default, the location Context -> Microsoft -> Auth -> Access Token which can be extracted by using the following CognigyScript:
If the Context location was not customized, one doesn't need to do anything else as all upcoming Extension Nodes use this above Context location by default as well.
Create a Dynamics 365 Connection
After authenticating the chat conversation with the previous step, the missing Dynamics 365 Connection can be created. The only value, that needs to be provided in this case, is the organization URI. This information is necessary in order to call the right Dynamics 365 instance and fetch the data.
- Next, to the Get Access Token Flow Node, add any other Microsoft Dynamics Extension Node. For instance, Search Entity:
- Such as we did before, please click on the Node in order to open the Edit menu:
- At the top, one can create a new Connection by clicking on the + next to the Connection field:
- Please fill in the organization URI, such as https://company.crm.dynamics.com.
- Click on the Create button.
Search for Contacts or Accounts
The same Search Entity Flow Node can be used for retrieving entity information based on,
- defined Return Values,
- A list of entity fields that should be returned and stored
- a Search Filter
- Which entity field should be used for searching
- and a Search Value
- The value that will be used together with the filter
while this example entity is stored as a Contact in Dynamics 365:
In step 2 of the previous chapter, the used Edit menu is displayed. By default, the contact ID, first name, and last name are returned while the mobile phone number is used for filtering all given contacts -- in this default case. As an example, the possible chat conversation could look like the following:
Please notice that any entity field of a contact or account could be used for filtering or defining the list of returned values. In some cases, it could make sense to use the email address as a filter or expand the list of return values.
Retrieve an Entity by Primary Key
If it should be the case, that the Entity ID / Primary Key of the searched entry is already known, the Retrieve Entity Flow Node can be used instead. In this case, the entire data information of an entity, for example, contact, is returned and stored in the Input or Context object of Cognigy.AI. A possible scenario would be the cooperation of Search Entity and Retrieve Entity since one could first find the right contact and then get all information by executing the second Flow Node:
Since the required Contact ID / Primary Key is returned by the Search Entity Node, it can be used dynamically by using CognigyScript again:
The used CognigyScript extracts the contact ID, in this case, from the previously-stored Context result:
The used contactid value is only available if the list of Return Values inside of the Edit menu of the Search Entity Flow Node contains the word "contactid".
Create a new Contact
Finally, a virtual agent could create a new entity, e.g. a new contact, during a chat/voice conversation. A possible chat could look such as the following:
Furthermore, the mentioned contact creation could be configured such as
in which the Entity Data field consists of the dynamically inserted values from the Cognigy Context:
These dynamic values will be translated into real values as soon as the request of creation is sent to Microsoft Dynamics: