Work with Microsoft Dynamics 365 Web API

March 28, 2017 / Author AlexR / Category Blog, Microsoft Dynamics CRM / Comment

Web API is a new interface introduced with Microsoft Dynamics CRM 2016 (Microsoft Dynamics 365). If you have not heard about it yet, I advice you to take a look at this post or to check MSDN directly. And if you have not started using it I would also advice to start doing it for all new projects in Microsoft Dynamics CRM 2016 or Microsoft Dynamics 365.

In this post I will tell you about a library that will help you to create web resources for CRM or develop Node.js application integrated with Microsoft Dynamics CRM Web API.

The library is called: DynamicsWebApi, and it can be found on GitHub or installed using npm.

npm install dynamics-web-api --save

DynamicsWebApi solves several important problems, for example: it makes correct requests to Web API, automatically converts JSON responses, makes the code look cleaner and etc. Obviously, it sounds like these tasks are quite trivial, especially for experienced developers, but therefore they become a routine work mostly because the code is usually repetitive. It is always one of the main goals of all helper libraries ever created is to make developers to be more productive by decreasing time spent doing repetitive work. The same goal have Microsoft SDK.REST.js that helps to perform operations using OData endpoint and very popular XrmServiceToolkit that solves various tasks which might have caused a lot of headache for many developers in the world if they would try to solve them on their own. It is important to say that mentioned scripts do not support Web API interface at the moment when the post has been written.

Main advantages of DynamicsWebApi

  • It does not any depend on any external library.
  • It can be used in browsers (to create CRM web resources), or in Node.js application that integrates with Microsoft Dynamics 365 Web API.
  • There are two versions of the library that can be chosen depending on your needs: one of them uses Promise for asynchronous requests and another one Callbacks, which is compatible with all browsers that do not support Promise, such as IE. It is also worth mentioning that you can use any Promise Polyfill with DynamicsWebApi Promise version.
  • It is simple to convert existing code to use DynamicsWebApi, you need only to rewrite requests that will become shorter and more readable; the results of the requests can be left untouched.
  • DynamicsWebApi contains description for each function and their parameters. If it is not enough, the project on GitHub has a detailed documentation with many examples.
  • The project itself is covered with tests with more than 90% coverage.
  • Each release is automatically built by Travis-CI and the build results can be seen for each commit made on GitHub.

Request examples using DynamicsWebApi

var dynamicsWebApi = new DynamicsWebApi({ webApiVersion: '8.2' });
var contactRecord = {
    firstname: 'John',
    lastname: 'Doe'
};
dynamicsWebApi.create(contactRecord, 'contacts').then(function(id){
    //'id' can be used somewhere further in the code
    var propertyToUpdate = {
        firstname: 'Joe';
    }
    return dynamicsWebApi.updateSingleProperty(id, 'contacts', propertyToUpdate, 'return=representation');
}).then(function(contactAfterUpdate)
    if (contactAfterUpdate.firstname === 'Joe'){
        return dynamicsWebApi.deleteRecord(contactAfterUpdate.contactid, 'contacts');
    }
    //and so on
});
.catch(function(error){
    //exception is caught!
});

CRM Functions and Action are also implemented in the library:

var parameters = {
    LocalizedStandardName: 'Pacific Standard Time',
    LocaleId: 1033
};
dynamicsWebApi.executeUnboundFunction('GetTimeZoneCodeByLocalizedName', parameters)
    .then(function (result) {
        alert(result.TimeZoneCode);
    }).catch(function (error) {
        console.trace(error.message);
    });

CRM Action example:

dynamicsWebApi.create({ subject: "test" }, "letters").then(function (letterActivityId) {
    var actionRequest = {
        Target: {
            activityid: letterActivityId,
            "@odata.type": "Microsoft.Dynamics.CRM.letter"
        }
    };
    return dynamicsWebApi.executeBoundAction(queueId, "queues", "Microsoft.Dynamics.CRM.AddToQueue", actionRequest);
}).then(function (response) {
    alert(response.QueueItemId);
}).catch(function (error) {
    console.trace(error.message);
});

DynamicsWebApi contains two groups of request functions: basic and advanced. Basic functions simplify access to most popular requests by limiting parameters that can be provided through the call. Advanced ones have suffix “Request” and give an ability to provide all possible parameter combinations supported by Web API by using a single Request object. Of course, all combinations could fit in one function but then the code would be highly unreadable, it would not be clear which value corresponds to which parameter in the function. So, in my opinion, a decision to make two groups of similar functions is very straightforward, especially if to take into a consideration a power of CRM Web API that will eventually be growing with future releases.

var request = {
    id: '00000000-0000-0000-0000-000000000001',
    collection: 'contacts',
    select: ['firstname', 'lastname', '_parentcustomerid_value'],
    //ETag in If-None-Match header indicates that the data needs to be
    //retrieved only if it has been updated from the last request
    ifnonematch: 'W/"468026"',
    //the next property indicates that the returned result should contain
    //additional data, for example: the name of the entity for a lookup field
    includeAnnotations: 'Microsoft.Dynamics.CRM.lookuplogicalname',
    //the request should be made on behalf of another System User with the
    //specified id
    impersonate: '00000000-0000-0000-0000-000000000002'
};
dynamicsWebApi.retrieveRequest(request).then(function (response) {
    if (response){    
        //update already existing contact object because it has been changed
        //existingContact.subject = response.subject;
    }
}).catch(function (error) {
    //if the contact has not been found
    console.trace(error.message);
});

Overall, DynamicsWebApi is a great library that will definitely increase a productivity of writing scripts for Microsoft Dynamics CRM Web API by automation of most trivial tasks and removing most of routine work that could be done by developer without using it.
DynamicsWebApi is fully compatible with Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016 and Dynamics CRM Online.

Comments