Microsoft Dynamics 365 Web API Limitations

Dynamics CRM 2016
 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Microsoft Dynamics 365 Web API will provide complete parity with the capabilities of the organization service. For Microsoft Dynamics 365 (online & on-premises), this topic describes some of the limitations.

This section provides information about the limitations in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises) .

If you define a custom action which includes a complex return value and a simple return value, a corresponding Action is not available in the Web API but is available using the 2011 SOAP endpoint. A complex return value is an EntityReference, Entity, or EntityCollection. You can have any combination of simple return values or a single complex return value. More information:  Create your own actions

The following table lists the messages that don't have a corresponding function or action after December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises) are applied.

GrantAccessRequest

ModifyAccessRequest

ReactivateEntityKeyRequest

RemoveMemberListRequest

RemoveItemCampaignRequest

RemoveItemCampaignActivityRequest

For a list of functions and actions missing from the initial release, combine this list with the list under Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1 and Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1.

The following operations have been added to the Web API for December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).

QualifyLead Action

RetrieveByResourcesService Function

RetrieveFilteredForms Function

System_CAPS_noteNote

This issue is addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).

JavaScript code running in form scripts, ribbon commands, or HTML web resources can't use the Web API. It's now enabled on the local server used when the user goes offline.

This issue was not actually limitation, just a syntax issue. Don't use single quotes when specifying a date as value for a filter.

When querying a date property, such as the birthdate of a contact, the following query syntax works.

/contacts?$select=fullname,birthdate&$filter=birthdate eq 1990-01-01

The following syntax will not:

/contacts?$select=fullname,birthdate&$filter=birthdate eq '1990-01-01'

System_CAPS_noteNote

This issue is addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).

The following actions contain an entity collection parameter, in addition to other parameters.

AddListMembersList Action

AddPrivilegesRole Action

CompoundUpdateDuplicateDetectionRule Action

DeliverIncomingEmail Action

DeliverPromoteEmail Action

InstantiateTemplate Action

QualifyMemberList Action

ReplacePrivilegesRole Action

SendTemplate Action

SetLocLabels Action

Before December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises), when you use these actions, the parameter that includes the entity collection must be passed as the last parameter in the JSON or the system returns an error. For example, you'll get an error when you use the QualifyMemberList Action and pass the parameter values in the following manner.

{
"ListMember": [
  {
   "@odata.type": "Microsoft.Dynamics.CRM.account",
   "accountid": "483F8080-6976-E511-9172-0024E8436263"
  },
  {
   "@odata.type": "Microsoft.Dynamics.CRM.account",
   "accountid": "4D3F8080-6976-E511-9172-0024E8436263"
  }
 ],
"OverrideorRemove": true
}

But the following should succeed.

{
 "OverrideorRemove": true,
 "ListMember": [
  {
   "@odata.type": "Microsoft.Dynamics.CRM.account",
   "accountid": "483F8080-6976-E511-9172-0024E8436263"
  },
  {
   "@odata.type": "Microsoft.Dynamics.CRM.account",
   "accountid": "4D3F8080-6976-E511-9172-0024E8436263"
  }
 ]
}

System_CAPS_noteNote

This issue is addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).

Creating customer lookup attribute using the Web API is not supported in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1.

To create a customer lookup attribute with the Web API using December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises), see Create a customer lookup attribute.

System_CAPS_noteNote

This issue is addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).

The organization service messages that retrieve metadata include a RetrieveAsIfPublished parameter that provides the option to return metadata definitions that haven't yet been committed by publishing. This capability is useful when you are building an application you would use to edit metadata and need to allow for uncommitted changes to be saved. In Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1 all retrieve operations on metadata return only the published metadata. More information: Use the Web API with Dynamics 365 metadata and Publish customizations.

Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1 have added functions and actions, and address the following issues with the Web API:

The following table lists the functions and actions added for Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1.

Book Action

Reschedule Action

CalculateRollupField Function

System_CAPS_noteNote

This issue is partially addressed in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1. You can now filter queries on the single-valued navigation property if the navigation property references the primary attribute value of the referenced entity. More information: Filter records based on single-valued navigation property

If you use the property of a single-valued navigation property as a filter in a query, you'll see a 501 error. For example, the following query attempts to return all accounts where the related primary contact firstname property value is "Renee".

Request
GET 
[Organization URI]/api/data/v8.0/accounts?$select=name&$filter=primarycontactid/firstname eq 'Renee' HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response
HTTP/1.1 501 Not Implemented
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{  
 "error": {    
  "code": "",
   "message": "The query node (0) is not supported",
   "innererror": {      
   "message": "The query node (0) is not supported",
   "type": "Microsoft.Crm.CrmHttpException",
   "stacktrace": 
                        <stacktrace value removed for brevity>
  }  
 }
}

System_CAPS_noteNote

This issue is addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.

There are two system entities with self-referential many-to-many relationships: connectionrole EntityType has connectionroleassociation_association and campaign EntityType has campaigncampaign_association. If you attempt a query that uses these collection-valued navigation properties the following HTTP Status 400 error is expected: Reflexive relationship must specify direction using ReflexiveManyToManyRelationship.

If you need to query data using these many-to-many relationships, you can use the intersect entities instead. For the campaigncampaign_association collection-valued navigation property, the campaignitem EntityType entity is the special intersect entity that defines the relationships. For connectionroleassociation_association, connectionroleassociation is the ordinary intersect entity that contains the data that define this many-to-many relationship. Ordinary intersect entities aren't included in the reference documentation but are available in the Web API. You can access the connectionroleassociation entity using this URI: /api/data/v8.0/connectionroleassociations. More information: Collection-valued navigation properties

System_CAPS_noteNote

This issue is addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.

When retrieving two navigation properties, if the last navigation property doesn’t have $select query option, all properties of first navigation property are returned. For example, if you construct the following query:

GET 
[Organization URI]/api/data/v8.0/accounts(0495779B-F67F-E511-80C2-00155DB09B03)$select=name&$expand=contact_customer_accounts($select=lastname),opportunity_customer_accounts

You are expecting the name property of the account, the lastname of the contacts associated using contact_customer_accounts and all the properties for opportunities associated using opportunity_customer_accounts.

However, you will get all the properties for the contacts as well as all the properties of related opportunities. It is a best practice to always use $select to limit the properties in any retrieve operations, so following this best practice will ensure that you get best performance and don't retrieve more data than you need.

System_CAPS_noteNote

This issue is addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.

According to the OData specification, when you expand a single navigation property and it doesn't contain a value, the property should be included with null set. The current behavior is that the property will not be included in the JSON response. In the following example, the account primarycontactid single-valued navigation property is requested, but because there is no contact associated with that navigation property, the value is null.

Request
GET 
[Organization URI]/api/data/v8.0/accounts(25DD0B31-ED8B-E511-80D2-00155D2A68D4)?$select=name&$expand=primarycontactid($select=fullname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

Expected Response
HTTP/1.1 200 OK
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name,primarycontactid,primarycontactid(fullname))/$entity",
 "@odata.etag": "W/\"504724\"",
 "name": "A. Datum Corporation (sample)",
 "accountid": "25dd0b31-ed8b-e511-80d2-00155d2a68d4",
 "primarycontactid": null
}

Actual Response
HTTP/1.1 200 OK
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name,primarycontactid,primarycontactid(fullname))/$entity",
 "@odata.etag": "W/\"504724\"",
 "name": "A. Datum Corporation (sample)",
 "accountid": "25dd0b31-ed8b-e511-80d2-00155d2a68d4"
}

System_CAPS_noteNote

This issue is addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.

When you create a query using FetchXML which includes activitypointer as a linked entity, the property values will be null. For example, if you use the following fetchXML:

<fetch version="1.0"
       output-format="xml-platform"
       mapping="logical"
       distinct="true">
  <entity name="account">
    <attribute name="name" />
    <link-entity name="activitypointer"
                 from="regardingobjectid"
                 to="accountid"
                 link-type="inner">
      <attribute name="subject" />
    </link-entity>
  </entity>
</fetch>

You are requesting the related activitypointer. subject value to be returned. It is returned with a null value when an actual value exists.

Request
GET 
[Organization URI]/api/data/v8.0/accounts?fetchXml=%3Cfetch%20version=%221.0%22%20output-format=%22xml-platform%22%20mapping=%22logical%22%20distinct=%22true%22%3E%3Centity%20name=%22account%22%3E%3Cattribute%20name=%22name%22%20/%3E%3Clink-entity%20name=%22activitypointer%22%20from=%22regardingobjectid%22%20to=%22accountid%22%20link-type=%22inner%22%3E%3Cattribute%20name=%22subject%22%20/%3E%3C/link-entity%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Expected Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name)",
 "value": [
  {
   "name": "A. Datum Corporation (sample)",
   "activitypointer1.subject": "Task Subject Value"
  }
 ]
}

Actual Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name)",
 "value": [
  {
   "name": "A. Datum Corporation (sample)",
   "activitypointer1.subject": null
  }
 ]
}

More information: Use custom FetchXML

System_CAPS_noteNote

This issue is addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.

When one of the expanded properties in a collection-valued navigation property is null, the expanded property will not be included in the results. The first example shows the data when one of the contacts related to an account has a null value for the expanded emailaddress1 property. The emailaddress1 property isn't returned even for the contact where it has a value.

Request
GET 
[Organization URI]/api/data/v8.0/accounts(25DD0B31-ED8B-E511-80D2-00155D2A68D4)?$select=name&$expand=contact_customer_accounts($select=emailaddress1,lastname,firstname) HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

Expected Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name,contact_customer_accounts,contact_customer_accounts(emailaddress1,lastname,firstname))/$entity",
 "@odata.etag": "W/\"504724\"",
 "name": "A. Datum Corporation (sample)",
 "accountid": "25dd0b31-ed8b-e511-80d2-00155d2a68d4",
 "contact_customer_accounts": [
  {
   "@odata.etag": "W/\"504749\"",
   "emailaddress1": null,
   "lastname": "Valdes (sample)",
   "firstname": "Rene",
   "contactid": "8bdd0b31-ed8b-e511-80d2-00155d2a68d4"
  },
  {
   "@odata.etag": "W/\"503647\"",
   "emailaddress1": someone_l@example.com,
   "lastname": "Burk (sample)",
   "firstname": "Susan",
   "contactid": "91dd0b31-ed8b-e511-80d2-00155d2a68d4"
  }
 ]
}

Actual Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#accounts(name,contact_customer_accounts,contact_customer_accounts(emailaddress1,lastname,firstname))/$entity",
 "@odata.etag": "W/\"504724\"",
 "name": "A. Datum Corporation (sample)",
 "accountid": "25dd0b31-ed8b-e511-80d2-00155d2a68d4",
 "contact_customer_accounts": [
  {
   "@odata.etag": "W/\"504749\"",
   "lastname": "Valdes (sample)",
   "firstname": "Rene",
   "contactid": "8bdd0b31-ed8b-e511-80d2-00155d2a68d4"
  },
  {
   "@odata.etag": "W/\"503647\"",
   "lastname": "Burk (sample)",
   "firstname": "Susan",
   "contactid": "91dd0b31-ed8b-e511-80d2-00155d2a68d4"
  }
 ]
}

The following query directly using the contact_customer_accounts collection-valued navigation property without expanding returns the expected data.

Request
GET 
[Organization URI]/api/data/v8.0/accounts(25DD0B31-ED8B-E511-80D2-00155D2A68D4)/contact_customer_accounts?$select=emailaddress1,lastname,firstname HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "
[Organization URI]/api/data/v8.0/$metadata#contacts(emailaddress1,lastname,firstname)",
 "value": [
  {
   "@odata.etag": "W/\"504749\"",
   "emailaddress1": null,
   "lastname": "Valdes (sample)",
   "firstname": "Rene",
   "contactid": "8bdd0b31-ed8b-e511-80d2-00155d2a68d4"
  },
  {
   "@odata.etag": "W/\"503647\"",
   "emailaddress1": "someone_l@example.com",
   "lastname": "Burk (sample)",
   "firstname": "Susan",
   "contactid": "91dd0b31-ed8b-e511-80d2-00155d2a68d4"
  }
 ]
}

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions

Show: