0% found this document useful (0 votes)

8 views444 pages

Client Scripting

The document provides a comprehensive guide on client scripting in Customer Engagement using JavaScript, detailing the Client API object model, event handling, and best practices. It covers various aspects such as execution context, form context, and grid context, along with a walkthrough for writing client scripts. Additionally, it emphasizes the importance of understanding the Client API to effectively implement custom business logic in Dynamics 365 (online), version 9.x.

Uploaded by

Swapnil Mahajan

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

8 views444 pages

Client Scripting

Uploaded by

Swapnil Mahajan

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

Client scripting in Customer Engagement using JavaScript

Events in forms and grids
Understand Client API object model
Execution context
Form context
Grid context
Xrm object
Walkthrough: Write your first client script
Debug your JavaScript code for Customer Engagement
Best practices: client scripting in Customer Engagement
Client API Reference
Client-side events
Attribute OnChange event
Form OnLoad event
Form OnSave event
Form data OnLoad event
Grid OnChange event
Grid OnRecordSelect event
Grid OnSave event
OnProcessStatusChange event
OnReadyStateComplete event
OnResultOpened event
OnSelection event
OnStageChange event
OnStageSelected event
PostSearch event
PreSearch event
Subgrid OnLoad event
TabStateChange event
Collections
forEach
get
getLength
GetGlobalContext function and [Link]
Execution context
getDepth
getEventArgs
getEventSource
getFormContext
getSharedVariable
setSharedVariable
Save event arguments
getSaveMode
isDefaultPrevented
preventDefault
Attributes
Composite attributes
addOnChange
controls collection
fireOnChange
getAttributeType
getFormat
getInitialValue
getIsDirty
getIsPartyList
getMax
getMaxLength
getMin
getName
getOption
getOptions
getParent
getPrecision
getRequiredLevel
getSelectedOption
getSubmitMode
getText
getUserPrivilege
getValue
isValid
removeOnChange
setPrecision
setRequiredLevel
setSubmitMode
setValue
Controls
addCustomFilter
addCustomView
addNotification
addOnPostSearch
addOnResultOpened
addOnSelection
addOption
addPreSearch
clearNotification
clearOptions
getAttribute
getControl
getControlType
getData
getDefaultView
getDisabled
getEntityTypes
getInitialUrl
getLabel
getName
getObject
getParent
getSearchQuery
getSelectedResults
getShowTime
getSrc
getState
getTotalResultCount
getValue
getVisible
openSearchResult
refresh
removeOnPostSearch
removeOnResultOpened
removeOnSelection
removeOption
removePreSearch
setData
setDefaultView
setDisabled
setEntityTypes
setFocus
setLabel
setNotification
setSearchQuery
setShowTime
setSrc
setVisible
[Link]
addOnLoad
getIsDirty
isValid
refresh
removeOnLoad
save
[Link]
addOnSave
getDataXml
getEntityName
getEntityReference
getId
getIsDirty
getPrimaryAttributeValue
isValid
removeOnSave
save
[Link]
Event handler methods
addOnProcessStatusChange
addOnStageChange
addOnStageSelected
removeOnProcessStatusChange
removeOnStageChange
removeOnStageSelected
Active Process methods
getActiveProcess
setActiveProcess
getEnabledProcesses
Process methods
getId
getName
getStages
isRendered
ProcessInstance methods
getProcessInstances
setActiveProcessInstance
Instance methods
getInstanceId
getInstanceName
getStatus
setStatus
Active Stage methods
getActiveStage
setActiveStage
getActivePath
getSelectedStage
Stage methods
getCategory
getEntityName
getId
getName
getNavigationBehavior
getStatus
getSteps
Step methods
getAttribute
getName
getProgress
isRequired
setProgress
Navigation methods
moveNext
movePrevious
[Link]
addOnLoad
clearFormNotification
close
getFormType
getViewPortHeight
getViewPortWidth
refreshRibbon
removeOnLoad
setFormEntityName
setFormNotification
[Link]
getId
getLabel
navigate
[Link]
getId
getLabel
getVisible
setFocus
setLabel
setVisible
[Link]
getDisplayState
getVisible
reflow
setDisplayState
setVisible
[Link]
getControl
getControlType
getDisabled
getLabel
getName
getParent
getVisible
isLoaded
refresh
setDisabled
setFocus
setLabel
setVisible
[Link]
addtabStateChange
addtabStateChange
getDisplayState
getLabel
getName
getParent
getVisible
removeTabStateChange
setDisplayState
setFocus
setLabel
setVisible
[Link]
getLabel
getName
getParent
getVisible
setLabel
setVisible
Grids and subgrids
GridControl
addOnLoad
getEntityName
getFetchXml
getGrid
getGridType
getRelationship
getUrl
getViewSelector
openRelatedGrid
refresh
refreshRibbon
removeOnLoad
Grid
getRows
getSelectedRows
getTotalRecordCount
GridRow
getData
GridRowData
getEntity
GridEntity
getEntityName
getEntityReference
getId
getPrimaryAttributeValue
GridAttribute
GridCell
ViewSelector
getCurrentView
isVisible
setCurrentView
[Link]
captureAudio
captureImage
captureVideo
getBarcodeValue
getCurrentPosition
pickFile
[Link]
htmlAttributeEncode
htmlDecode
htmlEncode
xmlAttributeEncode
xmlEncode
[Link]
openAlertDialog
openConfirmDialog
openErrorDialog
openFile
openForm
openUrl
openWebResource
[Link]
loadPanel
[Link]
closeProgressIndicator
getAllowedStatusTransitions
getEntityMetadata
getGlobalContext
client
organizationSettings
userSettings
getAdvancedConfigSetting
getClientUrl
getCurrentAppName
getCurrentAppProperties
getCurrentAppUrl
getVersion
isOnPremises
prependOrgName
getLearningPathAttributeName
getResourceString
invokeProcessAction
lookupObjects
refreshParentGrid
showProgressIndicator
[Link]
[Link]
[Link]
createRecord
deleteRecord
retrieveRecord
retrieveMultipleRecords
updateRecord
isAvailableOffline
execute
executeMultiple
Client scripting in Customer Engagement using
JavaScript
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Client-side scripting using JavaScript is one of the ways to apply custom business process logic for displaying data
on a form in Customer Engagement.

NOTE
You can also use business rules, which provides 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 business rules and recommendations to apply logic in a
form

Forms in Customer Engagement help display data to the user. A form in Customer Engagement can contain items
such as fields, a quick form, or a grid. An event occurs in Customer Engagement forms whenever:
A form loads
Data is changed in a field or an item within the form
Data is saved in a form
You can attach your JavaScript code to "react" to these events so that your code gets executed when the event
occurs on the form. You attach your JavaScript code (scripts) to these events by using a Script web resource in
Customer Engagement.
Customer Engagement provides you a rich set of client APIs to interact with form objects and events to control
what and when to display on a form.

NOTE
Some client APIs are deprecated in the current release of Dynamics 365 Customer Engagement. Ensure that you are aware of
these APIs as you write your client-side code for Customer Engagement. More information: Deprecated client APIs

Get Started
Events in forms and grids
Understand the Client API object model
Walkthrough: Write your first client script

Reference
Client API reference

Related topics
Web resources for Customer Engagement
Customize commands and the ribbon
Events in forms and grids in Customer Engagement
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

All client-side code is initiated by events. In Customer Engagement, you associate a specific function in a
JavaScript library (Script web resource) to be executed when an event occurs. This function is called an event
handler. Each event handler specifies a single function within a JavaScript library and any parameters that can be
passed to the function.
You can associate event handlers to only some events using the UI. For events that are not available to be
associated through UI, Client API provides methods that can be used to attach event handlers to such events.

Add or remove event handler function to event using UI

Use the Event Handlers section of the Form Properties dialog box to associate your script with an event for
forms and fields.

Add or remove event handler function to event using code

Using the following methods to add and remove event handler for events that cannot be associated through UI:

EVENTS EVENT HANDLER

Attribute OnChange addOnChange and removeOnChange methods

Form OnLoad [Link] addOnLoad and removeOnLoad methods

Form data OnLoad [Link] addOnLoad and removeOnLoad methods

EVENTS EVENT HANDLER

Form OnSave addOnSave and removeOnSave methods

Lookup control PreSearch addPreSearch and removePreSearch methods

kbsearch control OnResultOpened addOnResultOpened and removeOnResultOpened methods

kbsearch control OnSelection addOnSelection and removeOnSelection methods

kbsearch control PostSearch addOnPostSearch and removeOnPostSearch methods

IMPORTANT
The execution context is automatically passed as the first parameter to functions that are set using the code. More
information: Client API execution context

Form event pipeline

You can define up to 50 event handlers for each event. Each event handler is executed in the order that it is
displayed in the Event Handlers section in the Events tab of the Form Properties dialog box.
Use the setSharedVariable and getSharedVariable methods to pass a common variable between event handlers
(functions). Use the execution context getDepth method to know the sequence that an event handler is being
executed in relative to other event handlers.
Related topics
Understand the Client API object model
Client API execution context
Events (Client API reference)
Understand the Client API object model
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The Client API object model for Customer Engagement provides you objects and methods that you can use to
apply custom business logic in Customer Engagement using JavaScript, such as:
Get or set attribute values.
Show and hide user interface elements.
Reference multiple controls per attribute.
Access multiple forms per entity.
Manipulate form navigation items.
Interact with the business process flow control.
Its important that you understand the Customer Engagement Client API object model to effectively write and use
your JavaScript code in Customer Enagagement.

Root objects in the Client API object model

At the root of the Client API object model are the following contexts and the Xrm object:

OBJECT DESCRIPTION

executionContext Represents the execution context for an event in Customer

Engagement forms and grids.
More information: Client API execution context

formContext Provides a reference to a form or an item on the form against

which the current code executes. To get the formContext
object, use the [Link] method.
More information: Client API form context

gridContext Provides a reference to a grid or a subgrid on a form against

which the current code executes.
More information: Client API grid context

Xrm Provides a global object for performing operations that do

not directly impact the data and UI in forms, grids, subgrids,
controls, or attributes. For example, navigate forms, create
and manage records using Web API.
More information: Client API Xrm object

Related topics
Client API global context
Client API reference
Client API execution context
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The execution context defines the event context in which your code executes. The execution context is passed
when an event occurs on a form or grid, which you can use it in your event handler to perform various tasks
such as determine formContext or gridContext, or manage the save event.
The execution context is passed in one of the following ways:
Defining event handlers using UI: The execution context is an optional parameter that can be passed
to a JavaScript library function through an event handler. Use the Pass execution context as first
parameter option in the Handler Properties dialog while specify the name of the function to pass the
event execution context. The execution context is the first parameter passed to a function.

Defining event handlers using code: The execution context is automatically passed as the first
parameter to functions set using code. For a list of methods that can be used to define event handlers in
code, see Add or remove functions to events using code.
The execution context object provides a number of methods to further work with the context. More
information: Execution context (Client API reference)
Related topics
Client API form context
Client API grid context
Form and grid context in ribbon actions
Client API form context
8/24/2018 • 4 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The Client API form context (formContext) provides a reference to the form or to an item on the form, such
as, a quick view control or a row in an editable grid, against which the current code is executed.
Earlier, the global [Link] object was used to represent a form or an item on the form. With Dynamics 365
(online), version 9.0, the [Link] object is deprecated, and you should use the getFormContext method of
the passed in execution context object to return reference to the appropriate form or an item on the form.

IMPORTANT
Deprecated means that we intend to remove a feature or capability from a future major release of Dynamics 365; the
feature or capability will continue to work and is fully supported until it is officially removed.

Use of the [Link] object as a static access to the primary form context is still supported to maintain backward
compatibility with the existing scripts, and won’t be removed as soon as some other client API methods listed in the
Client API deprecation section. We recommend that you use the new formContext object instead of the [Link]
object in your code targeting version 9.0 or later where possible. Also, using the formContext object enables you to
create common event handlers that can operate either on a form or in an editable grid depending on where its called.
More information: getFormContext (Client API reference).

Getting the formContext object for JavaScript functions for ribbon actions is different from how you get it in form
scripting. More information: Form and grid context in ribbon actions.

Using the formContext object instead of the [Link] object

It's easy to convert existing code with [Link] to use the new formContext object. For example, consider
the following script that uses the [Link] object:

function displayName()
{
var firstName = [Link]("firstname").getValue();
var lastName = [Link]("lastname").getValue();
[Link](firstName + " " + lastName);
}

Here is the updated script that uses the passed in execution context to retrieve the formContext object
instead of using the static [Link] object:

function displayName(executionContext)
{
var formContext = [Link](); // get formContext

// use formContext instead of [Link]

var firstName = [Link]("firstname").getValue();
var lastName = [Link]("lastname").getValue();
[Link](firstName + " " + lastName);
}
IMPORTANT
You must remember to select the Pass execution context as first parameter option in the Handler Properties
dialog while defining your event handlers to use the formContext object. More information: Client API execution
context

formContext object model

Use the data and ui objects under the formContext object to programmatically manipulate data and user
interface elements in Customer Engagement.

data object
Provides access to the entity data and methods to manage the data in the form as well as in the business
process flow control. Contains the following objects:

OBJECT DESCRIPTION

entity Provides methods to retrieve information specific to the

record displayed on the page, the save method, and a
collection of all the attributes included on the form

process Provides methods to retrieve properties of a business

process flow.

It also provides an attributes collection for accessing non-entity bound control. See the Collections in the
formContext object model section later in this topic.
More information: [Link]
ui object
Provides methods to retrieve information about the user interface, in addition to collections for several sub
components of the form or grid. Contains the following objects:

OBJECT DESCRIPTION
OBJECT DESCRIPTION

formSelector Provides an items collection that provides capabilities to

query the forms available for the current user. Use the
navigate method to close the current form and open a
different one.

navigation Does not contain any methods. Provides access to

navigation items through the items collection. See the next
section on collections for more information.

process Provides methods to interact with the business process flow

control on a form.

More information: [Link]

Collections in the formContext object model

The following table describes the collections in Xrm object model. For information about the methods
available for collections in general, see Collections (Client API reference).

COLLECTION DESCRIPTION

attributes Two objects contain an attributes collection:

- [Link] collection provides access

to non-entity bound attributes.

- [Link] collection provides

access to each entity attribute that is available on the form.
Only those attributes that correspond to fields added to
the form are available.

controls Three objects contain a controls collection:

- [Link]: Provides access to each control

present on the form.

- [Link]: Because an
attribute may have more than one control on the form, this
collection provides access to each of them. This collection
will contain only one item unless multiple controls for the
attribute are added to the form.

- [Link]: This collection

only contains the controls found in the section.

[Link] and Provides access to stages and steps collection in a business

[Link] process flow. These also allow for adding and removing of
items from the collection.

[Link] When multiple forms are provided for an entity, you can
associate each form with security roles. When the security
roles associated with a user enable them to see more than
one form, the [Link]
collection provides access to each form definition available
to that user.
COLLECTION DESCRIPTION

[Link] The [Link] collection provides

access to navigation items that are defined using the
navigation area of the form editor. People navigate to these
using the command bar.

[Link] Provides methods to access all the quick view controls and
its constituent controls on the Customer Enagagement
forms.

[Link] You can organize each form by using one or more tabs. This
collection provides access to each of these tabs.

[Link] You can organize each form tab by using one or more
sections. The tab sections collection provides access to
each of these sections.

Related topics
getFormContext method
getGlobalContext method
Execution context methods
Client API grid context
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The grid context object provides a reference to the grid or a subgrid on a form against which the current code is
executed.
Depending on where your JavaScript code is executed, you get the gridContext object in one of the following
ways:
Executing code on a form event: Use the formContext object to get an instance of the form where the
code is executed, and then retrieve the subgrid control on the form. For example, when you know the name
of a subgrid control (say Contacts subgrid in the default account form), you can access it using the
following code:

function doSomething(executionContext) {
var formContext = [Link](); // get the form Context
var gridContext = [Link]("Contacts"); // get the grid context

// Perform operations on the subgrid

}

Executing code on a grid event: Use the getFormContext method of the passed in execution context
object to directly return reference to the grid where the code is executed. The grid events include
OnChange, OnRecordSelect, and OnSave.

function doSomething(executionContext) {
var gridContext = [Link](); // get the grid context

// Perform operations on the grid

}

For more information about working with methods and events available for grids and subgrids, see Grids and
subgrids.

NOTE
Getting the gridContext object for JavaScript functions for ribbon actions is different from how you get it in form scripting.
More information: Form and grid context in ribbon actions

Related topics
Client API form context
Client API execution context
Understand the Client API object model
Grids and subgrids
Client API Xrm object
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The Xrm object is globally available to use in your code without having to use the execution context in Client API.

Xrm object model

The following illustration displays the Xrm object model:

Here is the information about each of the namespaces in the Xrm object:

NAMESPACE DESCRIPTION

[Link] Provides methods to use native device capabilities of mobile

devices.

[Link] Provides methods to encode strings.

[Link] Provides methods for navigating forms and items in

Customer Engagement.

[Link] Provides a method to display a web page in the side pane of

Customer Engagement form.

[Link] Provides a container for useful methods.

[Link] Provides methods to use Web API to create and manage

records and execute Web API actions and functions.

[Link]: Provides methods to create and manage

records in the Dynamics 365 Customer Engagement mobile
clients while working in the offline mode.

[Link]: Provides methods to use Web API to

create and manage records and execute Web API actions and
functions when connected to the server.

Client API global context

Use the [Link] method in forms to retrieve information specific to an organization, a user,
or the client where script is run without going through the form execution context. This is a change from previous
versions where you had to use the form context to retrieve global context by using [Link].

NOTE
[Link] is deprecated in the current release, and you should now use the new [Link]
method to get global context in your code targeting version 9.0 or later.

To access the global context information in a standalone HTML Web resource, you should include a reference to
[Link] in the web resource, and then use the GetGlobalContext function. More
information: GetGlobalContext function and [Link]
Related topics
Understand the Client API object model
Deprecated client APIs
Walkthrough: Write your first client script
8/24/2018 • 8 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Ready to write your first client script to see things in action. Lets get started; we'll keep it simple.

Objective
After completing this walkthrough, you will know how to use your JavaScript code in Customer Engagement,
which involves the following steps at a high level:
Write your JavaScript code to address a business issue
Upload your JavaScript code as a web resource in Customer Engagement
Associate the JavaScript functions in the web resource to different client-side events in Customer Engagement.
We will draw your attention to important facts during the walkthrough, and provide references to actual methods
as appropriate.

Step 1: Write your custom JavaScript code

The first step is to identify the business issue you are trying to address using client scripting. Once you have
identified it, you need to write your JavaScript code containing the custom business logic that addresses your
business issue.
Dynamics 365 Customer Engagement does not provide a JavaScript editor. So, you can use an external authoring
tool that provides features to specifically support editing JavaScript files, such as Notepad++, Visual Studio Code,
or Microsoft Visual Studio.
You can review the complete sample code used in the walkthrough later in this topic.
Let's look at the code in detail:
Detailed code explanation
Define namespace: The code starts by defining a namespace for your custom script. As a best practice,
you should always create namespaced JavaScript libraries to avoid having your functions overriden by
functions in another library.

var Sdk = [Link] || {};

In this case, all the functions defined in this library can be used as Sdk.[functionName] .
Define global variables: The following section defines some global variables to be used in the script. Note
that you now don't need to go through the form context to get the user name. Context information is now
available globally using the [Link] method.

// Define some global variables

var myUniqueId = "_myUniqueId"; // Define an ID for the notification
var currentUserName = [Link]().[Link]; // get current user name
var message = currentUserName + ": Your JavaScript code in action!";

Code to execute on the OnLoad event: This section contains the code that will be executed when the
account form loads. For example, when you create a new account record or when you open an existing
account record.
The code uses the executionContext object to get the formContext object. When we attach our code with
the form event later, we will remember to select the option to pass the execution context to this function.
Next, we display a form level notification using the setFormNotification method. Next, we use the
setTimeOut method to delay the execution of the clearFormNotification method to clear the notification
after 5 seconds.

// Code to run in the form OnLoad event

[Link] = function (executionContext) {
var formContext = [Link]();

// display the form level notification as an INFO

[Link](message, "INFO", myUniqueId);

// Wait for 5 seconds before clearing the notification

[Link](function () { [Link](myUniqueId); }, 5000);
}

Code to execute on the OnChange event: Code in this sections will be associated with the Account
Name field in the account form so that it gets executed only when you change the account name value.
The code performs a case-insensitive search for "Contoso" in the account name, and if present,
automatically sets values for some fields in the account form.

// Code to run in the attribute OnChange event

[Link] = function (executionContext) {
var formContext = [Link]();

// Automatically set some field values if the account name contains "Contoso"
var accountName = [Link]("name").getValue();
if ([Link]().search("contoso") != -1) {
[Link]("websiteurl").setValue("[Link]
[Link]("telephone1").setValue("425-555-0100");
[Link]("description").setValue("Website URL, Phone and Description set using
custom script.");
}
}

Code to execute on the OnSave event: The code in this section displays an alert dialog box using the
openAlertDialog method. This dialog box displays a message with the OK button; user can close the alert by
clicking OK.
Note that we are not passing in the execution context in this function as its not required to execute
[Link].* methods.

// Code to run in the form OnSave event

[Link] = function () {
// Display an alert dialog
[Link]({ text: "Record saved." });
}

Step 2: Add your JavaScript code in a Script web resource

Now that your code is ready, you want to associate it with events in Customer Engagement. You use Script web
resources in Customer Engagement to upload the script to your Customer Engagement instance, and then
associate it with events.
1. Navigate to your Customer Engagement instance in browser, and go to Settings > Customizations.
2. In the Customization area, choose Customize the System.
3. In the solutions explorer, under Components, choose Web Resources.
4. Choose New to create a web resource.
5. In the new web resource dialog, specify the Name and Display Name for your web resource. For example:
"[Link]" and "Sample: Walkthrough" Script.
6. Select Script (JScript) from the Type drop-down list. You can either upload a file containing your JavaScript
code by selecting Choose File, or select Text Editor and then paste your JavaScript code in the editor.

7. Choose Save to create the web resource containing your JavaScript code.
8. Choose Publish to publish your web resource.

Step 3: Associate Script web resource to a form

Associate the web resource containing your JavaScript code to Customer Engagement forms to be able to
associate functions in your code with events. As the JavaScript code in this walkthrough is targeted at the account
record, we will associate the web resource with the account form.
1. Navigate to your Customer Engagement instance in browser, and go to Sales > Accounts or Service >
Accounts.
2. Open an account record, and select Form to open the form editor.

3. In the form editor, select Form Properties.

4. In the Form Properties dialog box, under the Events tab, click Add to search and add your web resource.
5. In the next dialog box, search for your web resource name, select it, and then click Add to add it as a
JavaScript library for the account form.

This makes the web resource available to be selected under the Event Hadlers section in the Form Properties
dialog. Remember that we have three functions in our JavaScript code to be associated with approprite events in
the form.
1. Under the Event Handlers section, select Form as the control and OnLoad as the Event; click Add to add
an event handler for the OnLoad event.
2. In the Handler Properties dialog box:
Select the name of your web resource from the Library drop-down list, and specify
[Link] in the Function field. The function name is [Namespace].[Function] from your
JavaScript code.
Select Pass execution context as first parameter to pass in the execution context as a parameter
to this function. If you review the function definition in the code, we are passing an
executionContext object to our function definition, and selecting this option wires them up.

3. Click OK to return to the Form Properties diaog box.

4. Under the Event Handlers section, select OnSave as the Event this time, and click Add to add an event
handler for the Form OnSave event.

5. In the Handler Properties dialog box, select the name of your web resource from the Library drop-down
list, and specify [Link] in the Function field. We won't pass the execution context to the
function this time as the [Link] function code does not require it.

6. Click OK to return to the Form Properties diaog box.

7. Under the Event Handlers section, select Account Name as the control and OnChange as the event; click
Add to add an event handler for the OnChange event.
8. In the Handler Properties dialog box:
Select the name of your web resource from the Library drop-down list, and specify
[Link] in the Function field.
Select Pass execution context as first parameter to pass in the execution context as a parameter
to this function. If you review the function definition in the code, we are passing an
executionContext object to our function definition, and selecting this option wires them up.

9. Click OK to return to the Form Properties diaog box.

10. Click OK in the Form Properties diaog box to return to the form editor.
11. Click Save to save the changes to the form.
12. Click Publish to publish the form changes.
Thats it! You have completed the steps to configure the account form to use custom business logic specified in
your JavaScript code.

Test your JavaScript code

Its recommended that you refresh your browser for the changes to take effect in your Customer Engagement
instance. To test custom business logic you configured in this walkthrough:
1. Sign in to your Customer Engagement instance.
2. Browse to Accounts, and try to open or create a new account. In this case, we will open an existing account
to load the account form. You will see a notification conytaining your user name that will automatically
disappear in 5 seconds.

3. Edit the account name to add "Contoso" in the name and move to the next field by pressing TAB. This will
fire the OnChange event, and will automatically update the Phone, Website and Description fields with
the value specified in the code.
4. Finally clicking Save will fire the OnSave event, and will display the alert dialog with a message that you
configured in your code. Click OK to close the alert.

Complete sample code used in the walkthrough

// A namespace defined for the sample code
// As a best practice, you should always define
// a unique namespace for your libraries
var Sdk = [Link] || {};
(function () {
// Define some global variables
var myUniqueId = "_myUniqueId"; // Define an ID for the notification
var currentUserName = [Link]().[Link]; // get current user name
var message = currentUserName + ": Your JavaScript code in action!";

// Code to run in the form OnLoad event

[Link] = function (executionContext) {
var formContext = [Link]();

// display the form level notification as an INFO

[Link](message, "INFO", myUniqueId);

// Wait for 5 seconds before clearing the notification

[Link](function () { [Link](myUniqueId); }, 5000);
}

// Code to run in the attribute OnChange event

[Link] = function (executionContext) {
var formContext = [Link]();

// Code to run in the form OnSave event

[Link] = function () {
// Display an alert dialog
[Link]({ text: "Record saved." });
}
}).call(Sdk);
Debug your JavaScript code for Customer
Engagement
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Each browser provides some kind of debugging extension. Microsoft Edge and Internet Explorer provide F12
Developer Tools you can use to debug scripts in Customer Engagement. The F12 Developer Tools can be opened
by pressing F12 when viewing a page using Microsoft Edge or Internet Explorer. For more information, see Using
the F12 developer tools guide.
For Google Chrome, press F12 to open developer tools. Firebug is a popular browser extension for web
development using Mozilla Firefox. For Apple Safari, you must first select the Show Develop menu in menu bar in
Advanced Preferences. Then you can select Show Web Inspector from the Develop menu.
When you use JavaScript libraries in Customer Engagement, your libraries are loaded with the web page. It can
sometimes be difficult to isolate your specific library in the debugging environment. When using debugging tools
in Microsoft Edge, on the Debugger tab, click on the folder icon at the top-left corner, and expand the available
scripts and find the one with the name that corresponds to the name of your JavaScript web resource, such as the
new_myCustomJavaScript.js web resource shown below. You can also search for your JavaScript library by
typing the file name in the search box.

Debugging tools for different browsers have similar capabilities. Once you have found your library, you can set a
break point and recreate the event that should cause your code to run.
Also look at the following blog post on our team blog site for more ideas on debugging your JavaScript code: Blog:
Debugging custom JavaScript code in CRM using browser developer tools.

Select appropriate frame to debug your code

Customer Engagement forms are composed of several frames. For the code to work in the Console of the browser
developer tools, you must select the appropriate frame.
For the web client forms, select the frame named ClientApiWrapper.
For the new Unified Interface forms, select the frame named ClientApiFrame_[n] where n is the internal page
ID. You should select the frame with the highest value for [n].

Write messages to the console

Using the [Link] method when debugging JavaScript is still a common way to troubleshoot code in the
application. But now that all modern browsers provide easy access to debugging tools, it is not a best practice,
especially when others might be using the application you are debugging.
Consider writing your messages to the console instead. The following is a small function you can add to your
libraries that you can use to send any messages you want to view to the console when it is open.

function writeToConsole(message)
{
if (typeof console != 'undefined') {
[Link](message);
}
}

Unlike using the alert method, if you forget to remove any code that uses this function, people using the application
will not see your messages.
Best practices: Client scripting in Customer
Engagement
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

These are some of the best practice tips you could consider while writing your JavaScript code for Customer
Engagement.

Define unique JavaScript function names

When you write functions that will be used in JavaScript libraries, your functions may be loaded into a form with
other JavaScript libraries. If another library contains a function that has the same name as a function you provide,
whichever function is loaded last is defined for the page. To avoid having your functions overwritten by functions in
another library, you should make sure that your functions have unique names. You can use of the following
strategies:
Unique function prefix: Define each of your functions using the standard syntax with a consistent name
that includes a unique naming convention, as shown in the following example.

function MyUniqueName_performMyAction()
{
// Code to perform your action.
}

Namespaced library names: Associate each of your functions with a JavaScript object to create a kind of
namespace to use when you call your functions as shown in the following example.

//If the MyUniqueName namespace object isn’t defined, create it.

if (typeof (MyUniqueName) == "undefined")
{ MyUniqueName = {}; }
// Create Namespace container for functions in this library;
[Link] = {
performMyAction: function(){
// Code to perform your action.
//Call another function in your library
[Link]();
},
anotherAction: function(){
// Code in another function
}
};

Then when you use your function you can specify the full name. The following example shows this.

[Link]();

If you call a function within another function you can use the this keyword as a shortcut to the object that
contains both functions. However, if your function is being used as an event handler, the this keyword will
refer to the object that the event is occurring on.
Avoid using unsupported methods
On the Internet, you can find many examples or suggestions that describe using unsupported methods. These may
include leveraging undocumented internal function for page controls. These methods may work but because they
are not supported, you can’t expect that they will continue to work in future versions of Microsoft Dynamics 365.

Avoid using jQuery for form scripts

We do not recommend using jQuery in form scripts and ribbon commands. Most of the benefit provided by
jQuery is that it allows for easy cross-browser manipulation of the DOM. This is explicitly unsupported within form
scripts and ribbon commands. Restrict your scripts to use the objects/methods avaailable in the Xrm object model.
If you decide to use the remaining capabilities of jQuery that are useful with Customer Engagement and include
the ability to use $.ajax, consider the following:
For best performance, don’t load jQuery in the page if you do not need it.
Using $.ajax to perform requests against the Customer Engagement web services is supported, but there are
alternatives. The alternative to using $.ajax is to use the browsers XMLHttpRequest object directly. The
jQuery $.ajax method is just a wrapper for this object. If you use the native XMLHttpRequest object directly,
you do not need to load jQuery.
Each version of jQuery that is loaded in a page can be a different version. Different versions of jQuery have
different behaviors and these can cause problems when multiple versions of jQuery are loaded on the same
page. There is a technique to mitigate this, but it depends on editing the jQuery library and any other libraries
that depend on jQuery.

Write your code for multiple browsers

Dynamics 365 for Customer Engagement supports mutiple browsers. You should make sure that any scripts that
you use will work with all supported browsers. Most of the significant differences between Internet Explorer and
other browser have to do with HTML and XML DOM manipulation. Because HTML DOM manipulation is not
supported, if script logic is only performing supported actions and using the Xrm object model, the changes
required to support other browsers could be small.
Client API Reference for Customer Engagement
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This section contains reference documentation for client API object model that can be used with JavaScript
libraries.

IMPORTANT
The Client API object model also contains the [Link] namespace, and use of the objects/methods in this namespace
isn’t supported. These objects, and any parts of the HTML Document Object Model (DOM), are subject to change without
notice. We recommend that you don’t use these functions or any script that depends on the DOM.

Also, while debugging, you may find methods and objects in the Client API object model that aren’t documented. Only
documented objects and methods are supported.

The topics under this section are organized as follows:

Starts with reference for all the events, collections, and the execution context object.
Continues on to provide information about methods for attributes and controls in Customer Enagagement
that are actually collections that appear under different objects in the Client API object model.
Provides reference for properties and methods for the formContext and gridContext objects.
Finally provides reference for namespaces in the Xrm object model.
Related topics
Client scripting in Customer Engagement using JavaScript
Understand the Client API object model
Developer Guide for Dynamics 365 Customer Engagement
Events (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Events occur in Custom Engagement forms and grids whenever a form or grid loads, data is changed, or saved.
You execute your JavaScript code by associating it an events so that it is executed when the event occurs. More
information: Events in forms and grids

Attribute event
OnChange

Form events
OnLoad
OnSave

Form data event

OnLoad

Grid and subgrid events

OnChange
OnLoad
OnRecordSelect
OnSave

IFRAME control event

OnReadyStateComplete

Knowledge base search control events

OnResultOpened
OnSelection
PostSearch

Lookup control event

PreSearch

Process events
OnProcessStatusChange
OnStageChange
OnStageSelected
Tab event
TabStateChange
Related topics
Events in forms and grids
Attribute OnChange Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnChange event occurs in the following situations:
Data in a form field has changed and focus is lost. There is an exception to this behavior that applies to Two-
Option (Boolean) fields that are formatted to use radio buttons or check boxes. In these cases the event occurs
immediately.
Data changes on the server are retrieved to update a field when the form is refreshed, such as after a record is
saved.
The [Link] method is used.
All fields support the OnChange event. Data in the field is validated before and after the OnChange event.
The OnChange event does not occur if the field is changed programmatically using the [Link] method.
If you want event handlers for the OnChange event to run after you set the value you must use the
[Link] attribute. fireOnchange method in your code.

NOTE
Although the Status field supports the OnChange event, the field is read-only on the form so the event cannot occur
through user interaction. Another script could cause this event to occur by using the fireOnchange method on the field.

Methods supported for this event

There are three methods you can use to work with the OnChange event for an attribute:
addOnChange
fireOnChange
removeOnChange
Related topics
attributes (Client API reference)
Form OnLoad Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The form OnLoad event occurs after the form has loaded. It cannot prevent the window from loading. Use the
OnLoad event to apply logic about how the form should be displayed, to set properties on fields, and interact with
other page elements.
When the Microsoft Dynamics 365 for tablets client is disconnected, the OnLoad event is the only event that will
occur.
Form OnSave Event (Client API reference) in
Dynamics 365 Customer Engagement
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnSave event occurs when:
The user clicks the Save icon in the lower right corner of the form, even when there is no changed data to be
saved.
Code executes the [Link] method, even when there is no changed data to be saved.
The user navigates away from the form and there is unsaved data in the form.
The auto-save option is enabled, 30 seconds after data has changed and there is unsaved data in the form.
Code executes the [Link] method and there is unsaved data in the form.
Code executes the [Link] method passing a true value as the first parameter and there is
unsaved data in the form.
To determine which button was clicked to perform the save, use the getSaveMode method.
You can cancel the save action by using the preventDefault method within the event arguments object. The
preventDefault method which is accessible by using the getEventArgs method that is part of the execution context.
Execution context is automatically passed to the form event handler.
Related topic
Grid OnSave Event
Form data OnLoad Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs whenever form data is loaded, specifically:
On initial page load
When the page data is explicitly refreshed using [Link] method.
When the data is refreshed on a page on saving a record, if there are any changes.
Use the [Link] and [Link] methods to manage event handlers
for this event.
Grid OnChange Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnChange event occurs when a value is changed in a cell in the editable grid and the cell loses focus. This
event can also occur when an attribute value is updated using the setValue method.
Grid OnRecordSelect Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnRecordSelect event occurs when a single row (record) is selected in the editable grid. This event won't occur
if a user selects different cells in the same row, or selects multiple rows.
Grid OnSave Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnSave event occurs before sending the updated information to the server, and when any of the following
occurs:
There is a change in the record selection.
The user explicitly triggers a save operation using the editable grid’s save button.
The user applies a sort, filter, group, pagination, or navigation operation from the editable grid while there are
pending changes.
Some important points to consider for the OnSave event:
If a user edits multiple columns of the same record in sequence, the OnSave event will only be fired once to
ensure optimal performance and form behavior compatibility.
Editable grid and the parent form have separate save buttons. Clicking the save button in one will not save
changes in the other.
Editable grid does not save pending changes when navigation operations are performed outside of its context.
If the control has unsaved data, that data may be lost. Consequently, the OnSave event may not fire. For
example, this could happen when navigating to a different record using a form lookup field or through the
ribbon.
Pressing the refresh button in the editable grid causes it to discard any pending changes, and the OnSave event
won't be fired.
Editable grid control does not implement an auto-save timer. Editable grid suppresses duplicate detection rules.
Related topic
Form OnSave Event
OnProcessStatusChange Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when the status of a process instance changes.
Use the [Link] method to add event handlers for this event
and the [Link] method to remove them.
IFRAME OnReadyStateComplete Event (Client API
reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The OnReadyStateComplete event indicates that the content of the IFRAME has loaded and can be accessed in code.
Use this event when referencing IFRAME controls within your scripts.
OnResultOpened Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when a knowledge base article is opened in the knowledge base search control in line or
through the pop-out action. Use the addOnResultOpened and removeOnResultOpened methods to manage
event handlers for this event.
OnSelection Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when a knowledge base article is selected in the knowledge base search control.
Use the addOnSelection and removeOnSelection methods to add and remove event handlers respectively for this
event.
OnStageChange Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when the stage of a business process flow control changes. This event occurs when the user
clicks the Next Stage or Move to previous stage buttons in the user interface or when a developer uses the
[Link] or [Link] methods. You can’t cancel the
stage change using code in a handler for this event.
An execution context object is passed to event handlers for this event. You can use the getEventArgs method to
retrieve an object that has the following methods:
getDirection: Returns a string that is either “next” or “previous” to show the direction of the stage change.
getStage: Returns a stage object. Except when the navigation moves to a new entity, the stage returned
represents the destination stage object,that is, the next active stage. When the navigation moves to a new
entity, the stage is the stage being navigated from, that is, the previous active stage object. More information:
Stage methods.

Methods supported for this event

[Link] method to add event handlers for this event.
[Link] method to remove event handlers for this event.
OnStageSelected Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when a stage of a business process flow control is selected. You can’t cancel the stage selection
using code in a handler for this event.
You can use the getEventArgs method to retrieve an object that has the following method:
getStage: Returns a stage object representing the selected stage. More information: Stage methods.

Methods supported for this event

[Link] method to add event handlers for this event.
[Link] method to remove event handlers for this event.
PostSearch Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when the search is complete in a knowledge base search control, and the results are displayed.
Use the addOnPostSearch and removeOnPostSearch methods to manage event handlers for this event.
Lookup Control PreSearch Event (Client API
reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs just before the Lookup control launches a dialog to search for records. There is no UI to set
event handlers for this event. You must use the addPreSearch and removePreSearch methods on the lookup
control to add or remove event handlers for this event.
Use this event with other Lookup control methods to change the results displayed in a lookup based on the form
data just before the lookup control shows search results for a user to choose from.

Related topics
addCustomFilter
Subgrid OnLoad Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs every time the subgrid refreshes. This includes when users sort values in subgrid by clicking the
column headings.
Use the [Link] and [Link] methods to manage event handlers, usually in
the form Onload event.
TabStateChange Event (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

This event occurs when the DisplayState of the tab changes due to user interaction or when the setDisplayState
method is applied in code.
Use this event when you want to change the src property of an IFRAME within the tab. If you set the [Link]
property in the OnLoad event for an IFRAME within a collapsed tab, the value will be overwritten when the tab is
expanded.
Use the addTabStateChange method to add event handlers for this event and the removeTabStateChange method
to remove them.
Collections (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Collections are structures to provide access to data that represent an array, but without the ability to modify the
data in the array. More information: Collections in formContext object model
These methods are available to all the collections in the formContext object model.

METHOD DESCRIPTION

forEach Applies the action contained in a delegate function.

get Get one or more objects from the collection depending on

the arguments passed.

getLength Gets the count of items in the collection.

Related topics
Client API form context
forEach method for collections (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Applies the action contained in a delegate function.

Syntax
[Link](delegate function(attribute, index))

Parameters
Delegate function with parameters for attribute and index. |
Related topics
Collections in Client API
get
getLength
get method for collections (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Get one or more objects from the collection depending on the arguments passed.

Syntax
[Link]([String][Number][delegate function(attribute, index)])

Parameters
PARAMETER RETURN VALUE RETURN TYPE

None All the objects in the collection Array

String The object where the name matches Object

the argument

The objects returned in the

[Link]
namespace don’t contain names. So,
using the string parameter for this
method returns no objects.

Number The object where the index matches the Object

number

delegate function(attribute, index) Any objects that cause the delegate Array
function to return true.

Related topics
Collections in Client API
forEach
getLength
getLength method for collections (Client API
reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the count of items in the collection.

Syntax
[Link]()

Return value
Type: Number
Description: Count of items in the collection.
Related topics
Collections in Client API
forEach
get
GetGlobalContext function and
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Use the GetGlobalContext function when programming with web resources to gain access to the global context
information such as the information specific to the client, organization or user for your Customer Engagement
instance.
To get access to the GetGlobalContext function in your HTML web resource, include a reference to
[Link].

NOTE
Including a reference to [Link] does not make the Xrm object available in HTML web resources.
Therefore, scripts containing Xrm.* methods aren’t supported in HTML web resources. [Link].* will work if the
HTML web resource is loaded in a form container. However, for other places, such as loading an HTML web resource as part of
the SiteMap, [Link].* also won’t work.

GetGlobalContext function
The GetGlobalContext function returns the same context object as returned by the
[Link] method, which implies that the context object will have the same properties and
methods as available for [Link]. More information: [Link]

[Link]
You must include a reference to the [Link] page located at the root of the web resources
directory to be able to use the GetGlobalContext function.
If you are not using backslash characters in HTML web resource names to simulate a folder structure, you
can include this script by directly referring to it. For example:

<head>
<title>HTML Web Resource</title>
<script src="[Link]" type="text/javascript" ></script>

</head>

If you are using backslash characters in HTML web resource names to simulate a directory structure, you
must reflect this in your script element. The following example is for an HTML web resource named
sdk_/[Link] and a JavaScript web resource named sdk_/Scripts/[Link] with a CSS web
resource named sdk_/Styles/[Link].
<head>
<title>HTML Web Resource</title>
<script src="../[Link]" type="text/javascript" ></script>

<script src="Scripts/[Link]" type="text/javascript"></script>

NOTE
Using a relative path including the root WebResources folder, for example, /WebResources/[Link], is not
recommended because it can cause the page to lose organization context in a multi-tenant environment.

The [Link] page will include some global event handlers. These event handlers will cancel
the onselectstart, contextmenu, and ondragstart events.
Related topics
[Link]
Understand Client API object model
Web resources for Customer Engagement
Execution context (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The execution context defines the event context in which your code executes. More information: Client API
execution context.
The execution context object provides the following methods.

METHOD DESCRIPTION

getDepth Returns a value that indicates the order in which this handler
is executed.

getEventArgs Returns an object with methods to manage the OnSave

event.

getEventSource Returns a reference to the object that the event occurred on.

getFormContext Returns a reference to the form or an item on the form

depending on where the method was called.

getSharedVariable Retrieves a variable set using the setSharedVariable method.

setSharedVariable Sets the value of a variable to be used by a handler after the

current handler completes.

Related topics
Client API execution context
Save event arguments
Understand Client API object model
getDepth (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value that indicates the order in which this handler is executed.

Syntax
[Link]()

Return value
Type: Number
Description: The order in which this handler is executed. The order begins with 0.
Related topics
Execution context
getEventArgs (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns an object with methods to manage the Save event.

Syntax
[Link]()

Return value
Type: Object
Description: See Save Event Arguments.
Related topics
Execution context
getEventSource (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a reference to the object that the event occurred on.

Syntax
[Link]()

Return value
Type: Object
Description: Returns the object from the Xrm object model that is the source of the event, not an HTML DOM
object. For example, in an OnChange event, this method returns the [Link] attribute object that
represents the changed attribute.
Related topics
Execution context
getFormContext (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a reference to the form or an item on the form depending on where the method was called.

Syntax
[Link]()

Return value
Type: Object
Description: Returns a reference to the form or an item on the form such as editable grid depending on where the
method was called. This method enables you to create common event handlers that can operate either on a form or
an item on the form depending on where its called.

Example
The following sample code demonstrates how you can create a method that sets notification on a form field or
editable grid cell depending on where you registered the script (Field OnChange event or editable grid OnChange
event):

function commonEventHandler(executionContext) {
var formContext = [Link]();
var telephoneAttr = [Link]('telephone1');
var isNumberWithCountryCode = [Link]().substring(0,1) === '+';

// telephoneField will be a form control if invoked from a form OnChange event;

// telephoneField will be a editable grid GridCell object if invoked from editable grid OnChange event.
var telephoneField = [Link](0);

if (!isNumberWithCountryCode) {
[Link]('Please include the country code beginning with ‘+’.',
'countryCodeNotification');
}
else {
[Link]('countryCodeNotification');
}
}

Related topics
Execution context
Form context
getSharedVariable (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Retrieves a variable set using the setSharedVariable method.

Syntax
[Link](key)

Parameters
key
Type: String
Description: The name of the variable.

Return value
Type: Object
Description: The specific type depends on what the value object is.
Related topics
setSharedVariable
Execution context
setSharedVariable (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the value of a variable to be used by a handler after the current handler completes.

Syntax
[Link](key, value)

Parameters
key: String: The name of the variable
Value: Object. The values to set

Return value
Type: Object
Description: The specific type depends on what the value object is.
Related topics
getSharedVariable
Execution context
Save event arguments (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

When the form OnSave event occurs, you can use the getEventArgs method of the execution context object to
retrieve an object that contains methods you can use to manage the save event.

METHOD DESCRIPTION

getSaveMode Returns a value indicating how the save event was initiated by
the user.

isDefaultPrevented Returns a value indicating whether the save event has been
canceled because the preventDefault method was used in this
event hander or a previous event handler.

preventDefault Cancels the save operation, but all remaining handlers for the
event will still be executed.

Related topics
Client API execution context
Execution context methods
getSaveMode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value indicating how the save event was initiated by the user.

Syntax
[Link]().getSaveMode()

Return Value
Type: Number
Description: The following table describes the supported values returned to detect different ways entity records
may be saved by the user.

VALUE SAVE MODE ENTITY

1 Save All

2 Save and Close All

5 Deactivate All

6 Reactivate All

7 Send Email

15 Disqualify Lead

16 Qualify Lead

47 Assign User or Team owned entities

58 Save as Completed Activities

59 Save and New All

70 Auto Save All

Remarks
This method is essential if you want to enable auto-save for most forms in an organization but disable it for specific
forms.

Example
The following code registered for the OnSave event with the execution context passed to it will prevent any saves
that initiate from an auto-save but allow all others. With auto-save enabled, navigating away is equivalent to Save
and Close. This code will prevent any saves that are initiated by the 30 second timer or when people navigate away
from a form with unsaved data.

function preventAutoSave(executionContext) {
var eventArgs = [Link]();
if ([Link]() == 70 || [Link]() == 2) {
[Link]();
}
}

To save a record the user must click the Save icon at the bottom of the form or a custom Save command needs to
be added to the command bar.
Related topics
isDefaultPrevented
preventDefault
isDefaultPrevented (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value indicating whether the save event has been canceled because the preventDefault method was used
in this event hander or a previous event handler.

Syntax
[Link]().isDefaultPrevented();

Return Value
Type: Boolean
Description: true if the save event has been canceled because the preventDefault method was used; false
otherwise.
Related topics
getSaveMode
preventDefault
preventDefault (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Cancels the save operation, but all remaining handlers for the event will still be executed.

Syntax
[Link]().preventDefault();

Related topics
getSaveMode
isDefaultPrevented
Attributes (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Attributes contain data in the Customer Engagement form or grids. Use the [Link]
collection or the [Link] shortcut method to access a collection of attributes. For more
information about collections, see Collections (Client API reference).
To access an attribute within the collection, you pass either the name (string) or the index value (number) of the
attribute as an argument to the method. For example: [Link](arg)
Attributes are categorized by type. You can determine the type of an attribute by using the getAttributeType
method. Certain attribute methods are only available for specific types of attributes.
This topic provides information about the methods available per attribute type.

All attribute types

controls getName isValid
addOnChange getParent removeOnChange
fireOnChange getRequiredLevel setRequiredLevel
getAttributeType getSubmitMode setSubmitMode
getFormat getUserPrivilege setValue
getIsDirty getValue

Boolean attribute type

In addition to the methods available for all attribute types as explained ealier, the following method is available
only for the boolean attribute:
getInitialValue

Lookup attribute type

In addition to the methods available for all attribute types as explained ealier, the following method is available
only for the lookup attribute:
getIsPartyList

MultiSelectOptionSet and OptionSet attribute types

In addition to the methods available for all attribute types as explained ealier, the following methods are available
only for the multiselectoption and optionset attributes:

User Full Name fullname

Address address1_composite

Other Address address2_composite

Quote Bill To Address billto_composite

Ship To Address shipto_composite

Order Bill To Address billto_composite

Ship To Address shipto_composite

Invoice Bill To Address billto_composite

Ship To Address shipto_composite

Composite attributes in the web application

When fields for composite attributes are added to a main form, the web application will show just the composite
attribute. When someone edits the field, a flyout appears showing the individual attributes that comprise the
composite attribute.
For example, the Address field on a Contact form is a composite attribute. Clicking the Address field dispays a
flyout with individual attributes that comprise the composite attribute.

Although not explicitly added to the form in the form editor, each of the attributes that are part of the attribute are
available to the form. Although you can read the value of the composite value using getValue, you can’t use
setValue to change the value of the composite attribute directly; you must set one or more of the attributes
referenced by the composite attribute.
You can access the individual constituent controls displayed in the flyout by name. These controls use the following
naming convention: <composite control name>_compositionLinkControl_<constituent attribute name>.
To access just the address_line1 control in the address1_composite control, you would use:
[Link]("address1_composite_compositionLinkControl_address1_line1")

Composite attributes in mobile clients

The mobile client for Dynamics 365 Customer Engagement use the same form definitions used for the entities that
have composite attributes but it interprets them differently. If a composite attribute is found in the form definition,
it will show all the attributes that are part of the composite attribute in that section of the form. There is no need
for a flyout because all the fields are visible. You can write scripts for the form accessing each of the individual
attributes just as if they had been individually added to the form. However, the actual composite control will not be
present in the Dynamics 365 mobile clients page.

Mitigate the differences

If you want to access the fullname field for the Contact, Lead, or User entities, using the
[Link] method is an easy way to get the value for this attribute
without referencing it directly. This method works for both the web application and Dynamics 365 mobile clients.
If you have code that needs to read the value of one of the address composite attributes, to work with both clients,
you need to separate the code using the getClient method as shown in the following function that will display the
formatted address using the [Link] method in either the main web application or the
mobile apps version of the same form.

function showAddressDialog(executionContext) {
var address1_compositeValue;
var formContext = [Link]();
if ([Link]().[Link]() != "Mobile") {
address1_compositeValue = [Link]("address1_composite").getValue();
}
else {
var address1_line1 = [Link]("address1_line1").getValue();
var address1_line2 = [Link]("address1_line2").getValue();
var address1_line3 = [Link]("address1_line3").getValue();
var address1_city = [Link]("address1_city").getValue();
var address1_stateorprovince = [Link]("address1_stateorprovince").getValue();
var address1_postalcode = [Link]("address1_postalcode").getValue();
var address1_country = [Link]("address1_country").getValue();

// Achieve equivalent formatting

//address1_line1
//address1_line2
//address1_line3
//address1_city, address1_stateorprovince address1_postalcode
//address1_country

var addressText = "";

if (address1_line1 != null) {
addressText += address1_line1 + "\n";
}
if (address1_line2 != null) {
addressText += address1_line2 + "\n";
}
if (address1_line3 != null) {
addressText += address1_line3 + "\n";
}
if (address1_city != null) {
addressText += address1_city + ", ";
}
if (address1_stateorprovince != null) {
addressText += address1_stateorprovince + " ";
}
if (address1_postalcode != null) {
addressText += address1_postalcode + "\n";
}
addressText += address1_country;

address1_compositeValue = addressText;
}
[Link]({ text: address1_compositeValue });
[Link](address1_compositeValue);
}
Related topics
Attributes
addOnChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a function to be called when the OnChange event occurs.

Attribute types supported

All

Syntax
[Link](arg).addOnChange(myFunction)

Parameters
PARAMETER NAME TYPE DESCRIPTION

myFunction Function reference Specifies the function to be executed on

the attribute OnChange event. The
execution context is automatically
passed as the first parameter to this
function.

All

Syntax
[Link](arg).getFormat()

Return Value
This method will return one of the following string values or "null":
date
datetime
duration
email
language
none
phone
text
textarea
tickersymbol
timezone
url

NOTE
This format information generally represents the format options of the application field. Format options for Boolean fields are
not provided.

The following table lists the format string values to expect for each type of attribute schema type and format option.

APPLICATION FIELD TYPE FORMAT OPTION ATTRIBUTE TYPE FORMAT VALUE

Date and Time Date Only datetime date

Date and Time Date and Time datetime datetime

Whole Number Duration integer duration

Single Line of Text E-mail string email

APPLICATION FIELD TYPE FORMAT OPTION ATTRIBUTE TYPE FORMAT VALUE

Whole Number Language optionset language

Whole Number None integer none

Single Line of Text Text Area string textarea

Single Line of Text Text string text

Single Line of Text Ticker Symbol string tickersymbol

Single Line of Text Phone string phone

Whole Number Time Zone optionset timezone

datetime Date
To get the string version of a date using the Microsoft
Dynamics 365 user’s locale preferences, use the format and
localeFormat methods. Other methods will format dates using
the operating system locale rather than the user’s Microsoft
Dynamics 365 locale preferences.

decimal Number

Double Number

integer Number

lookup Array
An array of lookup objects.

NOTE: Certain lookups allow for multiple records to be

associated in a lookup, such as the To: field for an email entity
record. Therefore, all lookup data values use an array of lookup
objects – even when the lookup attribute does not support
more than one record reference to be added.

Each lookup has the following properties:

- entityType: String. The name of the entity displayed in the
lookup.
- id: String: The string representation of the GUID value for the
record displayed in the lookup.
- name: String: The text representing the record to be
displayed in the lookup.
ATTRIBUTE TYPE RETURN TYPE

memo String

money Number

optionset Number

string String

Related topic
setValue (Client API reference)
isValid (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a boolean value to indicate whether the value of an attribute is valid.

Attribute types supported

All

Syntax
[Link](arg).isValid();

Return Value
Type: Boolean.
Description: true if the attribute value is valid; false otherwise.
removeOnChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes a function from the OnChange event hander for an attribute..

Attribute types supported

All

Syntax
[Link](arg).removeOnChange(myFunction)

Parameters
PARAMETER NAME TYPE DESCRIPTION

myFunction Function reference Specifies the function to be removed

from the OnChange event.

Related topics
addOnChange
Attribute OnChange Event
setPrecision (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the number of digits allowed to the right of the decimal point.

Attribute types supported

Money, decimal, double, and integer

Syntax
[Link](arg).setPrecision(value);

Parameter
PARAMETER NAME TYPE DESCRIPTION

value Number Number of digits allowed to the right of

the decimal point.

Related topics
getPrecision
setRequiredLevel (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets whether data is required or recommended for the attribute before the record can be saved.

IMPORTANT
Reducing the required level of an attribute can cause an error when the page is saved. If the attribute is required by the
server, an error will occur if there is no value for the attribute.

Attribute types supported

All

Syntax
[Link](arg).setRequiredLevel(requirementLevel)

Parameters
Type: String.
Description: Set the level to one of the following values:
none
required
recommended
Related topic
getRequiredLevel (Client API reference)
setSubmitMode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets whether data from the attribute will be submitted when the record is saved.

Attribute types supported

All

Syntax
[Link](arg).setSubmitMode(mode)

Parameters
Type: String.
Description: Set one of the following mode values:
always: The data is always sent with a save.
never: The data is never sent with a save. When this is used, the field(s) in the form for this attribute cannot be
edited.
dirty: Default behavior. The data is sent with the save when it has changed.

Remarks
Use this method to control when data for an attribute is submitted when a record is created or saved. For example,
you may have a field on the form which is only intended to control logic in the form. You are not interested in
capturing the data in it. You might set it so that the data is not saved. Or you may have a Plugin that depends on the
value always being included. You may want to set the attribute so that it will always be included.
Attributes that do not get updated after the initial save of the record, such as createdby, are set so that they will not
be submitted on save. To force an attribute value to be submitted whether it has changed or not, use this method
with the mode parameter set to “always”.
Related topic
getSubmitMode (Client API reference)
setValue (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the data value for an attribute.

Attribute types supported

All

Syntax
[Link](arg).setValue(value)

Parameters
Depends on the type of attribute.

ATTRIBUTE TYPE PARAMETERS TYPE

boolean Boolean

datetime Date

decimal Number

double Number

Integer Number

lookup Array An array of lookup objects.

Certain lookups, known as ‘partylist’ lookups, allow for

multiple records to be associated in a lookup, such as the To:
field for an email entity record. Therefore, all lookup data
values use an array of lookup objects – even when the lookup
attribute does not support more than one record reference to
be added.

Each lookup has the following properties:

- entityType: String. The name of the entity displayed in the
lookup.
- id: String: The string representation of the GUID value for the
record displayed in the lookup. The value should match the
following format: {XXXXXXXX-XXXX-XXXX-XXXX-
XXXXXXXXXXXX}
- name: String: The text representing the record to be
displayed in the lookup.

memo String

money Number
ATTRIBUTE TYPE PARAMETERS TYPE

optionset Number

string String

memo String

money Number

optionset, multiselectoptionset Number

The getOptions method returns option values as strings. You

must use parseInt to convert them to numbers before you can
use those values to set the value of an optionset attribute.
Valid statuscode (Status Reason) options depend on the
current statecode of the record. The statecode (Status) field
cannot be set in form scripts. To understand which statecode
values are valid, refer to the metadata for the attributes. For
custom entities use the Entity Metadata browser. Finally, also
consider any custom state transitions that have been applied
to the field. More information: Define status reason transitions.

String String

A String field with the email format requires that the string
represents a valid email address.

NOTE
Updating an attribute using setValue will not cause the OnChange event handlers to run. If you want the OnChange event
handlers to run you must use fireOnChange in addition to setValue.

When Microsoft Dynamics 365 for tablets is not connected to the server, setValue will not work.

You cannot set the value of composite attributes. More information: Write scripts for composite attributes.

Related topic
getValue (Client API reference)
Controls (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

A control represents an HTML element present on the form. Some controls are bound to a specific attribute,
whereas others may represent unbound controls such as an IFRAME, Web resource, or a sub grid that has been
added to the form.
The control object provides methods to change the presentation or behavior of a control and identify the
corresponding attribute. You access controls using one of the following collections:
[Link]
[Link] [Link]
[Link] [Link]
The [Link] method is a shortcut method to access [Link].
Controls are categorized by type. You can determine the type of a control by using the getControlType method.
Certain control methods are only available for specific types of controls.
This topic provides information about the methods available per control type.

standard control type

These are the methods available for a Standard control.

addNotification getLabel setFocus

clearNotification getName setLabel
getAttribute getParent setNotification
getControlType getVisible setVisible
getDisabled setDisabled

The following methods for the Standard control are deprecated in this release: addOnKeyPress, fireOnKeyPress,
and removeOnKeyPress.

iframe control type

These are the methods available for an IFRAME control.

getControlType getObject setFocus

getDisabled getParent setLabel
getInitialUrl getSrc setSrc
getLabel getVisible setVisible
getName setDisabled

kbsearch (Knowledge base search) control type

These are the methods available for knowledge base search control.
addOnPostSearch getParent removeOnResultOpened
addOnResultOpened getSearchQuery removeOnSelection
addOnSelection getSelectedResults setFocus
getControlType getTotalResultCount setLabel
getDisabled getVisible setSearchQuery
getLabel openSearchResult setVisible
getName removeOnPostSearch

NOTE
When the knowledge base search control is added to the social pane, the name of the control will be
"searchwidgetcontrol_notescontrol". This name can’t be changed.

lookup control type

These are the methods available for a lookup control.

addCustomFilter getDisabled setDisabled

addCustomView getEntityTypes setEntityTypes
addNotification getLabel setFocus
addPreSearch getName setLabel
clearNotification getParent setNotification
getAttribute getVisible setVisible
getControlType removePreSearch
getDefaultView setDefaultView

multiselectoptionset and optionset control types

Both multi-select option set and option set controls have the same set of methods available.

addNotification getDisabled setDisabled

addOption getLabel setFocus
clearNotification getName setLabel
clearOptions getParent setNotification
getAttribute getVisible setVisible
getControlType removeOption

quickform control type

See [Link] for information about methods supported for this control type.

subgrid control type

See Grids and subgrids for information methods supported for this control type.

timelinewall control type

The timeline control is a new control type introduced in Dynamics 365 (online), version 9.0 that presents the
Posts, Activities, and Notes in a unified view. These are the methods available for this control type.
getControlType getParent setFocus
getDisabled getVisible setLabel
getLabel refresh setVisible
getName setDisabled

timer control type

These are the methods available for the timer control.

getControlType getParent setDisabled

getDisabled getState setFocus
getLabel getVisible setLabel
getName refresh setVisible

webresource control type

A web resource control has the same set of methods available as the iframe control. See iframe control type
Related topics
Attributes
addCustomFilter (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds filters to the results displayed in the lookup. Each filter will be combined with any previously added filters as
an “AND” condition.

NOTE
Custom lookup filters are not supported in mobile offline. For information about the mobile offline feature, see Configure
mobile offline synchronization

Control types supported

Lookup

Syntax
[Link](arg).addCustomFilter(filter, entityLogicaName)

Parameters
filter: String. The fetchXml filter element to apply. For example:

entityLogicalName: (Optional) String. If this is set, the filter only applies to that entity type. Otherwise, it
applies to all types of entities returned.

Remarks
This method can only be used in a function in an event handler for the Lookup Control PreSearch Event.

Example
The following code sample is for the Opportunity form Account (parentaccountid) lookup. When the
[Link] function is set in the form Onload event handler, the [Link]
function is added to the PreSearch event for that lookup. Remember to select the option to pass in the execution
context when setting the function in the form Onload event handler. The result is that only accounts with the
Category (accountcategorycode) value of Preferred Customer (1) will be returned.
// A namespace defined for SDK sample code
// You should define a unique namespace for your libraries
var Sdk = [Link] || {};

// set '[Link]' in the Opportunity form onload event handler

[Link] = function (executionContext) {

// get the form context

formContext = [Link]();
[Link]("parentaccountid").addPreSearch([Link]);
}

[Link] = function () {

// Only show accounts with the type 'Preferred Customer'

var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq'
value='1'/></filter>";
[Link]("parentaccountid").addCustomFilter(customerAccountFilter, "account");
}

addPreSearch
formContext
addCustomView (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a new view for the lookup dialog box.

Control types supported

Lookup

Syntax
[Link](arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)

Parameters
viewId: String. The string representation of a GUID for a view.

NOTE
This value is never saved and only needs to be unique among the other available views for the lookup. A string for a
non-valid GUID will work, for example “00000000-0000-0000-0000-000000000001”. It’s recommended that you use
a tool like [Link] to generate a valid GUID.

entityName: String. The name of the entity.

viewDisplayName: String. The name of the view.
fetchXml: String. The fetchXml query for the view.
layoutXml: String. The XML that defines the layout of the view.
isDefault: Boolean: Indicates whether the view should be the default view.

Remarks
This method doesn’t work with Owner lookups. Owner lookups are used to assign user-owned records.
addNotification (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays an error or recommendation notification for a control, and lets you specify actions to execute based on the
notification. When you specify an error type of notification, a red "X" icon appears next to the control. When you
specify a recommendation type of notification, an "i" icon appears next to the control. On Dynamics 365 mobile
clients, tapping on the icon will display the message, and let you perform the configured action by clicking the
Apply button or dismiss the message.

Control types supported

All

Syntax
[Link](arg).addNotification(notification);

Parameters
NAME TYPE REQUIRED DESCRIPTION
notification Object Yes The notification to add. The
object contains the following
attributes:
actions: (Optional)
Array of objects. A
collection of objects
with the following
attributes:
message:
(Optional)
String. The
body message
of the
notification to
be displayed
to the user.
Limit your
message to
100
characters for
optimal user
experience.
actions:
(Optional)
Array of
functions. The
corresponding
actions for the
message.
messages: Array of
Strings. The message
to display in the
notification. In the
current release, only
the first message
specified in this array
will be displayed. The
string that you
specify here appears
as bold text in the
notification, and is
typically used for title
or subject of the
notification. You
should limit your
message to 50
characters for optimal
user experience.
notificationLevel:
String. Defines the
type of notification.
Valid values are
ERROR or
RECOMMENDATION.
uniqueId: String. The
ID to use to clear this
notification when
using the
clearNotification
method.
Return Value
Type: Boolean
Description: Indicates whether the method succeeded.

Remarks
The addNotification method displays a notification with the messages you specified and two standard buttons:
Apply and Dismiss. Clicking Apply executes the action you define; clicking Dismiss closes the notification
message.

Example
The following sample code displays a notification on the Account Name field of the account form to set the
Ticker Symbol if the Account Name field contains "Microsoft", and the ticker symbol is not already set to
"MSFT". Clicking Apply in the notification will set the Ticker Symbol field to "MSFT".

function addTickerSymbolRecommendation(executionContext) {
var formContext = [Link]();
var myControl = [Link]('name');
var accountName = [Link]('name');
var tickerSymbol = [Link]('tickersymbol');

if ([Link]() == 'Microsoft' && [Link]() != 'MSFT') {

OptionSet, MultiSelectOptionSet

Syntax
[Link](arg).clearOptions();

Related topics
addOption
removeOption
getAttribute (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the attribute that the control is bound to.
Controls that aren’t bound to an attribute (subgrid, web resource, and IFRAME ) don’t have this method. An error
will be thrown if you attempt to use this method on one of these controls.

Control types supported

Standard, Lookup, OptionSet

Syntax
[Link](arg).getAttribute();

Return Value
Type: Object
Description: An attribute

Remarks
The constituent controls within a quick view control are included in the controls collection and these controls have
the getAttribute method. However, the attribute is not part of the attribute collection for the entity. While you can
retrieve the value for that attribute using getValue and even change the value using setValue, changes you make
will not be saved with the entity.
The following code shows using the value the contact mobilephone attribute when displayed on an account entity
form using a quick view control named contactQuickForm. This code hides the control when the value of the
attribute is null.

var quickViewMobilePhoneControl =
[Link]("contactQuickForm_contactQuickForm_contact_mobilephone");
if ([Link]().getValue() == null) {
[Link](false);
}

Quick view control

Attributes
getControl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets a control on the form.

Syntax
[Link](arg);

The [Link](arg) method is a shortcut method to access [Link].

Parameter
arg: Optional. You can access a ontrol on a form by passing an argument as either the name or the index value of
the control on a form. For example: [Link]("firstname") or [Link](0)

Return Value
Type: Object or Object collection.
Description: Object if you use the method with parameter; object collection if you use the method without any
parameters.
Related topics
formContext
getControlType (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value that categorizes controls.

Control Types supported

All

Syntax
getControl(arg).getControlType();

Return Value:
Type: String

RETURN VALUE DECSRIPTION

standard A standard control

iframe An IFRAME control

kbsearch A knowledge base search control

lookup A lookup control

multiselectoptionset A multi-select option set control

notes A notes control

optionset An option set control

quickform A quick view control

subgrid A subgrid control

timercontrol A timer control

timelinewall A timeline control (for Unified Interface)

Control types supported

All

Syntax
[Link](arg).getLabel();

Return Value
Type: String
Description: The label of the control.
Related topics
setLabel
getName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name assigned to the control.

Return Value
Type: Number
Description: Returns one of the following values:

VALUE STATE

1 Not Set

2 In progress

3 Warning

4 Violated

5 Success

6 Expired

7 Canceled

8 Paused

Related topics
Controls
getTotalResultCount (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the count of results found in the search control.

Control types supported

knowledge base search control

Syntax
var kbSearchControl = [Link]("<name>");
var searchCount = [Link]();

Return Value
Type: Number
Description: The count of the search result.
getValue (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the latest value in a control as the user types characters in a specific text or number field. This method helps
you to build interactive experiences by validating data and alerting users as they type characters in a control.
The getValue method is different from the attribute getValue method because the control method retrieves the
value from the control as the user is typing in the control as opposed to the attribute getValue method that
retrieves the value after the user commits (saves) the field.

Syntax
[Link](arg).getValue();

Return Value
Type: String
Description: The latest data value for a control.
getVisible (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value that indicates whether the control is currently visible.

Control types supported

All

Syntax
[Link](arg).getVisible();

Return Value
Type: Boolean.
Description: true if the control is visible; false otherwise.
Related topics
setVisible
openSearchResult (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens a search result in the search control by specifying the result number..

Control types supported

knowledge base search control

Syntax
var kbSearchControl = [Link]("<name>");
var openResultStatus = [Link](resultNumber, mode);

Parameter
NAME TYPE REQUIRED DESCRIPTION

resultNumber Number Yes Numerical value specifying

the result number to be
opened. Result number
starts from 1.

mode String No Specify "Inline" or "Popout". If

you do not specify a value
for the argument, the default
("Inline") option is used.

The "Inline" mode opens the

result inline either in the
reading pane of the control
or in a reference panel tab in
case of reference panel. The
"Popout" mode opens the
result in a pop-out window.

Return Value
Type: Boolean
Description: Status of opening the specified search result. Returns 1 if successful; 0 if unsuccessful. The method
will return -1 if the specified resultNumber value is not present, or if the specified mode value is invalid.
refresh (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Refreshes the data displayed in a timelinewall and timer control.

Control types supported

viewId String Yes The ID of the view to be set

Applies to Dynamics 365 (online), version 9.x

Sets the label of the control.

Control types supported

All

Syntax
[Link](arg).setLabel(label);

Parameter
NAME TYPE REQUIRED DESCRIPTION

label String Yes The new label of the control.

Related topics
getLabel
setNotification (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays an error message for the control to indicate that data isn’t valid. When this method is used, a red "X" icon
appears next to the control. On Dynamics 365 mobile clients, tapping on the icon will display the message.

Control types supported

All

Syntax
[Link](arg).setNotification(message,uniqueId);

Parameters
NAME TYPE REQUIRED DESCRIPTION

message String Yes The message to display.

uniqueId String No The ID to use to clear this

string String Yes The URL.

Related topics
getSrc
setVisible (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a value that indicates whether the control is visible.

Control types supported

All

Syntax
[Link](arg).setVisible(bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true to show the

control; false to hide the
control.

Related topics
getVisible
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides properties and methods to work with the data on a form.

Properties
NAME DESCRIPTION

attributes Collection of non-entity data on the form. Items in this

collection are of the same type as the attributes collection, but
they are not attributes of the form entity.
More information: Collections
NOTE: This is supported only for Unified Interface clients.

entity Provides methods to retrieve information specific to the record

displayed on the page, the save method, and a collection of all
the attributes included on the form. Attribute data is limited to
attributes represented by fields on the form.
More information: [Link]

process Provides objects and methods to interact with the business

process flow data on a form.
More information: [Link]

Methods
NAME DESCRIPTION

addOnLoad Adds a function to be called when form data is loaded.

getIsDirty Gets a boolean value indicating whether the form data has
been modified.

isValid Gets a boolean value indicating whether all of the form data is
valid. This includes the main entity and any unbound
attributes.

refresh Asynchronously refreshes and optionally saves all the data of

the form without reloading the page.

removeOnLoad Removes a function to be called when form data is loaded.

save Saves the record asynchronously with the option to set

callback functions to be executed after the save operation is
completed.

Related topics
[Link]
[Link]
addOnLoad (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a function to be called when form data is loaded.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be executed

when the form data loads.
The function will be added to
the bottom of the event
handler pipeline. The
execution context is
automatically passed as the
first parameter to the
function. See Execution
context for more
information.

Related topics
removeOnLoad
Form data OnLoad event
getIsDirty (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets a boolean value indicating whether the form data has been modified.

Syntax
[Link]();

Return Type
Type: Boolean
Description: true if the form data has changed; false otherwise.
Related topics
[Link]
formContext
isValid (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets a boolean value indicating whether all of the form data is valid. This includes the main entity and any unbound
attributes.

Syntax
[Link]();

Return Type
Type: Boolean
Description: true if all of the form data is valid; false otherwise.
Related topics
formContext
refresh (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Asynchronously refreshes and optionally saves all the data of the form without reloading the page.

Syntax
[Link](save).then(successCallback, errorCallback);

Parameter
NAME TYPE REQUIRED DESCRIPTION

save Boolean No true if the data should be

saved after it is refreshed,
otherwise false.

successCallback Function No A function to call when the

operation succeeds.

errorCallback Function No A function to call when the

operation fails.

Related topics
formContext
removeOnLoad (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes a function to be called when form data is loaded.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be removed

when the form data loads.

Related topics
addOnLoad
Form data OnLoad event
save (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Saves the record asynchronously with the option to set callback functions to be executed after the save operation is
completed.
You can also set an object to control how appointment, recurring appointment, or service activity records are
processed.

Syntax
[Link](saveOptions).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

saveOptions Object No An object for specifying

options for saving the
record. The object has
following attributes:

- saveMode: (Optional)
Number. Specify a value
indicating how the save
event was initiated. For a list
of supported values, see the
return value of the
getSaveMode method. Note
that setting the saveMode
does not actually take the
corresponding action; it is
just to provide information
to the OnSave event
handlers about the reason
for the save operation.

- useSchedulingEngine:
(Optional) Boolean. Indicate
whether to use the Book or
Reschedule messages
rather than the Create or
Update messages. This
option is only applicable
when used with
appointment, recurring
appointment, or service
activity records.

successCallback Function No A function to call when the

operation succeeds.
NAME TYPE REQUIRED DESCRIPTION

errorCallback Function No A function to call when the

operation fails. An object
with the following properties
will be passed:

- errorCode: Number. The

error code.

- message: String. A
localized error message.

Related topics
[Link]
formContext
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides properties and methods to retrieve information specific to the record displayed on the page, the save
method, and a collection of all the attributes included in the form. Attribute data is limited to attributes represented
by fields on the form.

Properties
NAME DESCRIPTION

attributes Collection of attributes for a record displayed on the form.

More information: Collections and Attributes.

Methods
NAME DESCRIPTION

addOnSave Adds a function to be called when the record is saved.

getDataXml Returns a string representing the XML that will be sent to the
server when the record is saved. Only data in fields that have
changed are set to the server.

getEntityName Returns a string representing the logical name of the entity for
the record.

getEntityReference Returns a lookup value that references the record.

getId Returns a string representing the GUID value for the record.

getIsDirty Gets a boolean value indicating whether any fields in the form
have been modified.

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

isValid Gets a boolean value indicating whether all of the entity data
is valid.

removeOnSave Removes a function to be called when form data is loaded.

save Saves the record synchronously with the options to close the
form or open a new form after the save is completed.

Related topics
Understand Xrm object model
Controls (Client API reference)
addOnSave (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a function to be called when the record is saved.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be executed

when the record is saved.
The function will be added to
the bottom of the event
handler pipeline. The
execution context is
automatically passed as the
first parameter to the
function. See Execution
context for more
information.

Related topics
removeOnSave
Form OnSave event
getDataXml (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a string representing the XML that will be sent to the server when the record is saved. Only data in fields
that have changed are set to the server.

Applies to Dynamics 365 (online), version 9.x

Gets a boolean value indicating whether all of the entity data is valid.

Syntax
[Link]();

Return Type
Type: Boolean
Description: true if all of the entity data is valid; false otherwise.
Related topics
formContext
removeOnSave (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes a function to be called when form data is loaded.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be removed

for the OnSave event.

Related topics
addOnSave
Form OnSave event
save (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Saves the record synchronously with the options to close the form or open a new form after the save is completed.

Syntax
[Link](saveOption);

Parameters
NAME TYPE REQUIRED DESCRIPTION

saveOption String No Specify options for saving

the record. If no parameter is
included in the method, the
record will simply be saved.
This is the equivalent of
using the Save command.
You can specify one of the
following values:

- saveandclose: This is the

equivalent of using the Save
and Close command.

- saveandnew: This is the

equivalent of the using the
Save and New command.

Example
To open a new form after the save is completed:
[Link]("saveandnew");

Related topics
[Link]
formContext
[Link] (Client API reference)
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides events, methods, and objects to interact with the business process flow data on a form. See
[Link] (Client API reference) for methods to interact with the business process flow control on the
form.

Process events and event handler methods

Use the following events and event handler methods to write scripts for business process flows.

EVENT EVENT HANDLER METHODS

OnProcessStatusChange addOnProcessStatusChange
removeOnProcessStatusChange

OnStageChange addOnStageChange
removeOnStageChange

OnStageSelected addOnStageSelected
removeOnStageSelected

Active Process methods

Use these methods to retrieve information about the active process and set a different process as the active
process.

NAME DESCRIPTION

getActiveProcess Returns a Process object representing the active process.

setActiveProcess Sets a Process as the active process.

Process methods
A process contains the data for a business process flow. Use the methods to access properties of the process.

NAME DESCRIPTION

getId Returns the unique identifier of the process.

getName Returns the name of the process.

getStages Returns a collection of stages in the process.

isRendered Returns a boolean value indicating whether the process is

rendered.
ProcessInstance methods
Use these methods to retrieve information about all the process instances for an entity record and to set a process
instance as the active instance.

NAME DESCRIPTION

getProcessInstances Returns all the process instances for the entity record that the
calling user has access to.

setActiveProcessInstance Sets a process instance as the active instance.

Instance methods
A process instance contains the data for an instance of the business process flow. Use the methods to access
properties of the process instance.

NAME DESCRIPTION

getInstanceId Returns the unique identifier of the process instance.

getInstanceName Returns the name of the process instance.

getStatus Returns the current status of the process instance.

setStatus Sets the current status of the active process instance.

Active Stage methods

Use these methods to retrieve information about the active stage and set a different stage as the active stage.

NAME DESCRIPTION

getActiveStage Returns a Stage object representing the active stage.

setActiveStage Sets a completed stage as the active stage.

Stage methods
A stage contains the data for a stage in a business process flow. Use the methods to access properties of the stage.

NAME DESCRIPTION

getCategory Returns an object with a getValue method which will return

the integer value of the business process flow category.

getEntityName Returns the logical name of the entity associated with the
stage.

moveNext Progresses to the next stage.

movePrevious Moves to the previous stage.

Other useful methods

Use these methods to find information about the stages in the active path, enabled processes, and selected stage.

NAME DESCRIPTION

getActivePath Gets a collection of stages currently in the active path with

methods to interact with the stages displayed in the business
process flow control.

getEnabledProcesses Asynchronously retrieves the business process flows enabled

for an entity that the current user can switch to.
NAME DESCRIPTION

to a named function rather
than an anonymous function
if you may later want to
remove the event handler.

Related topics
removeOnStageSelected
[Link]
removeOnProcessStatusChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes an event handler from the OnProcessStatusChange event.

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction Function reference Yes The function to be removed

from the
OnProcessStatusChange
event.

Related topics
addOnProcessStatusChange
[Link]
removeOnStageChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Removes an event handler from the OnStageChange event.

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction Function reference Yes The function to be removed

from the OnStageChange
event.

Related topics
addOnStageChange
[Link]
removeOnStageSelected (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes an event handler from the OnStageSelected event.

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction Function reference Yes The function to be removed

from the OnStageSelected
event.

Related topics
addOnStageSelected
[Link]
getActiveProcess (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a Process object representing the active process.

Syntax
var activeProcess = [Link]();

Return Value
Type: Process.
Description: The currently active process. See Process methods for the methods to access the properties of the
process returned.
Related topics
setActiveProcess)
[Link]
setActiveProcess (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a Process as the active process.
If there is an active instance of the process, the entity record is loaded with the process instance ID. If there is no
active instance of the process, a new process instance is created and the entity record is loaded with the process
instance ID. If there are multiple instances of the current process, the record is loaded with the first instance of the
active process as per the defaulting logic, that is the most recently used process instance per user.

Syntax
[Link](processId, callbackFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

processInstanceId String Yes The Id of the process to set

as the active process.

callbackFunction Function No A function to call when the

operation is complete. This
callback function is passed
one of the following string
values to indicate whether
the operation succeeded:
- success: The operation
succeeded.
- invalid: The processId isn’t
valid or the process isn’t
enabled.

Related topics
getActiveProcess
setActiveProcessInstance
[Link]
getEnabledProcesses (Client API reference)
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Asynchronously retrieves the business process flows enabled for an entity that the current user can switch to.

Syntax
[Link](callbackFunction(enabledProcesses));

Parameter
NAME TYPE REQUIRED DESCRIPTION

callbackFunction Function Yes The callback function must

accept a parameter that
contains an object with
dictionary properties where
the name of the property is
the Id of the business
process flow and the value of
the property is the name of
the business process flow.

The enabled processes are

filtered according to the
user’s privileges. The list of
enabled processes is the
same ones a user can see in
the UI if they want to
change the process
manually.

Example
The [Link] function in the example uses the [Link]
method to asynchronously retrieve information about business process flows that are enabled for the entity. The
sample passes an anonymous function as the first parameter. This function is executed asynchronously when the
data is returned and the data is passed as the parameter to the anonymous function.
The information about enabled business process flow is provided as a dictionary object where the Id of the process
is the name of the property and the name of the business process flow is the value of the property. The sample
code processes this information and sets the values in a global [Link] array to be accessed by
logic that executes later. The sample also loops through the values in the [Link] array, and uses
the [Link] function to write information about the retrieved business process flows to the console.
NOTE
The [Link] function in the sample JavaScript library must be set as the OnLoad event handler for a form, and the
Pass execution context as the first parameter check box must be selected in the Handler Properties dialog.
Also, this sample just illustrates the use of some of the methods in the [Link] API. It doesn’t represent
using this API to meet a business requirement; it’s only intended to demonstrate how the key property values can be
accessed in code.

//A namespace defined for SDK sample code

//You should define a unique namespace for your libraries
var Sdk = [Link] || {};
(function () {
//A global variable to store information about enabled business processes after they are retrieved
asynchronously
[Link] = [];

// A function to log messages while debugging only

[Link] = function (message) {
if (typeof console != 'undefined')
{ [Link](message); }
};

// Code to run in the OnLoad event

[Link] = function (executionContext) {
// Retrieve the formContext
var formContext = [Link]();

// Retrieve Enabled processes

[Link](function (processes) {
//Move processes to the global [Link] array;
for (var processId in processes) {
[Link]({ id: processId, name: processes[processId] })
}
[Link]("Enabled business processes flows retrieved and added to [Link]
array.");

//Write the values of the [Link] array to the console

if ([Link] < 0) {
[Link]("There are no enabled business process flows for this entity.");
}
else {
[Link]("These are the enabled business process flows for this entity:");
for (var i = 0; i < [Link]; i++) {
var enabledProcess = [Link][i];
[Link]("id: " + [Link] + " name: " + [Link])
}
}

//Any code that depends on the [Link] array needs to be initiated here

});
};

}).call(Sdk);

When you run this sample with the browser developer tools open, the following is an example of the output written
to the console for an entity with multiple business process flows enabled.
Enabled business processes flows retrieved and added to [Link] array.
These are the enabled business process flows for this entity:
id: 7994be68-899e-4a40-8d18-f5c3b6940188 name: Sample Lead Process
id: 919e14d1-6489-4852-abd0-a63a6ecaac5d name: Lead to Opportunity Sales Process

Related topics
setActiveProcessInstance
[Link]
getId (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the unique identifier of the process.

Syntax
var processId = [Link]();

Return Value
Type: String.
Description: Value represents the string representation of a GUID value.
Related topics
[Link]
getName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the process.

Syntax
var processName = [Link]();

Return Value
Type: String.
Description: Name of the process.
Related topics
[Link]
getStages (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a collection of stages in the process.

Syntax
var stageCollection = [Link]();

Returns
Type: Collection.
Description: See Stage methods for the methods to access the properties of the stages returned.
Related topics
[Link]
isRendered (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a boolean value indicating whether the process is rendered.

Syntax
var processRendered = [Link]();

Returns
Type: Boolean.
Description: true if the process is rendered; false otherwise.
Related topics
[Link]
getProcessInstances (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns all the process instances for the entity record that the calling user has access to.

Syntax
[Link](callbackFunction(object));

Parameter
NAME TYPE REQUIRED DESCRIPTION

callbackFunction Function Yes The callback function is

passed an object with the
following attributes and their
corresponding values as the
key: value pair. All returned
values are of String type
except for CreatedOnDate,
which is of Date type.
- CreatedOn (deprecated)
- CreatedOnDate
- ProcessDefinitionID
- ProcessDefinitionName
- ProcessInstanceID
- ProcessInstanceName
- StatusCodeName

The process instances are

filtered according to the
user’s privileges.

Related topics
setActiveProcessInstance
[Link]
setActiveProcessInstance (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a process instance as the active instance.

Syntax
[Link](processInstanceId, callbackFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

processInstanceId String Yes The Id of the process

instance to set as the active
instance.

callbackFunction Function No A function to call when the

operation is complete. This
callback function is passed
one of the following string
values to indicate whether
the operation succeeded:
- success: The operation
succeeded.
- invalid: The
processInstanceId isn’t valid
or the process isn’t enabled.

Related topics
getProcessInstances
[Link]
getInstanceId (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the unique identifier of the process instance.

Syntax
[Link]();

Return Value
Type: String.
Description: Value represents the string representation of a GUID value.
Related topics
[Link]
getInstanceName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the process instance.

Syntax
[Link]();

Return Value
Type: String.
Description: Pocess instance name.
Related topics
[Link]
getStatus (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the current status of the process instance.

Syntax
[Link]();

Return Value
Type: String.
Description:Returns one of the following values: active, aborted, or finished.
Related topics
[Link]
setStatus (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the current status of the active process instance.

Syntax
[Link](status, callbackFunction);

Parameters
NAME TYPE REQUIRED DESCRIPTION

status String Yes The new status. The values

can be active, aborted, or
finished.

callbackFunction Function No A function to call when the

operation is complete. This
callback function is passed
the new status as a string
value.

Type: String.
Description:Returns one of the following values: active, aborted, or finished.
Related topics
[Link]
getActiveStage (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a Stage object representing the active stage.

Syntax
[Link]();

Return Value
Type: Stage.
Description: The currently active stage. See Stage methods for the methods to access the properties of the stage
returned.
Related topics
setActiveStage)
getSelectedStage (Client API reference)
[Link]
setActiveStage (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a completed stage as the active stage.

Syntax
[Link](stageId, callbackFunction);

Parameters
NAME TYPE REQUIRED DESCRIPTION

stageId String Yes The ID of the completed

stage for the entity to make
the active stage.

callbackFunction Function No A function to call when the

operation is complete. This
callback function is passed
one of the following string
values to indicate the status
of the operation:

VALUE REASO N

success The
operation
succeeded.
invalid There are
three
reasons
why this
value may
be
returned:
The
sta
geI
d
par
am
ete
r is
a
non
-
exis
tent
sta
ge
ID
val
ue.
The
acti
ve
sta
ge
isn’
t
the
sel
ect
ed
sta
ge.
The
rec
ord
has
n’t
bee
n
sav
ed
yet.

unreachabl The stage

e exists on a
different
path.

dirtyForm This value

will be
returned if
the data in
the page is
not saved.
IMPORTANT
This method can only be used when the selected stage and the active stage are the same. When your code is initiated from
the OnStageChange event, the current stage will be selected. When your code is initiated from the OnStageSelected event,
you should use the getActiveStage method to verify that the selected stage is also the active stage. For any other form event,
it isn’t possible to determine which stage is currently selected. For best results, this method should only be used in code that
is called in functions initiated by the OnStageChange and OnStageSelected events.

Related topics
getActiveStage
[Link]
getActivePath (Client API reference)
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets a collection of stages currently in the active path with methods to interact with the stages displayed in the
business process flow control.
The active path represents stages currently rendered in the process control based on the branching rules and
current data in the record.

Syntax
var stageCollection = [Link]();

Return Value
Type: Collection.
Description: A collection of all completed stages, the currently active stage, and the predicted set of future stages
based on satisfied conditions in the branching rule. This may be a subset of the stages returned with
[Link] because it will only include those stages which represent a valid
transition from the current stage based on branching that has occurred in the process.

Example
The [Link] function uses the [Link] method to retrieve a
collection of stages. Then, the sample code uses the forEach method of the collection to loop through each stage.
The code then writes key properties of the stage to the console using the [Link] function defined in
this library. The code then accesses a collection of steps for each stage using the getSteps method. Finally, the
sample uses the forEach method of the steps collection to access each step and write key properties of the step to
the console.

NOTE
The [Link] function in the sample JavaScript library must be set as the OnLoad event handler for a form, and the
Pass execution context as the first parameter check box must be selected in the Handler Properties dialog.
Also, this sample just illustrates the use of some of the methods in the [Link] API. It doesn’t represent
using this API to meet a business requirement; it’s only intended to demonstrate how the key property values can be
accessed in code.
// A namespace defined for SDK sample code
// You should define a unique namespace for your libraries
var Sdk = [Link] || {};
(function () {

// A function to log messages while debugging only

[Link] = function (message) {
if (typeof console != 'undefined')
{ [Link](message); }
};

// Code to run in the OnLoad event

[Link] = function (executionContext) {
// Retrieve the formContext
var formContext = [Link]();

// Enumerate the stages and steps in the active path

var activePathCollection = [Link]();
[Link](function (stage, n) {
[Link]("Stage Index: " + n);
[Link]("Entity: " + [Link]());
[Link]("StageId: " + [Link]());
[Link]("Status: " + [Link]());
var stageSteps = [Link]();
[Link](function (step, i) {
[Link](" Step Name: " + [Link]());
[Link](" Step Attribute: " + [Link]());
[Link](" Step Required: " + [Link]());
[Link](" ---------------------------------------")
})
[Link]("---------------------------------------")
});
};
}).call(Sdk);

When the sample runs in the browser, you can use the developer tools of the browser to view the text written to the
console. For example, when this sample is run in the Opportunity entity form with the Opportunity Sales Process,
the following is written to the console:

Stage Index: 0
Entity: opportunity
StageId: 6b9ce798-221a-4260-90b2-2a95ed51a5bc
Status: active
Step Name: Identify Contact
Step Attribute: parentcontactid
Step Required: false
---------------------------------------
Step Name: Identify Account
Step Attribute: parentaccountid
Step Required: false
---------------------------------------
Step Name: Purchase Timeframe
Step Attribute: purchasetimeframe
Step Required: false
---------------------------------------
Step Name: Estimated Budget
Step Attribute: budgetamount
Step Required: false
---------------------------------------
Step Name: Purchase Process
Step Attribute: purchaseprocess
Step Required: false
---------------------------------------
Step Name: Identify Decision Maker
Step Attribute: decisionmaker
Step Required: false
Step Required: false
---------------------------------------
Step Name: Capture Summary
Step Attribute: description
Step Required: false
---------------------------------------
---------------------------------------
Stage Index: 1
Entity: opportunity
StageId: 650e06b4-789b-46c1-822b-0da76bedb1ed
Status: inactive
Step Name: Customer Need
Step Attribute: customerneed
Step Required: false
---------------------------------------
Step Name: Proposed Solution
Step Attribute: proposedsolution
Step Required: false
---------------------------------------
Step Name: Identify Stakeholders
Step Attribute: identifycustomercontacts
Step Required: false
---------------------------------------
Step Name: Identify Competitors
Step Attribute: identifycompetitors
Step Required: false
---------------------------------------
---------------------------------------
Stage Index: 2
Entity: opportunity
StageId: d3ca8878-8d7b-47b9-852d-fcd838790cfd
Status: inactive
Step Name: Identify Sales Team
Step Attribute: identifypursuitteam
Step Required: false
---------------------------------------
Step Name: Develop Proposal
Step Attribute: developproposal
Step Required: false
---------------------------------------
Step Name: Complete Internal Review
Step Attribute: completeinternalreview
Step Required: false
---------------------------------------
Step Name: Present Proposal
Step Attribute: presentproposal
Step Required: false
---------------------------------------
---------------------------------------
Stage Index: 3
Entity: opportunity
StageId: bb7e830a-61bd-441b-b1fd-6bb104ffa027
Status: inactive
Step Name: Complete Final Proposal
Step Attribute: completefinalproposal
Step Required: false
---------------------------------------
Step Name: Present Final Proposal
Step Attribute: presentfinalproposal
Step Required: false
---------------------------------------
Step Name: Confirm Decision Date
Step Attribute: finaldecisiondate
Step Required: false
---------------------------------------
Step Name: Send Thank You
Step Attribute: sendthankyounote
Step Required: false
---------------------------------------
Step Name: File De-brief
Step Name: File De-brief
Step Attribute: filedebrief
Step Required: false
---------------------------------------
---------------------------------------

Related topics
[Link]
getSelectedStage (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the currently selected stage.

Syntax
[Link]();

Return Value
Type: Stage.
Description: The currently selected stage. See Stage methods for the methods to access the properties of the stage
returned.
Related topics
getActiveStage (Client API reference)
[Link]
getCategory (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns an object with a getValue method which will return the integer value of the business process flow
category.

Syntax
var stageCategoryNumber = [Link]().getValue();

Return Value
Type: Number.
Description: Here is the list of possible values.

VALUE DESCRIPTION

0 Qualify

1 Develop

2 Propose

3 Close

4 Identify

5 Research

6 Resolve

Related topics
[Link]
getEntityName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the logical name of the entity associated with the stage.

Syntax
var stageEntityName = [Link]();

Return Value
Type: String.
Description: Logical name of the entity associated with the stage.
Related topics
[Link]
getId (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the unique identifier of the stage.

Syntax
var stageId = [Link]();

Returns
Type: String.
Description: Unique identifier of the stage in the GUID format.
Related topics
[Link]
getName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the stage.

Syntax
var stageName = [Link]();

Return Value
Type: String.
Description: Name of the stage.
Related topics
[Link]
getNavigationBehavior (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a navigation behavior object for a stage that can be used to define whether the Create button is available
for users to create other entity record in a cross-entity business process flow navigation scenario.

NOTE
This method is available only for Unified Interface.

Syntax
[Link]().allowCreateNew = function () {
return true|false;
}

Returns
Type: Object
Description: An object with the allowCreateNew property that lets you define whether the Create button will be
available in a stage so that user can create an instance of entityB from the entityA form in a cross-entity business
process flow navigation scenario.
For example, here is the Create button in the Develop stage of the AccountToContactProcess sample business
process flow that lets you create a Contact record from the Account form.
The allowCreateNew property will return undefined for business process flow records that do not implement
cross-entity navigation.

Example
The following sample code shows how you can hide or display the Create button for an active stage of a business
process flow depending on its name.

Related topics
[Link]
getStatus (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the status of the stage.

Syntax
var stageStatus = [Link]();

Returns
Type: String.
Description: This method will return either active or inactive.
Related topics
[Link]
getSteps (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a collection of steps in the stage.

Syntax
var stepsCollection = [Link]();

Return Value
Type: Array.
Description: See Step methods for methods to access the property values of the step.
Related topics
[Link]
getAttribute (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the logical name of the attribute associated to the step.

Syntax
var stepAttributeName = [Link]();

Returns
Type: String.
Description: Some steps don’t contain an attribute value.
Related topics
[Link]
getName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the step.

Syntax
var stepName = [Link]();

Return Value
Type: String.
Description: Name of the step.
Related topics
[Link]
getProgress (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the progress of the action step.

Syntax
var stepProgress = [Link]();

Return Value
Type: Number.
Description: Returns one of the following values:

VALUE DESCRIPTION

0 None

1 Processing

2 Completed

3 Failure

4 Invalid

Remarks
This method is supported only for the action steps; not for the data steps. Action steps are buttons on the business
process stages that users can click to trigger an on-demand workflow or action. Action step is a preview feature
introduced in the Dynamics 365 (online), version 9.0 release. More information: See the Business Process Flow
automation with Action Steps section in Blog: New automation and visualization features for Business Process
Flows (public preview )
Related topics
setProgress
[Link]
isRequired (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a boolean value indicating whether the step is required in the business process flow.

Syntax
var stepIsRequired = [Link]();

Returns
Type: Boolean.
Description: true if the step is marked as required in the Business Process Flow editor; false otherwise.
Related topics
[Link]
setProgress (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Updates the progress of the action step.

Syntax
[Link](stepProgress,message);

Parameters
NAME TYPE REQUIRED DESCRIPTION

stepProgress Number Yes Specify one of the following

values to specify the step
progress:
0: None
1: Processing
2: Completed
3: Failure
4: Invalid

message String No An optional message

that is set as the Alt text
on the icon for the step.

Return Value
Type: String.
Description: Returns "invalid" or "success" depending on whether the step progress was updated.

Remarks
This method is supported only for the action steps. Action steps are buttons on the business process stages that
users can click to trigger an on-demand workflow or action. Action step is a preview feature introduced in the
Dynamics 365 (online), version 9.0 release. More information: See the Business Process Flow automation with
Action Steps section in Blog: New automation and visualization features for Business Process Flows (public
preview ).
Related topics
getProgress
[Link]
moveNext (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Progresses to the next stage.
You can also move to a next stage in a different entity.

Syntax
[Link](callbackFunction);

Parameters
NAME TYPE REQUIRED DESCRIPTION
callbackFunction Function No A function to call when the
operation is complete. This
callback function is passed
one of the following string
values to indicate the status
of the operation:

VALUE REASO N

success The
operation
succeeded.

crossEntity The next

stage is
for a
different
entity.

end The active

stage is
the last
stage of
the active
path.

invalid The
operation
failed
because
the
selected
stage isn’t
the same
as the
active
stage.

dirtyForm This value

will be
returned if
the data in
the page is
not saved.

IMPORTANT
This method can only be used when the selected stage and the active stage are the same. When your code is initiated from
the OnStageChange event, the current stage will be selected. When your code is initiated from the OnStageSelected event,
you should use the getActiveStage method to verify that the selected stage is also the active stage. For any other form event,
it isn’t possible to determine which stage is currently selected. For best results, this method should only be used in code that
is called in functions initiated by the OnStageChange and OnStageSelected events.

Remarks
This methods will cause the OnStageChange event to occur.
Related topics
movePrevious
[Link]
movePrevious (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Moves to the previous stage.
You can also move to a previous stage in a different entity.

Syntax
[Link](callbackFunction);

VALUE REASO N

success The
operation
succeeded.

crossEntity The
previous
stage is
for a
different
entity.

beginning The active

stage is
the first
stage of
the active
path.

invalid The
operation
failed
because
the
selected
stage isn’t
the same
as the
active
stage.

dirtyForm This value

will be
returned if
the data in
the page is
not saved.

Remarks
This methods will cause the OnStageChange event to occur.
Related topics
moveNext
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides properties and methods to retrieve information about the user interface (UI) as well as collections for
several subcomponents of the form.

Properties
NAME DESCRIPTION

Controls Collection of all the controls on the page. See Collections for
information about the collections and Controls for information
about the control objects in the collection.

formSelector Use the [Link] method to retrieve

information about the form currently in use. Use the
[Link] collection to return information about all
the forms available for the user. formSelector is not available
for Microsoft Dynamics 365 for tablets.

navigation A collection of all the navigation items on the page. See

Collections for information about the collection methods and
[Link] item for information about the
items in the collection. navigation is not available for
Microsoft Dynamics 365 for tablets.

process Provides objects and methods to interact with the business

process flow control on a form.
More information: [Link]

quickForms A collection of all the quick view controls on a form using the
new form rendering engine (also called "turbo forms").
More information: [Link] quickForms
NAME DESCRIPTION

tabs A collection of all the tabs on the page.

See Collections for information about the collection methods
and [Link] tab for information about the items in the
collection.

Methods
NAME DESCRIPTION

addOnLoad Adds a function to be called on the form OnLoad event.

clearFormNotification Removes form level notifications.

close Closes the form.

getFormType Gets the form type for the record.

getViewPortHeight Gets the height of the viewport in pixels.

getViewPortWidth Get the width of the viewport in pixels.

refreshRibbon Causes the ribbon to re-evaluate data that controls what is

displayed in it.

removeOnLoad Removes a function from the form OnLoad event.

setFormEntityName Sets the name of the entity to be displayed on the form.

setFormNotification Displays form level notifications.

Related topics
formContext
addOnLoad (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a function to be called on the form OnLoad event.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be executed

on the form OnLoad event.
The function will be added to
the bottom of the event
handler pipeline. The
execution context is
automatically passed as the
first parameter to the
function. See Execution
context for more
information.

Related topics
removeOnLoad
Form OnLoad event
[Link]
formContext
clearFormNotification (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes form level notifications.

Syntax
[Link](uniqueId)

Parameter
NAME TYPE REQUIRED DESCRIPTION

uniqueId String Yes A unique identifier for the

message to be cleared that
was set using the
setFormNotification method.

Return Value
Type: Boolean
Description: true if the method succeeded, false otherwise.
Related topics
setFormNotification
[Link]
formContext
close (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Closes the form.

Syntax
[Link]();

Remarks
The HTML [Link] method is suppressed. To close a form window, you must use this method. If there are
any unsaved changes in the form, the user will be prompted whether they want to save their changes before the
window closes.
For Microsoft Dynamics 365 for tablets, this method mimics the behavior of the back navigation button.
Related topics
[Link]
formContext
getFormType (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the form type for the record.

Syntax
[Link]();

Return Value
Type: Number
Description: Form type. Returns one of the following values

VALUE FORM TYPE

0 Undefined

1 Create

2 Update

3 Read Only

4 Disabled

6 Bulk Edit

NOTE
Quick Create forms return 1.

Related topics
[Link]
formContext
getViewPortHeight (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the height of the viewport in pixels.
The viewport is the area of the page containing form data. It corresponds to the body of the form and does not
include the navigation, header, footer or form assistant areas of the page.

Syntax
[Link]();

Return Value
Type: Number
Description: The viewport height in pixels.
Related topics
getViewPortWidth
[Link]
formContext
getViewPortWidth (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Get the width of the viewport in pixels.
The viewport is the area of the page containing form data. It corresponds to the body of the form and does not
include the navigation, header, footer or form assistant areas of the page.

Syntax
[Link]();

Return Value
Type: Number
Description: The viewport width in pixels.
Related topics
getViewPortHeight
[Link]
formContext
refreshRibbon (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Causes the ribbon to re-evaluate data that controls what is displayed in it.

Syntax
[Link](refreshAll);

Parameter
NAME TYPE REQUIRED DESCRIPTION

refreshAll Boolean No Indicates whether all the

ribbon command bars on
the current page are
refreshed. If you specify
false, only the page-level
ribbon command bar is
refreshed. If you do not
specify this parameter, by
default false is passed.

Remarks
This function is typically used when a ribbon (RibbonDiffXml) depends on a value in the form. After your code
changes a value that is used by a rule, use this method to force the ribbon to re-evaluate the data in the form so
that the rule can be applied.
Related topics
[Link]
formContext
removeOnLoad (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Removes a function from the form OnLoad event.

Syntax
[Link](myFunction)

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be removed

from the form OnLoad
event.

Related topics
addOnLoad
Form data OnLoad event
[Link]
formContext
setFormEntityName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the name of the entity to be displayed on the form.

Syntax
[Link](arg);

Parameter
NAME TYPE REQUIRED DESCRIPTION

arg String Yes Name of the entity to be

displayed on the form.

Related topics
[Link]
formContext
setFormNotification (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays form level notifications.
You can display any number of notifications and they will be displayed until they are removed using
clearFormNotification. The height of the notification area is limited so each new message will be added to the top.
Users can scroll down to view older messages that have not yet been removed.

Syntax
[Link](message, level, uniqueId);

Parameter
NAME TYPE REQUIRED DESCRIPTION

message String Yes The text of the message.

level String Yes The level of the message,

which defines how the
message will be displayed.
Specify one of the following
values:
ERROR : Notification will use
the system error icon.
WARNING : Notification will
use the system warning icon.
INFO : Notification will use
the system info icon.

uniqueId String Yes A unique identifier for the

message that can be used
later with
clearFormNotification to
remove the notification.

Return Value
Type: Boolean
Description: true if the method succeeded; false otherwise.
Related topics
clearFormNotification
[Link]
formContext
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

The [Link] property lets you work with form items where a form item represents a form
that is available to a user because it is associated with a security role that the user is also associated to. Often there
will be only one form. When more than one form is available, methods for a form item can be used to change the
form the user is viewing.
Form Items are available through any of the following:
[Link] collection: A collection of all the form items accessible to the current user. Only those
forms that share an association with one of the user’s security roles are available in this collection. Example:
formItem = [Link](arg);

See Collections) for information about the collection methods.

NOTE
This collection isn't available for Dynamics 365 mobile clients (phones and tablets).

[Link] method: Returns a reference to the form currently being shown. When only
one form is available this method will return null. Example:
formItem = [Link]();

Form Item methods

After retrieving a form item using one of the above ways, use the following methods to work with the form item.

NAME DECRIPTION

getId Returns the ID of the form.

getLabel Returns the label of the form.

navigate Opens the specified form.

getId (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the ID of the form.

Syntax
[Link]();

Return Value
Type: String.
Description: ID of the form.
Related topics
[Link]
getLabel (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the label of the form.

Syntax
[Link]();

Return Value
Type: String.
Description: Label of the form.
Related topics
[Link]
navigate (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens the specified form.
When you use the navigate method while unsaved changes exist, the user is prompted to save changes before the
new form can be displayed. The Onload event occurs when the new form loads.

Syntax
[Link]();

Related topics
[Link]
[Link] item (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Each item represents one of the available navigation options available in the navigation bar for entities that have
been updated to the new user experience or on the left side of the form for entities that have not been updated.

NOTE
These methods do not work with Microsoft Dynamics 365 for tablets.

Navigation item methods

NAME DESCRIPTION

getId Returns the name of the item.

getLabel Returns the label for the item.

getVisible Returns a value that indicates whether the item is currently

visible.

setFocus Sets the focus on the item.

setLabel Sets the label for the item.

Applies to Dynamics 365 (online), version 9.x

Sets a value that indicates whether the item is visible.

Syntax
[Link](bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true or false to

indicate whether the item is
visible or not.

Related topics
getVisible
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to interact with the business process flow control on a form.

NAME DESCRIPTION

getDisplayState Retrieves the display state for the business process control.

getVisible Returns a value indicating whether the business process

control is visible.

reflow Reflows the UI of the business process control.

setDisplayState Sets the display state of the business process control.

setVisible Shows or hides the business process control.

getDisplayState (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Retrieves the display state for the business process control.

Syntax
[Link]();

Return Value
Type: String.
Description: Returns "expanded" or "collapsed" on the web client; returns "expanded", "collapsed", or "floating" on
Unified Interface.
Related topics
setDisplayState
[Link]
getVisible (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a value indicating whether the business process control is visible.

Syntax
[Link]();

Return Value
Type: Boolean.
Description: true if the control is visible; false otherwise.
Related topics
setVisible
[Link]
reflow (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Reflows the UI of the business process control.

Syntax
[Link](updateUI, parentStage, nextStage);

Parameter
NAME TYPE REQUIRED DESCRIPTION

updateUI Boolean Yes Specify true to update the

UI of the process control;
false otherwise.

parentStage String Yes Specify the ID of the parent

stage in the GUID format.

nextStage String Yes Specify the ID of the next

stage in the GUID format.

Related topics
[Link]
setDisplayState (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the display state of the business process control.

Syntax
[Link](state);

Parameter
NAME TYPE REQUIRED DESCRIPTION

state String Yes Specify "expanded",

"collapsed", or "floating". The
value "floating" is not
supported on the web client.

Related topics
getDisplayState
[Link]
setVisible (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Shows or hides the business process control.

Syntax
[Link](bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true to show the

control; false to hide the
control.

Related topics
getVisible
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to access all the quick view controls and its constituent controls on the Customer Engagement
forms when using the new form rendering engine (also called "turbo forms"). A quick view control is a quick view
form added to a main form in Customer Engagement that enables you to view information about a related entity
record within the main form. Data in constituent controls in a quick view control cannot be edited.
The quickForms collection provides access to all the quick view controls on a form, and supports all the standard
methods of the collections. See Collections) for information about the collection methods.
You can retrieve a quick view control in the quickForms collection by using the get method by specifying either the
index value (integer) or name (string) of the quick view control as the argument:
quickViewControl = [Link](arg)

Quick form control Methods

NAME DESCRIPTION

getControl Gets the control on a form.

getControlType Returns a string value that categorizes quick view controls.

getDisabled Gets a boolean value indicating whether the control is

disabled.

getLabel Returns the label for the quick view control.

getName Returns the name assigned to the quick view control.

getParent Returns a reference to the section object that contains the

control.

getVisible Returns a value that indicates whether the quick view control is
currently visible.

isLoaded Returns whether the data binding for the constituent controls
in a quick view control is complete.

refresh Refreshes the data displayed in a quick view control.

setDisabled Sets the state of the control to either enabled or disabled.

setFocus Sets focus on the control.

setLabel Sets the label for the quick view control.

setVisible Displays or hides a control.

Related topics
[Link]
getControl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the control on a form.

Syntax
[Link](arg);

Parameter
arg: Optional. You can access a single control in the constituent controls collection by passing an argument as
either the name or the index value of the constituent control in a quick view control. For example:
[Link]("firstname") or [Link](0)

Return Value
Type: Object or Object collection.
Description: Object if you use the method with parameter; object collection if you use the method without any
parameters.

Remarks
After you have retrieved a constituent control in a quick view control, you can use any of the methods supported
for a control in Customer Engagement on the constituent control that does not alter the constituent control data.
This is because constituent controls in a quick view control are read only. For example, you can use:
[Link](0).getAttribute()

Returns a value that indicates whether the quick view control is currently visible.

Displays or hides a control.

Syntax
[Link](bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true or false to

display or hide the control.

Related topics
getVisible
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

A tab is a group of sections on a page. It contains properties and methods to manipulate tabs as well as access to
sections within the tab through the sections collection.
You can retrieve a tab object (say tabObj) by using the following example code:

var tabObj = [Link](arg);

Properties
Sections: The sections collection provides access to sections within the tab. See Collections (Client API
reference) for information about methods to access the sections in the collection. See [Link] section for
information about the properties and methods of the section objects in the collection.

Methods
NAME DESCRIPTION

addTabStateChange Adds a function to be called when the TabStateChange event

occurs.

getDisplayState Gets display state of the tab.

getLabel Returns the label for the tab.

getName Returns the name of the tab.

getParent Returns the [Link] object containing the tab.

getVisible Returns a value that indicates whether the tab is currently

visible.

removeTabStateChange Removes a function to be called when the TabStateChange

event occurs.

setDisplayState Sets display state of the tab.

setFocus Sets the focus on the tab.

setLabel Sets the label of the tab.

setVisible Sets a value that indicates whether the tab is visible.

Related topics
[Link]
formContext
addTabStateChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a function to be called when the TabStateChange event occurs..

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be executed

on the TabStateChange
event. The function will be
added to the bottom of the
event handler pipeline. The
execution context is
automatically passed as the
first parameter to the
function. See Execution
context for more
information.

Related topics
[Link]
formContext
addTabStateChange (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds a function to be called when the TabStateChange event occurs..

Syntax
[Link](myFunction);

Removes a function to be called when the TabStateChange event occurs..

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be removed

from the TabStateChange
event.

Related topics
[Link]
formContext
setDisplayState (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets display state of the tab.

Syntax
[Link](state);

Parameter
NAME TYPE REQUIRED DESCRIPTION

state String Yes Specify "expanded" or

"collapsed".

Related topics
getDisplayState
setFocus (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the focus on the tab.

Syntax
[Link]();

Related topics
[Link]
setLabel (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets the label of the tab.

Syntax
[Link](label);

Parameter
NAME TYPE REQUIRED DESCRIPTION

label String Yes The new label of the tab.

Related topics
getLabel
setVisible (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Sets a value that indicates whether the tab is visible.

Syntax
[Link](bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true to show the tab;

false to hide the tab.

Remarks
Another way to hide a tab is to hide all the sections within it. If all the sections within a tab are not visible, the tab
will not be visible.
Related topics
getVisible
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

A section contains methods to manage how it appears as well as accessing the tab that contains the section.
You can retrieve a section object (say sectionObj) by using the following example code:

var tabObj = [Link](arg);

var sectionObj = [Link](arg);

Properties
Controls: The section controls collection provides access to the controls within a section. See Collections (Client
API reference) for information about the methods exposed by collections. See Controls (Client API reference)
for information about the properties and methods exposed by the objects in this collection.

Methods
NAME DESCRIPTION

getLabel Returns the label for the section.

getName Returns the name of the section.

getParent Returns the tab containing the section.

getVisible Returns a value that indicates whether the section is currently

visible.

setLabel Sets the label of the section.

Applies to Dynamics 365 (online), version 9.x

Sets a value that indicates whether the section is visible.

Syntax
[Link](bool);

Parameter
NAME TYPE REQUIRED DESCRIPTION

bool Boolean Yes Specify true to show the

section; false to hide the
section.

Related topics
getVisible
Grids and subgrids in Customer Engagement (Client
API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Grids present data in a tabular format in Customer Engagement. Grids can span the entire form or can be one of
the items on a form; the latter are called subgrids.

Types of grids
There are two types of grids in Customer Engagement:
Read-only grids: Display data in a tabular format. To edit the data displayed in a read-only grid, you have to
click the record in the grid to open the form, edit the data, and then save.
Editable grids: In addition to displaying data in a tabular format, provides rich inline editing capabilities on
web and mobile clients including the ability to group, sort, and filter data within the same grid so that you do
not have to switch records or views. The editable grid is a custom control, and is supported in the main grid
and subgrids on a form in the web client and in dashboards and on form grids on the mobile clients. Although
the editable grid control provides editing capability, it honors the read-only grid metadata and field-level
security settings.

Getting the grid context

Grid context is the grid or subgrid instance on a form against which you want to run your code. For more
information about getting the grid context to execute your JavaScript code, see Client API grid context

Events
NAME DESCRIPTION APPLICABLE FOR

Subgrid OnLoad Event Occurs every time the subgrid Read-only grid
refreshes. This includes when users sort
values in subgrid by clicking the
column headings.

Grid OnChange Occurs when a value is changed in a Editable grid

cell in the editable grid and the cell
loses focus

Grid OnRecordSelect Occurs when a single row (record) is Editable grid

selected in the editable grid
NAME DESCRIPTION APPLICABLE FOR

Grid OnSave Occurs before sending the updated Editable grid

information to the server, and when
any of the following occurs: there is a
change in the record selection, the user
explicitly triggers a save operation
using the editable grid’s save button,
or the user applies a sort, filter, group,
pagination, or navigation operation
from the editable grid while there are
pending changes.

NOTE
You can register for the OnChange, OnRecordSelect, and OnSave events using the Events tab of the Dynamics 365
Customer Engagement page that is used to enable editable grids for an entity or a read-only grid.

Methods
NAME DESCRIPTION AVAILABLE FOR

GridControl Provides methods to work with the Read-only and editable grids
grid or subgrid control.

Grid Provides methods to access Read-only and editable grids

information about data in the grid.

GridRow Provides methods to work with rows or Read-only and editable grids
selected rows in the grid.

GridRowData Provides methods to work with rows or Read-only and editable grids
selected rows in the grid.

GridEntity Provides methods to access data about Read-only and editable grids
the specific records in the rows.

GridAttribute Provides methods to access the data in Editable grid

the cell of an editable grid.

GridCell Provides methods to access the data Editable grid

related to control on a form that is tied
to an attribute in an editable grid.

ViewSelector Provides methods to get or set Read-only grid

information about the view selector of
the subgrid control.

Related topics
Client API grid context
Use editable grids in Customer Engagement
Client API Reference for Customer Engagement
Developer Guide for Dynamics 365 Customer Engagement
GridControl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

GridControl or the gridContext is the instance of grid or subgrid on a form against which you want to execute your
script. Use the form context to get GridControl (gridContext) on a form.

Methods
NAME DESCRIPTION AVAILABLE FOR

addOnLoad Adds event handlers to the Subgrid Read-only grid

OnLoad event event.

getEntityName Gets the logical name of the entity data Read-only and editable grids
displayed in the grid.

getFetchXml Gets the FetchXML query that Read-only and editable grids
represents the current data, including
filtered and sorted data, in the grid
control.

getGrid Get access to the Grid available in the Read-only and editable grids
GridControl (gridContext).

getGridType Gets the grid type (grid or subgrid). Read-only and editable grids

getRelationship Gets information about the relationship Read-only and editable grids
used to filter the subgrid.

getUrl Gets the URL of the current grid control. Read-only and editable grids

getViewSelector Use this method to access the Read-only grid

ViewSelector methods available for the
grid control.

openRelatedGrid Displays the the associated grid for the Read-only and editable grids
grid.

refresh Refreshes the grid. Read-only and editable grids

refreshRibbon Refreshes the ribbon rules for the grid Read-only and editable grids
control.

removeOnLoad Removes event handlers from the Read-only grid

Subgrid OnLoad event event.

Related topics
Grid
Grids and subgrids in Customer Engagement
addOnLoad (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Adds event handlers to the Subgrid OnLoad event event.

Grid types supported

Read-only grids

Syntax
[Link](myFunction);

Parameter
NAME TYPE REQUIRED DESCRIPTION

myFunction function reference Yes The function to be executed

when the subgrid loads. The
function will be added to the
bottom of the event handler
pipeline. The execution
context is automatically
passed as the first parameter
to the function. See
execution context for more
information.

Remarks
To get the gridContext , see Getting the grid context.

Example
Add the myContactsGridOnloadFunction function to the Contacts subgrid OnLoad event.

function myFunction(executionContext) {
var formContext = [Link](); // get the form context
var gridContext = [Link]("Contacts");// get the grid context
var myContactsGridOnloadFunction = function () { [Link]("Contacts Subgrid OnLoad event occurred") };
[Link](myContactsGridOnloadFunction);
}

Related topics
removeOnLoad
getEntityName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the logical name of the entity data displayed in the grid.

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: String
Description: The logical name of the entity data displayed in the grid.

Applies to Dynamics 365 (online), version 9.x

Gets information about the relationship used to filter the subgrid.

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: Object.
Description: A relationship object with the following attributes:
attributeName: String. Name of the attribute.
name: String. Name of the relationship.
navigationPropertyName: String. Name of the navigation property for this relationship.
relationshipType: Number. Returns one of the following values to indicate the relationship type:
0: OneToMany
1: ManyToMany
roleType: Number. Returns one of the following values to indicate the role type of relationship:
1: Referencing
2: AssociationEntity

Remarks
To get the gridContext , see Getting the grid context.
Related topics
openRelatedGrid
Customize entity relationship metadata
getUrl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the URL of the current grid control.

Grid types supported

Read-only and editable grids

Syntax
[Link](client);

Parameter
NAME TYPE REQUIRED DESCRIPTION

client Number No Indicates the client type. You

can specify one of the
following values:
0: Browser
1: MobileApplication

Return Value
Type: String
Description: The Url of the current grid control.

Remarks
To get the gridContext , see Getting the grid context.
getViewSelector (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Use this method to access the ViewSelector methods available for the grid control.

Grid types supported

Read-only grid

Syntax
[Link]();

Return Value
Type: ViewSelector
Description: The ViewSelector object.

Remarks
To get the gridContext , see Getting the grid context.
openRelatedGrid (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays the the associated grid for the grid.
This method does nothing if the grid is not filtered based on a relationship.

Grid types supported

Read-only and editable grids

Syntax
var allRows = [Link]().getRows();

Return Value
Type: Collection
Description: A collection of rows in the grid.

Remarks
To get the gridContext , see Getting the grid context.
See Collections (Client API reference) for information on the methods available to access data in a collection.
getSelectedRows (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a collection of every selected GridRow in the Grid.

Grid types supported

Read-only and editable grids

Syntax
var allSelectedRows = [Link]().getSelectedRows();

Return Value
Type: Collection
Description: A collection of selected rows in the grid.

Remarks
To get the gridContext , see Getting the grid context.
See Collections (Client API reference) for information on the methods available to access data in a collection.
getTotalRecordCount (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the total number of records that match the filter criteria of the view, not limited by the number visible in a
single page.
When the Dynamics 365 for Outlook client isn’t connected to the server, this number is limited to those records
that the user has selected to take offline.
For Dynamics 365 mobile clients, this method will return the number of records in the subgrid.

Grid types supported

Read-only and editable grids

Syntax
var filteredRecordCount = [Link]().getTotalRecordCount();

Return Value
Type: Number
Description: Total number of records that match the filter criteria of the view.

Remarks
To get the gridContext , see Getting the grid context.
See Collections (Client API reference) for information on the methods available to access data in a collection.
GridRow (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

A collection of GridRow is returned by [Link] and [Link] methods.

var myRows = [Link]().getRows();

var gridRow = [Link](arg);

Properties
NAME DESCRIPTION AVAILABLE FOR

data A collection containing the Read-only and editable grids

GridRowData for the GridRow. See
Collections (Client API reference) for
information on the methods available
for accessing data in a collection.

Methods
NAME DESCRIPTION AVAILABLE FOR

getData Deprecated. Returns the GridRowData Read-only and editable grids

for the GridRow.

Related topics
GridRowData
Grids and subgrids in Customer Engagement
getData (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Deprecated. Returns the GridRowData for the GridRow.
As this is deprecated, you should use [Link].

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: GridRowData

Remarks
To get the gridRow object, see GridRow.
GridRowData (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

GridRowData is returned by the [Link] method.
GridRowData also provides methods for retrieving information specific to a record displayed in an editable grid
row, including a collection of all the attributes included in the row. Attribute data is limited to the columns
presented by the editable grid. See Collections (Client API reference) for information on the methods available to
access data in a collection.

var myRows = [Link]().getRows();

var myRow = [Link](arg);
var gridRowData = [Link]();

Properties
NAME DESCRIPTION AVAILABLE FOR

entity Returns the GridEntity for the Read-only and editable grids
GridRowData.

Methods
NAME DESCRIPTION AVAILABLE FOR

getEntity Deprecated. Returns the GridEntity for Read-only and editable grids
the GridRowData.
getEntity (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Deprecated. Returns the GridEntity for the GridRowData.
As this is deprecated, you should use [Link].

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: GridEntity

Remarks
To get the gridRowData object, see GridRowData.
GridEntity (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

GridEntity is returned by the [Link] method or by directly accessing the [Link]
object. Use the GridEntity methods to access data about the specific records in the rows.

var myRows = [Link]().getRows();

var myRow = [Link](arg);
var gridEntity = [Link]().getEntity();

GridEntity also supports the attributes collection that provides methods of working with a collection of
attributes for an entity in the editable grid. Each attribute (GridAttribute) represents the data in the cell of an
editable grid, and contains a reference to all the cells associated with the attribute. See Collections (Client API
reference) for information on the methods available to access data in a collection.

Methods
NAME DESCRIPTION AVAILABLE FOR

getEntityName Returns the logical name for the record Read-only and editable grids
in the row.

getEntityReference Returns a Lookup value that references Read-only and editable grids
the record in the row.

getId Returns the Id for the record in the row. Read-only and editable grids

getPrimaryAttributeValue Returns the primary attribute value for Read-only grid

the record in the row.

Related topics
GridAttribute
Grids and subgrids in Customer Engagement
Attributes
getEntityName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the logical name for the record in the row.

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: String
Description: The logical name for the record in the row.

Remarks
To get the gridEntity object, see GridEntity.
getEntityReference (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a Lookup value that references the record in the row.

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: Lookup
Description: Lookup object that references the record in the row. The object has the following attributes:
entityType: String. The logical name for the record in the row. The same data returned by the
[Link] method.
id: String. The Id for the record in the row. The same data returned by the [Link] method.
name: String. The primary attribute value for the record in the row. The same data returned by the
[Link] method.

Remarks
To get the gridEntity object, see GridEntity.
getId (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the Id for the record in the row.

Grid types supported

Read-only and editable grids

Syntax
[Link]();

Return Value
Type: String
Description: The Id for the record in the row.

Remarks
To get the gridEntity object, see GridEntity.
getPrimaryAttributeValue (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the primary attribute value for the record in the row.

Grid types supported

Read-only grid

Syntax
[Link]();

Return Value
Type: String
Description: The primary attribute value for the record in the row.

Remarks
To get the gridEntity object, see GridEntity.
GridAttribute (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

GridAttribute is only supported for editable grids.
GridAttribute represents the data in the cell of an editable grid, and contains a reference to all the cells associated
with the attribute. See Collections (Client API reference) for information on the methods available to access data
in a collection.
GridAttribute also supports the controls collection for attributes of a selected grid row, which provides methods
to work with a collection of cells associated with the attribute. Each cell (GridCell) of a selected grid row is
analogous to a control on a form that is tied to an attribute in an editable grid. See Collections (Client API
reference) for information on the methods available to access data in a collection.

TIP
For performance reasons, a row (record) in an editable grid is not editable until the record is selected. Users must select a
single record in a grid to edit it. Once a record is selected in an editable grid, Dynamics 365 internally evaluates a number of
things including user access to the record, whether the record is active, and field validations to ensure that data security and
validity are honored when you edit data. Consider using the OnRecordSelect event with the getFormContext method to
access records in the grid that are in the editable state.

Methods
GridAttribute supports the following methods for attributes of a selected grid row.

NAME DESCRIPTION

getName Returns the logical name of the attribute of a selected grid

row.

getRequiredLevel Returns a string value indicating whether a value for the

attribute is required or recommended.

setRequiredLevel Sets whether data is required or recommended for the

attribute of a selected grid row before the record can be
saved.

getValue Retrieves the data value for an attribute.

setValue Sets the data value for an attribute.

NOTE
To select a row in an editable grid, use the [Link]

Related topics
GridCell
Grids and subgrids in Customer Engagement
Controls collection
GridCell (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

GridCell is only supported for editable grids.
GridCell of a selected grid row is analogous to a control on a form that is tied to an attribute in an editable grid.
See Collections (Client API reference) for information on the methods available to access data in a collection.

Methods
GridCell supports the following methods.

NAME DESCRIPTION

clearNotification Clears notification for a cell.

getDisabled Returns whether the cell is disabled (read-only).

setDisabled Sets whether the cell is disabled.

NOTE: Enabling a read-only cell for editing can cause an error

when the record is saved. If the field is considered read-only
by the server, an error may occur if the value is modified. This
may happen in scenarios where the user doesn't have write
privileges to the record, the record is disabled, or the user
doesn't have the necessary field-level security privileges.

setNotification Displays an error message for a cell to indicate that data isn’t
valid.

getLabel Returns the label of the column that contains the cell.

Related topics
Grids and subgrids in Customer Engagement
Controls
ViewSelector methods (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to get or set information about the view selector of the subgrid control. If the subgrid control is
not configured to display the view selector, calling the ViewSelector methods will throw an error.
ViewSelector is available only for read-only grids. ViewSelector is returned by the [Link]
method.

var viewSelector = [Link]();

Methods

NAME DESCRIPTION AVAILABLE FOR

getCurrentView Gets a reference to the current view. Read-only grid

isVisible Returns a boolean value to indicate Read-only grid

Syntax
[Link](object);

Parameter
NAME TYPE REQUIRED DESCRIPTION

object Lookup object Yes Specify the Lookup object

that has the following
attributes:
- entityType: Number. The
object type code for the
SavedQuery (1039) or
UserQuery (4230) that
represents the view the user
can select.
- id: String. The Id for the
view the user can select.
- name: String. The name of
the view the user can select.

Remarks
If the subgrid control is not configured to display the view selector, calling this method on the viewSelector object
will throw an error.
To get the viewSelector object, see ViewSelector.

Example
function setView(executionContext) {
var ContactsIFollow = {
entityType: 1039, // SavedQuery
id: "3A282DA1-5D90-E011-95AE-00155D9CFA02",
name: "Contacts I Follow"
}
// Get the gridContext
var formContext = [Link]();
var gridContext = [Link]("Contacts");

// Set the view using ContactsIFollow

[Link]().setCurrentView(ContactsIFollow);
}

Related topics
ViewSelector
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to use native device capabilities of mobile devices.

METHOD DESCRIPTION

captureAudio Invokes the device microphone to record audio.

captureImage Invokes the device camera to capture an image.

captureVideo Invokes the device camera to record video.

getBarcodeValue Invokes the device camera to scan the barcode information,

such as a product number.

getCurrentPosition Returns the current location using the device geolocation

capability.

pickFile Opens a dialog box to select files from your computer (web
client) or mobile device (mobile clients).

Related topics
Client API Xrm object
captureAudio (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Invokes the device microphone to record audio.

Syntax
[Link]().then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when audio

is returned. A base64
encoded audio object with
the following attributes is
passed to the function:
- fileContent: Contents of
the audio file. String
- fileName: Name of the
audio file. String.
- fileSize: Size of the audio
file in KB. Number.
- mimeType: Audio file
MIME type. String.

errorCallback Function Yes A function to call when the

operation fails.

Return Value
On success, returns a base64 encoded audio object with the attributes specified earlier.

Remarks
This method is supported only for the mobile clients.
Related topics
[Link]
captureImage (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Invokes the device camera to capture an image.

Syntax
[Link](imageOptions).then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

imageOptions Object No An object with the following

attributes:
- allowEdit: Indicates
whether to edit the image
before saving. Boolean.
- height: Height of the
image to capture. Number.
- preferFrontCamera:
Indicates whether to capture
image using the front
camera of the device.
Boolean.
- quality: Quality of the
image file in percentage.
Number.
- width: Width of the image
to capture. Number..

successCallback Function Yes A function to call when

image is returned. A base64
encoded image object with
the following attributes is
passed to the function:
- fileContent: Contents of
the image file. String
- fileName: Name of the
image file. String.
- fileSize: Size of the image
file in KB. Number.
- mimeType: Image file
MIME type. String.

errorCallback Function Yes A function to call when the

operation fails.

Return Value
On success, returns a base64 encoded image object with the attributes specified earlier.
Remarks
This method is supported only for the mobile clients.
Related topics
[Link]
captureVideo (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Invokes the device camera to record video.

Syntax
[Link]().then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when

Video is returned. A base64
encoded Video object with
the following attributes is
passed to the function:
- fileContent: Contents of
the Video file. String
- fileName: Name of the
Video file. String.
- fileSize: Size of the Video
file in KB. Number.
- mimeType: Video file
MIME type. String.

errorCallback Function Yes A function to call when the

operation fails.

Return Value
On success, returns a base64 encoded Video object with the attributes specified earlier.

Remarks
This method is supported only for the mobile clients.
Related topics
[Link]
getBarcodeValue (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Invokes the device camera to scan the barcode information, such as a product number.

Syntax
[Link]().then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when the

barcode value is returned as
a String.

errorCallback Function Yes A function to call when the

operation fails. An error
object with the message
property (String) will be
passed that describes the
error details.

Return Value
On success, returns a string containing the scanned barcode value.

Remarks
This method is supported only for the mobile clients.

Example
[Link]().then(
function success(result) {
[Link]({ text: "Barcode value: " + result });
},
function (error) {
[Link]( {text: [Link]} );
}
);

Related topics
[Link]
getCurrentPosition (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the current location using the device geolocation capability.

Syntax
[Link]().then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when the

current geolocation
information is returned. A
geolocation object with the
following attributes is passed
to the function.:
- coords: Contains a set of
geographic coordinates
along with associated
accuracy as well as a set of
other optional attributes
such as altitude and speed.
- timestamp: Represents the
time when the object was
acquired and is represented
as DOMTimeStamp.

errorCallback Function Yes A function to call when the

operation fails. An object
with the following properties
will be passed:
- code: The error code.
Number.
- message: RLocalized
message describing the error
details. String.

If the user location setting is

not enabled on your mobile
device, the error message
indicates the same. If you are
using an earlier version of
the Dynamics 365 Customer
Engagement mobile client or
if geolocation capability is
not available on your mobile
device, null is passed to the
error callback.

Return Value
On success, returns a geolocation object with the attributes specified earlier in the successCallback function.

Remarks
For the getCurrentPosition method to work, the geolocation capability must be enabled on your mobile device,
and the Dynamics 365 Customer Engagement mobile clients must have permissions to access the device location,
which isn't enabled by default.
This method is supported only for the mobile clients.

Example
[Link]().then(
function success(location) {
[Link]({
text: "Latitude: " + [Link] +
", Longitude: " + [Link]
});
},
function (error) {
[Link]({ text: [Link] });
}
);

Related topics
[Link]
pickFile (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens a dialog box to select files from your computer (web client) or mobile device (mobile clients).

Syntax
[Link](pickFileOptions).then(successCallback, errorCallback)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

pickFileOptions Object No An object with the following

attributes:
- accept: Image file types to
select. Valid values are
"audio", "video", or "image".
String.
- allowMultipleFiles:
Indicates whether to allow
selecting multiple files.
Boolean.
-
maximumAllowedFileSize:
Maximum size of the files(s)
to be selected. Number.

successCallback Function Yes A function to call when

selected files are returned.
An array of objects with each
object having the following
attributes is passed to the
function:
- fileContent: Contents of
the file. String
- fileName: Name of the file.
String.
- fileSize: Size of the file in
KB. Number.
- mimeType: File MIME
type. String.

errorCallback Function Yes A function to call when the

operation fails.

Return Value
On success, returns a promise with array of objects as specified earlier for the successCallback function.
Related topics
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to encode and decode strings.

METHOD DESCRIPTION

htmlAttributeEncode Encodes the specified string so that it can be used in an HTML

attribute.

htmlDecode Converts a string that has been HTML-encoded into a

decoded string.

htmlEncode Converts a string to an HTML-encoded string.

xmlAttributeEncode Encodes the specified string so that it can be used in an XML

attribute.

xmlEncode Converts a string to an XML-encoded string.

Related topics
Client API Xrm object
htmlAttributeEncode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Encodes the specified string so that it can be used in an HTML attribute.

Syntax
[Link](arg)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

arg String Required String to be encoded.

Return Value
Type: String
Description: Encoded string.

Related topics
htmEncode
htmlDecode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Converts a string that has been HTML -encoded into a decoded string.

Syntax
[Link](arg)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

arg String Required HTML-encoded string to be

decoded.

Return Value
Type: String
Description: Decoded string.

Related topics
htmlEncode
htmlAttributeEncode
htmlEncode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Converts a string to an HTML -encoded string.

Syntax
[Link](arg)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

arg String Required String to be encoded.

Return Value
Type: String
Description: Encoded string.

Related topics
htmlAttributeEncode
htmlDecode
xmlAttributeEncode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Encodes the specified string so that it can be used in an XML attribute.

Syntax
[Link](arg)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

arg String Required String to be encoded.

Return Value
Type: String
Description: Encoded string.

Related topics
xmlEncode
xmlEncode (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Converts a string to an XML -encoded string.

Syntax
[Link](arg)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

arg String Required String to be encoded.

Return Value
Type: String
Description: Encoded string.

Related topics
xmlAttributeEncode
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides navigation-related methods.

METHOD DESCRIPTION

openAlertDialog Displays an alert dialog containing a message and a button.

openConfirmDialog Displays a confirmation dialog box containing a message and

two buttons.

openErrorDialog Displays an error dialog.

openFile Opens a file.

openForm Opens an entity form or a quick create form.

openUrl Opens a URL, including file URLs.

openWebResource Opens an HTML web resource.

Related topics
Client API Xrm object
openAlertDialog (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays an alert dialog containing a message and a button.

Syntax
[Link](alertStrings,alertOptions).then(closeCallback,errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

alertStrings Object Yes The strings to be used in the

alert dialog. The object
contains the following
attributes:
- confirmButtonLabel:
(Optional) String. The
confirm button label. If you
do not specify the button
label, OK is used as the
button label.
- text: String. The message
to be displyed in the alert
dialog.

alertOptions Object No The height and width

options for alert dialog. The
object contains the following
attributes:
- height: (Optional) Number.
Height of the alert dialog in
pixels.
- width: (Optional) Number.
Width of the alert dialog
pixels.

successCallback function No A function to execute when

the alert dialog is closed by
either clicking the confirm
button or canceled by
pressing ESC.

errorCallback function No A function to execute when

the operation fails.

Example
The following sample code displays an alert dialog. Clicking Yes button in the alert dialog or canceling the alert
dialog by pressing ESC calls the close function::
var alertStrings = { confirmButtonLabel: "Yes", text: "This is an alert." };
var alertOptions = { height: 120, width: 260 };
[Link](alertStrings, alertOptions).then(
function success(result) {
[Link]("Alert dialog closed");
},
function (error) {
[Link]([Link]);
}
);

Related topics
[Link]
openConfirmDialog (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays a confirmation dialog box containing a message and two buttons.

Syntax
[Link](confirmStrings,confirmOptions).then(successCallback,errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

confirmStrings Object Yes The strings to be used in the

confirmation dialog. The
object contains the following
attributes:
- cancelButtonLabel:
(Optional) String. The cancel
button label. If you do not
specify the cancel button
label, Cancel is used as the
button label.
- confirmButtonLabel:
(Optional) String. The
confirm button label. If you
do not specify the confirm
button label, OK is used as
the button label.
- subtitle: (Optional) String.
The subtitle to be displayed
in the confirmation dialog.
- text: String. The message
to be displayed in the
confirmation dialog.
- title: (Optional) String. The
title to be displayed in the
confirmation dialog.

confirmOptions Object No The height and width

options for confirmation
dialog. The object contains
the following attributes:
- height: (Optional) Number.
Height of the confirmation
dialog in pixels.
- width: (Optional) Number.
Width of the confirmation
dialog in pixels.
NAME TYPE REQUIRED DESCRIPTION

successCallback function No A function to execute when

the confirmation dialog is
closed by clicking the
confirm, cancel, or X in the
top-right corner of the
dialog. An object with the
confirmed (Boolean)
attribute is passed that
indicates whether the
confirm button was clicked
to close the dialog.

errorCallback function No A function to execute when

the operation fails.

Example
The following code sample displays a confirmation dialog box. Appropriate message is logged in the console
depending on whether confirm or cancel/X was clicked to close the dialog.

var confirmStrings = { text:"This is a confirmation.", title:"Confirmation Dialog" };

var confirmOptions = { height: 200, width: 450 };
[Link](confirmStrings, confirmOptions).then(
function (success) {
if ([Link])
[Link]("Dialog closed using OK button.");
else
[Link]("Dialog closed using Cancel button or X.");
});

Related topics
[Link]
openErrorDialog (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays an error dialog.

Syntax
[Link](errorOptions).then(successCallback,errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

errorOptions Object Yes An object to specify the

options for error dialog. The
object contains the following
attributes:
- details: (Optional) String.
Details about the error.
When you specify this, the
Download Log File button
is available in the error
message, and clicking it will
let users download a text file
with the content specified in
this attribute.
- errorCode: (Optional)
Number. The error code. If
you just set errorCode, the
message for the error code is
automatically retrieved from
the server and displayed in
the error dialog. If you
specify an invalid errorCode
value, an error dialog with a
default error message is
displyed.
- message: (Optional) String.
The message to be displayed
in the error dialog.

You must set either the

errorCode or message
attribute.

successCallback function No A function to execute when

the error dialog is closed.

errorCallback function No A function to execute when

the operation fails.

Example
The following code sample passes an incorrect errorCode (1234) to display an error dialog with default message:

[Link]({ errorCode:1234 }).then(

function (success) {
[Link](success);
},
function (error) {
[Link](error);
});

This displays an error dialog with the default message:

Related topics
[Link]
openFile (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens a file.

Syntax
[Link](file,openFileOptions)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

file Object Yes An object describing the file

to open. The object has the
following attributes:
- fileContent: String.
Contents of the file.
- fileName: String. Name of
the file.
- fileSize: Number. Size of
the file in KB.
- mimeType: String. MIME
type of the file.

openFileOptions Number No Specify whether to open or

save the file:
1:Open
2:Save
If you do not specify this
parameter, by default 1
(open) is passed.

Related topics
[Link]
openForm (Client API reference)
8/24/2018 • 4 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens an entity form or a quick create form.

Syntax
[Link](entityFormOptions,formParameters).then(successCallback,errorCallback);

Parameters

NAME TYPE REQUIRED DESCRIPTION

entityFormOptions Object Yes Entity form options for

opening the form. The object
contains the following
attributes:
cmdbar: (Optional)
Boolean. Indicates
whether to display the
command bar. If you
do not specify this
parameter, the
command bar is
displayed by default.
createFromEntity:
(Optional) Lookup.
Designates a record
that will provide
default values based
on mapped attribute
values. The lookup
object has the
following String
properties:
entityType , id ,
and name (optional).
entityId: (Optional)
String. ID of the entity
record to display the
form for.
entityName:
(Optional) String.
Logical name of the
entity to display the
form for.
formId: (Optional)
String. ID of the form
instance to be
displayed.
height: (Optional)
Number. Height of the
form window to be
displayed in pixels.
navBar: (Optional)
String. Controls
whether the
navigation bar is
displayed and
whether application
navigation is available
using the areas and
subareas defined in
the sitemap. Valid
values are: "on", "off",
or "entity".
on : The
navigation bar
is displayed.
This is the
default
behavior if the
navBar
parameter is
not used.
off : The
navigation bar
is not
displayed.
People can
navigate using
other user
interface
elements or
the back and
forward
buttons.
entity : On
an entity form,
only the
navigation
options for
related entities
are available.
After
navigating to a
related entity,
a back button
is displayed in
the navigation
bar to allow
returning to
the original
record.
openInNewWindow:
(Optional) Boolean.
Indicates whether to
display form in a new
window.
windowPosition:
(Optional) Number.
Specify one of the
following values for
the window position
of the form on the
screen:
1:center
2:side
processId: (Optional)
String. ID of the
business process to
be displayed on the
form.
processInstanceId:
(Optional) String. ID of
the business process
instance to be
displayed on the form.
relationship:
(Optional) Object.
Define a relationship
object to display the
related records on the
form. The object has
the following
attributes.

NAM T YPE DESC

E RIPTI
ON

attr Stri Na
ibu ng me
teN of
am the
e attr
ibut
e
use
d
for
rela
tion
shi
p.

na Stri Na
me ng me
of
the
rela
tion
shi
p.

nav Stri Na
iga ng me
tio of
nPr the
op nav
ert igat
yN ion
am pro
e per
ty
for
this
rela
tion
shi
p.
rel Nu Rel
ati mb atio
ons er nsh
hip ip
Typ typ
e e.
Spe
cify
one
of
the
foll
owi
ng
val
ues
:

0:OneToMany

1:ManyToMany

rol Nu Rol
eTy mb e
pe er typ
e in
rela
tion
shi
p.
Spe
cify
one
of
the
foll
owi
ng
val
ues
:

1:Referencing

2:AssociationEntity

selectedStageId:
(Optional) String. ID of
the selected stage in
business process
instance.
useQuickCreateFor
m: (Optional) Boolean.
Indicates whether to
open a quick create
form. If you do not
specify this, by default
false is passed.
width: (Optional)
Number. Width of the
form window to be
displayed in pixels.
formParameters Object No A dictionary object that
passes extra parameters to
the form. Invalid parameters
will cause an error.

For information about

passing parameters to a
form, see Set field values
using parameters passed to a
form and Configure a form to
accept custom querystring
parameters

successCallback Function No A function to execute when:

The entity form is
displayed for existing
records.
The record is saved in
the entity form
displayed for a new
record.
The record is saved in
the quick create form.
This function is passed an
object as a parameter.
The object has a
savedEntityReference
array with the following
properties to identify the
record(s) displayed or
created:
entityType: The
logical name of the
entity.
id: A string
representation of a
GUID value for the
record.
name: The primary
attribute value of the
record displayed or
created.
NOTE:
On web client, when
you open a form for
an existing or new
record, or open a
quick create form, the
savedEntityReferenc
e array will contain a
single item.
On Unified Interface:
The
successCallba
ck function is
executed only
when you save
a record in a
quick create
form that was
opened using
the
openForm
method.
When you
open a quick
create form,
and create
multiple
records by
clicking Save
& New, the
savedEntityR
eference
array will
contain
multiple items,
each item
representing
the record
created using
the quick
create form.

errorCallback Function No A function to execute when

the operation fails.
NOTE: On Unified
Interface, the
errorCallback function
will be executed only if
you are opening a quick
create form.

Remarks
You must use this method to open entity or quick create forms instead of the deprecated [Link]
and [Link] methods.

Examples
Example 1: Open an entity form for existing record
The following sample code opens a contact form to display an existing contact record:

var entityFormOptions = {};

entityFormOptions["entityName"] = "contact";
entityFormOptions["entityId"] = "8DA6E5B9-88DF-E311-B8E5-6C3BE5A8B200"

// Open the form.

[Link](entityFormOptions).then(
function (success) {
[Link](success);
},
function (error) {
[Link](error);
});

Example 2: Open an entity form for new record

The following sample code opens a contact form with some pre-populated values to create a new record:
var entityFormOptions = {};
entityFormOptions["entityName"] = "contact";

// Set default values for the Contact form

var formParameters = {};
formParameters["firstname"] = "Sample";
formParameters["lastname"] = "Contact";
formParameters["fullname"] = "Sample Contact";
formParameters["emailaddress1"] = "contact@[Link]";
formParameters["jobtitle"] = "Sr. Marketing Manager";
formParameters["donotemail"] = "1";
formParameters["description"] = "Default values for this record were set programmatically.";

// Open the form.

[Link](entityFormOptions, formParameters).then(
function (success) {
[Link](success);
},
function (error) {
[Link](error);
});

Example 3: Open a quick create form

The following sample code opens a quick create contact form with some pre-populated values:

var entityFormOptions = {};

entityFormOptions["entityName"] = "contact";
entityFormOptions["useQuickCreateForm"] = true;

// Set default values for the Contact form

// Open the form.

[Link](entityFormOptions, formParameters).then(
function (success) {
[Link](success);
},
function (error) {
[Link](error);
});

Related topics
[Link]
openUrl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens a URL, including file URLs.

Syntax
[Link](url,openUrlOptions)

Parameters
NAME TYPE REQUIRED DESCRIPTION

url String Yes URL to open.

openUrlOptions Object No Options to open the

[Link] object contains the
following attributes:
- height: (Optional) Number.
Height of the window to
display the resultant page in
pixels.
- width: (Optional) Number.
Width of the window to
display the resultant page in
pixels.

Remarks
This method is especially helpful for mobile clients to open a URL in a browser outside of shim.
Related topics
[Link]
openWebResource (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens an HTML web resource.

Syntax
[Link](webResourceName,windowOptions,data)

Parameters
NAME TYPE REQUIRED DESCRIPTION

webResourceName String Yes Name of the HTML web

resource to open.

windowOptions Object No Window options for opening

the web resource. The object
contains the following
attributes:
- height: (Optional) Number.
Height of the window to
open in pixels.
- width: (Optional) Number.
Width of the window to
open in pixels.

data String No Data to be passed into the

data parameter.

Remarks
You must use this method to display web resources instead of the deprecated [Link]
method.
An HTML web resource can accept the parameter values described in Pass parameters to HTML web resources.
This function only provides for passing in the optional data parameter. To pass values for the other valid
parameters, you must append them to the webResourceName parameter.

NOTE
The Xrm object isn’t available in HTML web resources. Therefore, scripts containing Xrm.* methods aren’t supported in
HTML web resources. [Link].* will work if the HTML web resource is loaded in a form container. However, for other
places, such as loading an HTML web resource as part of the SiteMap, [Link].* also won’t work. More information:
GetGlobalContext function and [Link]

Examples
Open an HTML web resource named “new_webResource.htm”:
[Link]("new_webResource.htm");

Open an HTML web resource, setting the windowOptions:

var windowOptions = { height: 400, width: 400 }

[Link]("new_webResource.htm",windowOptions);

Open an HTML web resource including a single item of data for the data parameter
[Link]("new_webResource.htm",null,"dataItemValue");

Related topics
[Link]
[Link]
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides a method to display a web page in the side pane of Customer Engagement form.

METHOD DESCRIPTION

loadPanel Displays the web page represented by a URL in the static area
in the side pane, which appears on all pages in the Dynamics
365 Customer Engagement web client.

NOTE
The [Link] namespace was introduced in the December 2016 update for Dynamics 365 (online and on-premises), and
the method under this namespace is a preview feature. A preview feature is a feature that is not complete, but is made
available before it’s officially in a release so customers can get early access and provide feedback. Preview features aren’t
meant for production use and may have limited or restricted functionality. We expect changes to this feature, so you
shouldn’t use it in production. Use it only in test and development environments. Microsoft doesn't provide support for this
preview feature. Microsoft Dynamics 365 Technical Support won’t be able to help you with issues or questions. Preview
features aren't meant for production use and are subject to a separate supplemental terms of use.

Related topics
Client API Xrm object
loadPanel (Client-side reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays the web page represented by a URL in the static area in the side pane, which appears on all pages in the
Dynamics 365 Customer Engagement web client.

Syntax
[Link](url, title)

Parameters
PARAMETER NAME TYPE REQUIRED DESCRIPTION

url String Yes URL of the page to be

loaded in the side pane static
area.

title String Yes Title of the side pane static

area.

Remarks
This method is supported only for the web client.
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides a container for useful methods.

Methods
METHOD DESCRIPTION

closeProgressIndicator Closes a progress dialog box.

getAllowedStatusTransitions Returns the valid state transitions for the specified entity type
and state code.

getEntityMetadata Returns the entity metadata for the specified entity.

getGlobalContext Gets the global context.

getLearningPathAttributeName Returns the name of the DOM attribute expected by the

Learning Path (guided help) Content Designer for identifying
UI controls in the Dynamics 365 Customer Engagement
forms.

getResourceString Returns the localized string for a given key associated with
the specified web resource.

invokeProcessAction Invokes an action based on the specified parameters.

lookupObjects Opens a lookup control to select one or more items.

refreshParentGrid Refreshes the parent grid containing the specified record.

showProgressIndicator Displays a progress dialog with the specified message.

Deprecated methods
The following table lists the new methods you should use instead of the deprecated methods in the [Link]
namespace. These methods were deprecated in Dynamics 365 (online), version 9.0.

DEPRECATED METHOD NEW METHOD TO BE USED

[Link] [Link]

[Link] [Link]
DEPRECATED METHOD NEW METHOD TO BE USED

[Link] [Link]

More information: Deprecated client APIs

Related topics
Client API execution context
Client API Xrm object
Client API reference
closeProgressIndicator (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Closes a progress dialog box.
If no progress dialog is displayed currently, this method will do nothing. You can display a progress dialog using the
showProgressIndicator method.

Syntax
[Link]()

Related topics
showProgressIndicator
[Link]
getAllowedStatusTransitions (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the valid state transitions for the specified entity type and state code.

Syntax
[Link](entityName,stateCode).then(successCallback, errorCallback)

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityName String Yes The logical name of the

entity.

stateCode Number Yes The state code to find out

the allowed status transition
values.

successCallback Function No The function to execute

when the operation
succeeds.

errorCallback Function No The function to execute

when the operation fails.

Related topics
[Link]
getEntityMetadata
8/24/2018 • 5 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the entity metadata for the specified entity.

Syntax
[Link](entityName,attributes).then(successCallback, errorCallback)

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityName String Yes The logical name of the

entity.

attributes array of strings No The attributes to get

metadata for.

successCallback function No A function to call when the

entity metadata is returned.

errorCallback function No A function to call when the

operation fails.

Returns
Type: Object
Description: An object containing the entity metadata information with the following attributes.

ATTRIBUTE NAME TYPE DESCRIPTION

ActivityTypeMask Number Whether a custom activity should

appear in the activity menus in the Web
application. 0 indicates that the custom
activity doesn't appear; 1 indicates that
it does appear.

AutoRouteToOwnerQueue Boolean Indicates whether to automatically

move records to the owner’s default
queue when a record of this type is
created or assigned.

CanEnableSyncToExternalSearchIndex Boolean For internal use only.

CanTriggerWorkflow Boolean Indicates whether the entity can trigger

a workflow process.

Description String Description for the entity.

DisplayCollectionName String Plural display name for the entity.

DisplayName String Display name for the entity.

EnforceStateTransitions Boolean Indicates whether the entity will enforce

custom state transitions.

EntityColor String The hexadecimal code to represent the

color to be used for this entity in the
application.

EntitySetName String The name of the Web API entity set for
this entity.

HasActivities Boolean Indicates whether activities are

associated with this entity.

IsActivity Boolean Indicates whether the entity is an

activity.

IsActivityParty Boolean Indicates whether the email messages

can be sent to an email address stored
in a record of this type.

IsBusinessProcessEnabled Boolean Indicates whether the entity is enabled

for business process flows.

IsBPFEntity Boolean Indicates whether the entity is a

business process flow entity.

IsChildEntity Boolean Indicates whether the entity is a child

entity.

IsConnectionsEnabled Boolean Indicates whether connections are

enabled for this entity.

IsCustomEntity Boolean Indicates whether the entity is a custom

entity.

IsCustomizable Boolean Indicates whether the entity is

customizable.

IsDocumentManagementEnabled Boolean Indicates whether document

management is enabled.

IsDocumentRecommendationsEnabled Boolean Indicates whether the documemt

recommendations is enabled.

IsDuplicateDetectionEnabled Boolean Indicates whether duplicate detection is

enabled.

IsEnabledForCharts Boolean Indicates whether charts are enabled.

IsImportable Boolean Indicates whether the entity can be

imported using the Import Wizard.
IsInteractionCentricEnabled Boolean Indicates the entity is enabled for
interactive experience.

IsKnowledgeManagementEnabled Boolean Indicates whether knowledge

management is enabled for the entity.

IsMailMergeEnabled Boolean Indicates whether mail merge is enabled

for this entity.

IsManaged Boolean Indicates whether the entity is part of a

managed solution.

IsOneNoteIntegrationEnabled Boolean Indicates whether OneNote integration

is enabled for the entity.

IsOptimisticConcurrencyEnabled Boolean Indicates whether optimistic

concurrency is enabled for the entity.

IsQuickCreateEnabled Boolean Indicates whether the entity is enabled

for quick create forms.

IsStateModelAware Boolean Indicates whether the entity supports

setting custom state transitions.

IsValidForAdvancedFind Boolean Indicates whether the entity is will be

shown in Advanced Find.

IsVisibleInMobileClient Boolean Indicates whether Microsoft Dynamics

365 for tablets users can see data for
this entity.

IsEnabledInUnifiedInterface Boolean Indicates whether the entity is enabled

for Unified Interface.

LogicalCollectionName String The logical collection name.

LogicalName String The logical name for the entity.

ObjectTypeCode Number The entity type code.

OwnershipType String The ownership type for the entity:

"UserOwned" or "OrganizationOwned".

PrimaryIdAttribute String The name of the attribute that is the

primary id for the entity.

PrimaryImageAttribute String The name of the primary image

attribute for an entity.

PrimaryNameAttribute String The name of the primary attribute for

an entity.
Privileges Array of objects The privilege metadata for the entity
where each object contains the
following attributes to define the
security privilege for access to an entity:
CanBeBasic: Boolean. Whether
the privilege can be basic access
level.
CanBeDeep: Boolean. Whether
the privilege can be deep access
level.
CanBeEntityReference:
Boolean. Whether the privilege
for an external party can be
basic access level.
CanBeGlobal: Boolean. Whether
the privilege can be global access
level.
CanBeLocal: Boolean. Whether
the privilege can be local access
level.
CanBeParentEntityReference:
Boolean. Whether the privilege
for an external party can be
parent access level.
Name: String. The name of the
privilege.
PrivilegeId: String. The ID of the
privilege.
PrivilegeType: Number. The
type of privilege, which is one of
the following:
0: None
1: Create
2: Read
3: Write
4: Delete
5: Assign
6: Share
7: Append
8: AppendTo

Attributes Collection A collection of attribute metadata

objects. The object returned depends on
the type of attribute metadata.
Attribute metadata for the base
type
An object returned with the
following properties:
AttributeType: Number. Type of
an attribute. For a list of
attribute type values, see
AttributeTypeCode
DisplayName: String. Display
name for the attribute.
EntityLogicalName: String.
Logical name of the entity that
contains the attribute.
LogicalName: String. Logical
name for the attribute.
Attribute metadata for the
boolean type
An object returned with the
following properties in addition to
the base attribute metadata type
properties:
DefaultFormValue: Boolean.
Default value for a Boolean
option set.
OptionSet: Object. Options for
the boolean attribute where
each option is a key:value pair.
Attribute metadata for the enum
type
An object returned with the
following properties in addition to
the base attribute metadata type
properties:
OptionSet: Object. Options for
the attribute where each option
is a key:value pair.
Attribute metadata for the
picklist type
An object returned with the
following properties in addition to
the base attribute metadata type
properties:
DefaultFormValue: Number.
Default form value for the
attribute.
OptionSet: Object. Options for
the attribute where each option
is a key:value pair.
Attribute metadata for the state
type
An object returned with the
following properties in addition to
the base attribute metadata type
properties:
OptionSet: Object. Options for
the attribute where each option
is a key:value pair.
The object also contains the
following methods:
getDefaultStatus(arg): Returns
the default status (number)
based on the passed in state
value for an entity. For default
state and status values for an
entity, see entity metadata
information of the entity in
entity reference.
getStatusValuesForState(arg):
Returns possible status values
(array of numbers) for a specified
state value. For state and status
values for an entity, see entity
metadata information of the
entity in entity reference.
Attribute metadata for the status
type
An object returned with the
following properties in addition to
the base attribute metadata type
properties:
OptionSet: Object. Options for
the attribute where each option
is a key:value pair.
The object also contains the
following method:
getState(arg): Returns the state
value (number) for the specified
status value (number). For
default state and status values
for an entity, see entity metadata
information of the entity in
entity reference.

Related topics
[Link]
getGlobalContext (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Gets the global context.
The method provides access to the global context without going through the form context. It contains an equivalent
of all the methods available for the [Link] object (now deprecated) to retrieve information specific to
the client, organization or user.

IMPORTANT
To access the global context information in a standalone HTML Web resource, you should include a reference to
[Link] in the web resource, and then use the GetGlobalContext function. More information:
GetGlobalContext function and [Link]

Properties of Global Context (getGlobalContext)

Use the following properties of global context to return information about the client, organization settings, or user
settings:

PROPERTY DESCRIPTION

client Returns information about the client.

organizationSettings Returns information about the current organization settings.

userSettings Returns information about the current user settings.

Methods of Global Context (getGlobalContext)

METHOD DESCRIPTION

getAdvancedConfigSetting Returns information about the advanced configuration settings

for the organization.

getClientUrl Returns the base URL that was used to access the application.

getCurrentAppName Returns the name of the current business app in Customer

Engagement.

getCurrentAppProperties Returns the properties of the current business app in

Customer Engagement.

getCurrentAppUrl Returns the URL of the current business app in Customer

Engagement.

getVersion Returns the version number of the Dynamics 365 Customer

Engagement instance.
METHOD DESCRIPTION

isOnPremises Returns a boolean value indicating if the Customer

Engagement instance is hosted on-premises or online.

prependOrgName Prefixes the current organization's unique name to a string,

typically a URL path.
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides access to the methods to determine which client is being used, whether the client is connected to the
server, and what kind of device is being used.
var clientContext = [Link]().client

The following methods are available for the client context.

getClient
Returns a value to indicate which client the script is executing in.
Syntax
[Link]()

Return Value
Type: String
Description: The values returned are:

VALUE CLIENT

Web Web application

Web Unified Interface

Outlook Outlook

Mobile Mobile app

getClientState
Returns a value to indicate the state of the client.
Syntax
[Link]()

Return Value
Type: String
Description: The values returned are:

VALUE CLIENT

Online Web application, Outlook, Mobile app, Unified Interface

Offline Outlook, Mobile app

getFormFactor
Returns information about the kind of device the user is using.
Syntax
[Link]()

Return Value
Type: Number
Description: The values returned are:

VALUE FORM FACTOR

0 Unknown

1 Desktop

2 Tablet

3 Phone

isOffline
Returns information whether the server is online or offline.
Syntax
[Link]()

Return Value
Type: Boolean
Description: true if the server is offline; false otherwise.

Related topics
Organization Settings
User Settings
[Link]
[Link] (Client API
reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns information about the current organization settings.
var organizationSettings = [Link]().organizationSettings

The organizationSettings object provides following properties.

attributes
Returns attributes and their values as key:value pairs that are available for the organization entity. Additional
values will be available as attributes if they are specified as attribute dependencies in the web resource dependency
list. The key will be the attribute logical name.
Syntax
[Link]

Return Value
Type: Object
Description: An object with attributes and their values.

baseCurrencyId
Returns the ID of the base currency for the current organization.
Syntax
[Link]

Return Value
Type: String
Description: ID of the base currency.

defaultCountryCode
Returns the default country/region code for phone numbers for the current organization.
Syntax
[Link]

Return Value
Type: String
Description: Default country/region code for phone numbers.

isAutoSaveEnabled
Indicates whether the auto-save option is enabled for the current organization.
Syntax
[Link]

Return Value
Type: Boolean
Description: true if enabled; false otherwise.

languageId
Returns the preferred language ID for the current organization.
Syntax
[Link]

Return Value
Type: Number
Description: Preferred Language ID. For example:
1033

organizationId
Returns the ID of the current organization.
Syntax
[Link]

Return Value
Type: String
Description: Id of the current organization.

uniqueName
Returns the unique name of the current organization.
Syntax
[Link]

Return Value
Type: String
Description: Unique name of the current organization.

useSkypeProtocol
Indicates whether the Skype protocol is used for the current organization.
Syntax
[Link]

Return Value
Type: Boolean
Description: true if Skype protocol is used; false otherwise.

Related topics
Client context
User settings
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns information about the current user settings.
var userSettings = [Link]().userSettings

The userSettings object provides following properties and a method.

dateFormattingInfo
Returns the date formatting information for the current user.
Syntax
[Link]

Return Value
Type: Object
Description: An object with informatiuon about date formatting such as FirstDayOfWeek, LongDatePattern,
MonthDayPattern, TimeSeparator, and so on.

defaultDashboardId
Returns the ID of the default dashboard for the current user.
Syntax
[Link]

Return Value
Type: String
Description: ID of the default dashboard.

isGuidedHelpEnabled
Indicates whether guided help is enabled for the current user.
Syntax
[Link]

Return Value
Type: Boolean
Description: true if enabled; false otherwise.

isHighContrastEnabled
Indicates whether high contrast is enabled for the current user.
Syntax
[Link]

Return Value
Type: Boolean
Description: true if enabled; false otherwise.

isRTL
Indicates whether the language for the current user is a right-to-left (RTL ) language.
Syntax
[Link]

Return Value
Type: Boolean
Description: true if it is RTL; false otherwise.

languageId
Returns the language ID for the current user.
Syntax
[Link]

Return Value
Type: Number
Description: Language ID.

securityRolePrivileges
Returns an array of strings that represent the GUID values of each of the security role privilege that the user is
associated with or any teams that the user is associated with.
Syntax
[Link]

Return Value
Type: Array
Description: GUID values of each of the security role privilege.

securityRoles
Returns an array of strings that represent the GUID values of each of the security role that the user is associated
with or any teams that the user is associated with.
Syntax
[Link]

Return Value
Type: Array
Description: GUID values of each of the security role. For example:
["0d3dd20a-17a6-e711-a94e-000d3a1a7a9b", "ff42d20a-17a6-e711-a94e-000d3a1a7a9b"]

transactionCurrencyId
Returns the transaction currency ID for the current user.
Syntax
[Link]

Return Value
Type: String
Description: Transaction currency ID.

userId
Returns the GUID of the [Link] value for the current user.
Syntax
[Link]

Return Value
Type: String
Description: The ID of the user. For example:
"{75B5BA27-FD41-4D45-8E3A-C8446C95F0CC}"

userName
Returns the name of the current user.
Syntax
[Link]

Return Value
Type: String
Description: Name of the current user.

getTimeZoneOffsetMinutes method
Returns the difference in minutes between the local time and Coordinated Universal Time (UTC ).
Syntax
[Link]()

Return Value
Type: number
Description: Time zone offset in minutes.

Related topics
Client context
Organization settings
[Link]
getAdvancedConfigSetting (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns information about the advanced configuration settings for the organization.

Syntax
var globalContext = [Link]();
[Link](setting);

Parameters
NAME TYPE REQUIRED DESCRIPTION

setting String Yes Name of the configuration

setting.
Only the following two
configuration settings are
supported:
"MaxChildIncidentNumber
" and
"MaxIncidentMergeNumb
er"

Return Value
Returns the advanced configuration setting value.
Related topics
[Link]
getClientUrl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the base URL that was used to access the application.

Syntax
var globalContext = [Link]();
[Link]();

Return Value
Type: String
Description: The values returned will resemble those listed in the following table.

VALUE CLIENT

[Link] Dynamics 365 Customer Engagement (online)

http(s)://[server]/[org] Dynamics 365 Customer Engagement (on-premises)

[Link] Dynamics 365 Customer Engagement for Outlook with Offline

Access when offline

Related topics
[Link]
getCurrentAppName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the current business app in Customer Engagement.

Syntax
var globalContext = [Link]();
[Link]().then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when the

business app name is
returned.

errorCallback Function Yes A function to call when the

operation fails.

Return Value
If this method is called in the context of a business app, returns the name of the business app. Otherwise, it fails
with an error.
Related topics
Create and manage custom business apps using code
[Link]
getCurrentAppProperties (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the properties of the current business app in Customer Engagement.

Syntax
var globalContext = [Link]();
[Link]().then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

successCallback Function Yes A function to call when the

business app property
information is returned. An
object with the following
attributes (app properties) is
passed to the function :
- appId
- displayName
- uniqueName
- url
- webResourceId
- webResourceName
- welcomePageId
- welcomePageName

errorCallback Function Yes A function to call when the

operation fails.

Return Value
If this method is called in the context of a business app, returns the properties of the business app. Otherwise, it
fails with an error.
Related topics
Create and manage custom business apps using code
[Link]
getCurrentAppUrl (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the URL of the current business app in Customer Engagement.

Syntax
var globalContext = [Link]();
[Link]();

Return Value
Type: String
Description: URL of the current business app. Possible return values:

VALUE CLIENT

[Link] Dynamics 365 Customer Engagement (online)

[Link] Dynamics 365 Customer Engagement (on-premises)

Related topics
Create and manage custom business apps using code
[Link]
getVersion (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the version number of the Dynamics 365 Customer Engagement instance.

Syntax
var globalContext = [Link]();
[Link]();

Return Value
Type: String
Description: Version of the Customer Engagement instance. For example:
"9.0.0.1103"

Related topics
[Link]
isOnPremise (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns a boolean value indicating if the Customer Engagement instance is hosted on-premises or online.

Syntax
var globalContext = [Link]();
[Link]();

Return Value
Type: Boolean
Description: true if the Customer Engagement instance is on-premises; false otherwise.
Related topics
[Link]
prependOrgName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Prefixes the current organization's unique name to a string, typically a URL path.

Syntax
var globalContext = [Link]();
[Link](sPath);

Parameters
NAME TYPE REQUIRED DESCRIPTION

sPath String Yes A local path to a resource.

Return Value
Type: String
Description: A path string with the organization name prefixed in the following format:
"/"+ orgName + sPath

Related topics
[Link]
getLearningPathAttributeName (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the name of the DOM attribute expected by the Learning Path (guided help) Content Designer for
identifying UI controls in the Dynamics 365 Customer Engagement forms.
An attribute by this name must be added to the UI element that needs to be exposed to Learning Path (guided
help).

Syntax
[Link]()

Returns
Type: String
Description: DOM attribute expected by the Learning Path (guided help) Content Designer.
Related topics
Create your own guided help (Learning Path) for your customers
[Link]
getResourceString (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Returns the localized string for a given key associated with the specified web resource.

Syntax
[Link](webResourceName,key)

Parameters
NAME TYPE REQUIRED DESCRIPTION

webResourceName String Yes The name of the web

resource.

key String Yes The key for the localized

string.

Return value
A localized string.

Remarks
When you create RESX web resources you must explicitly set the language value and include the locale identifier
(LCID ) for the appropriate language in the name of the web resource. For example,
new_/strings/[Link] would contain resources for English language. See Microsoft Locale ID
Values for a list of LCID values.
For example [Link]("new_/strings/MyAppResources","hello") will return the localized string
value for the resource key hello within the new_/strings/[Link] web resource if the user’s
preferred language is English. Notice that the function doesn’t refer to any specific language or full name of any
RESX web resource. This functionality depends on the RESX web resource being associated to the calling
JavaScript web resource as a dependency. More information: Web resource dependencies.
The appropriate string value will be determined by the individual user’s language preference and the languages
available in the organization. If a localized string is not found that matches the user’s language preference, the
localized string will automatically fallback to the base language for the organization. If no matching localized string
is found for the organizations base language, a null value will be returned.
Related topics
[Link]
String (RESX) web resources
Web resource dependencies
invokeProcessAction (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Invokes an action based on the specified parameters.
For more information about actions, see Actions overview

Syntax
[Link](name,parameters).then(successCallback, errorCallback)

Parameters
NAME TYPE REQUIRED DESCRIPTION

name String Yes Name of the process action

to invoke.

parameters object No An object containing input

parameters for the action.
You define an object using
key:value pairs of items,
where key is of String
type.

successCallback Function Yes A function to call when the

action is invoked.

errorCallback Function Yes A function to call when the

operation fails.

Returns
On success, returns Web API result along with any action output.
Related topics
Actions overview
[Link]
lookupObjects (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Opens a lookup control to select one or more items.

Syntax
[Link](lookupOptions).then(successCallback, cancelCallback)

Parameters
lookupOptions: Object. Defines the options for opening the lookup dialog. Has the following properties:

PROPERTY NAME TYPE REQUIRED DESCRIPTION

allowMultiSelect Boolean No Indicates whether the lookup

allows more than one item
to be selected.

defaultEntityType String No The default entity type to

use.

defaultViewId String No The default view to use.

entityTypes Array No The entity types to display.

showBarcodeScanner Boolean No Indicates whether the lookup

control should show the
barcode scanner in mobile
clients.

viewIds Array No The views to be available in

the view picker. Only system
views are supported.

successCallback Function Yes A function to call when the

lookup control is invoked. An
object with the following
properties is passed:
- entityType: String. Entity
type of the record selected in
the lookup control.
- id: String. ID of the record
selected in the lookup
control.
- name: String. Name of the
record selected in the lookup
control.

errorCallback Function Yes A function to call when you

cancel the lookup control or
the operation fails.
PROPERTY NAME TYPE REQUIRED DESCRIPTION

Related topics
[Link]
refreshParentGrid (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Refreshes the parent grid containing the specified record.

Syntax
[Link](lookupOptions)

Parameters
lookupOptions: An object with the following properties to specify the record:

PROPERTY NAME TYPE REQUIRED DESCRIPTION

entityType String Yes Entity type of the record.

id String Yes ID of the record.

name String No Name of the record.

Related topics
[Link]
showProgressIndicator (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Displays a progress dialog with the specified message.
Any subsequent call to this method will update the displayed message in the existing progress dialog with the
message specified in the latest method call.

WARNING
The progress dialog blocks the UI until it is closed using the closeProgressIndicator method. So, you must use this method
with caution.

Syntax
[Link](message)

Parameters
NAME TYPE REQUIRED DESCRIPTION

message String Yes The message to be displayed

in the progress dialog.

Related topics
closeProgressIndicator
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides properties and methods to use Web API to create and manage records and execute Web API actions
and functions in Customer Engagement.

Properties
PROPERTY DESCRIPTION

online Provides methods to use Web API to create and manage

records and execute Web API actions and functions in
Customer Engagement when connected to the Customer
Engagement server (online mode).

offline Provides methods to create and manage records in the

Dynamics 365 Customer Engagement mobile clients while
working in the offline mode.

Methods
METHOD DESCRIPTION

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.

isAvailableOffline 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.

Supported only for the online mode ([Link]).

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

Supported only for the online mode ([Link]).

Related topics
Use the Dynamics 365 Customer Engagement Web API
Client API Xrm object
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to use Web API to create and manage records and execute Web API actions and functions in
Customer Engagement when connected to the Customer Engagement server (online mode).
var onlineWebApi = [Link];

The onlineWebApi object provides the following methods:

createRecord
deleteRecord
retrieveRecord
retrieveMultipleRecords
updateRecord
execute
executeMultiple
Related topics
[Link]
[Link]
[Link] (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Provides methods to create and manage records in the Dynamics 365 Customer Engagement mobile clients while
working in the offline mode.
For information about the mobile offline feature, see Configure mobile offline synchronization to allow users to
work in offline mode on their mobile device
var offlineWebApi = [Link];

NOTE
Use [Link] instead of the deprecated [Link] namespace to create and manage records in the
mobile clients while working in the offline mode.

The offlineWebApi object provides the following methods. When in the offline mode, these methods will work
only for entities that are enabled for mobile offline synchronization and available in current user’s mobile offline
profile.
createRecord
deleteRecord
isAvailableOffline
retrieveRecord
retrieveMultipleRecords
updateRecord

IMPORTANT
While creating or updating record in the offline mode, only basic validation is performed on the input data. Basic validation
includes things such as ensuring that the entity attribute name specified is in lower case and does exist for an entity, checking
for data type mismatch for the specified attribute value, preventing records getting created with the same GUID value,
checking whether the related entity is offline enabled when retrieving related entity records, and validating if the record that
you want to retrieve, update, or delete actually exists in the offline data store. Business-level validations happen only when
you are connected to the server and the data is synchronized. A record is created or updated only if the input data is
completely valid.

Related topics
[Link]
[Link]
createRecord (Client API reference)
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Creates an entity record.

Syntax
[Link](entityLogicalName, data).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes Logical name of the entity

you want to create. For
example: "account".

data Object Yes A JSON object defining

the attributes and values
for the new entity
record.
See examples later in this
topic to see how you can
define the data object
for various create
scenarios.

successCallback Function No A function to call when a

record is created. An
object with the following
properties will be passed
to identify the new
record:
entityType: String.
The entity logical
name of the new
record.
id: String. GUID of
the new record.

errorCallback Function No A function to call when the

operation fails. An object
with the following properties
will be passed:
errorCode: Number.
The error code.
message: String. An
error message
describing the issue.
Return Value
On success, returns a promise object containing the attributes specified earlier in the description of the
successCallback parameter.

Examples
These examples use the same request objects as demonstrated in Create an entity using the Web API to define the
data object for creating an entity record.
Basic create
Creates a sample account record.

// define the data to create new account

var data =
{
"name": "Sample Account",
"creditonhold": false,
"address1_latitude": 47.639583,
"description": "This is the description of the sample account",
"revenue": 5000000,
"accountcategorycode": 1
}

// create account record

[Link]("account", data).then(
function success(result) {
[Link]("Account created with ID: " + [Link]);
// perform operations on record creation
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

Create related entity records along with the primary record

You can create entities related to each other by defining them as navigation properties values. This is known as
deep insert. In this example, we will create a sample account record along with the primary contact record and an
associated opportunity record.
// define data to create primary and related entity records
var data =
{
"name": "Sample Account",
"primarycontactid":
{
"firstname": "John",
"lastname": "Smith"
},
"opportunity_customer_accounts":
[
{
"name": "Opportunity associated to Sample Account",
"Opportunity_Tasks":
[
{ "subject": "Task associated to opportunity" }
]
}
]
}

// create account record

Associate entities on creating new records

To associate new entity records to existing entity records, set the value of single-valued navigation properties using
the @[Link] annotation. However, for mobile clients in the offline mode, you cannot use the @[Link]
annotation, and instead have to pass a lookup object (logicalname and id) pointing to the target record. Here are
code examples for both the scenarios:
For online scenario (connected to server)
The following example creates an account record, and associates it to an existing contact record to set the latter as
the primary contact for the new account record:

var data =
{
"name": "Sample Account",
"primarycontactid@[Link]": "/contacts(465b158c-541c-e511-80d3-3863bb347ba8)"
}

// create account record

For mobile offline scenario

Here is the updated sample code to create an account record, and associate it to an existing contact record to set the
latter as the primary contact for the new account record from mobile clients when working in the offline mode:

var data =
{
"name": "Sample Account",
"primarycontactid":
{
"logicalname": "contact",
"id": "465b158c-541c-e511-80d3-3863bb347ba8"
}
}

// create account record

Related topics
Create an entity using the Web API
[Link]
deleteRecord (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Deletes an entity record.

Syntax
[Link](entityLogicalName, id).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes The entity logical name of

the record you want to
delete. For example:
"account".

id String Yes GUID of the entity record

you want to delete.

successCallback Function No A function to call when a

record is deleted. An
object with the following
properties will be passed
to identify the deleted
record:
entityType: String.
The entity type of the
record.
id: String. GUID of
the record.
name: String. Name
of the record.

errorCallback Function No A function to call when the

operation fails.

Return Value
On success, returns a promise object containing the attributes specified earlier in the description of the
successCallback parameter.

Examples
These examples use some of the same request objects as demonstrated in Update and delete entities using the
Web API to define the data object for updating an entity record.
Deletes an account with record ID = 5531d753-95af-e711-a94e-000d3a11e605.
[Link]("account", "5531d753-95af-e711-a94e-000d3a11e605").then(
function success(result) {
[Link]("Account deleted");
// perform operations on record deletion
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

Related topics
[Link]
retrieveRecord (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Retrieves an entity record.

Syntax
[Link](entityLogicalName, id, options).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes The entity logical name of the record

you want to retrieve. For example:
"account".

id String Yes GUID of the entity record you want

to retrieve.

options String No OData system query options,

$select and $expand, to retrieve
your data.
Use the $select system query
option to limit the properties
returned by including a
comma-separated list of
property names. This is an
important performance best
practice. If properties aren’t
specified using $select, all
properties will be returned.
Use the $expand system
query option to control what
data from related entities is
returned. If you just include
the name of the navigation
property, you’ll receive all the
properties for related records.
You can limit the properties
returned for related records
using the $select system
query option in parentheses
after the navigation property
name. Use this for both
single-valued and
collection-valued navigation
properties.
You specify the query options
starting with ? . You can also
specify multiple query options by
using & to separate the query
options. For example:
?
$select=name&$expand=primarycontactid($select=cont
See examples later in this topic to
see how you can define the
options parameter for various
retrieve scenarios.

successCallback Function No A function to call when a record is

retrieved. A JSON object with the
retrieved properties and values
will be passed to the function.
errorCallback Function No A function to call when the operation
fails.

Return Value
On success, returns a promise containing a JSON object with the retrieved attributes and their values.

Examples
Basic retrieve
Retrieves the name and revenue of an account record wwith record ID = 5531d753-95af-e711-a94e-000d3a11e605.

[Link]("account", "a8a19cdd-88df-e311-b8e5-6c3be5a8b200", "?$select=name,revenue").then(

The above example displays the following in your console; you might see other values depending on your data:
Retrieved values: Name: Sample Account, Revenue: 5000000

Retrieve related entities for an entity instance by expanding single-valued navigation properties
The following example demonstrates how to retrieve the contact for an account record with record ID = a8a19cdd-88df-e311-b8e5-
6c3be5a8b200. For the related contact record, we are only retrieving the contactid and fullname properties.

[Link]("account", "a8a19cdd-88df-e311-b8e5-6c3be5a8b200", "?

$select=name&$expand=primarycontactid($select=contactid,fullname)").then(
function success(result) {
[Link](`Retrieved values: Name: ${[Link]}, Primary Contact ID: ${[Link]}, Primary Contact Name:
${[Link]}`);
// perform operations on record retrieval
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

The above example displays the following in your console; you might see other values depending on your data:
Retrieved values: Name: Adventure Works, Primary Contact ID: 49a0e5b9-88df-e311-b8e5-6c3be5a8b200, Primary Contact Name: Adrian Dumitrascu

Related topics
[Link]
[Link]
retrieveMultipleRecords (Client API reference)
8/24/2018 • 4 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Retrieves a collection of entity records.

Syntax
[Link](entityLogicalName, options, maxPageSize).then(successCallback,
errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes The entity logical name of

the records you want to
retrieve. For example:
"account".
options String No OData system query
options or FetchXML
query to retrieve your
data.
Following system
query options are
supported: $select,
$top, $filter,
$expand, and
$orderby.
To specify a
FetchXML query, use
the fetchXml
attribute to specify
the query.
NOTE: You must always
use the $select system
query option to limit the
properties returned for
an entity record by
including a comma-
separated list of
property names. This is
an important
performance best
practice. If properties
aren’t specified using
$select, all properties
will be returned.
You specify the query
options starting with ?
. You can also specify
multiple system query
options by using & to
separate the query
options.
See examples later in this
topic to see how you can
define the options
parameter for various
retrieve multiple
scenarios.
maxPageSize Number No Specify a positive
number that indicates
the number of entity
records to be returned
per page. If you do not
specify this parameter,
the default value is
passed as 5000.
If the number of records
being retrieved is more
than the specified
maxPageSize value,
nextLink attribute in
the returned promise
object will contain a link
to retrieve the next set
of entities.

successCallback Function No A function to call when

entity records are
retrived. An object with
the following attributes
is passed to the function:
entities: An array of
JSON objects, where
each object
represents the
retrieved entity
record containing
attributes and their
values as
key: value pairs.
The Id of the entity
record is retrieved by
default.
nextLink: String. If
the number of
records being
retrieved is more
than the value
specified in the
maxPageSize
parameter in the
request, this attribute
returns the URL to
return next set of
records.

errorCallback Function No A function to call when the

operation fails.

Return Value
On success, returns a promise that contains an array of JSON objects (entities) containing the retrieved entity
records and the nextLink attribute (optional) with the URL pointing to next set of records in case paging (
maxPageSize ) is specified in the request, and the record count returned exceeds the paging value.
Examples
Most of the scenarios/examples mentioned in Query Data using the Web API can be achieved using the
retrieveMutipleRecords method. Some of the examples are listed below.
Basic retrieve multiple
This example queries the accounts entity set and uses the $select and $top system query options to return the
name property for the first three accounts:

[Link]("account", "?$select=name&$top=3").then(
function success(result) {
for (var i = 0; i < [Link]; i++) {
[Link]([Link][i]);
}
// perform additional operations on retrieved records
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

Specify the number of entities to return in a page

The following example demonstrates the use of the maxPageSize parameter to specify the number of records (3) to
be displayed in a page.

This example will display 3 records and a link to the next page. Here is an example outout from the Console in the
browser developer tools:

{@[Link]: "W/"1035541"", name: "A. Datum", accountid: "475b158c-541c-e511-80d3-3863bb347ba8"}

@[Link]: "W/"1035541""accountid: "475b158c-541c-e511-80d3-3863bb347ba8"name: "A. Datum"__proto__: Object
VM5595:4
{@[Link]: "W/"947306"", name: "Adventure Works", accountid: "a8a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:4
{@[Link]: "W/"1033754"", name: "Alpine Ski House", accountid: "aaa19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:6
Next page link: [Organization URI]/api/data/v9.0/accounts?
$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2
53e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-
6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-
3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

Use the query part in the URL in the nextLink property as the value for the options parameter in your
subsequent retrieveMultipleRecords call to request the next set of records. Don’t change or append any
additional system query options to the value. For every subsequent request for additional pages, you should use
the same maxPageSize value used in the original retrieve multiple request. Also, cache the results returned or the
value of the nextLink property so that previously retrieved pages can be returned.
For example, to get the next page of records, we will pass in the query part of the nextLink URL to the options
parameter:

[Link]("account", "?
$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%2
53e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-
6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-
3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E", 3).then(
function success(result) {
for (var i = 0; i < [Link]; i++) {
[Link]([Link][i]);
}
[Link]("Next page link: " + [Link]);
// perform additional operations on retrieved records
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

This will return the next page of the resultset:

{@[Link]: "W/"1035542"", name: "Blue Yonder Airlines", accountid: "aca19cdd-88df-e311-b8e5-6c3be5a8b200"}

VM5597:4
{@[Link]: "W/"1031348"", name: "City Power & Light", accountid: "aea19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:4
{@[Link]: "W/"1035543"", name: "Coho Winery", accountid: "b0a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:6
Next page link: [Organization URI]/api/data/v9.0/accounts?
$select=name&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%2
53e%253caccountid%2520last%253d%2522%257bB0A19CDD-88DF-E311-B8E5-
6C3BE5A8B200%257d%2522%2520first%253d%2522%257bACA19CDD-88DF-E311-B8E5-
6C3BE5A8B200%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

IMPORTANT
The value of the nextLink property is URI encoded. If you URI encode the value before you send it, the XML cookie
information in the URL will cause an error.

Retrieve related entities by expanding navigation properties

Use the $expand system query option in the navigation properties to control the data that is returned from related
entities. The following example demonstrates how to retrieve the contact for all the account records. For the related
contact records, we are only retrieving the contactid and fullname :
[Link]("account", "?
$select=name&$top=3&$expand=primarycontactid($select=contactid,fullname)", 3).then(
function success(result) {
for (var i = 0; i < [Link]; i++) {
[Link]([Link][i]);
}
// perform additional operations on retrieved records
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

For more examples of retrieving multiple records using Web API, see Query Data using the Web API.
Related topics
Query Data using the Web API
[Link]
[Link]
updateRecord (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Updates an entity record.

Syntax
[Link](entityLogicalName, id, data).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes The entity logical name of

the record you want to
update. For example:
"account".

id String Yes GUID of the entity record

you want to update.

data Object Yes A JSON object

containing key: value
pairs, where key is the
property of the entity
and value is the value
of the property you
want to update.
See examples later in this
topic to see how you can
define the data object
for various update
scenarios.

successCallback Function No A function to call when a

record is updated. An
object with the following
properties will be passed
to identify the updated
record:
entityType: String.
The entity type of the
updated record.
id: String. GUID of
the updated record.
errorCallback Function No A function to call when the
operation fails. An object
with the following properties
will be passed:
errorCode: Number.
The error code.
message: String. An
error message
describing the issue.

Return Value
On success, returns a promise object containing the attributes specified earlier in the description of the
successCallback parameter.

// define the data to update a record

Update associations to the related entities

To update association to the related entity records (lookups), set the value of single-valued navigation properties
using the @[Link] annotation to another record. However, for mobile clients in the offline mode, you cannot
use the @[Link] annotation, and instead have to pass a lookup object (logicalname and id) pointing to the
target record. Here are code examples for both the scenarios:
For online scenario (connected to server)
The following example updates an account record to associate another contact record as the primary contact for the
account:
// define the data to update a record
var data =
{
"primarycontactid@[Link]": "/contacts(61a0e5b9-88df-e311-b8e5-6c3be5a8b200)"
}
// update the record
[Link]("account", "5531d753-95af-e711-a94e-000d3a11e605", data).then(
function success(result) {
[Link]("Account updated");
// perform operations on record update
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

For mobile offline scenario

Here is the updated sample code to update an account record to associate another contact record as the primary
contact for the account from mobile clients when working in the offline mode:

// define the data to update a record

Related topics
[Link]
isAvailableOffline (Client API reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

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

Syntax
[Link](entityLogicalName);

Parameters
NAME TYPE REQUIRED DESCRIPTION

entityLogicalName String Yes Logical name of the entity.

For example: "account".

Return Value
Type: Boolean.
Description: true if the entity is present in user’s profile and is currently available for use in offline mode;
otherwise false.
[Link]
[Link]
[Link] (Client API reference)
8/24/2018 • 3 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Execute a single action, function, or CRUD operation.

NOTE
This method is supported only for the online mode ([Link]).

Syntax
[Link](request).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION

request Object Yes Object that will be

passed to the Web API
endpoint to execute an
action, function, or
CRUD request. The
object exposes a
getMetadata method
that lets you define the
metadata for the action,
function or CRUD
request you want to
execute. The
getMetadata method
has the following
parameters:
boundParameter:
(Optional) String. The
name of the bound
parameter for the
action or function to
execute.
Specify undefined if
you are executing a
CRUD request.
Specify null if the
action or function to
execute is not bound
to any entity.
Specify entity logical
name or entity set
name in case the
action or function to
execute is bound to
one.
operationName:
(Optional). String.
Name of the action,
function, or one of
the following values if
you are executing a
CRUD request:
"Create", "Retrieve",
"RetrieveMultiple",
"Update", or "Delete".
operationType:
(Optional). Number.
Indicates the type of
operation you are
executing; specify one
of the following
values:
0: Action
1: Function
2: CRUD
parameterTypes:
Object. The metadata
for parameter types.
The object has the
following attributes:
enumProper
ties:
(Optional)
Object. The
metadata for
enum types.
The object has
two string
attributes:
name and
value
structuralPro
perty:
Number. The
category of
the parameter
type. Specify
one of the
following
values:
0: Unknown
1:
PrimitiveType
2:
ComplexType
3:
EnumerationType
4:
Collection
5:
EntityType
typeName:
String. The
fully qualified
name of the
parameter
type.
successCallback Function No A function to call when
operation is executed
successfully. A response
object is passed to the
function with the
following attributes:
body: (Optional).
Object. Response
body.
headers: Object.
Response headers.
ok: Boolean.
Indicates whether the
request was
successful.
status: Number.
Numeric value in the
response status code.
For example: 200
statusText: String.
Description of the
response status code.
For example: OK
type: String.
Response type.
Values are: the empty
string (default),
"arraybuffer", "blob",
"document", "json",
and "text".
url: String. Request
URL of the action,
function, or CRUD
request that was sent
to the Web API
endpoint.

errorCallback Function No A function to call when the

operation fails.

Return Value
On success, returns a promise object with the attributes specified earlier in the description of successCallback
function.

Examples
Execute an action
The following example demonstrates how to execute the WinOpportunity action. The request object is created
based on the action definition here: Unbound actions
var Sdk = [Link] || {};
/**
* Request to win an opportunity
* @param {Object} opportunityClose - The opportunity close activity associated with this state change.
* @param {number} status - Status of the opportunity.
*/
[Link] = function (opportunityClose, status) {
[Link] = opportunityClose;
[Link] = status;

[Link] = function () {
return {
boundParameter: null,
parameterTypes: {
"OpportunityClose": {
"typeName": "[Link]",
"structuralProperty": 5 // Entity Type
},
"Status": {
"typeName": "Edm.Int32",
"structuralProperty": 1 // Primitive Type
}
},
operationType: 0, // This is an action. Use '1' for functions and '2' for CRUD
operationName: "WinOpportunity",
};
};
};

var opportunityClose = {
"opportunityid@[Link]": "/opportunities(c60e0283-5bf2-e311-945f-6c3be5a8dd64)",
"description": "Product and maintainance for 2018",
"subject": "Contract for 2018"
}

// Construct a request object from the metadata

var winOpportunityRequest = new [Link](opportunityClose, 3);

// Use the request object to execute the function

[Link](winOpportunityRequest).then(
function (result) {
if ([Link]) {
[Link]("Status: %s %s", [Link], [Link]);
// perform other operations as required;
}
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

Execute a function
The following example demonstrates how to execute the WhoAmI function:
var Sdk = [Link] || {};
/**
* Request to execute WhoAmI function
*/
[Link] = function () {
[Link] = function () {
return {
boundParameter: null,
parameterTypes: {},
operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
operationName: "WhoAmI",
};
};
};

// Construct a request object from the metadata

var whoAmIRequest = new [Link]();

// Use the request object to execute the function

[Link](whoAmIRequest).then(
function (result) {
if ([Link]) {
[Link]("Status: %s %s", [Link], [Link]);
var response = [Link]([Link]);
[Link]("User Id: %s", [Link]);
// perform other operations as required;
}
},
function (error) {
[Link]([Link]);
// handle error conditions
}
);

Related topics
[Link]
[Link] (Client API
reference)
8/24/2018 • 2 minutes to read • Edit Online

Applies to Dynamics 365 (online), version 9.x

Execute a collection of action, function, or CRUD operations.

NOTE
This method is supported only for the online mode ([Link]).

If you want to execute multiple requests in a transaction, you must pass in a change set as a parameter to this
method. Change sets represent a collection of operations that are executed in a transaction. You can also pass in
individual requests and change sets together as parameters to this method.

NOTE
You cannot include read operations (retrieve, retrieve multiple, and Web API functions) as part of a change set; this is as per
the OData v4 specifications.

Syntax
Execute multiple requests:

var requests = [req1, req2, req3];

[Link](requests).then(successCallback, errorCallback);

Execute multiple requests in a transaction:

In this case, req1 , req2 , and req3 will be executed in transaction.

var changeSet = [req1, req2, req3];

var requests = [changeSet];
[Link](requests).then(successCallback, errorCallback);

Execute a mix of individual requests and multiple requests in a transaction:

In this case, req1 , req2 , and req3 will be executed in transaction, but req4 and req5 will be executed
individually.

var changeSet = [req1, req2, req3];

var requests = [req4, req5, changeset];
[Link](requests).then(successCallback, errorCallback);

Parameters
NAME TYPE REQUIRED DESCRIPTION
requests Array of objects Yes An array of one of one
of the following types:
objects where each
object is an action,
function, or CRUD
request that you
want to execute
against the Web API
endpoint. Each object
exposes a
getMetadata
method that lets you
define the metadata
for the action,
function or CRUD
request you want to
execute. This is the
same object that you
pass in the execute
method. For
information about
the object, see
execute.
Change set (an array
of objects), where
each object in the
change set is as
defined above. In this
case, all the request
objects specified in
the change set will
get executed in a
transaction.
See request examples
earlier in the Syntax
section for more
information.
successCallback Function No A function to call when
operation is executed
suucessfully. An array of
response objects are
passed to the function
where weach response
object has the following
attributes:
body: (Optional).
Object. Response
body.
headers: Object.
Response headers.
ok: Boolean.
Indicates whether the
request was
successful.
status: Number.
Numeric value in the
response status code.
For example: 200
statusText: String.
Description of the
response status code.
For example: OK
type: String.
Response type.
Values are: the empty
string (default),
"arraybuffer", "blob",
"document", "json",
and "text".
url: String. Request
URL of the action,
function, or CRUD
request that was sent
to the Web API
endpoint.

errorCallback Function No A function to call when the

operation fails.

Return Value
On success, returns a promise containing an array of objects with the attributes specified earlier in the description
of successCallback function.
Related topics
[Link]

Understanding Client Scripts in ServiceNow
100% (1)
Understanding Client Scripts in ServiceNow
6 pages
Client Script Types in ServiceNow
No ratings yet
Client Script Types in ServiceNow
5 pages
Client Script Types in ServiceNow
No ratings yet
Client Script Types in ServiceNow
5 pages
Client Scripts in Servicenow: Types of Client Scripts 1. On Load Client Script
No ratings yet
Client Scripts in Servicenow: Types of Client Scripts 1. On Load Client Script
4 pages
ServiceNow Scripting and API Overview
No ratings yet
ServiceNow Scripting and API Overview
96 pages
ServiceNow Client Scripts Overview
No ratings yet
ServiceNow Client Scripts Overview
30 pages
Client-Side Scripting in ServiceNow
100% (1)
Client-Side Scripting in ServiceNow
66 pages
Model Driven Summary
No ratings yet
Model Driven Summary
24 pages
ServiceNow Client Script Tutorial: Priority Change
No ratings yet
ServiceNow Client Script Tutorial: Priority Change
2 pages
JScript in CRM: Basics and Benefits
No ratings yet
JScript in CRM: Basics and Benefits
21 pages
Understanding Script Actions in ServiceNow
No ratings yet
Understanding Script Actions in ServiceNow
3 pages
Mastering Servicenow Client Scripts 1769725738
No ratings yet
Mastering Servicenow Client Scripts 1769725738
28 pages
ServiceNow Client Script Overview
100% (2)
ServiceNow Client Script Overview
30 pages
ServiceNow Client Scripts Guide
No ratings yet
ServiceNow Client Scripts Guide
12 pages
Client Script 1766392175
No ratings yet
Client Script 1766392175
12 pages
CRM 4.0 to 2011: Developer Changes
No ratings yet
CRM 4.0 to 2011: Developer Changes
46 pages
ServiceNow Client Script Overview
0% (1)
ServiceNow Client Script Overview
27 pages
ServiceNow ACL and Client Script Guide
No ratings yet
ServiceNow ACL and Client Script Guide
1 page
ServiceNow Client and UI Scripts Guide
No ratings yet
ServiceNow Client and UI Scripts Guide
17 pages
Microsoft Dynamics CRM Event Programming
No ratings yet
Microsoft Dynamics CRM Event Programming
38 pages
Understanding Client Scripts in ServiceNow
No ratings yet
Understanding Client Scripts in ServiceNow
7 pages
Microsoft Dynamics CRM Plug-ins Guide
No ratings yet
Microsoft Dynamics CRM Plug-ins Guide
48 pages
Client Script Examples for ServiceNow
No ratings yet
Client Script Examples for ServiceNow
7 pages
Overview of ServiceNow Script Types
No ratings yet
Overview of ServiceNow Script Types
3 pages
Dynamics 365 JavaScript API Guide
No ratings yet
Dynamics 365 JavaScript API Guide
2 pages
ServiceNow - Development Page 1
No ratings yet
ServiceNow - Development Page 1
17 pages
Client Scripts
No ratings yet
Client Scripts
25 pages
Event Handlers in Dynamics 365 CRM
No ratings yet
Event Handlers in Dynamics 365 CRM
6 pages
Dynamics 365: Plugins vs Workflows vs Actions
No ratings yet
Dynamics 365: Plugins vs Workflows vs Actions
8 pages
SuiteScript Client Script
No ratings yet
SuiteScript Client Script
5 pages
Client Scripting in Model-Driven Apps
No ratings yet
Client Scripting in Model-Driven Apps
2 pages
Features of CRM
No ratings yet
Features of CRM
4 pages
Personalization Strategies for Purchasing
No ratings yet
Personalization Strategies for Purchasing
40 pages
ServiceNow Scripting Course Outline
100% (1)
ServiceNow Scripting Course Outline
43 pages
Zoho CRM Client Scripting Guide
No ratings yet
Zoho CRM Client Scripting Guide
21 pages
Advanced Client Scripts in ServiceNow
No ratings yet
Advanced Client Scripts in ServiceNow
159 pages
CRM 4.0 to 2011: Developer Changes
No ratings yet
CRM 4.0 to 2011: Developer Changes
46 pages
Workflow Process Execution in Siebel 8.0
No ratings yet
Workflow Process Execution in Siebel 8.0
25 pages
ServiceNow Study Guide Client Script UI Policy Data Policy Business Rule
No ratings yet
ServiceNow Study Guide Client Script UI Policy Data Policy Business Rule
17 pages
ServiceNow Client Scripting Best Practices
No ratings yet
ServiceNow Client Scripting Best Practices
5 pages
Client Script Notes
No ratings yet
Client Script Notes
22 pages
Client-Side Scripting in ServiceNow
No ratings yet
Client-Side Scripting in ServiceNow
14 pages
Dynamics AX Workflow Development Guide
100% (1)
Dynamics AX Workflow Development Guide
23 pages
Java JSON in UI Builder Scripting
No ratings yet
Java JSON in UI Builder Scripting
7 pages
Power Apps JavaScript Cheat Sheet
No ratings yet
Power Apps JavaScript Cheat Sheet
1 page
ChronoForms v4: Events and Actions Guide
No ratings yet
ChronoForms v4: Events and Actions Guide
40 pages
Understanding Business Rules and Client Scripts
No ratings yet
Understanding Business Rules and Client Scripts
16 pages
Strengthening Hands-On Development Skills in Servicenow: Servicenow Client-Side Scripting Practice
No ratings yet
Strengthening Hands-On Development Skills in Servicenow: Servicenow Client-Side Scripting Practice
5 pages
ServiceNow UI and Workflow Overview
No ratings yet
ServiceNow UI and Workflow Overview
3 pages
ServiceNow Client Script and Notifications Guide
No ratings yet
ServiceNow Client Script and Notifications Guide
2 pages
ServiceNow Client Scripts Cheat Sheet
No ratings yet
ServiceNow Client Scripts Cheat Sheet
2 pages
Service Now Questions and Answers Updated
No ratings yet
Service Now Questions and Answers Updated
15 pages
Sales Cloud Opportunity Management Guide
No ratings yet
Sales Cloud Opportunity Management Guide
162 pages
Form Personalizations for User Experience
No ratings yet
Form Personalizations for User Experience
58 pages
Dynamics GP Workflow Development Guide
No ratings yet
Dynamics GP Workflow Development Guide
28 pages
Java Script With Dynamics 365 CRM
No ratings yet
Java Script With Dynamics 365 CRM
23 pages
Client Scripts vs Business Rules
No ratings yet
Client Scripts vs Business Rules
8 pages
Microsoft Dynamics CRM API Development For Online and On Premise Environments 1st Edition Mark Beckner Ebook Testbank Solutions Fully Upgraded Text
100% (12)
Microsoft Dynamics CRM API Development For Online and On Premise Environments 1st Edition Mark Beckner Ebook Testbank Solutions Fully Upgraded Text
102 pages
ServiceNow Scheduled Jobs Events Training
No ratings yet
ServiceNow Scheduled Jobs Events Training
20 pages
Factorials and S-units in Recurrence Sequences
No ratings yet
Factorials and S-units in Recurrence Sequences
20 pages
Dwarka Expressway Width Details
No ratings yet
Dwarka Expressway Width Details
1 page
Spinor Analysis of Partition Function
No ratings yet
Spinor Analysis of Partition Function
12 pages
Urdu Roll Number Instructions
No ratings yet
Urdu Roll Number Instructions
20 pages
C++ Inheritance and Composition Explained
No ratings yet
C++ Inheritance and Composition Explained
40 pages
Mock Demo - Uncle Paul's Job - Updated TG
No ratings yet
Mock Demo - Uncle Paul's Job - Updated TG
12 pages
Telenor SMS API Documentation
No ratings yet
Telenor SMS API Documentation
31 pages
LRN B2 Answer Sheet Instructions
No ratings yet
LRN B2 Answer Sheet Instructions
1 page
Mastering React State Management
No ratings yet
Mastering React State Management
57 pages
MTHS111 mcPaper1Jun2023
No ratings yet
MTHS111 mcPaper1Jun2023
4 pages
Nepal Driving License Exam Schedule
No ratings yet
Nepal Driving License Exam Schedule
77 pages
Zakat and Hajj: Islamic Obligations Explained
No ratings yet
Zakat and Hajj: Islamic Obligations Explained
11 pages
Senior High School Career Pathways Toolkit
No ratings yet
Senior High School Career Pathways Toolkit
64 pages
1910 Year Book of Seventh-day Adventists
No ratings yet
1910 Year Book of Seventh-day Adventists
260 pages
Changes in Solid Materials for Grade 4
No ratings yet
Changes in Solid Materials for Grade 4
7 pages
Composing with Chrome Music Lab
No ratings yet
Composing with Chrome Music Lab
7 pages
Macasandig NHS Learning Camp 2024 Report
No ratings yet
Macasandig NHS Learning Camp 2024 Report
2 pages
C++ Programming Assignments Guide
No ratings yet
C++ Programming Assignments Guide
3 pages
Crafting Effective Argumentative Texts
No ratings yet
Crafting Effective Argumentative Texts
4 pages
Appalling Meaning - Google Search
No ratings yet
Appalling Meaning - Google Search
1 page
Boolean Function Implementation with Decoders
No ratings yet
Boolean Function Implementation with Decoders
21 pages
Questions 1 Through 10 Are Based On The Following Passage
100% (1)
Questions 1 Through 10 Are Based On The Following Passage
6 pages
Understanding Closet Drama in Literature
100% (1)
Understanding Closet Drama in Literature
2 pages
C# 13 Features and Enhancements Overview
No ratings yet
C# 13 Features and Enhancements Overview
1 page
Top 80+ AI & ML Interview Questions
No ratings yet
Top 80+ AI & ML Interview Questions
73 pages
Hello World 19
No ratings yet
Hello World 19
100 pages
Uniting Faith Across Religions
No ratings yet
Uniting Faith Across Religions
2 pages
Engaging Book Reviews: Goosebumps & Harry Potter
No ratings yet
Engaging Book Reviews: Goosebumps & Harry Potter
3 pages
Foucault's Confession and Obedience Analysis
No ratings yet
Foucault's Confession and Obedience Analysis
24 pages
Arria 10 FPGA EMIF Release Notes
No ratings yet
Arria 10 FPGA EMIF Release Notes
4 pages