Tips and FAQ

How to Create an Activity

Dynamics CRM is not the easiest API to work with and creating an activity is a multiple step process. To create an activity, you first have to create the activity object and secondly associate it with the object in a second API call. For this example, I will be creating a phone call on an account.

1. Get the ID of the account you want to create the activity on.

2. Create the activity. I recommend you create an activity in the UI and then try to retrieve it so you can see what the correct format is. To do this call:

GET /activities?where=regardingobjectid = <id of the object with an activity on it> 

Keep in mind, Dynamics CRM has a number of different types of activities. For example they have a "phonecall" activity, these are defined as the "activitytypecode". If you were to create a phone call you call POST /phonecall via the POST /{objectName} api.

You can retrieve a list of objects by calling GET /objects?getAll=true

Sample phonecall:

{
 "attributes": {
 "subject": "had a phone call",
 "actualend": 1516473667000,
 "prioritycode": 1,
 "description": "had a phone call",
 "statecode": 1,
 "statuscode": 2,
 "leftvoicemail": false,
 "activitytypecode": "phonecall",
 "regardingobjectid": "fdda942a-03f4-e611-80ec-c4346bacaac0",
 "actualstart": 1516473667000
 }
}

3. Associate the activity with the parent object.

Call PATCH /accounts/{id}
{
 "action": "associate",
 "association": {
 "entity": "phonecall",
 "id": "<id of the phone call created in step 2>",
 "associationName": "Account_Phonecalls"
 }
}

Every object relationship will have its own associationName. To find the correct association name follow these steps in the Dynamics CRM UI:

1. Go to Settings > Customizations > Customize the System.

A popup window appears

Image_2018-01-20_at_12.05.51_PM.png

2. Navigate to Entities.

3. Find the entity that you are trying to create an activity on. In my case, account.

4. Select 1:N relationships.

Image_2018-01-20_at_12.08.41_PM.png

5. Find the correct relationship. It will always be formatted {parentObjectName}_{childObjectName}s.

Mine is Account_Phonecalls.

Fixing Slow Requests

When making calls to instances of Microsoft Dynamics 365, you may notice that some calls are very slow, often taking several seconds to complete. This scenario is usually a side effect of using basic (username/password) authentication to create your Dynamics instance. Basic authentication connections require the handshake process to occur more frequently, particularly when the same user name and password are used to log in elsewhere. This handshake process can add several seconds to API calls. 

To fix this issue, we encourage users to use OAuth 2.0 to authenticate element instances. This prevents the issue of credentials being used elsewhere and thus requiring the handshake process to take place. For more information on how to create instances of Dynamics via OAuth 2.0, see our documentation.

What Microsoft Dynamics CRM Versions are Supported?

Cloud Elements primarily supports Microsoft Dynamics 2016 with additional support for edition 2013 - 2015.

500 Errors While Authenticating an Element Instance

When authenticating an element instance of Microsoft Dynamics CRM, you might receive this error:

"response_status": 500
"message": "Unable to get change token"

Multiple problems can cause authentication to fail with this response message, but two of the most common reasons for this error are the MS Dynamics tenant URL or the poller configuration.

Tenant URL

The tenant URL of the MS Dynamics account might not be accessible. Confirm that the URL can be accessed directly through a browser to determine if there is an account or server issue at play before proceeding.

Poller Configuration

If the element instance is configured for polling events, then the poller configuration could be the reason. Different versions of Dynamics CRM support different queries in the poller configurations. If you attempt to use the wrong poller configuration, then you will experience authentication errors. 

The main difference to be aware of is that version 2015 of Dynamics CRM requires a different poller configuration because the fetchChanges polling query is valid only for Dynamics CRM version 2016. So when authenticating element instances for customers that have Dynamics 2015 and earlier, you must instead reference the modifiedon field in the poller url.

If you experience this error with a more recent Dynamics CRM version, we recommended that you still try the modifiedon version poller configuration URL before looking for other potential causes of this error because this query works for both versions.

For example the two main event.poller.configuration URLs for polling contacts are:

  • Version 2015 and earlier: /hubs/crm/contacts?where=modifiedon >'${gmtDate:yyyy-MM-dd'T'HH:mm:ss'Z'}'
  • Version 2016 and later: /hubs/crm/contacts?where=fetchChanges='true'