Web API functions in Dynamics CRM 2016

By | February 3, 2016

The Web API which is introduced in Microsoft Dynamics CRM 2016 enhances the experience while developing through different programming languages, devices and platforms. It implements the OData, version 4.0, an OASIS standard which is used to build as well as to consume Restful APIs over rich data sources.

There are predefined functions introduced in the Web API which when executed help you to retrieve data. They may have parameters and they may return values. Functions may be bound to a specific entity. You will find the list of Web API functions on the web page: https://msdn.microsoft.com/en-us/library/mt607866.aspx

Let’s take an example of RetrieveVersion function

The RetrieveVersion function is used to get the version number of Microsoft Dynamics CRM Server. It is similar to the RetrieveVersionRequest which is used to get the version number through organization services.

The function is not bound to any entity types and does not require any parameters.

Here is the code for executing the standard functions of the WebAPI.

//This function is used execute the standard functions of webAPI

function exeFunction() {
    try {
        Inogic.ApiLib.executeFunction("RetrieveVersion()", exeFunctionSucess, function(error){throw new Error(error.message)};

    } catch (e) {
        showMessage(e.message);
    }
}

//success call back
function exeFunctionSucess(data) {
    try {

        var versionNumber = data;
    }
    catch (e) {
        showMessage(e.message);
    }
}

Here is the main code for executing the functions and fetching the results.

// This function is used to execute the function and get the results
 
            executeFunction: function (funName, successCallback, errorCallback) {

                //create the AJAX request
                $.ajax({
                    type: "GET",
                    contentType: "application/json; charset=utf-8",
                    datatype: "json",                  
                    url: encodeURI(this.getWebAPIPath() + funName),                   
                    beforeSend: function (xhr) {
                        
// This header ensures that the results will be returned as JSON.   
          
                        xhr.setRequestHeader("Accept", "application/json");                    
                     
//xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");

                        xhr.setRequestHeader("OData-MaxVersion", "4.0");
                        xhr.setRequestHeader("OData-Version", "4.0");
                    },
                    success: function (data, textStatus, xhr) {

                        //successCallback function - Here you get the version number.

                        successCallback(data.Version);
                    },
                    error: function (xhr, textStatus, errorThrown) {
                        errorCallback(Inogic.ApiLib.errorHandler(xhr));
                    }
                });

            }

Web API Query Functions:

Query functions are those which are used to add a filter criteria in Odata query. These functions accept parameters and return a Boolean value. It serves to be an additional filter applied on Odata query.

You would find predefined query functions of Web API in the following link. https://msdn.microsoft.com/en-us/library/mt607843.aspx

Let us consider ThisYear Function. It is used to retrieve data within the current year. It accepts parameter as property name (date attribute name) and returns data within this year.

Note: This function only accepts Date Datatype as a parameter. If you pass a parameter other than the date, then it throws an error.

// This function is used to execute the query function 

function executeQueryFunction() {

    var query = null;

    try {

        // create the query

        query = "?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue";

        // add the query function
 
        query += "&$filter=Microsoft.Dynamics.CRM.ThisYear(PropertyName='modifiedon')";

        //query += "&$filter=Microsoft.Dynamics.CRM.Today(PropertyName='modifiedon')";

        //call this function to execute the query function
        Inogic.ApiLib.executeQueryFunction("accounts", query, executeQueryFunctionSuccess, executeQueryFunctionError, executeQueryFunctionError, false);

    } catch (e) {
        showMessage(e.message);
    }
}

//success call back

function executeQueryFunctionSuccess(data) {
    try {

        //This function is used to process return data

        processData(data);

        HideBusyIndicator();
    }
    catch (e) {
        showMessage(e.message);
    }
}

This is the main Ajax call function.

   // This function is used to retrieve records using WebAPI query function

            executeQueryFunction: function (entitySetName, query, successCallback, errorCallback, onComplete) {

                try {
                
                    //create AJAX request

                    $.ajax({
                        type: "GET",
                        contentType: "application/json; charset=utf-8",
                        datatype: "json",
                        url: encodeURI(oDataUrl),
                        beforeSend: function (xhr) {
                           
//This header ensures that the results will be returned as JSON. 

                            xhr.setRequestHeader("Accept", "application/json");
                            xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");
                            xhr.setRequestHeader("OData-MaxVersion", "4.0");
                            xhr.setRequestHeader("OData-Version", "4.0");                          
                            xhr.setRequestHeader("Prefer", "odata.include-annotations=*");

                        },
                        success: function (data, textStatus, xhr) {
                            if (data != null) {
                                successCallback(data.value);                              
                            }
                        },
                        error: function (xhr, textStatus, errorThrown) {
                            errorCallback(xhr.statusText);
                        }
                    });
                } catch (e) {
                    throw new Error(e);
                }

            },

When you execute the above query then it will return all Accounts which are modified during a particular year.

Before moving on to the next post, you may like to read about Dynamics CRM and Bing Maps integration.

Leave a Reply

Your email address will not be published. Required fields are marked *