Client-side context (client-side reference)

 

Applies To: Dynamics CRM 2013

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.

Context Properties and Methods

  • client
    Provides access to the getClient and getClientState methods you can use to determine which client is being used and whether the client is connected to the server.

  • 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.

  • getOrgLcid
    Returns the 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.

  • 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.

  • isOutlookClient
    Deprecated. Use client.getClient instead.

  • isOutlookOnline
    Deprecated. Use client.getClientState instead.

  • prependOrgName
    Prepends the organization name to the specified path.

  • Removed Methods
    The getAuthenticationHeader and getServerUrl methods were deprecated with Microsoft Dynamics CRM 2011 and are no longer present in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online.

client

With Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, the context includes the client object which contains the getClient and getClientState methods to get information about the client.

These methods are only available for Updated entities.

getClient

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

context.client.getClient()

Use this instead of the deprecated isOutlookClient method.

  • Return Value
    Type: String

    The values returned are:

    Client

    Value

    Browser

    Web

    Outlook

    Outlook

    Mobile

    Mobile

  • Remarks
    This method is only available for Updated entities.

getClientState

Use this instead of the deprecated 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

    Online

    Outlook, Mobile

    Offline

  • Remarks
    This method is only available for Updated entities.

getClientUrl

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

context.getClientUrl()

Use this instead of the deprecated getServerUrl method.

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

Client

Value

Microsoft Dynamics CRM (on-premises)

http(s)://server/org

Microsoft Dynamics CRM Online

https://org.crm.dynamics.com

Microsoft Dynamics CRM for Outlook with Offline Access when offline

http://localhost:2525

  • Return Value
    Type: String

getCurrentTheme

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

Note

This function does not work with Microsoft Dynamics CRM for tablets.

context.getCurrentTheme()
  • Return Value
    Type: String

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

Note

Forms do not adapt to changes in the office theme, so the only case where you might want to adapt to the 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 CRM web application

Office12Blue

Microsoft Dynamics CRM for Outlook 2007 or 2010 Blue Theme

Office14Silver

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

getOrgLcid

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.

    1033
    

getOrgUniqueName

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"
    

getQueryStringParameters

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

getUserId

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

context.getUserId()
  • Return Value
    Type: String

    Example:

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

getUserLcid

Returns the LCID value that represents the Microsoft Dynamics CRM Language Pack that is 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.

    1041
    

getUserName

Returns the name of the current user.

context.getUserName()
  • Return Value
    Type: String

  • Remarks
    This method is only available for Updated entities.

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.

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

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"]
    

isOutlookClient

Deprecated. Use client.getClient instead.

Returns a Boolean value indicating if the user is using Microsoft Dynamics CRM for Microsoft Office Outlook.

context.isOutlookClient()
  • Return Value
    Type: Boolean

isOutlookOnline

Deprecated. Use client.getClientState instead.

Returns a Boolean value that indicates whether the user is connected to the Microsoft Dynamics CRM server while using Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access. When this function returns false, the user is working offline without a connection to the server.

context.isOutlookOnline()
  • Return Value
    Type: Boolean

prependOrgName

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

The following methods were deprecated with Microsoft Dynamics CRM 2011 and are no longer present in Dynamics CRM 2013 or Dynamics CRM Online:

  • 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.

See Also

GetGlobalContext function and ClientGlobalContext.js.aspx (client-side reference)
Form scripting quick reference
Write code for Microsoft Dynamics CRM 2013 forms
Use the Xrm.Page object model
Client-side programming reference