The Microsoft Dynamics CRM Blog
News and views from the Microsoft Dynamics CRM Team

Resolve Breaking Script Issues When Upgrading Microsoft Dynamics CRM

Resolve Breaking Script Issues When Upgrading Microsoft Dynamics CRM

  • Comments 0

We want you to have a great experience when you upgrade to Microsoft Dynamics CRM. A future update rollup for Microsoft Dynamics CRM on-premises and service update for Microsoft Dynamics CRM Online  will include significant changes in the web application in order to be able to support a variety of browsers.

This change will expand the number of users and organizations that will use Microsoft Dynamics CRM.  This represents an opportunity for everyone who provides solutions that work with Microsoft Dynamics CRM. With this opportunity is the responsibility to ensure that those solutions will continue to work after organizations using them are upgraded. To help everyone be successful, we want to provide you with advance notice about potential client script issues that we have identified in our research and guidelines to resolve
those issues.

Microsoft Dynamics CRM provides a Client Scripting API to extend the web user interface using EcmaScript/JavaScript. Along with this, we provide code samples and documented best practices to simplify development and facilitate future upgrades. When using JavaScript code in Dynamics CRM, it is possible to use unsupported methods that will stop working or cause an error when you upgrade. Your best defense against such situations is to always use the supported APIs as documented in the Software Development Kit for Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online.

However, we also appreciate that you have business requirements that have to be met and staying within the boundaries of what is supported sometimes requires that you use unsupported methods. Sometimes these methods will work and continue to work across service releases and upgrades, but there is no guarantee.  The risk you take when doing this is that your code may have dependencies on the underlying structure of the page or internal methods that were not intended for everyone to use. The structure of the page can change with an upgrade without notice. 

With the extended support for browsers we made a lot of changes internally but we took care to make sure all the supported APIs continue to work. Some unsupported code that has worked up until now will break during this upgrade. If you have code that was provided by a partner or as part of a solution you purchased, now is a good time to start checking with them to see if they have tested it to verify it works correctly with these changes.  If you have code that you have applied to your organization, it is a good time to review your code and identify whether any unsupported methods have been used.

The best way to determine whether a problem exists is to test your code using the beta release. The beta release is primarily for developers and partners, but anyone can download the software. See this blog post for details.

Anticipating the need to review existing code, we recently conducted some research on JScript libraries that some of our Microsoft Online customers are using and identified some code that we know will generate errors or simply not work. The Microsoft Dynamics CRM 2011 Custom Code Validation Tool can help you identify problem areas. The following items represent the types of issues the custom code validation tool will detect.. This list is not exhaustive; it simply provides some examples of the most common types of things that can break.

Examples:

getElementById

As the name suggests this DOM function is used to access an element of the page and it is used very often by most web developers. However, because the Xrm.Page object model provides the supported way to access form elements, any use of the getElementById function should be examined carefully.

It is fine to use getElementById to access elements in HTML web resources. But if this method is used to access Microsoft CRM application elements, there is no guarantee that the Id attribute value will be the same. When it changes, code that depends on this method to access the Microsoft CRM application elements will be broken. The way to avoid this is to use the Xrm.Page API.

Issues with crmForm

Before Microsoft Dynamics CRM 2011 developers creating form scripts used the crmForm API to access form properties. With Microsoft Dynamics CRM 2011 the crmForm API was deprecated. This means it still works for backward compatibility, but we don’t recommend any new code be written using it. For this next release crmForm remains backward compatible, but only for Internet Explorer.

To support other browsers you must upgrade your code to use the new Xrm.Page API. For information about how to upgrade your code see the Microsoft CRM SDK topic Upgrade Scripts to Microsoft Dynamics CRM 2011.

There are also third party tools you can use to upgrade your scripts. For example, Dynamics XRM Tools includes a CRM4 to CRM 2011 JavaScript Converter.

There are other issues related to crmForm where people used undocumented crmForm properties. The following are code issues we have discovered will break even if you are using Internet Explorer:

crmForm.SetFieldReqLevel

This is the most common example of code that will stop working with this next release. This internal method could be used to make a field required in Microsoft Dynamics CRM 4.0. The fix is to use the setRequiredLevel method with the Xrm.Page object model.

crmForm.SubmitCrmForm

This internal method managed saving records in CRM 4.0. The supported method to use is Xrm.Page.data.entity.save. If you want to manage how individual attributes are saved you can use the setSubmitMode method of the attribute object.

crmForm.detachCloseAlert

People used this internal method to suppress the save changes message when closing a form where the data was changed but not saved. The getDirty method can be used at both the Xrm.Page.data.entity level or by querying each attribute. The only supported way to suppress the save changes message is to use the attribute.setSubmitMode method to set the submit mode to ‘never’ for each attribute that is ‘dirty’.

crmForm.IsValid

This internal method was used to check whether all the required fields contained data. This method is no longer in the application. The fix is to use supported methods to achieve the same functionality. For example:

   
  var requiredAttributesWithNullValues = [];
   Xrm.Page.data.entity.attributes.forEach(
   function (attribute, index) {
    if (attribute.getValue() == null && attribute.getRequiredLevel() == "required") {
     requiredAttributesWithNullValues.push(attribute);
    }
   }
   );
   if (requiredAttributesWithNullValues.length > 0) {
    var message = "The following fields cannot be null:\n";
    for (var i = 0; i < requiredAttributesWithNullValues.length; i++) {
     message += requiredAttributesWithNullValues[i].controls.get(0).getLabel() + "\n";
    }
    alert(message);
   }

crmForm.<attribute name>.Clear

This internal method was used to remove data from an attribute. The supported way to do this is Xrm.Page.getAttribute("<attribute name>").setValue(null);

Issues with crmGrid

The crmGrid object represents a grid control. There have never been any supported functions that can be called on this object directly. There are three types of grids:

  • ‘Homepage’ grids: These appear in the main navigation pane when you view lists of records
  • Contextual grids: These display when you use the form navigation to view related records
  • Subgrids: These are embedded within a form

There only supported method for grids is that you can reference a subgrid control within a form and use the refresh method. There is no supported way to refresh the ‘Homepage’ or contextual grids.

crmGrid.InnerGrid

We can see that some code is being used to access properties and methods of the innerGrid. The purpose of this unsupported code appear sot be to get text of fields in a grid or count the rows of a grid.

The supported way to access information about the records in a grid apply to the scenario where you are adding a control to the ribbon to perform some action on the records in the grid. <CrmParameter> (RibbonDiffXml) is an element that can be passed through to a rule or JavaScript function that controls the behavior of a control in the Ribbon. If you are using crmGrid.innerGrid to access the contents of a grid for the purpose of taking some actions on the records, you should convert your code to be launched from a ribbon control that can capture this data in a supported way.

crmGrid.GetParameter

We have found people using this internal function to access parameters for a grid. If you are using this, you should evaluate what data you need and alternative, supported ways to get to it. Using <CrmParameter> (RibbonDiffXml) to pass data about the state of the grid to a ribbon command may be the solution.

Issues with Lookup Controls

We found some examples where people are using internal methods to work with lookup controls.

LookupControl.AddParam

We found cases where people were using the AddParam method to add parameters to a lookup. The supported way to do this is to use the addCustomView method.

LookupControl.AddItems

The AddItems internal method was used to add items to a lookup form control. The correct way to do this is to use the setValue method. The SDK provides a sample. See Set Lookup Attribute Value

Leave a Comment
  • Please add 5 and 2 and type the answer here:
  • Post