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

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

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

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

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

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>
    }  
   }
  }
  

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

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

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

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"
  }
  

FetchXML queries linked to activitypointer may not include linked fields

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

Null-valued properties may not be returned in expanded navigation property results

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": [email protected],
     "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": "[email protected]",
     "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