Dynamics 365 Web API: Query data with examples (Javascript)

When it comes to retrieving data client-side using Javascript the Dynamics 365 Web API is the best way to do this. In this post I’m going to share a reusable Javascript function I’ve written that makes using the Web API and retrieving data a breeze.

I’ll also step through an example based on the lead form and the existing contact field. Click here to jump straight to the example.

About the Dynamics 365 Web API

The Dynamics 365 Web API is a HTTP REST API which provides CRUD (Create, Read, Update and Delete) access to Dynamics (amongst other things). Because it’s built on open standards it can be used across a wide variety of programming languages and platforms. In this post I’ll be showing you how to use it to retrieve data in real-time and then use that data to populate fields on a form.

To get your Dynamics 365 Web API URL, head to:

1. Settings | Customizations | Developer Resources
2. It will be the first URL on the left:

I’ve included some useful links at the end of this post if you would like to read more about the Web API’s capabilities.

How to Retrieve Data using the Web API

I’ve written the reusable functions below to make retrieving data via the Web API a sinch. Simply copy and paste it into a new JScript web resource and then include the web resource on the Dynamics 365 form you wish to call it from.

Note: when including it on a form, ensure it’s positioned before the calling script within the Form Properties window.

The retrieveWebAPIData is the function to call to query data and accepts the following variables:

• sEntityName = a string containing the name of the entity being queried
• sColumns= a comma-separated string containing the fields to be retrieved
• sFilter = an optional string containing the query filter (where clause)
• sOrderBy = an optional string containing the query sort order

The other function (dateReviver) is used to revive (properly format) any dates passed back in the JSON response.

The following code snippet is a sample on how to use it (note there’s a full example of this code below). In the sample I pull fields from the contact entity using a contact ID as a filter:

WebAPI Query Gotchas

In regards to putting together the Web API query there’s a couple of things to keep in mind:

1. The entity name (sEntityName variable) is the schema name of the entity. For example, Lead is leads. It’s usually plural and lower case, but it’s always good to check from the customization area if you are unsure:

2. The fields names that the select statement (sSelect variable) uses is actually the field name as per the customization area (usually all lowercase) e.g. the Lead’s Description field is “description”:

3. Lookup fields within the select statement (sSelect variable) must be prefixed with an underscore and suffixed with “_value”. For example, the Customer ID field (customerid) on the Lead entity would be: _customerid_value
4. When dealing with record IDs (GUIDs) within the where clause (sFilter variable) be sure to strip the brackets “{” and “}” from the value otherwise it will fail with the following error:

A binary operator with incompatible types was detected. Found operand types ‘Edm.Guid‘ and ‘Edm.String’ for operator kind ‘Equal’.”,”innererror“:{“message“:”A binary operator with incompatible types was detected. Found operand types ‘Edm.Guid‘ and ‘Edm.String’ for operator kind ‘Equal’.”,”type”:”Microsoft.OData.ODataException”

How to use it (with example)

For the example below I’ll use the Dynamics 365 Web API on the Lead form to retrieve contact data and populate the following contact related fields on the lead when the Existing Contact field is populated:

• Name (Full name)
• Business Phone
• Mobile Phone
• Job Title
• Email
• Address 1 (composite field)

Here’s what it will look like once the Existing Contact is selected from the Process:

1. Firstly copy and paste the 2 functions in the code sample above into a new web resource (JScript) called “Retrieve Data” and publish it:

• Name = RetrieveData
• Display Name = Retrieve Data
• Type = Script (JScript)

2. Copy and paste the following script into a new web resource (JScript) which we will call Lead and publish it:

• Name = Lead
• Display Name = Lead Script
• Type = Script (JScript)

3. Add both scripts to the Lead form and ensure the RetrieveData script is above the Lead script:

• From the lead form in edit mode, select Form Properties
• Click the + Add button within the Form Libraries section
• Search for the RetrieveData script and click Add
• Click the +Add  button within the Form Libraries section
• Search for the Lead script and click Add
• Click ok

4. If the “Parent Contact for lead” field is not on the form, drag it onto any section
5. Select it and click Change Properties
6. Uncheck Visible by default. Since the field is going to be used from the Process we don’t need to see it on the form. However, we do need it on there so we can add an OnChange event.
7. Select the Events tab
8. Click +Add
9. In the library drop down select the Lead script and enter the following text for the function: setExistingContact

10. Click Ok
11. Click Ok on the Field Properties window
12. Click Save
13. Click Publish

That’s it. Head to the lead form to test your change.

Note that you may need to clear your browser cache to get the latest script changes.

Any questions or issues, please leave a comment below.

Useful Links

• Getting Started:
  • https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/use-microsoft-dynamics-365-web-api
• Dynamics 365 Basic Web API Samples:
  • https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/webapi/web-api-basic-operations-sample
• Web API Operations:
  • https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/webapi/perform-operations-web-api