Client API execution context

The execution context defines the event context in which your code executes. The execution context is passed when an event occurs on a form or grid. Use it in your event handler to perform various tasks such as determine formContext or gridContext, or manage the save event.

The execution context is passed in one of the following ways:

  • Defining event handlers using UI: The execution context is an optional parameter that can be passed to a JavaScript library function through an event handler. Use the Pass execution context as first parameter option in the Handler Properties dialog while specify the name of the function to pass the event execution context. The execution context is the first parameter passed to a function.


  • Defining event handlers using code: The execution context is automatically passed as the first parameter to functions set using code. For a list of methods that can be used to define event handlers in code, see Add or remove functions to events using code.

The execution context object provides many methods to further work with the context. More information: Execution context (Client API reference)

Common mistakes in accessing contexts

The context passed to an event is only valid during the event. Don't keep a reference to a context after the event ends. The following are common anti-patterns because they access the context after the event handler finishes:

Accessing context in a promise

The context isn't valid in the promise returned by fetch.

function onLoad(executionContext) {
    var formContext = executionContext.getFormContext();
    fetch("https://www.contoso.com/").then(
        function (result) {
            // Using formContext or executionContext here is not supported
            // because onLoad has already completed when the promise is resolved.
            formContext.getAttribute("name").setValue(result);
        }
    );
}

Accessing context after an await statement

The context isn't valid after using await within an async function.

async function onLoad(executionContext) {
    var formContext = executionContext.getFormContext();
    var result = await fetch("https://www.contoso.com/");
    // Using formContext or executionContext here is not supported
    // because the synchronous part of onLoad has already completed.
    formContext.getAttribute("name").setValue(result);
}

Accessing context in a timeout function

The context isn't valid after using setTimeout or setInterval to defer executing some code.

function onLoad(executionContext) {
    var formContext = executionContext.getFormContext();
    if (notReady) {
        setTimeout(function () {
            // Using formContext or executionContext here is not supported
            // because onLoad has already completed when this delayed function executes.
            var name = formContext.getAttribute("name").getValue();
        }, 100);
    } else {
        formContext.getAttribute("name").setValue("abc");
    }
}

Accessing context in a stored variable

Don't cache the context as a variable.

function onLoad(executionContext) {
    window.__myExecutionContext = executionContext;
}

// This function is called any time later.
function customFunction() {
    // Using formContext or executionContext here is not supported
    // because onLoad has already completed when customFunction executes.
    var formContext = window.__myExecutionContext.getFormContext();
    formContext.getAttribute("name").setValue("abc");
}

Client API form context
Client API grid context
Form and grid context in ribbon actions