Web API Actions in Dynamics CRM 2016

Taking forward our series on using WEB API in Microsoft Dynamics CRM 2016, we will now touch upon a feature that was not available in ODATA v2 of the earlier versions.

ODATA v2 only provided support for CRUD operations. But Dynamics CRM has some special messages/functions for special operations that are beyond the basic CRUD on an entity. To perform these actions in the earlier versions of Microsoft Dynamics CRM, we had to fall back on SOAP messages.

With Web API, actions are now supported. Action is equivalent to requests that are available in Dynamics CRM.

There are predefined Actions defined in Dynamics CRM 2016 that can be executed using Web API. Following is like where you will find the list of Web API actions. https://msdn.microsoft.com/en-in/library/mt607829.aspx

There are three types of Action as listed below.

1. Unbound actions: It is not bound to any specific entity. i.e the first parameter to such actions does not include the entity. E.g. WinOpportunity, CancelContract etc
2. Bound actions: It is bound to specific entity. i.e the first parameter to such actions does not include the entity. e.g. – AddToQueue Action
3. Custom action: It is custom actions developed by developers using Processes.

We are explaining Web API Action called ConvertSalesOrderToInvoice which corresponds to the organization service ConvertSalesOrderToInvoiceRequest. ConvertSalesOrderToInvoice action is not bound to any entity and does not return a value. ConvertSalesOrderToInvoice Action require following parameters.

SalesOrderId: Guid of the order to convert. (This is compulsory parameter)

ColumnSet: List of attributes to retrieve from the created invoice. (This is compulsory parameter)

Below is the code that are used to execute ConvertSalesOrderToInvoice Action.

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

Here is the main Ajax request that execute the Action.

function executeAction() {

    var saleOrderID = null;

    var columnsSet = null;

    try {      

        //set the param values

        saleOrderID = "D035DD97-3AB5-E511-80E2-6C3BE5A852B0"; 

        columnsSet = new Array("name", "totalamount");      

        //create the action object

        var actionObj = {

            "SalesOrderId": saleOrderID,

            "ColumnSet":

                {

'AllColumns': false,

                    'Columns': columnsSet

                },

        };

        // call this function to execute the action. Please note the () used along with the function name

        Inogic.ApiLib.execute(actionObj, "ConvertSalesOrderToInvoice()", function (data) {

            // open the Created invoice record

            Xrm.Utility.openEntityForm("invoice", data.invoiceid);           

        }, function (error) { throw new Error(error.message);

    } catch (e) {

        alert(e.message);

    }

}

//This function is used to execute the Web API Action

            execute: function (req, reqName, successCallback, errorCallback) {

                //create AJAX request

                $.ajax({

                    type: "POST",

                    contentType: "application/json; charset=utf-8",

                    datatype: "json",

                    url: encodeURI(this.getWebAPIPath() + reqName),

                    data: window.JSON.stringify(req),

                    beforeSend: function (xhr) {

                        //Specifying 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

                        successCallback(data);

                    },

                    error: function (xhr, textStatus, errorThrown) {

                        errorCallback(Inogic.ApiLib.errorHandler(xhr));

                    }});

            },

//This function is used to get the client URL

   getClientUrl: function () {

                //Get the organization URL

                if (typeof GetGlobalContext == "function" &&

                    typeof GetGlobalContext().getClientUrl == "function") {

                    return GetGlobalContext().getClientUrl();

                }               

            }

Similar to this you can execute any Web API actions that are listed and your custom action that you developed.

Conclusion:

Web API can be used for executing messages other than CRUD as well.

Everything in Maplytics – Dynamics CRM and Bing Maps integration is now a search away at our Maplytics InfoCentre.