Web API Actions in Dynamics CRM 2016

In Dynamics CRM 2016 (on-premises) and Dynamics CRM Online 2016 Microsoft introduced Web API. You can use it across wide variety of programming languages, devices and platforms. The Web API implements the OData version 4.0, an OASIS standard for building and consuming RESTful APIs.

The Dynamics CRM Web API is advance version of OData. We can perform following operations with it:

• Create
• Delete
• Update
• Retrieve
• Retrieve multiple( using Odata Query and fetch)
• Execute Web API functions
• Execute Web API Actions
• Execute Web API Query Functions

In this blog post we will cover how to execute Dynamics CRM Web API Actions.

Web API Actions

Actions represent an operation which may have observable side effects, such as creating or updating records. It may require parameters and may return a value.

There are many system Actions available which you can execute. You can find the list of all available system actions here at Web API Action Reference. We will execute WinOpportunity Action here as an example.

WinOpportunity Action

This Web API action corresponds to the organization service WinOpportunityRequest. It sets the state of an opportunity to Won and create an opportunityclose activity to record the event. It replicates the  same actions when we click on “Close as Won” in an Opportunity.

To execute WinOpportunity Action , you have to pass the following parameters.

• OpportunityClose

The OpportunityClose parameter requires a JSON representation of the opportunityclose entity to create in the operation. This entity must be related to the opportunity issuing the opportunityid. In the JSON this is set using the @odata.bind.

"opportunityid@odata.bind": "[Organization URI]/api/data/v8.0/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"

• Status

The Status parameter must be set. The Won option has a value of 3. You may define custom status options to represent a win, such as Big Win or Small Win, so the value could potentially be different from 3 and you can pass that value in Status parameter.

The following example is the HTTP request and response to call the WinOpportunity action for an opportunity with an opportunityid value of b3828ac8-917a-e511-80d2-00155d2a68d2.

Request:

POST [Organization URI]/api/data/v8.0/WinOpportunity HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
{
"Status": 3,
"OpportunityClose": {
"subject": "Won Opportunity",
"opportunityid@odata.bind": "[Organization URI]/api/data/v8.0/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
}
}

Response:

HTTP/1.1 204 No ContentOData-Version: 4.0

To execute Dynamics CRM Web API Actions use POST in XmlHttpRequest.

As we are going to execute WinOpportunity Action using JavaScript from within Dynamics CRM so we don’t need any authentication but if we are calling Web API outside of Dynamics CRM you have to implement authentication as well.

To execute this action you can use the following code, just replace the id “A033CAE4-E1AC-E511-80D5-2C59E5420648″ on line 32 with “opportunityid” of which you want to change status to won.

Code:

function closeOpportunityAsWon() {
var clientURL = Xrm.Page.context.getClientUrl();
var req = new XMLHttpRequest();

req.open("POST", encodeURI(clientURL+"/api/data/v8.0/WinOpportunity"), true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
if (this.readyState == 4 /* complete */
)
{
req.onreadystatechange = null;
if (this.status == 204) {

//Action Executed Successfully
console.log("Success");
} else {
var error = JSON.parse(this.response).error;
console.log(error.message);
}
}
};
//Parameters

//Replace your organization and opportunityId with your own
var body = JSON.stringify({
"Status" : 3,
"OpportunityClose" : {
"subject" : "Won Opportunity",
"opportunityid@odata.bind" : clientURL+ "/api/data/v8.0/opportunities(A033CAE4-E1AC-E511-80D5-2C59E5420648)" }}); req.send(body); }