JavaScript Changes – Dynamics 365 9.0

This blog is re-blogged, thanks to Sachin Bansal!!

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 formContextgridContext 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
}
Earlierfunction displayName(){var firstName = Xrm.Page.getAttribute(“firstname”).getValue();var lastName = Xrm.Page.getAttribute(“lastname”).getValue();console.log(firstName + ” ” + lastName);}
Nowfunction displayName(executionContext){var formContext = executionContext.getFormContext(); // get formContext// use formContext instead of Xrm.Pagevar 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.

Earlierfunction doSomething(){var contactsSubgrid = Xrm.Page.getControl(“Contacts”);}
Now1)       Code is executed on form eventfunction doSomething(executionContext) {var formContext = executionContext.getFormContext(); // get the form Contextvar gridContext = formContext.getControl(“Contacts”); // get the grid context// Perform operations on the subgrid}2)       Code is executed on grid eventfunction doSomething(executionContext) {var formContext = executionContext.getFormContext(); // get the form Contextvar gridContext = formContext.getControl(“Contacts”); // get the grid context// Perform operations on the subgrid}

Some other methods:

GridEarlierXrm.Page.getControl(“Contacts”).getGrid();NowgridContext.getGrid();//where griContext = formContext.getControl(“Contacts”);
GridRowEarlier Xrm.Page.getControl(“Contacts”).getGrid().getRows();NowgridContext.getGrid().getRows();
GridRowDataEarlier Xrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getData()NowgridContext.getGrid().getRows().get(0).dataNote – getDate() is deprecated in this release
GridEntityEarlierXrm.Page.getControl(“Contacts”).getGrid().getRows().get(0).getEntity()NowgridContext.getGrid().getRows().get(0).entityNote – 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 APIReplacement Client APIComments
Xrm.PageForms: ExecutionContext.getFormContextXrm.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.contextXrm.Utility.getGlobalContextAllows access to the global context without going through the form context.
Xrm.Page.context.getQueryStringParametersformContext.data.attributesThe 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.getTimeZoneOffsetMinutesglobalContext.userSettings.getTimeZoneOffsetMinutesMoved to globalContext.userSettings
Xrm.Page.context.getUserIdglobalContext.userSettings.userIdMoved to globalContext.userSettings
Xrm.Page.context.getUserLcidglobalContext.userSetings.languageIdMoved to globalContext.userSettings
Xrm.Page.context.getUserNameglobalContext.userSettings.userNameMoved to globalContext.userSettings
Xrm.Page.context.getUserRolesglobalContext.userSettings.securityRolesMoved to globalContext.userSettings
Xrm.Page.context.getIsAutoSaveEnabledglobalContext.organizationSettings.isAutoSaveEnabledMoved to globalContext.organizationSettings
Xrm.Page.context.getOrgLcidglobalContext.organizationSettings.languageIdMoved to globalContext.organizationSettings
Xrm.Page.context.getOrgUniqueNameglobalContext.organizationSettings.uniqueNameMoved to globalContext.organizationSettings
Xrm.Page.data.entity.getDataXmlNo change in the method, but use “typename” instead of type for lookup attributes.
GridRow.getDataGridRow.dataGridRow is essentially a form context. This change unifies the interface of GridRow with formContext.
GridRowData.getEntityGridRowData.entityGridRowData is form data. This change unifies the interface of GridRowData with formContextData.
Xrm.Mobile.offlineXrm.WebApi.offlineMoved the offline-related methods under Xrm.WebApi.offline
parent.XrmEarlier: 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.
addOnKeyPressUse a custom control
removeOnKeyPressUse a custom control
showAutoCompleteUse a custom control and corresponding UI
hideAutoCompleteUse a custom control and corresponding UI
Xrm.Utility.alertDialogXrm.Navigation.openAlertDialogThe new signature is consistent with other APIs (openForm) and takes a new set of parameters for flexibility.
Xrm.Utility.confirmDialogXrm.Navigation.openConfirmDialogThe new signature is consistent with other APIs (openForm) and takes a new set of parameters for flexibility.
Xrm.Utility.isActivityTypeXrm.Utility.getEntityMetadataThe 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.openEntityFormXrm.Navigation.openFormMoving navigation actions to Xrm.Navigation
Xrm.Utility.openQuickCreateXrm.Navigation.openFormMoving navigation actions to Xrm.Navigation
Xrm.Utility.openWebResourceXrm.Navigation.openWebResourceMoving 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

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s