How to Use the Dynamics 365 Xrm.WebApi

In Dynamics 365 9.x, there are new Xrm.WebApi JavaScript methods available to call the Dynamics 365 Web APIs. These new methods are very useful in that the plumbing for making these calls is taken care of, so as a developer you can easily create, retrieve, update and delete etc in a few lines of code.

Here we will go through examples of how to use the API.

Create

To create a new record, you use WebApi.createRecord.

Xrm.WebApi.createRecord(entityLogicalName, data).then(successCallback, errorCallback);

Provide the entity name, and in a JSON object called data provide the fields you would like to set on the record:

[sourcecode language=”JavaScript”] var ContactId;
var data = {
"firstname": "Bob",
"lastname": "Smith"
}

parent.Xrm.WebApi.createRecord("contact", data).then(
function success(result) {
ContactId = result.id;
alert("Success. Id: " + ContactId);
},
function(error) {
alert("Error: " + error.message);
}
);

[/sourcecode]

In my test environment, I have this code running from a button in a web resource.

Running this, we can see the new Id of the record is created:

And the new record is created in Dynamics 365:

RetrieveMultiple

Using the WebApi, we can access records directly in a browser through a URL. For example, to retrieve the first and last name of all people with lastname=”Smith”, we can do:

https://yourorg.crm.dynamics.com/api/data/v9.0/leads?$select=firstname,lastname&$filter=lastname eq 'Smith'

Running this in a browser, we see:

Now let’s say we want to use the Xrm.WebApi to get the same results using RetrieveMultiple.

Syntax:

Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);

Below is the code, see we add the fields we want to select and the filter as the second parameter, i.e. select=firstname,lastname&$filter=lastname eq ‘Smith’. Note we are just printing out the first result in our for loop, just for the demo:

[sourcecode language=”JavaScript”] parent.Xrm.WebApi.retrieveMultipleRecords("contact", "?$select=firstname,lastname&$filter=lastname eq ‘Smith’").then(
function success(result) {
for (var i = 0; i < result.entities.length; i++) {
alert(result.entities[i].firstname);
break; // just for code demo
}
},
function(error) {
alert("Error: " + error.message);
}
);
}
[/sourcecode]

Running this, we see:

Retrieve

What if we want to do a single Retrieve?

Syntax:

Xrm.WebApi.retrieveRecord(entityLogicalName, id, options).then(successCallback, errorCallback);

Let’s grab the Id of a Contact record using Email a Link, for example: 25A17064-1AE7-E611-80F4-E0071B661F02. The code:

[sourcecode language=”JavaScript”] parent.Xrm.WebApi.retrieveRecord("contact", "25A17064-1AE7-E611-80F4-E0071B661F02", "?$select=lastname").then(
function success(result) {
alert("Retrieved values: Last Name: " + result.lastname);
},
function (error) {
alert(error.message);
}
);
}

[/sourcecode]

Running this, we get:

Update

If we want to update a record, use the syntax:

Xrm.WebApi.updateRecord(entityLogicalName, id, data).then(successCallback, errorCallback);

Example:

[sourcecode language=”JavaScript”] var data =
{
"lastname": "Smith"
}
// update the record
parent.Xrm.WebApi.updateRecord("contact", "25A17064-1AE7-E611-80F4-E0071B661F02", data).then(
function success(result) {
alert("Updated");
},
function (error) {
console.log(error.message);
}
);
[/sourcecode]

Running this:

Delete

To delete a record using the WebApi, use the syntax:

Xrm.WebApi.deleteRecord(entityLogicalName, id).then(successCallback, errorCallback);

Example:

[sourcecode] parent.Xrm.WebApi.deleteRecord("contact", "25A17064-1AE7-E611-80F4-E0071B661F02").then(
function success(result) {
alert("Deleted");
},
function (error) {
alert(error.message);
}
);
[/sourcecode]

This will delete the record.