Quick Guide: Transitioning away from Microsoft Dynamics 365 Xrm.Page JavaScript API

With the release of version 9.0 of Dynamics CRM/365, Microsoft announced that it would deprecate part of the JavaScript client API. Part of the client API being deprecated is Xrm.Page. To give enough transition time to the users of Microsoft Dynamics 365, Xrm.Page will continue to function in this transition period, until Microsoft fully retires the client API.

Despite, the Xrm.Page client API deprecation announcement was made 2 years ago, the use of this API continues to be extensive (visit any Dynamics 365 online forums e.g community.dynamics.com). In my line of work, when I ask developers why they are still using a client API destined for deprecation, the common response is that they have no time to learn the new API and the pressing demands of their work, they have more work than the time available. Therefore, I have written this post to help Microsoft Dynamics 365 software developers, who are pressed for time, and need a quick guide to transition away from Xrm.Page. I have provided examples of the most commonly used Dynamics 365 Xrm.Page JavaScript client API functions, on entity forms, and their formContext client API equivalents.

Examples and application

To view the table below, in full, please use a device larger than your mobile phone.

ObjectiveUsing Xrm.Page (Deprecated Client API)Using formContext (Replacement Client API)
Simple JavaScript function function demoFunction(){ } function demoFunction(eContext){
//Get form context
var formContext = eContext.getFormContext();
}
Disable/lock field, “addRegions”, for selection Xrm.Page.getControl("addRegions").
setDisabled(true);		formContext.getControl("addRegions").
setDisabled(true);
Enable/unlock field, “addRegions”, for selectionXrm.Page.getControl("addRegions").
setDisabled(false); 		formContext.getControl("addRegions").
setDisabled(false);
Hide field, “addRegions”Xrm.Page.getControl("addRegions").
setVisible(false); 		formContext.getControl("addRegions").
setVisible(false);
Show field, “addRegions” Xrm.Page.getControl("addRegions").
setVisible(true); 		formContext.getControl("addRegions").
setVisible(true);
Get lookup field “region”, and its propertiesvar regionLookup = Xrm.Page.
getAttribute("region").getValue();
if (regionLookup != null) {
var name = regionLookup[0].name;
var guid = regionLookup[0].
id.slice(1, -1);
var entityType =
regionLookup[0].entityType;
} 		var regionLookup = formContext.
getAttribute("region").getValue();
if ( regionLookup != null) {
var name = regionLookup[0].name;
var guid = regionLookup[0].
id.slice(1, -1);
var entityType =
regionLookup[0].entityType;
}
Remove option, 15220000, from ‘showRegions’ option set. Xrm.Page.getControl("showRegions").
removeOption(15220000); 		formContext.getControl("showRegions").
removeOption(15220000);
Add option, 15220001 (with text: ‘Africa’), to ‘showRegions’ option set. Xrm.Page.getControl("showRegions").
addOption({
value:15220001,
text:'Africa'}); 		formContext.getControl("showRegions").
addOption({
value:15220001,
text:'Africa'});
Show tab, with logical name “regionsTab”Xrm.Page.ui.tabs.get("regionsTab").
setVisible(true); 		formContext.ui.tabs.get("regionsTab").
setVisible(true);
Hide tab, with logical name “regionsTab” Xrm.Page.ui.tabs.get("regionsTab").
setVisible(false); 		formContext.ui.tabs.get("regionsTab").
setVisible(false);
Show section “regionsTab_regSection”, located in tab “regionsTab” Xrm.Page.ui.tabs.get("regionsTab").
sections.get("regionsTab_regSection").
setVisible(true); 		formContext.ui.tabs.get("regionsTab").
sections.get("regionsTab_regSection").
setVisible(true);
Hide section “regionsTab_regSection”, located in tab “regionsTab” Xrm.Page.ui.tabs.
get("regionsTab").sections.
get("regionsTab_regSection").
setVisible(false); 		formContext.ui.tabs.
get("regionsTab").sections.
get("regionsTab_regSection").
setVisible(false);
Count number of records on sub-grid called “demo-grid” var count = Xrm.Page.
getControl("demo-grid").getGrid().
getTotalRecordCount(); 		var count = formContext.
getControl("demo-grid").getGrid().
getTotalRecordCount();

Transition from deprecated client API table

To view the table below, in full, please use a device larger than your mobile phone.

Deprecated Client API Replacement Client API
Xrm.Page Forms: ExecutionContext.
getFormContext
Commands: Send it as the 
PrimaryControl parameter
Xrm.Page.context Xrm.Utility.getGlobalContext
Xrm.Page.context.
getQueryStringParameters		 formContext.data.attributes
Xrm.Page.context.
getTimeZoneOffsetMinutes		globalContext.userSettings.
getTimeZoneOffsetMinutes
Xrm.Page.context.
getUserId		globalContext.userSettings.
userId
Xrm.Page.context.
getUserLcid		globalContext.userSetings.
languageId
Xrm.Page.context.
getUserName		globalContext.userSettings.
userName
Xrm.Page.context.getUserRolesglobalContext.userSettings.
securityRoles
Xrm.Page.context.
getIsAutoSaveEnabled		globalContext.organizationSettings.
isAutoSaveEnabled
Xrm.Page.context.
getOrgLcid		globalContext.organizationSettings.
languageId
Xrm.Page.context.
getOrgUniqueName		globalContext.organizationSettings.
uniqueName
Xrm.Page.data.
entity.getDataXml		No change in the method, but use
“typename” instead of type for lookup
attributes.
GridRow.getDataGridRow.data
GridRowData.getEntityGridRowData.entity
Xrm.Mobile.offlineXrm.WebApi.offline
parent.XrmUse one of the following:

a) Use a custom control created using Power Apps component framework instead of HTML web resources.
b) On forms, use the getContentWindow method of the web resource control.
c) If the getContentWindow method doesn’t work, you can use parent.Xrm to get to the Xrm object inside an HTML web resource. If the HTML web resource is opened in a new window then you should use opener.Xrm instead.
addOnKeyPressUse a custom control created using Power Apps component framework
fireOnKeyPressUse a custom control created using Power Apps component framework
removeOnKeyPressUse a custom control created using Power Apps component framework
showAutoCompleteUse a custom control created using Power Apps component framework
hideAutoCompleteUse a custom control created using Power Apps component framework
Xrm.Utility.alertDialogXrm.Navigation.openAlertDialog
Xrm.Utility.confirmDialogXrm.Navigation.openConfirmDialog
Xrm.Utility.getBarcodeValueXrm.Device.getBarcodeValue
Xrm.Utility.getCurrentPositionXrm.Device.getCurrentPosition
Xrm.Utility.isActivityTypeXrm.Utility.getEntityMetadata
Xrm.Utility.openEntityFormXrm.Navigation.openForm
Xrm.Utility.openQuickCreateXrm.Navigation.openForm
Xrm.Utility.openWebResourceXrm.Navigation.openWebResource
globalContext.organizationSettings.
baseCurrencyId		globalContext.organizationSettings.baseCurrency
globalContext.userSettings.
securityRoles		globalContext.userSettings.Roles
globalContext.userSettings.
transactionCurrencyId		globalContext.userSettings.transactionCurrency
getData and setData for Silverlight web resourcesNone
formContext.data.entity.saveformContext.data.save
ClientGlobalContext.js.aspxNone
getObjectgetContentWindow
Source: Microsoft

Conclusion

Time saved now is time saved in the future. Therefore, I am of the view that it is better to take the time to learn the new Dynamics 365 JavaScript client API and begin to write your code using an API that will continue to function beyond the short/medium term. If today, a team begins to use the new client API to write new code, they will have less legacy code to update when Microsoft pulls the plug on Xrm.Page and other deprecated APIs. Even better, a team can learn the new JavaScript client API, update their legacy code and stop using the deprecated client API. Taking the latter approach, a team will not need to perform an emergency update of their legacy code when Microsoft eventually completely retires the Xrm.Page and other deprecated APIs.