Use the OData endpoint with Ajax and JScript web resources

The OData endpoint lets you interact with Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update data by using JavaScript libraries. You create script web resources using files defining the JavaScript libraries. Then you associate functions in the libraries with form or field event handlers or ribbon command actions. You can use them as you would any other JavaScript library within webpage (HTML) web resources.

AJAX (Asynchronous JavaScript and XML) is a web development technique used to create interactive web applications. Server requests are made from the browser in the background using an XmlHttpRequest object. Although you can send synchronous requests, the recommended practice is to send asynchronous requests. Asynchronous requests require two JScript functions, one to send the request and a second “callback” function to process a response.

The JavaScript Object Notation (JSON) format is used for serializing and transmitting structured data much in the same way that XML is typically used. Like XML, it’is text based and designed to be readable by humans. To convert regular JavaScript objects into the JSON format you use the JSON.stringify method. Because the text in JSON defines JavaScript objects, the text could be converted to JavaScript objects by using the eval method. However, this practice creates security vulnerabilities. You should use the JSON.parse method instead.

XmlHttpRequest (sometimes referred to as XHR) provides capabilities to configure and send requests and define a callback function if the request is asynchronous. The HTTP response from the server includes a status code indicating whether the request was successful. HTTP status code values in the 200 range are considered successful.

An XmlHttpRequest provides instructions to the server about the format of any data to be included in the response. Because the ODATA endpoint supports both ATOM and JSON formats, you have the option to request data to be returned in the XML ATOM format. However, with JavaScript code the expected typical request will use JSON because it’s easily consumable using JavaScript.

The OData protocol uses less common HTTP verbs PUT and DELETE as well as defining a new verb: MERGE. Depending on the supporting libraries you use, you may encounter issues while using these verbs. The way to work around this is to use the POST verb and specify an X-HTTP-Method HTTP header with the desired action. Use the setRequestHeader method to override the action specified in the XmlHttpRequest.

The first thing to do when you start to use the ODATA endpoint with JavaScript is establish the URL to the organization root URL. Use the d7d0b052-abca-4f81-9b86-0b9dc5e62a66#BKMK_getclienturl function from the context object.

If your script is designed to operate in the context of a form or field event, or a <JavaScriptFunction> (RibbonDiffXml) for a ribbon command, you can use the Xrm.Page.context object to call d7d0b052-abca-4f81-9b86-0b9dc5e62a66#BKMK_getclienturl.

If your script executes in the context of a webpage (HTML) web resource you must include a reference to the af74d417-1359-4eaa-9f87-5b33a8852e83#BKMK_ClientGlobalContext_js_aspx page in the HTML web resource so that you can then use the af74d417-1359-4eaa-9f87-5b33a8852e83#BKMK_GetGlobalContext.

jQuery is a great library with a variety of uses, but using jQuery is not a prerequisite for performing operations using the ODATA endpoint for Microsoft Dynamics CRM. We recommend you don’t use jQuery in form scripts or command scripts that run in application pages but use the XmlHttpRequest directly and avoid having to load the jQuery library. jQuery $.ajax uses the XmlHttpRequest available in the browser. Using this object directly is slightly different from using $.ajax. If you’re already familiar with using XMLHttpRequest you should continue to use it. If you have always used jQuery, consider using XMLHttpRequest directly. More information: XMLHttpRequest Object

With XmlHttpRequest, you create an event handler for the onreadystatechange event and detect when the request has completed. In the event handler, check the status code returned to determine whether the request succeeded. Finally, use the open and send methods. The following sample uses XmlHttpRequest to create a new account record.

jQuery is a popular JavaScript library that is included with web application projects in Microsoft Visual Studio. jQuery provides an extensive framework of objects and functions that let you query and work with HTML pages using JavaScript. To use XMLHttpRequest, jQuery provides the jQuery.ajax method.

Note

We don’t recommend using jQuery with form scripts or commands. More information: b7840a25-f25e-409b-8b6a-0ef04c7ed9c4#BKMK_UsingjQuery.

The jQuery object is referenced using the $ character so the short form for jQuery.ajax is $.ajax. The ajax method is typically used with an imperative syntax and the request is sent as soon as the object is instantiated. The following sample creates a new account record.

When you’re expecting results in a JSON format, just setting the dataType property might not work. You can use the beforeSend property to explicitly set the headers on the XMLHttpRequest to return data as JSON. This is typically performed by using an anonymous function as shown in the following example.

As described in Method tunneling through POST, when you perform an action that requires an HTTP action other than POST or GET, use POST and the beforeSend property to explicitly set the headers on the XMLHttpRequest to perform a different action. This is typically performed by using an anonymous function, as shown in the following example.

When you perform POST or GET operations you can expect that data will be returned. If you have specified that results be returned in the JSON format, the results will be in the d property of the data object returned. When you create or retrieve a record using the unique identifier, d will represent the data for the record. In every other case d will be an array.

The following sample shows processing the results of a query that returns multiple account records.

When you retrieve records using the ODATA endpoint, date values are returned as strings that use the format “\/Date(<ticks>)\/” where <ticks> is the number of milliseconds since midnight January 1, 1970. For example: "\/Date(1311170400000)\/". All values returned from Microsoft Dynamics CRM represent the Coordinated Universal Time (UTC) values so no offset information is included.

There are two strategies you can use to parse dates in records returned using the ODATA endpoint:

The JSON.parse method supports an optional reviver argument as described in the JSON.parse method documentation on MSDN. The following is an example that converts the string values that match a pattern defined in a regular expression into Date objects.

After the string date values are converted to Date objects, you can use a variety of JavaScript methods, or create your own, to display the date as a string in a user interface. Because the JavaScript Date object is UTC aware, the dates displayed in your user interface using methods such as toString or toLocaleString will reflect the time zone settings of the user’s operating system.

However, notice that the values in your application might be different from the same values displayed in Microsoft Dynamics CRM, which doesn’t rely on the user’s operating system time zone settings. These values will be different when the user’s current operating system time zone preference doesn’t match the time zone preference saved in Microsoft Dynamics CRM. Microsoft Dynamics CRM also allows for setting personalized presentation options that won’t be applied by using standard JavaScript date functions like toString.

If you want to reconcile the displayed date and time values to match the values shown in Microsoft Dynamics CRM, you can query data stored in the UserSettings entity and entities like TimeZoneDefinition and TimeZoneRule to create functions to display dates that match the user’s preference. Microsoft Dynamics CRM doesn’t provide functions to perform these actions.

When you change the values of a JavaScript date using standard set methods such as setMinutes or setHours, these changes are in the user’s local time. When you save the record, the actual UTC values are serialized and saved back to Microsoft Dynamics CRM. You don’t have to do anything to convert the dates to a UTC value.

When a Date is serialized, the format differs from the format that was used when the data is retrieved. As noted in Parse retrieved data, dates are retrieved as strings that use the format "\/Date(1311179400000)\/". When you examine the results of JSON.stringify for date values to be passed back to the server, the format is "2013-07-20T16:30:00Z".

When you use a date value with a $filter system query option, you must use a UTC date. To convert a JavaScript Date object into the format expected for a filter, you have to process the date using a function such as the following example. The result is a string that matches the following format: datetime'2010-09-28T18:21:46:594Z' .