Xrm.WebApi.online.execute (Client API reference)

Execute a single action, function, or CRUD operation.

Note

This method is supported only for the online mode (Xrm.WebApi.online).

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 in case the action or function to execute is bound to an entity.
  • operationName: (Optional). String. Name of the action, function, or one of the following values if you are executing a CRUD request: "Create", "Retrieve", "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 (Deprecated): 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 (Deprecated): 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.
  • json: Promise. Parameter to the callback delegate is of type any (JSON object).
  • text: Promise. Parameter to the callback delegate is a String.
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 () { };
Sdk.WhoAmIRequest.prototype.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);
            result.json().then(
                function (response) {
                    console.log("User Id: %s", response.UserId);
                    // perform other operations as required;
                });
        }
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Xrm.WebApi