Microsoft Dynamics 365 Web API Limitations
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.
In this topic
Limitations in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises)
Limitations addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises)
Limitations addressed in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1
Limitations addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1
Limitations in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises)
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) .
Some custom actions not available in Web API
Missing functions and actions for some organization service messages
Some custom actions not available in Web API
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
Missing functions and actions for some organization service messages
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.
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.
Limitations addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises)
This section provides information about the limitations addressed in December 2016 update for Microsoft Dynamics 365 (online) and December 2016 Service Pack for Microsoft Dynamics 365 (on-premises).
Web API not enabled for Microsoft Dynamics 365 for Outlook with Offline Access while user is offline
Can't query date values
When calling actions with entity collection parameters as well as other parameters, a collection parameter must be passed as the last parameter in the body
Can't create customer lookup attribute
Can't retrieve unpublished metadata
New operations added
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).
Web API not enabled for Microsoft Dynamics 365 for Outlook with Offline Access while user is offline
Note
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.
Can't query date values
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'
When calling actions with entity collection parameters as well as other parameters, a collection parameter must be passed as the last parameter in the body
Note
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.
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"
}
]
}
Can't create customer lookup attribute
Note
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.
Can't retrieve unpublished metadata
Note
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.
Limitations addressed in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1
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:
Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1
Can't filter queries based on the value of a single-valued navigation property
Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 1 and Microsoft Dynamics CRM 2016 Service Pack 1
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.
Can't filter queries based on the value of a single-valued navigation property
Note
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.0Response
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> } } }
Limitations addressed in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1
Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM Online 2016 Update 0.1 has added functions and actions, and addressed the following issues with the Web API.
Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1
Error when querying self-referential many-to-many relationships
$select on some $expand expressions may be ignored
Single-valued navigation properties may not be returned from a $expand query if they have a null value
FetchXML queries linked to activitypointer may not include linked fields
Null-valued properties may not be returned in expanded navigation property results
Functions and actions added in Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1
The following table lists the functions and actions added for Microsoft Dynamics CRM Online 2016 Update 0.1 and Microsoft Dynamics CRM 2016 Update 0.1.
Error when querying self-referential many-to-many relationships
Note
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
$select on some $expand expressions may be ignored
Note
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.
Single-valued navigation properties may not be returned from a $expand query if they have a null value
Note
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.0Expected 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" }
FetchXML queries linked to activitypointer may not include linked fields
Note
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.0Expected 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
Null-valued properties may not be returned in expanded navigation property results
Note
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.0Expected 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.0Response
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" } ] }
See Also
Use the Microsoft Dynamics 365 Web API
Authenticate to Microsoft Dynamics 365 with the Web API
Web API types and operations
Perform operations using the Web API
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright