Write code for Microsoft Dynamics CRM forms

Applies To: Microsoft Dynamics CRM 2013, Microsoft Dynamics CRM Online

Form programming provides ways to interact with entity forms by using JavaScript that is executed for events that occur on the form.

When to use form programming

Microsoft Dynamics CRM provides many options to control business processes. Form programming is one option. With Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, you have a new option: business rules. Business rules provide a way for someone who does not know JavaScript and is not a developer to apply business process logic in a form. More information: Create and edit business rules

The primary advantage of form programming and business rules is that they are immediate. They do not require data to be submitted to the server and, therefore, provides the best performance for many scenarios. Because they allow for human interaction, they are also the most flexible options.

While business rules have an advantage because they can be created and maintained by someone who is not a developer, they have certain limitations and are not intended to replace form scripts. Form programming allows you to achieve things that cannot yet be done using business rules.

Tasks frequently performed by using form programming include the following:

  • Data validation

  • Automation

  • Process enhancement and enforcement

Whenever possible, you should perform validation of data while the data is being edited. The definition of the Form field will perform the most common data validation for you. For example, a Single Line of Text field formatted for an email address will not allow an invalid value to be entered into it.

Use form programming for additional validation of data that is unique to your organization. For example, your organization may have specific rules about how telephone numbers should be formatted or a minimum length for the Subject field in a service activity.

You can achieve significant productivity enhancements when you use form scripting to automate common tasks. You can set field values that depend on the data that is entered into a form, that will help save users considerable time when entering data. Using form programming for automation is valuable because it lets the user verify that a standard process is valid in a particular case. Users can make necessary adjustments before saving a record.

You can customize the data to display or the layout of the form to optimize the form for specific tasks in your organization’s processes. You can use form programming to show or hide specific form elements, or to open different forms that have been defined for an entity. You can control which fields are required based on data present in the form or in related records.

Factors to Consider When You Use Form Programming

The logic applied in form programming can only be executed in the browser of someone interacting within the Microsoft Dynamics CRM application entity form. Because of this, you should not rely solely on form programming to initiate or enforce processes related to your data. Records can be created or updated directly through the Web service APIs or through workflows outside the context of the form. Form programming should complement business logic applied by using plugins and processes so that all records created or updated in any manner will comply with the same processes.

While form programming provides capabilities to hide form fields so that users may not be able to view or update some entity data, it does not represent a complete solution for enforcing security requirements. A user can see entity data that is not visible on the form by using a variety of methods, such as Advanced Find. More information: The security model of Microsoft Dynamics CRM

Write form scripts that perform well

When you write scripts for forms, use the following practices to help achieve the best performance:

Avoid including unnecessary JavaScript web resource libraries
The more scripts you add to the form, the more time it will take to download them. Usually scripts are cached in your browser after they are loaded the first time, but the performance the first time a form is viewed often creates a significant impression.

For a specific example, don’t include jQuery in your form scripts simply because you want to use XMLHttpRequests. While jQuery has the $.ajax function that many people are familiar with to perform these requests, it is a developer preference, not a necessity. It is possible to perform these requests using the native XMLHttpRequest object found in all browsers supported by Microsoft Dynamics CRM. More information: Use of jQuery

Avoid loading all scripts in the Onload event
If you have code that only supports OnChange events for fields or the OnSave event, make sure to set the script library with the event handler for those events instead of the OnLoad event. This way loading those libraries can be deferred and increase performance when the form loads.

We do not recommend using the addOnChange method within the OnLoad event handler simply as a matter of convenience. While this may reduce the number of steps necessary to add your event handlers, it causes the form to load more slowly.

Use collapsed tabs to defer loading web resources
When web resources or IFRAMES are included in sections inside a collapsed tab, they will not be loaded if the tab is collapsed. They will be loaded when the tab is expanded. When the tab state changes, the TabStateChange event occurs. Any code that is required to support web resources or IFRAMEs within collapsed tabs can use event handlers for the TabStateChange event and reduce code that might otherwise have to occur in the OnLoad event.

Set default visibility options
Avoid using form scripts in the OnLoad event that hide form elements. Instead, set the default visibility options for form elements that might be hidden to not be visible by default when the form loads. Then, use scripts in the OnLoad event to show those form elements you want to display.

Different Form Presentations

There are several different ways that forms are presented. These affect the type of code or available events you can use for each.

Updated entities

All custom entities and certain system entities have an updated user interface that includes using the command bar and new form APIs. The updated system entities are listed in the following table:





Campaign Activity

Campaign Response





Contract Line






Marketing List


Opportunity Product


Phone Call

Price List Item


Quick Campaign


Recurring Appointment

Sales Literature




Some updated entities include composite attributes. These require some special consideration. More information: Write scripts for composite attributes.

Updated entity forms may also include a collaboration control that provides access to Notes, Activities, and Posts if they are enabled for the entity. The Xrm.Page object does not provide access to the collaboration control. You can access the section element that contains the collaboration control if you want to show or hide it by using scripts.

New form programming methods and event

The following table lists the new form programming methods available in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online for updated entities only.


Method Description

Xrm.Page.context. client.getClient

Returns a value to indicate which client the script is executing in.

Xrm.Page.context. client.getClientState

Returns a value to indicate the state of the client.

Xrm.Page.context. getUserName

Returns the name of the current user.

Xrm.Page.data.entity. getPrimaryAttributeValue

Gets a string for the value of the primary attribute of the entity.

Xrm.Page.data. refresh

Asynchronously refreshes the data of the form without reloading the page.

Xrm.Page.data. save

Saves the record asynchronously with the option to set callback functions to be executed after the save operation is completed.

Xrm.Page.data.entity attribute. getIsPartyList

Determines whether a lookup attribute represents a partylist lookup.

Xrm.Page.ui control. clearNotification

Removes a message already displayed for a control.

Xrm.Page.ui control. setNotification

Displays a message near the control to indicate that data is not valid.

Xrm.Page.ui. clearFormNotification

Use this method to remove form level notifications.

Xrm.Page.ui. setFormNotification

Use this method to display form level notifications.

Xrm.Page.ui control. addCustomFilter

Use fetchXml to add additional filters to the results displayed in the lookup. Each filter will be combined with any previously added filters as an ‘AND’ condition.

Xrm.Page.ui control. setShowTime

Specifies whether a date control should show the time portion of the date.

Xrm.Utility. alertDialog

Displays a non-blocking alert dialog with a callback function.

Xrm.Utility. confirmDialog

Displays a non-blocking confirm dialog with different callbacks depending on the button clicked by the user.

The new PreSearch Event occurs just before the search dialog box opens when you set a lookup value. This event does not have user interface to set an event handler in the application; it can only be set using the Xrm.Page.ui control.addPreSearch method. Use this event with the addCustomFilter, addCustomView and setDefaultView methods to control the views opened when people search for a record to set as the value of a lookup field.

Entities that use classic forms

System entities that were not updated use classic form presentation. Forms for these entities continue to use the ribbon if they did in CRM 2011 and do not have access to form APIs added in this release. These entities are listed in the following table:




Article Comment

Bulk Delete Operation

Business Unit



Discount List

Document Location

Email Attachment



Goal Metric

Import Source File

Invoice Product

Order Product

Price List

Queue Item

Quote Product

Rollup Field

Rollup Query

Saved View


Service Activity

SharePoint Site




Unit Group


Only selected system entities and custom entities are available to be shown by using Microsoft Dynamics CRM for tablets. The following system entities may have editable forms in CRM for tablets.











Opportunity Product

Phone Call


Because CRM for tablets does not have the same behaviors as forms in the web application, some APIs are not available. For example, in CRM for tablets tabs cannot be expanded or collapsed, so the Tab TabStateChange Event does not occur and the Xrm.Page.ui tab.setDisplayState cannot be used to expand or collapse tabs.

Development tools

Because JavaScript is an interpreted language special development tools are not required. JavaScript is just text so it can be edited in the application or in a text editor such as Notepad. However, you can achieve significant productivity gains when you use an integrated development environment (IDE) that provides features to support editing JavaScript files, such as Microsoft Visual Studio and Microsoft Visual Studio Express.

See Also

Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2014 Microsoft Corporation. All rights reserved.