Client-side context (client-side reference)

 

Updated: November 29, 2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Your code will need to operate in a context where a number of variables are not known at design time. The context object provides methods to retrieve information specific to an organization, a user, or parameters passed to a page.

The context object is available in forms by referencing Xrm.Page.context.

For web resources executed outside of a form, use the GetGlobalContext function to retrieve a context object.

client

Provides access to the getClient, getClientState and getFormFactor methods you can use to determine which client is being used, whether the client is connected to the server, and what kind of device is being used.

getClientUrl

Returns the base URL that was used to access the application.

getCurrentTheme

Returns a string representing the current Microsoft Office Outlook theme chosen by the user.

getIsAutoSaveEnabled

Returns whether Autosave is enabled for the organization.

getOrgLcid

Returns the language code identifier (LCID) value that represents the base language for the organization.

getOrgUniqueName

Returns the unique text value of the organization’s name.

getQueryStringParameters

Returns a dictionary object of key value pairs that represent the query string arguments that were passed to the page.

getTimeZoneOffsetMinutes

Returns the difference between the local time and Coordinated Universal Time (UTC).

This method was introduced with Microsoft Dynamics CRM Online 2015 Update 1.

getUserId

Returns the GUID of the SystemUser.Id value for the current user.

getUserLcid

Returns the LCID value that represents the provisioned language that the user selected as their preferred language.

getUserName

Returns the name of the current user.

getUserRoles

Returns an array of strings that represent the GUID values of each of the security roles that the user is associated with or any teams that the user is associated with.

prependOrgName

Prepends the organization name to the specified path.

Removed methods

Removed methods are either obsolete or replaced with other methods. You should make sure these methods are not used in your scripts.

The getAuthenticationHeader and getServerUrl methods were deprecated with Microsoft Dynamics CRM 2011 and are no longer present in Microsoft Dynamics 365 (online & on-premises).

The isOutlookClient and isOutlookOnline methods were deprecated with Microsoft Dynamics CRM 2013 and are no longer present in Microsoft Dynamics 365 (online & on-premises).

Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online added the client object which contains the getClient and getClientState methods to get information about the client.

Microsoft Dynamics CRM Online 2015 Update 1 added the getFormFactor method.

Returns a value to indicate which client the script is executing in.

context.client.getClient()

Use this instead of the removed isOutlookClient method.

Return Value

Type: String

The values returned are:

Client

Value

Browser

Web

Outlook

Outlook

Mobile

Mobile

Interactive Service Hub

Mobile

Use this instead of the removed isOutlookOnline method.

Returns a value to indicate the state of the client.

context.client.getClientState()
Return Value

Type: String

The possible values returned are:

Client

Values returned

Web, Outlook, Mobile, Interactive Service Hub

Online

Outlook, Mobile

Offline

Use this method to get information about the kind of device the user is using.

context.client.getFormFactor()
Return Value

Type: Number

The possible values returned are:

Value

Form factor

0

Unknown

1

Desktop

2

Tablet

3

Phone

Remarks

This method was introduced with Microsoft Dynamics CRM Online 2015 Update 1

Returns the base URL that was used to access the application.

context.getClientUrl()

Use this instead of the removed getServerUrl method.

The values returned will resemble those listed in the following table.

Client

Value

Dynamics 365 (on-premises)

http(s)://server/org

Microsoft Dynamics 365 (online)

https://org.crm.dynamics.com

Microsoft Dynamics 365 for Outlook with Offline Access when offline

http://localhost:2525

Return Value

Type: String

Returns a string representing the current Microsoft Office Outlook theme chosen by the user.

System_CAPS_noteNote

This function isn't supported for Dynamics 365 mobile clients (phones and tablets) and the interactive service hub.

context.getCurrentTheme()
Return Value

Type: String

Use this information to select an appropriate theme for your HTML and Silverlight web resources when viewed in Microsoft Dynamics 365 for Outlook. The following table lists the values that may be returned from this method.

System_CAPS_noteNote

Forms don’t adapt to changes in the Microsoft Office theme, so the only case where you might want to adapt to the Microsoft Office themes is when you display a page in the navigation using an HTML web resource. Even in this scenario, visual differences may be difficult to detect.

Value

Theme

default

Microsoft Dynamics 365 web application

Office12Blue

Microsoft Dynamics 365 for Outlook 2007 or 2010 Blue Theme

Office14Silver

Microsoft Dynamics 365 for Outlook 2007 or 2010 Silver or Black Theme

This method was introduced with Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update

Returns whether Autosave is enabled for the organization.

context.getIsAutoSaveEnabled()
Return Value

Type: Boolean

System_CAPS_noteNote

This function returns the value set at the time the page is opened. When testing code using this value, you must refresh the page after changing the value in order to get the new value.

More information: TechNet: Manage auto-save.

Returns the LCID value that represents the base language for the organization.

context.getOrgLcid()
Return Value

Type: Number

Example: 1033 indicates the English language. Valid locale ID values can be found at Locale ID (LCID) Chart.

Returns the unique text value of the organization’s name.

context.getOrgUniqueName()
Return Value

Type: String

Example: This corresponds to the organization name value

"adventureworkscycle"

Returns a dictionary object of key value pairs that represent the query string arguments that were passed to the page.

context.getQueryStringParameters()
Return Value

Type: Object

Returns the difference between the local time and Coordinated Universal Time (UTC).

System_CAPS_noteNote

This method was introduced with Microsoft Dynamics CRM Online 2015 Update 1.

context.getTimeZoneOffsetMinutes()
Return Value

Type: Number

Returns the GUID of the SystemUser.Id value for the current user.

context.getUserId()
Return Value

Type: String

Example:

"{B05EC7CE-5D51-DF11-97E0-00155DB232D0}"

Returns the LCID value that represents the Microsoft Dynamics 365 Language Pack that the user selected as their preferred language.

context.getUserLcid()
Return Value

Type: Number

Example: 1041 indicates the Japanese language. Valid locale ID values can be found at Locale ID (LCID) Chart.

Returns the name of the current user.

context.getUserName()
Return Value

Type: String

Returns an array of strings that represent the GUID values of each of the security roles that the user is associated with or any teams that the user is associated with.

For more information about security roles, see How role-based security can be used to control access to entities in Microsoft Dynamics 365.

context.getUserRoles()
Return Value

Type: Array

Example: This user has only one security role associated with their user account. The JSON representation of this array with a single value is:

["cf4cc7ce-5d51-df11-97e0-00155db232d0"]

Prepends the organization name to the specified path.

context.prependOrgName(sPath)
Arguments

Type: String

A local path to a resource.

Return Value

Type: String

The value returned follows this pattern:

"/"+ OrgName + sPath

Removed methods are either obsolete or replaced with other methods. You should make sure these methods aren’t used in your scripts.

The following methods were deprecated with earlier versions of Microsoft Dynamics 365 and are no longer present in the current version:

getAuthenticationHeader

This method supported use of the Microsoft Dynamics CRM 4.0 web services, which no longer exist.

getServerUrl

This method was replaced by getClientUrl.

isOutlookClient

This method was replaced by client.getClient.

isOutlookOnline

This method was replaced by client.getClientState.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright

Community Additions

ADD
Show: