SAP Open Connectors

Tips and FAQ

Microsoft Dynamics CRM - How to Create and Associate an Email Activity to a Contact

To create the activity object, first POST to the appropriate activity type. In this example, it is email. The following POST works:

POST /{objectName} where objectName=email
{
"attributes":{
"activitytypecode":"email",
"description":"EMAIL BODY!!!"
}
}

Then, to create the association to the contact, execute a PATCH /contacts/{id} with the following json body:

{ "action": "associate", "association": { "entity": "email", "id": "bf027250-a2b5-e611-80e4-c4346bacaac0", "associationName": "Contact_Emails" } }



Microsoft Dynamics CRM - Are Any Updates Necessary if I Migrated to a Different Version of Dynamics?

Depending on the migration, the CRM Tenant URL for a customer's organization may change. If the URL changes, the instances associated to that account must be updated and re-authenticated in order to prevent delay in service.

Microsoft Dynamics CRM Supported Versions

What versions of Microsoft Dynamics does our Dynamics CRM connector support?

  • OnPrem Internet Facing Deployments: Dynamics CRM 2011, 2013, 2015, 2016
  • Cloud Versions: Dynamics CRM Online 2016, Dynamics 365

Does our Dynamics CRM connector support on-prem deployments? 

  • Yes, if it is deployed through an IFD (Internet Facing Deployment)
    • and if so, no IP addresses are necessary
  • SDK 7 supported 

Can I use a Dynamics 365 sandbox/account with our Dynamics CRM connector?

Yes, Dynamics365 is backward compatible with our Dynamics CRM connector. 

What's the URL to connect my Dynamics to SAP Open Connectors connectors? 

The siteURL is the URL that's displayed when you log into Dynamics from a web browser. 

What's the difference between Dynamics CRM and Dynamics 365?

Dynamics365 is the giant umbrella product that holds all the modules of Dynamics (a module is something like: CRM, Finance & Operations, Helpdesk etc.), and users purchase the modules they need and that’s what API access you get as a result of what you’ve purchased. Dynamics 365 offers a better, more consistent API than its legacy systems (every Dynamics CRM version 2016 and before had slightly different APIs) and should work across all Dynamics 365 versions.

Dynamics 365 Sandbox Information

Trial Access:  https://trials.dynamics.com/ 

Note: these trials do NOT all have API access; for example, sales does, but finance/operations does not.

Microsoft Dynamics CRM - Characters to Avoid in your Dynamics Password

Although the use of special characters is highly recommended when it comes to setting up a password, here is a list of characters that should be avoided when setting a password for Microsoft Dynamics:  [ \ ^ $ . | ? * + ( ) #  / % ' " ` to prevent issues in provisioning instances. 

The error message reported by customers that had one or more characters from this list in their passwords is the following: "Error = Format of the initialization string does not conform to specification starting at index {x}".

Microsoft Dynamics - How to Retrieve a List of All Supported Dynamics Objects

Using the GET /objects endpoint, you can pass the following query parameter: getAll=true. This API call returns a list of all objects you can use in a GET /{objectName} request.

Microsoft Dynamics CRM - Error Retrieving Column

You may receive this kind of error when querying or mapping fields to Dynamics CRM objects: 

Retrieve can only return columns that are valid for read.  Column : isprivate. Entity : account"

If you receive this error, the field is likely not valid for reading purposes. You can check to see if that field is valid by navigating through Microsoft's Entity Documentation and checking if your object's field has the following field flag: "IsValidForRead": False. 

Microsoft Dynamics - Bulk Support for Static and Dynamic Lists

Bulk APIs in Dynamics support static lists only. For dynamic lists, it might work for basic queries like example: select * from leads where list id=‘12’. No other filters can be applied for dynamic lists because all filters are already built into the list set up and MS Dynamics does not let you add additional filters on the dynamic list.

Microsoft Dynamics - Using Custom Entities With Common Resources

Dynamics CRM allows you to create Custom Entities, however, because CE does not have response models for these entities they will not populate in the common resource transformation UI. That being said, you can still map these custom entities using the API. 

Before creating the object definition, you need to gather the custom entity metadata to use in defining the object fields. The Dynamics CRM connector has an /objects/{objectName}/metadata endpoint that you can use to gather this metadata. 

After you have obtained the object's metadata, the next step is to create the object definition using the Platform API Docs. Under the instances section of the Platform API docs, there is a /instances/{id}/object/{objectName}/definitions endpoint. You can use the response from the previous step as the body for this endpoint.

The final step is to use the /instances/{id}/transformations/{objectName} endpoint to create the common resource transformation for the objectName. You can use the information in this article to understand that different parts of the JSON body.

After you have created the transformation, it also displays in the common resource UI and from there you can continue working with this common resource. 

Microsoft Dynamics CRM - Dictionary Keys

When a custom field for a MS Dynamics object is created, the custom field should also have a valid key present in the Dynamics Dictionary. If the Custom Field Type is not part of the valid attribute types in key definitions, it cannot be used to interact with an external integration. Here is a list of valid attributes to be used in Dynamics key definitions.

Microsoft Dynamics CRM Supported Versions

What versions of Microsoft Dynamics does our Dynamics CRM connector support?

  • OnPrem Internet Facing Deployments: Dynamics CRM 2011, 2013, 2015, 2016
  • Cloud Versions: Dynamics CRM Online 2016, Dynamics 365
  • OnPrem G2C (non-internet facing): Not Supported Today

Does our Dynamics CRM connector support on-prem deployments? 

  • Yes, if it is deployed through an IFD (Internet Facing Deployment)
    • and if so, no IP addresses are necessary
  • SDK 7 supported 

Can we use Ground2Cloud if it is not an IFD?

  • No, currently Ground2Cloud cannot support Dynamics On-Prem deployments that are not IFD
  • Dynamics does not use Ground2Cloud as it uses multiple undocumented ports underneath to perform authentication

Can I use a Dynamics 365 sandbox/account with our Dynamics CRM connector?

Yes, Dynamics365 is backward compatible with our Dynamics CRM connector. 

What's the URL to connect my Dynamics to SAP Open Connectors connectors? 

The siteURL is the URL that's displayed when you log into Dynamics from a web browser. 

What's the difference between Dynamics CRM and Dynamics 365?

Dynamics365 is the giant umbrella product that holds all the modules of Dynamics (a module is something like: CRM, Finance & Operations, Helpdesk etc.), and users purchase the modules they need and that’s what API access you get as a result of what you’ve purchased. Dynamics 365 offers a better, more consistent API than its legacy systems (every Dynamics CRM version 2016 and before had slightly different APIs) and should work across all Dynamics 365 versions.

Dynamics 365 Sandbox Information

Trial Access:  https://trials.dynamics.com/ 

Note: these trials do NOT all have API access; for example, sales does, but finance/operations does not.

Microsoft Dynamics CRM - 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.

Microsoft Dynamics - 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 connector 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.

Microsoft Dynamics CRM - 500 Errors While Authenticating a Connector Instance

When authenticating a connector 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 connector 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 connector 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'

Microsoft Dynamics - Create Objects Attached to other Objects

Microsoft Dynamics allows for the creation of objects that can be attached to other objects. For example, one can create a Contact with Activities attached to the Account. Another example is creating an Account and then creating a Case attached to that Account. The Activity and the Case are independent objects that can be created without having to be attached to another object as well. 


Img 1 - A Task (which is a type of Activity) attached to a Contact


In SAP Open Connectors, you can create this Task using the Swagger on the Microsoft Dynamics connector instance. 


If you would like this Task to be attached to an Account, or a Contact (or another object that allows Tasks to be attached to it), the minimum Task create body looks like this:

{

 

  "fetchMetaInfo": true,

 

  "attributes": {

 

    "regardingobjectid": {

 

      "id": "41xxxxxx-bxx9-exx1-axx9-00xxxxxxxxxa4",

 

      "lookup": "contact"

 

    },

 

    "subject": "newest task"

 

  }

 

}





To create a Case attached to an object, the body is a little different. Here is the payload for creating a Case on an Account object. You can change the name of the object in the lookup value.


{

 

  "attributes": {

 

    "title": "New Case",

 

    "description": "description here",

 

    "customerid": {

 

      "id": "7xxxxxxxxd-cxx6-exx1-axxx2-00xxxxxxxxdd",

 

      "lookup": "account"

 

    }

 

  },

 

  "fetchMetaInfo": true

 

}