Dynamics 365Cloud-based Customer Relationship Management tool
Microsoft Dynamics 365 is a powerful cloud based Customer Relationship Management tool. The Tray.io connector works by providing the ability to create, update, get and list numerous types of entities within MS Dynamics, including accounts, users, cases and activities such as phone calls.
In configuring a Tray app to integrate with Dynamics365 there are two very important steps to be taken:
- The user who will be authenticating with Dynamics 365 must have the right level of authority to register the Tray app with Azure.
- Be aware of the individual permissions/scopes that the Tray app will access and set these accordingly. The Tray authentication dialog is programmed to mirror the permissions of the user who is authenticating. So when you authenticate with the Tray app it will ask for the permissions that user has in Azure AD.
You can access your Microsoft Dynamics account by entering your account credentials and agreeing to give Tray.io access to your account data, so that create, update, get and list operations will work.
If you are getting the error in the screenshot below, then there are some prerequisites that need to be taken care of before a Microsoft Dynamics account can be used through the Tray.io platform. This section will explain this process step by step. Please be advised that this guide assumes you already have a Microsoft Dynamics 365 account.
Become admin and verify domain
This step may need to be carried out by your organisation's IT team, if they have not already done so. Please check with them to see if they have Azure admin privileges. If they have, then skip to step 2.
First you must become admin in the Azure portal in order to allow your organisation's users to gain access through the Tray.io app. To become admin in the Azure portal, you must verify that the domain name of your Azure portal login e.g. email@example.com, (the domain is companyname.com in this example) is owned by you.
To verify ownership of the domain, the following Microsoft guide can be used:
Ensure the user has the authority to register the Tray.io app in Azure
If you are using an Azure account which has admin privileges, then you should already be able to access your Dynamics data through the Tray.io platform.
If not, then an Azure admin will need to set up access for the Tray app in one of three ways:
- Give all users the ability to consent to 3rd party apps accessing company data
- The Azure admin can login to Tray themselves in order to create the Authentication with their account
- An Azure admin can create a specific 'Tray app' user in Azure AD and give this user a specific role
The first option grants all users in your organisation the ability to log into Microsoft services through any 3rd party application. To enable this setting, an admin must sign into the Azure portal > Navigate to Azure Active Directory in the left hand navigation > Click on User Settings in the menu then Click on Enterprise applications > Manage how end users launch and view their applications > Click on yes to "Users can consent to apps accessing company data on their behalf"
The second option requires an Azure admin to log into the Tray app to create an Authentication and consent on behalf of the organisation. This means no other user for your organisation should have to consent to the Tray.io app accessing data in your organisation's Azure AD instance.
The third option requires creating a 'Tray app' user in Azure and then going to Users > Select User > Directory Role > Add Role:
For this user you will want to assign it the 'least priveleged role' in order for it to be able to carry out the operations you want.
There is a useful Microsoft guide on what roles are required for what tasks here
Creating your Authentication in Tray
When creating your authentication in Tray you will be asked to enter your Dynamics 365 url:
Click Next to sign into your Microsoft account and complete the OAuth flow.
The Azure Active Directory administrator should be able to confirm the permissions delegated to the app in Azure Active Directory under Azure Active Directory > Users > Click on the specific user > Applications > Click on the app > View Granted Permissions
Operations available on the Microsoft Dynamics 365 connector are:
- Create entity
- Delete entity
- Get entity
- List status attribute options
- List entities
- Update entity
Webhooks are events sent out by external services which can be consumed by the tray.io platform to trigger workflows. Workflows can then use the data contained within those event messages. However, Microsoft Dynamics must first be set up to send these events out.
In Microsoft Dynamics, events can be sent out using workflows and
custom workflow activities (these are just custom workflow steps that have been registered in the Dynamics instance).
custom workflow activity is responsible for sending events out to an external URL, which in this case would be the public URL of the workflow you would like to trigger.
The first step is to register the
Webhook in MS Dynamics (this sets up where the URL the events should be sent to). Once this has been done, you can then register the custom step or
custom workflow activity. This is where the event message and information about the entities can be configured.
These steps are completed through the
Plug-in Registration tool. It can then be placed in a workflow in Dynamics. Please see this link for more information about registering webhooks within MS Dynamics.
Once Dynamics is set up to send out events, the
Webhook trigger connector can be used to listen for these events.
Example 1 - Creating a Phonecall entity
The following example will show you how to create a phone call activity in Microsoft Dynamics 365 and associate it with an Owner ID and also specifying the "Call to" and "Call from" (as shown in the Dynamics UI).
To create a phone call, we need to use the "Create entity" operation. This operation needs to be used for any record that needs to be created in Dynamics. It works in a similar way for all entity types.
To get started, navigate to the Tray.io workflow builder and drag a Microsoft Dynamics 365 connector step to the workflow. Click on the microsoft-dynamics step and choose the "Create entity" from the "Operation" dropdown in the right hand side input property panel.
Step 1 - Choose entity type
First you need to choose the type of entity you want to create. This can be selected in the "Entity type" dropdown in the input panel.
Step 2 - Add field information to entity
Now that we've selected an entity type (in this case Phone Call), we now need to add information about the entity we are creating. For a phone call, we will want to add information such as a description, duration and other entities associated with the phone call.
We can add information like this to any entity type using the Fields list. Click on "Add Field" and three input boxes will appear. These are
- Field - name of the field specific to the entity type, chosen from a dropdown
- Value - value of the field (this could be text, number, date or an ID of another entity)
- Target type - if relating an existing entity (by entering an ID as the value), the type of that entity needs to be selected here e.g. a user entity. Not required if not relating to another entity.
In specifying a subject for the phone call please note since we are not relating another entity we have left Target type blank
Associating a Lead entity by specifying the Lead ID and a target type of Lead
Since the Owner field is relating the call entity with another entity we use the Target type field (in this case the Owner is a User but could also be a Team)
Step 3 - Adding activity parties to the entity
Since a phone call is classed as an activity in Dynamics, those involved with the activity (such as the caller, an email recipient, etc) are known as Activity Parties. These parties can be added when creating an activity entity by using the "Party list" section in the input property panel.
The party list for a phone call would include the "Call to" and "Call from" fields, which are visible by default in the Dynamics UI.
To add these fields to a phone call, click on "Add Field" and complete the following three input fields:
- Entity type - the entity type of the activity party e.g. user, contact, etc
- Participation type mask - the role of the activity party. Varies for the entity type being created, call to and call from for a phone call
- Value - ID of entity
When the entity is created by running the workflow with the step configured as above, Dynamics will return the ID of the created entity