Use JavaScript with Microsoft Dynamics CRM 2011


Applies To: Dynamics CRM 2011

Microsoft Dynamics CRM 2011 provide many opportunities to use JavaScript. This topic has information for developers who use JavaScript and includes links to relevant topics in the Microsoft Dynamics CRM SDK and other sources.

In This Topic

Areas Where You Can Use JavaScript in Microsoft Dynamics CRM

Write JavaScript for Multiple Browsers

Data Access Using JavaScript

JavaScript Programming Best Practices

Debugging JavaScript in Microsoft Dynamics CRM

Areas Where You Can Use JavaScript in Microsoft Dynamics CRM

You can use JavaScript to perform actions in form scripts, ribbon commands, and web resources.

Form Scripts

The most common use of JavaScript in Microsoft Dynamics CRM is to add functions as event handlers for entity form events. For more information, see Write Code for Microsoft Dynamics CRM 2011 Forms.

Ribbon Commands

When you customize the Microsoft Dynamics CRM ribbon, you can configure commands for controls that you add. These commands contain rules that control whether the control is enabled and what action is performed when the control is used. For more information, see Customize the Ribbon.

Web Resources

Microsoft Dynamics CRM provides an organization-owned entity that stores a binary representation of a file that can be accessed by using a URL. This file is called a web resource. There are several types of web resources. A web resource that represents a JavaScript library is called a JScript web resource. You can use a webpage (HTML) web resource to provide a user interface with JavaScript libraries included just as you would for files on a web server. Because these files are part of Microsoft Dynamics CRM, users who access them are already authenticated. Therefore, you can use Microsoft Dynamics CRM web services without having to write code to authenticate the user. For more information, see Web Resources for Microsoft Dynamics CRM 2011.

Write JavaScript for Multiple Browsers

Before Microsoft Dynamics CRM 2011 Update Rollup 12 and the Microsoft Dynamics CRM December 2012 Service Update developers writing scripts for Microsoft Dynamics CRM only needed to consider how their scripts worked using Internet Explorer. With the support for multiple browsers included in Update Rollup 12 and the December 2012 Service Update script developers should make sure that any scripts that they use will work with all supported browsers. Most of the significant differences between Internet Explorer and other browser have to do with HTML and XML DOM manipulation. Because HTML DOM manipulation is not supported, if script logic is only performing supported actions and using the Xrm.Page API the changes required to support other browsers could be small. Use the Custom Code Validation Tool to identify code that only works for Internet Explorer.

A cross-browser library like jQuery is a good solution for developing web resources but may not be necessary for form scripts or ribbon commands. For more information, see JavaScript Programming Best Practices.

Support for other Browsers

Because Update Rollup 12 and the December 2012 Service Update supports W3C standards, the application will be accessible using any modern browser and from any platform that supports those standards. However Microsoft Dynamics CRM will only be tested using a specific set of browsers and platforms. For the list of supported platforms and browsers see Microsoft Dynamics CRM 2011 web application and mobile device requirements

If you use a browser, or browser version, that is not supported and you type just the server name or server name with organization as the URL, you will be redirected to the Mobile Express for Microsoft Dynamics CRM page. The Mobile Express pages can be expected to work properly on most browsers, such as browsers used in mobile devices, with limited functionality.

HTC Support for Internet Explorer in CRM Forms

Update Rollup 12 and the December 2012 Service Update support additional browsers by generating HTML that supports W3C standards. This requires removing dependencies on HTML components (HTC) that are specific to Internet Explorer.

The crmForm API that was used to access form elements in Microsoft Dynamics CRM 4.0 will continue to provide backward compatibility only for Internet Explorer. If you have code that uses the crmForm API, or any unsupported internal methods that interact with form objects that used HTC components, you must select to Include HTC support in CRM Forms on the Customization tab of System Settings. Using this setting will not allow newer versions of Internet Explorer to provide the best performance possible. Internet Explorer 10 does not support HTC components. The option to continue support for HTC will be removed in the next major release of Microsoft Dynamics CRM. At that time the crmForm API will no longer be supported. Before that time you should upgrade your form scripts to use Xrm.Page. For more information, see Upgrade Scripts to Microsoft Dynamics CRM 2011.

For all Microsoft Dynamics CRM Online organizations, the default value for HTC support is ‘off’. If you have an existing script that requires HTC support or if you install a new solution that depends on HTC support you must change this setting to ‘on’.

For all on-premises deployments, the default value for HTC support is ‘on’. If you have no scripts that depend on HTC support you can change this setting to ‘off’ and enjoy better performance when using Internet Explorer.

Specify Whether to Use Internet Explorer Compatibility View

For Update Rollup 12 and the December 2012 Service Update, you have the option to set which document mode your pages load in when using Internet Explorer. By default, web pages on an intranet will load using Compatiblity View. This means that unless the page or web site includes some additional configuration the page will be rendered using only those features that were supported by Internet Explorer 7, even if you are using a more recent version of Internet Explorer. By default with Update Rollup 12 and Microsoft Dynamics CRM 2011 pages are configured to overcome this default behavior and use the latest capabilities of Internet Explorer. This allows for the best possible performance and support for recent Internet Explorer capabilities, such as support for HTML5 capabilities.

However, if you have scripts that depend on Internet Explorer features no longer supported by more recent versions of Internet Explorer, your script can break. To immediately overcome these issues you can change the setting to clear the Always load all pages in the most recent version of Internet Explorer option in the Customization tab of System Settings. You should update any scripts that depend on legacy Internet Explorer features to use newer capabilities that replace them.

Some examples of Internet Explorer features no longer supported by Internet Explorer 10 include XML data islands and Element behaviors and HTCs

For more information, see Investigating Document Mode Issues, Defining Document Compatibility, Windows Internet Explorer 9 Compatibility Cookbook and Internet Explorer 10 Compatibility Cookbook.

Control Browser Support for Your Organization or Solution

Although creating public websites requires that you support most modern browsers, few public websites support all browsers that have ever existed. You need to establish what browsers you will support. To save development and testing costs, many business applications require that users use specific browsers.

If you are an ISV preparing solutions for any organization using Microsoft Dynamics CRM, you should expect that any organization could use one of the browsers that Microsoft Dynamics CRM 2011 will support. However, if you are preparing customizations only for an organization that requires that people use a specific browser, there is no reason to develop and test your customizations for browsers the organization doesn’t support.

Network administrators may use Software Restriction Policies and/or AppLocker to enforce which applications are allowed to run or be installed on a domain.

Technical Article: Control Which Browsers Your Organization Supports provides an approach that a developer can modify to enforce browser policy options for just the Microsoft Dynamics CRM application.

XMLHttpRequest Status Values

Internet Explorer sometimes uses a different XMLHttpRequest status value that is used in onreadystatechange event handlers. When applying an UPDATE or DELETE action, Internet Explorer may return a status value of 1223 rather than the expected value of 204. To compensate for this, you should check for both as shown in the following code sample:

if (this.readyState == 4 /* complete */) {
    this.onreadystatechange = null; //avoids memory leaks
    if (this.status == 204 || this.status == 1223) {
    else {

The SDK.REST.js library and other libraries in the SDK samples check for both possible status values using this technique. For more information about these libraries, see Sample: Create, Retrieve, Update and Delete Using the REST Endpoint with JavaScript and Sample: Retrieve Entity Metadata Using JavaScript.

Parsing XML

There are many opportunities where you will need to parse XML using JavaScript. Be aware that there are significant differences in the way you can parse XML using Internet Explorer and other browsers. Internet Explorer uses Microsoft XML Core Services (MSXML) APIs to interact with XML document objects. These APIs include a number of extensions to the W3C DOM that are not available to other browsers. Following are two examples:

  • Two common methods used to extract data from an XML document using Internet Explorer are selectNodes and selectSingleNode. Both of these methods use an XPath expression as the parameter and return either a node or a node list. For other browsers, use the evaluate method when you want to use an XPath expression. Alternatively, you can refactor your code to navigate the document hierarchy and use the getElementsByTagNameNS method.

  • Internet Explorer uses the text property to access the text of an element. Other browsers use the textContent property.

There are a number of different ways you can address these differences. The approach you use depends on your preferences and the requirements of your code.

The SDK.MetaData.js library found in Sample: Retrieve Entity Metadata Using JavaScript uses helper functions. This library uses the SOAP endpoint for web resources to retrieve entity and attribute metadata. This library depends on parsing data from the XML document returned as XMLHttpRequest.responseXML. In this library the following helper functions were added and used throughout the other functions in the library.

With these helper functions the existing code that was written only for Internet Explorer was updated as shown:

Original Internet Explorer Only Code

New Function to Support Multiple Browsers




SDK.MetaData._selectSingleNode(node, XPathExpr);


SDK.MetaData._selectSingleNodeText(node, ElementName);



Data Access Using JavaScript

There are two web services you can use to access data by using JavaScript.


It is not supported for an external application to use these web services because authentication is provided by the Microsoft Dynamics CRM application.

REST Endpoint for Web Resources

You can use the REST endpoint to execute HTTP requests by using a web service that is based on a Uniform Resource Identifier (URI). “RESTful” web services are popular because they can make programming easier.

The current implementation of the REST endpoint is limited to create, retrieve, update and delete operations. The Sample: Create, Retrieve, Update and Delete Using the REST Endpoint with JavaScript includes an SDK.REST.js library that provides an example of a reusable library that can further simplify using the REST endpoint.

One of the advantages of the REST endpoint is that it implements the OData protocol, which provides the way to query and update data. When you use JavaScript, you usually retrieve objects in JavaScript Object Notation (JSON) format. This makes the results easier to work with. The primary limitation of the REST endpoint is that you cannot use the IOrganizationService.Execute method to execute messages (Request and Response classes). You use the SOAP endpoint for web resources to execute messages.

For more information, see Use the REST Endpoint for Web Resources.

SOAP Endpoint for Web Resources

The SOAP endpoint lets you execute messages because the REST endpoint does not yet allow this. You can also call the Create, Retrieve, Update, Delete and RetrieveMultiple methods of this web service, but using it is not as easy as using the REST endpoint.

Microsoft Dynamics CRM does not provide a JavaScript library to facilitate using the SOAP endpoint. When using the SOAP endpoint, you must post http requests that contain the XML defining the request and then parse the XML returned in the response.

The SDK provides a Microsoft Visual C# solution called SoapLogger that lets you capture the XML sent and received when you perform operations with the Microsoft Dynamics CRM web services by using Visual C#. With this information, you can build your own JavaScript libraries. Microsoft CRM MVP Jamie Miley has released a CRM 2011 Jscript Soap Request Formatter program on CodePlex that takes this a step further and actually generates JavaScript libraries for you.

The SDK includes an example that shows how to retrieve entity and attribute metadata. For more information, see Sample: Retrieve Entity Metadata Using JavaScript. The SDK.MetaData.js library in that sample can be used when you want to retrieve entity or attribute metadata.

For more information, see Use the SOAP Endpoint for Web Resources.

JavaScript Programming Best Practices

The following sections describe best practices when you use JavaScript with Microsoft Dynamics CRM.

Avoid Using Unsupported Methods

On the Internet, you can find many examples or suggestions that describe using unsupported methods. These may include leveraging undocumented internal function for page controls. These methods may work but because they are not supported you can’t expect that they will continue to work in future versions of Microsoft Dynamics CRM. This is especially true with Update Rollup 12 and the December 2012 Service Update because of significant changes to the internal application functions to support browsers other than Internet Explorer. For more information, see this blog post: Resolve Breaking Script Issues When Upgrading Microsoft Dynamics CRM.

Use the Custom Code Validation Tool to identify code that is using unsupported methods.

Use a Cross-browser JavaScript Library for HTML Web Resource User Interfaces

A cross-browser JavaScript library, such as jQuery, provides many advantages when developing HTML web resources that must support multiple browsers. JavaScript libraries like jQuery provide a unified development experience for all browsers supported by Microsoft Dynamics CRM. These capabilities are most appropriate when you are using HTML web resources to provide user interfaces. JavaScript libraries like jQuery provide consistent ways to interact with the Document Object Model (DOM).

Do Not Create Unnecessary Dependencies on JavaScript Libraries

JavaScript libraries like jQuery are typically not required when you write functions that will be used as form event handlers. The Xrm.Page object model provides functions to perform all supported interactions with Microsoft Dynamics CRM entity forms. Libraries, such as jQuery, often provide capabilities to perform XMLHttpRequests using functions like $.ajax. However, you can perform XMLHttpRequests, with little additional code, in all supported browsers using the native XMHHttpRequest object provided by the browser. For example, compare the sample_/Scripts/SDK.JQuery.js and sample_/Scripts/SDK.REST.js libraries used in SDK samples. These libraries perform the same actions for all browsers, except that SDK.REST.js does not have a dependency on jQuery.

Recognize Limitations for Content Delivery Network (CDN) Libraries

Content delivery network (CDN) JavaScript libraries provide many advantages for public websites. Because these libraries are hosted on the Internet, you do not need to create web resources that contain the content of the libraries. For Microsoft Dynamics CRM you should consider the following issues before you use a CDN JavaScript library.

  • Users of the Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access client have the capability to work with no Internet connection while working offline. If you are depending on an Internet connection for your JavaScript libraries, your code will fail.

  • Some organizations will restrict Internet access for employees. Unless they configure the network to allow access to the CDN library sites, your code may fail for those organizations.

The alternative to using CDN libraries is to create a script (JavaScript) web resource with the contents of the library. Because web resources are organization-owned entities they will be synchronized when a Microsoft Dynamics CRM for Outlook with Offline Access user goes offline. Because these web resources now become part of the application they will not be blocked if an organization restricts access to the Internet.

Use Feature Detection When Writing Functions for Multiple Browsers

Even when you use a cross-browser library like jQuery, you need to be very aware of differences between browsers. You can generally detect which browser is being used by querying the navigator.useragent property. This is called browser detection. Browser detection is not a good strategy for most cases because it can’t take into account what features newer versions of a browser have. Also, some browsers provide the capability to modify the navigation.useragent property so that they appear to be a different browser.

Feature detection is the recommended approach. By detecting what features are available, you can create code paths for the browsers you support without knowing exactly which browser is being used. For more information about feature detection, see How to Detect Features Instead of Browsers.

Do Not Access the DOM

JavaScript developers are used to interacting with Document Object Model (DOM) elements in code. You might use the window.getElementById method or the jQuery library. You are free to use these techniques in your HTML web resources, but they are not supported to access elements in Microsoft Dynamics CRM application pages or entity forms. Instead, access to entity form elements are exposed through the Xrm.Page object model. The Microsoft Dynamics CRM development team reserves the right to change how pages are composed, including the ID values for elements, so using the Xrm.Page object model protects your code from changes in how pages are implemented. For more information, see Use the Xrm.Page Object Model.

Define Unique Names for Your JavaScript Functions

When you are the only developer for an HTML page you can easily manage the names of the JavaScript functions you use. In Microsoft Dynamics CRM, other solutions may add JavaScript functions to the page where your function is used.

If two JavaScript functions on a page have the same name, the first function defined is overwritten by the second. For this reason, make sure that you define unique names for your JavaScript functions. For more information, see Creating Script Libraries.

Use Asynchronous Data Access Methods

When you access data by using the Microsoft Dynamics CRM web services that use the REST or SOAP endpoint for web resources, always use an XMLHttpRequest that is configured to execute asynchronously. The reason is that the browser operates on a single thread. If that thread is being used to execute a long-running process synchronously the browser will stop responding.

Debugging JavaScript in Microsoft Dynamics CRM

Each browser provides some kind of debugging extension. Internet Explorer provides developer tools you can use to debug scripts in Microsoft Dynamics CRM. The Internet Explorer developer tools can be opened by pressing F12 when viewing a page using Internet Explorer. For more information, see How-to series: Easily debug your CRM JavaScript code in IE8 and Debugging Script with Developer Tools.

For Google Chrome, press F12 to open developer tools. Firebug is a popular browser extension for web development using Mozilla Firefox. For Apple Safari, you must first choose the Show Develop menu in menu bar in Advanced Preferences. Then you can choose Show Web Inspector from the Develop menu.

You can also use Microsoft Visual Studio. For more information, see How to Debug JScript in Microsoft Dynamics CRM 2011.

When you use JavaScript libraries in Microsoft Dynamics CRM, your libraries are added to a page that includes many libraries. It can sometimes be difficult to isolate your specific library in the debugging environment. The Xrm.Page script library template solution provides a way to develop and test form scripts in Microsoft Visual Studio without creating JScript web resources in Microsoft Dynamics CRM. For preliminary development and testing, the experience debugging JavaScript in the Xrm.Page script library template solution is useful to simplify the environment to debug scripts. For more information, see Use the Xrm.Page Script Library Template.

See Also

Write Applications and Server Extensions
Write Code for Microsoft Dynamics CRM 2011 Forms
Customize the Ribbon
Web Resources for Microsoft Dynamics CRM 2011
Use the REST Endpoint for Web Resources
Use the SOAP Endpoint for Web Resources
Use the Xrm.Page Object Model

Microsoft Dynamics CRM 2011

© Microsoft Corporation. All rights reserved. Copyright