Xrm.Utility (client-side reference)

Artikel
11/28/2016

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

The Xrm.Utility object provides a container for useful functions not directly related to the current page.

These functions are available in every application page that supports scripting. You can use them in form scripts or in ribbon commands. For HTML web resources, they are available when you include the ClientGlobalContext.js.aspx page. For more information, see GetGlobalContext function and ClientGlobalContext.js.aspx (client-side reference).

Functions

Dialogs
Use alertDialog and confirmDialog display messages to users and set code to execute based on their response. These functions must be used with Dynamics 365 mobile clients (phones and tablets) in place of the window.alert and window.confirm methods.
Native device capabilities (Dynamics 365 mobile clients)
Use getBarcodeValue and getCurrentPosition to use the native device capabilities of mobile devices to retrieve barcode value or to retrieve the current position of the device.
isActivityType
Determine if an entity is an activity entity.
openEntityForm
Opens an entity form.
openQuickCreate
For Microsoft Dynamics CRM Online 2015 Update 1 or later use this function to open a new quick create form. You can use this function to set default values using attribute mappings or for specific attributes. If the user saves the record, you can capture a reference to the record created.
openWebResource
Opens an HTML web resource.

Dialogs

There are two types of dialogs: alertDialog and confirmDialog. These are included for use with scripts that will work with Dynamics 365 mobile clients (phones and tablets). Dynamics 365 mobile clients will not allow the use of JavaScript functions that block the flow of code such as window.alert and window.confirm. Use these methods in place of those methods in case you need to display a message to the user. They key difference is that these methods will not block code until a user closes them. They contain a callback function parameter to indicate what code should be executed depending on the user’s response.

Note

In Dynamics 365 mobile clients (phones and tablets), any use of the window.alert method will be overridden to use Xrm.Utility.alertDialog without a callback. This will display the message but will not block the execution of code as window.alert does. This mapping of window.alert to Xrm.Utility.alertDialog in Dynamics 365 mobile clients is deprecated and will be removed in the next major release. You should migrate any code you have today to use Xrm.Utility.alertDialog rather than window.alert.

alertDialog

Displays a dialog box containing an application-defined message.

Xrm.Utility.alertDialog(message,onCloseCallback)

Parameters

Name

Type

Required

Description

message

String

Yes

The text of the message to display in the dialog.

onCloseCallback

Function

No

A function to execute when the OK button is clicked.
Remarks
This method is only available for Updated entities.

Name	Type	Required	Description
message	String	Yes	The text of the message to display in the dialog.
onCloseCallback	Function	No	A function to execute when the OK button is clicked.

confirmDialog

Displays a confirmation dialog box that contains an optional message as well as OK and Cancel buttons.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

Parameters

Name	Type	Required	Description
message	String	Yes	The text of the message to display in the dialog
yesCloseCallback	Function	No	A function to execute when the OK button is clicked.
noCloseCallback	Function	No	A function to execute when the Cancel button is clicked.

Remarks
This method is only available for Updated entities.

Native device capabilities (Dynamics 365 mobile clients)

Use these methods for Dynamics 365 for phones and Dynamics 365 for tablets clients to help enrich the user experience for mobile business users in sales, field service, and other areas.

Note

These methods were introduced in December 2016 update for Dynamics 365 (online and on-premises).

getBarcodeValue

Returns the barcode information, such as a product number, scanned using the device camera.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

Parameters

Name	Type	Required	Description
successCallback	Function	Yes	A function to call when the barcode value is returned.
errorCallback	Function	Yes	A function to call when the operation fails. An error object with the message property will be passed that describes the error details.

Remarks
For the getBarcodeValue method to work, the Dynamics 365 mobile clients must have access to your device camera, which is enabled by default.

Example
The following sample code demonstrates the usage of this method.

Xrm.Utility.getBarcodeValue().then(
    function (result) {
        Xrm.Utility.alertDialog("Barcode value: " + result);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

getCurrentPosition

Returns the current location using the device geolocation capability.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

Parameters

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: Number. The error code. message: String. Localized message describing the error details. 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 mobile client or if geolocation capability is not available on your mobile device, null is passed to the error callback.

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: Number. The error code.
message: String. Localized message describing the error details.

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 mobile client or if geolocation capability is not available on your mobile device, null is passed to the error callback.

Remarks
For the getCurrentPosition method to work, the geolocation capability must be enabled on your device, and the Dynamics 365 mobile clients must have permissions to access the device location, which isn't enabled by default.

Example
The following sample code demonstrates the usage of this method.

Xrm.Utility.getCurrentPosition().then
    (function (location) {
        Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
           ", Longitude: " + location.coords.longitude);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

isActivityType

Determine if an entity is an activity entity.

Xrm.Utility.isActivityType(entityName)

Parameter

Name

Type

Required

Description

entityName

String

Yes

The logicalName of an entity.
Return Value

Type

Description

Boolean

True if the entity is an activity entity, otherwise false.

Name	Type	Required	Description
entityName	String	Yes	The logicalName of an entity.

Type	Description
Boolean	True if the entity is an activity entity, otherwise false.

openEntityForm

Opens an entity form for a new or existing entity record using the options you set as parameters.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

Parameters

Name	Type	Required	Description
name	String	Yes	The logical name of the entity.
id	String	No	The string representation of a unique identifier or the record to open in the form. If not set, a form to create a new record is opened.
parameters	Object	No	A dictionary object that passes extra parameters to the form. Invalid parameters will cause an error. Valid extra query string parameters are: Form id: To set the id value of the main form to use when more than one form is available. The parameter is formid. Default field ids: To set default values for a new record form. For more information, see Set field values using parameters passed to a form. The navbar and cmdbar parameters described in Query String Parameters for the Main.aspx Page. Custom query string parameters: A form can be configured to accept custom query string parameters. For more information, see Configure a form to accept custom querystring parameters.
windowOptions	Object	No	For Microsoft Dynamics CRM Online 2015 Update 1 or later use this optional parameter in the web application to control how the form opens. You can open a form in a new window by passing a dictionary object with a Boolean openInNewWindow property set to true. This parameter is ignored in Dynamics 365 mobile clients (phones and tablets).

Remarks
Using this function helps ensure that users are not prompted to log in again under certain circumstances.

Examples
Open a new account record using the default form

Xrm.Utility.openEntityForm("account");

Open an existing account record using the default form

Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");

Open a new account record with a specific form and setting default values

var parameters = {};
parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
parameters["name"] = "Test";
parameters["telephone1"] = "(425) 555-1234";
Xrm.Utility.openEntityForm("account", null, parameters);

Open a new account record using the default form in a new window

var windowOptions = {
 openInNewWindow: true
};
Xrm.Utility.openEntityForm("account",null,null,windowOptions);

openQuickCreate

For Microsoft Dynamics CRM Online 2015 Update 1 or later use this function to open a new quick create form. You can use this function to set default values using attribute mappings or for specific attributes. If the user saves the record, you can capture a reference to the record created.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

Parameters

Name	Type	Required	Description
entityLogicalName	String	Yes	The logical name of the entity to create.
createFromEntity	Lookup	No	Designates a record that will provide default values based on mapped attribute values. A lookup object has the following String properties: 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.
parameters	Object	No	A dictionary object that passes extra query string parameters to the form. Invalid query string parameters will cause an error. Valid extra query string parameters are: Default field ids: To set default values for a new record form. For more information, see Set field values using parameters passed to a form. Custom query string parameters: A form can be configured to accept custom query string parameters. For more information, see Configure a form to accept custom querystring parameters.
successCallback	Function	No	The function that will be called when a record is created. This function is passed an object as a parameter. This object has a savedEntityReference property with the following properties to identify the record 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 created.
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.

Remarks
This function is only available for Microsoft Dynamics CRM Online 2015 Update 1 or later.

There is a limit of 10 nested quick create forms in the web application. If this limit is exceeded this function will open the full entity form rather than the quick create form.

Example
When this code is run in an account entity form, a quick create form to create a new child account with a default name set to include the name of the parent account.

var thisAccount = {
    entityType: "account",
    id: Xrm.Page.data.entity.getId()
};
var callback = function (obj) {
    console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
}
var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
    console.log(error.message);
});

When this code is run with browser developer tools (F12 tools) the following represents the output to the console when run in the context of an account named ‘A. Datum Corporation (sample)’ and the user does not change the default name set for the new child account..

Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}

openWebResource

Opens an HTML web resource.

Note

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

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

Parameters

Name	Type	Required	Description
webResourceName	String	Yes	The name of the HTML web resource to open.
webResourceData	String	No	Data to be passed into the data parameter.
width	Number	No	The width of the window to open in pixels.
height	Number	No	The height of the window to open in pixels.

Return Value
Window object.
Remarks
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.
Examples
Open an HTML web resource named “new_webResource.htm”
```
Xrm.Utility.openWebResource("new_webResource.htm");
```
Open an HTML web resource including a single item of data for the data parameter
```
Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
```
Open an HTML web resource passing multiple values through the data parameter
```
var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
```
Note

These values have to be extracted from the value of the data parameter in the HTML web resource. For more information, see Sample: Pass multiple values to a web resource through the data parameter

Open an HTML web resource with the parameters expected by HTML web resources
```
Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
```
For more information, see Pass parameters to HTML web resources.

Open an HTML web resource, setting the height and width
```
Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
```

Kongsi melalui

Xrm.Utility (client-side reference)

Functions

Dialogs

alertDialog

confirmDialog

Native device capabilities (Dynamics 365 mobile clients)

getBarcodeValue

getCurrentPosition

isActivityType

openEntityForm

openQuickCreate

openWebResource

See Also

Sumber tambahan