execute (Client API reference)

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

Execute a single action, function, or CRUD operation.

Note

This method isn't supported for Unified Interface. Also, this method is supported only for the online mode, which implies that you must use the Xrm.WebApi.online object to execute the method. Otherwise, it will fail.

Syntax

Xrm.WebApi.online.execute(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:
    • enumProperties: (Optional) Object. The metadata for enum types. The object has two string attributes: name and value
    • structuralProperty: 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 = window.Sdk || {};
/**
 * Request to win an opportunity
 * @param {Object} opportunityClose - The opportunity close activity associated with this state change.
 * @param {number} status - Status of the opportunity.
 */
Sdk.WinOpportunityRequest = function (opportunityClose, status) {
    this.OpportunityClose = opportunityClose;
    this.Status = status;

    this.getMetadata = function () {
        return {
            boundParameter: null,
            parameterTypes: {
                "OpportunityClose": {
                    "typeName": "mscrm.opportunityclose",
                    "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@odata.bind": "/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 Sdk.WinOpportunityRequest(opportunityClose, 3);

// Use the request object to execute the function
Xrm.WebApi.online.execute(winOpportunityRequest).then(
    function (result) {
        if (result.ok) {
            console.log("Status: %s %s", result.status, result.statusText);
            // perform other operations as required;
        }
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Execute a function

The following example demonstrates how to execute the WhoAmI function:

var Sdk = window.Sdk || {};
/**
 * Request to execute WhoAmI function
 */
Sdk.WhoAmIRequest = function () {
    this.getMetadata = 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 Sdk.WhoAmIRequest();

// Use the request object to execute the function
Xrm.WebApi.online.execute(whoAmIRequest).then(
    function (result) {
        if (result.ok) {
            console.log("Status: %s %s", result.status, result.statusText);
            var response = JSON.parse(result.responseText);
            console.log("User Id: %s", response.UserId);
            // perform other operations as required;
        }
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Xrm.WebApi