JavaScript Model Changes ||    New Client APIs     ||     Deprecated Client APIs

J1

There are significant changes made to Client APIs in Dynamics 365 version 9.0 release. Table below lists four main changes happened in this release:

Execution Context Use execution context to retrieve form or grid context instead of using    Xrm.Page which is deprecated in this release
Global Context New API added to Xrm.Utility object to retrieve information specific to organization, user or client where script is executed instead of using Xrm.Page.context which is deprecated in this release
New Client APIs Number of new namespaces and APIs introduced with this release

New namespaces:

  • Xrm.Device
  • Xrm.Encoding
  • Xrm.Navigation
  • Xrm.WebApi

New APIs in existing namespaces:

  • formContext.data – onload, isValid, saveOptions, saveMode
  • formContext.data.entity – getEntityReference, isValid
  • formContext.ui – onload event handlers
  • Xrm.Utility – getEntityMetadata, getGlobalContext, lookupObjects, showProgressIndicator, closeProgressIndicator

Refer link for complete list.
Deprecated APIs Some of client APIs are deprecated:

  • Xrm.Page
  • Xrm.Page.context
  • GridRow.getData
  • GridRowData.getEntity
  • Xrm.Mobile.offline
  • parent.Xrm
  • Xrm.Utility.alertDialog
  • Xrm.Utility.confirmDialog
  • Xrm.Utility.openEntityForm
  • Xrm.Utility.openQuickCreate
  • Xrm.Utility.openWebResource

Refer section Deprecated Client APIs below for more details.

JavaScript Model Changes:

At root of Client API object model, we have executions object and Xrm object as shown below:

J2

Let’s have a look at each of these in detail:

1. Execution Context – Context which is passed when an event occurs on a form or grid which you can use it in your event handler to determine formContext, gridContext or manage the save event

We can pass execution context through UI or code:

  • Pass through UI – Execution context is an optional parameter and can be passed through UI at time of defining event handler under handler properties. Use “Pass execution context as first parameter” option to pass execution context to JavaScript function

J3

  • Pass through code – Event handlers which cannot be defined from UI, can be defined from code. The execution context is automatically passed as the first parameter to functions set using code. Below is the example:
    • addOnChange – formContext.getAttribute(arg).addOnChange(myFunction)
    • removeOnChange – formContext.getAttribute(arg).removeOnChange(myFunction)
                            function myFunction(executionContext)
{
//first parameter passed as execution context
}
Earlier

function displayName()

{

var firstName = Xrm.Page.getAttribute(“firstname”).getValue();

var lastName = Xrm.Page.getAttribute(“lastname”).getValue();

console.log(firstName + ” ” + lastName);

}
Now

function displayName(executionContext)

{

var formContext = executionContext.getFormContext(); // get formContext

// use formContext instead of Xrm.Page

var firstName = formContext.getAttribute(“firstname”).getValue();

var lastName = formContext.getAttribute(“lastname”).getValue();

console.log(firstName + ” ” + lastName);

}

2. Form Context (Replaced Page) – Context provides reference to form or any item on form against which current code is executed. Form Context can be retrieved using executionContext.getFormContext Form context replaced Xrm.Page which is deprecated in this release and was used to represent form or any item on form earlier.

         Form Context Object Model:

J4

For more details please refer link

3. Grid Context (Replace Xrm.Page) – Context provides reference to grid or sub-grid on form against which code is executed. Grid context can be retrieved from execution context based on where code is being executed. Grid context also replaced Xrm.Page which was used to represent grid or sub grid on form earlier.

Earlier

function doSomething()

{

var contactsSubgrid = Xrm.Page.getControl(“Contacts”);

}
Now

1)       Code is executed on form event

function doSomething(executionContext) {

var formContext = executionContext.getFormContext(); // get the form Context

var gridContext = formContext.getControl(“Contacts”); // get the grid context

// Perform operations on the subgrid

}

2)       Code is executed on grid event

function doSomething(executionContext) {

var formContext = executionContext.getFormContext(); // get the form Context

var gridContext = formContext.getControl(“Contacts”); // get the grid context

// Perform operations on the subgrid

}

Some other methods:

Grid Earlier

Xrm.Page.getControl(“Contacts”).getGrid();

Now

          gridContext.getGrid();

//where griContext = formContext.getControl(“Contacts”);
GridRow Earlier

         Xrm.Page.getControl(“Contacts”).getGrid().getRows();

Now

         gridContext.getGrid().getRows();
GridRowData Earlier

         Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getData()

Now

gridContext.getGrid().getRows().get(0).data

Note – getDate() is deprecated in this release
GridEntity Earlier

Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getEntity()

Now

        gridContext.getGrid().getRows().get(0).entity

Note – getEntity() is deprecated in this release

 For more details please refer link

4. Xrm Object – Xrm object is globally available which provides methods to use device capabilities, navigation settings, information specific to organization or user and offline capabilities without having to use execution context in Client API. In this release Xrm object is updated to have new namespaces and new APIs in existing namespaces.

 New Xrm Object Model:

J5

 New Namespaces:

  • Device – Provides methods to use native device capabilities of mobile devices.
    • captureAudio
    • captureImage
    • captureVideo
    • getBarcodeValue
    • getCurrentPosition
    • pickFile
  • Encoding – Provides methods to encode strings.
    • xmlAttributeEncode
    • xmlEncode
  • Navigation – Provides methods for navigating forms and items in Customer Engagement.
    • openAlertDialog
    • openConfirmDialog
    • openErrorDialog
    • openFile
    • openForm
    • openUrl
    • openWebResource
  • WebApi – Provides methods to use Web API to create, manage records and execute Web API actions and functions. Comes with offline capabilities also for mobile clients.

          Properties:

online – perform actions or functions when connect to server (online mode)

offline – perform actions or functions when offline with mobile clients

          Methods: 

createRecord – Creates an entity record

deleteRecord – Deletes an entity record

retrieveRecord – Retrieves an entity record

retrieveMultipleRecords – Retrieves a collection of entity records

updateRecord – Updates an entity record

isAvaiableOffline – Returns a boolean value indicating whether an entity is                            present in user’s profile and is currently available for use in offline mode

execute – Execute a single action, function, or CRUD operation

executeMultiple – Execute a collection of action, function, or CRUD operations

Refer to my blog for more details on Xrm.WebApi

Deprecated Client APIs:

Following are deprecated Client APIs in this release which will be replaced with replacement client API mentioned. Deprecated Client APIs will continue to be available and supported until they are officially removed from a future major release of Dynamics 365.

Deprecated Client API Replacement Client API Comments
Xrm.Page Forms: ExecutionContext.getFormContext Xrm.Page is the primary form context. If a script is run on a secondary context (grid row, quick form, related entity) then Xrm.Page will be for the wrong form context. By using alternate methods of getting the form context we allow the same script to be used without modification in all contexts.
Xrm.Page.context Xrm.Utility.getGlobalContext Allows access to the global context without going through the form context.
Xrm.Page.context.getQueryStringParameters formContext.data.attributes The formContext.data.attributes API will make retrieval of non-entity bound data consistent across entity forms, metadata-driven dialogs, and task-based flows. The data will be a combination of custom values sent using the query string and what was specified in the parameters in the openForm method.
Xrm.Page.context.getTimeZoneOffsetMinutes globalContext.userSettings.getTimeZoneOffsetMinutes Moved to globalContext.userSettings
Xrm.Page.context.getUserId globalContext.userSettings.userId Moved to globalContext.userSettings
Xrm.Page.context.getUserLcid globalContext.userSetings.languageId Moved to globalContext.userSettings
Xrm.Page.context.getUserName globalContext.userSettings.userName Moved to globalContext.userSettings
Xrm.Page.context.getUserRoles globalContext.userSettings.securityRoles Moved to globalContext.userSettings
Xrm.Page.context.getIsAutoSaveEnabled globalContext.organizationSettings.isAutoSaveEnabled Moved to globalContext.organizationSettings
Xrm.Page.context.getOrgLcid globalContext.organizationSettings.languageId Moved to globalContext.organizationSettings
Xrm.Page.context.getOrgUniqueName globalContext.organizationSettings.uniqueName Moved to globalContext.organizationSettings
Xrm.Page.data.entity.getDataXml No change in the method, but use “typename” instead of type for lookup attributes.  
GridRow.getData GridRow.data GridRow is essentially a form context. This change unifies the interface of GridRow with formContext.
GridRowData.getEntity GridRowData.entity GridRowData is form data. This change unifies the interface of GridRowData with formContextData.
Xrm.Mobile.offline Xrm.WebApi.offline Moved the offline-related methods under Xrm.WebApi.offline
parent.Xrm   Earlier: An HTML web resource may interact with the Xrm.Page or Xrm.Utility objects within the form by using parent.Xrm.Page or parent.Xrm.Utility.
Now: parent.Xrm.* will work if the HTML web resource is loaded in a form container. For other places, such as loading an HTML web resource as part of the SiteMap, parent.Xrm.* won’t work.
addOnKeyPress Use a custom control  
removeOnKeyPress Use a custom control  
showAutoComplete Use a custom control and corresponding UI  
hideAutoComplete Use a custom control and corresponding UI  
Xrm.Utility.alertDialog Xrm.Navigation.openAlertDialog The new signature is consistent with other APIs (openForm) and takes a new set of parameters for flexibility.
Xrm.Utility.confirmDialog Xrm.Navigation.openConfirmDialog The new signature is consistent with other APIs (openForm) and takes a new set of parameters for flexibility.
Xrm.Utility.isActivityType Xrm.Utility.getEntityMetadata The isActivityType method is synchronous so it was suitable for ribbon rules. However, the replacement method, getEntityMetadata, is asynchronous, and is not suitable for ribbon rules.
Xrm.Utility.openEntityForm Xrm.Navigation.openForm Moving navigation actions to Xrm.Navigation
Xrm.Utility.openQuickCreate Xrm.Navigation.openForm Moving navigation actions to Xrm.Navigation
Xrm.Utility.openWebResource Xrm.Navigation.openWebResource Moving navigation actions to Xrm.Navigation
Note: This API returns VOID in Unified Interface.

References:

https://docs.microsoft.com/en-us/dynamics365/get-started/whats-new/customer-engagement/new-in-version-9-for-developers

https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/clientapi/understand-clientapi-object-model

https://docs.microsoft.com/en-us/dynamics365/get-started/whats-new/customer-engagement/important-changes-coming#some-client-apis-are-deprecated