Dynamics 365 Web API enhancements

In this blog post we will explore the enhancements and the issues addressed in Web API for Dynamics 365 December 2016 release.

Web API Enhancements:

Return entity data on create or update:

Sometimes you want to retrieve an entity right after you create or update it. Before this release, you needed to use two operations. The POST request to create an entity returns an HTTP 204 (No content) status and a Uri to the entity created is returned in the OData-EntityId header property. You can then use this Uri with a GET request to retrieve the created entity.

With this release you can specify the return=representation preference in the header of the request. A successful POST request will return HTTP 201 (Created) and include the entity properties you select. You can select which properties are returned by using the $select system query option. A successful request will return the full entity.

Method to create an account and get newly created record data

var entity = {};
entity.name = "TEST";

var req = new XMLHttpRequest();
req.open("POST", Xrm.Page.context.getClientUrl() + "/api/data/v8.0/accounts", true);
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("Prefer", "return=representation");// if this header is removed we will get nothing in response.
req.onreadystatechange = function () {
if (this.readyState === 4) {
req.onreadystatechange = null;

if (this.status === 204) {
var uri = this.getResponseHeader("OData-EntityId");
var regExp = /\(([^)]+)\)/;
var matches = regExp.exec(uri);
var newEntityId = matches[1];
}
else if (this.status === 201) {
alert(this.response); // response will return the new record data
}

}
};
req.send(JSON.stringify(entity));

Access to local data while Dynamics 365 for Outlook is offline:

Now we can access local data while dynamics 365 for outlook is offline using web API. When you write form scripts/web resources that use the Web API, these scripts can work using the local data in Dynamics 365 for Outlook when the user is offline. This capability has been available for the Organization service (SOAP endpoint) and the Organization Data service (OData v2), but was not previously available with the Web API.

Reference metadata by name:

With this release, you can use the name of certain metadata properties as alternate keys to reference an item of metadata. This will make it easier to query metadata using the Web API. Before this, you needed to perform a query to access the MetadataId of a particular item of metadata before you could retrieve it using that MetadataId as the key. For more information click here.

Bug fixes for WEB API

Can’t query date values

Now we can query date fields, Previously when we specify a date field  as a filter it wasn’t working which is fixed now. We can query date fields as shown below:

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

 

This issue is addressed in December 2016 update for Microsoft Dynamics 365 (online).

Can’t create customer lookup attribute

Creating customer lookup( A customer lookup attribute has two one-to-many relationships (one to the account entity and the other one to contact entity).) attribute using the Web API was not supported supported previously but this issue is addressed in this release.

Unlike other attributes, a customer lookup attribute is created using the CreateCustomerRelationships Action. The parameters for this action require the definition of the lookup attribute and a pair of one-to-many relationships.

Below is the example creates a customer lookup attribute, new_CustomerId, and adds it to the custom entity: new_bankaccount. The response is a CreateCustomerRelationshipsResponse Complex Type.

Request:

POST [Organization URI]/api/data/v8.2/CreateCustomerRelationships HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8

{
 "OneToManyRelationships": [{
 "SchemaName": "new_bankaccount_customer_account",
 "ReferencedEntity": "account",
 "ReferencingEntity": "new_bankaccount"
 }, {
 "SchemaName": "new_bankaccount_customer_contact",
 "ReferencedEntity": "contact",
 "ReferencingEntity": "new_bankaccount"
 }],
 "Lookup": {
 "AttributeType": "Lookup",
 "AttributeTypeName": {
 "Value": "LookupType"
 },
 "Description": {
 "@odata.type": "Microsoft.Dynamics.CRM.Label",
 "LocalizedLabels": [{
 "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
 "Label": "Sample Customer Lookup Attribute",
 "LanguageCode": 1033
 }],
 "UserLocalizedLabel": {
 "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
 "Label": "Sample Customer Lookup Attribute",
 "LanguageCode": 1033
 }
 },
 "DisplayName": {
 "@odata.type": "Microsoft.Dynamics.CRM.Label",
 "LocalizedLabels": [{
 "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
 "Label": "Customer",
 "LanguageCode": 1033
 }],
 "UserLocalizedLabel": {
 "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
 "Label": "Customer",
 "LanguageCode": 1033
 }
 },
 "SchemaName": "new_CustomerId",
 "@odata.type": "Microsoft.Dynamics.CRM.ComplexLookupAttributeMetadata"
 }
}

Response :


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

{
 "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.CreateCustomerRelationshipsResponse",
 "RelationshipIds": [
 "a7d261bc-3580-e611-80d7-00155d2a68de", "aed261bc-3580-e611-80d7-00155d2a68de"
 ],
 "AttributeId": "39a5d94c-e8a2-4a41-acc0-8487242d455e"
}

Can’t filter queries based on the value of a single-valued navigation property

You can now filter queries on the single-valued navigation property if the navigation property references the primary attribute value of the referenced entity.

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 “Scaleable”.

Request:


GET
[Organization URI]/api/data/v8.0/accounts?$select=name&$filter=primarycontactid/firstname eq 'Scaleable' 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>
}
}
}

The above request failed because we are not pointing to a primary key of related table. Below request gets succeeded  because we are retrieving child accounts for the specified Account ID(primary attribute).

Request:


GET [Organization URI]/api/data/v8.2/accounts?$select=name&$filter=parentaccountid/accountid%20eq%203adbf27c-8efb-e511-80d2-00155db07c77
Accept: application/json
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.2/$metadata#accounts(name)",
"value":[
{
"@odata.etag":"W/\"514058\"",
"name":"Scaleable Solutions",
"accountid":"915e89f5-29fc-e511-80d2-00155db07c77"
},{
"@odata.etag":"W/\"514061\"",
"name":" Scaleable Solutions2",
"accountid":"03312500-2afc-e511-80d2-00155db07c77"
}
]
}

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. This issue is fixed in the latest release of Microsoft Dynamics 365.

 

This is all for now keep visiting our blog for the latest updates regarding Dynamics 365.



Leave a Reply