Foreground and Background Actions

Foreground actions are the default. An action can be marked as a background action. This is useful when you want your app to remain responsive to a user while it executes a low priority, long-running action. A rough guideline is to use a background action if it takes more than five seconds for the response to return from the server.

Batching of Actions

Multiple queued foreground actions are batched in a single request (XHR) to minimize network traffic. The batching of actions is also known as boxcar’ing, similar to a train that couples boxcars together.

The server sends the XHR response to the client when all actions have been processed on the server. If a long-running action is in the boxcar, the XHR response is held until that long-running action completes. Marking an action as background results in that action being sent separately from any foreground actions. The separate transmission ensures that the background action doesn’t impact the response time of the foreground actions.

When the server-side actions in the queue are executed, the foreground actions execute first and then the background actions execute. Background actions run in parallel with foreground actions and responses of foreground and background actions may come back in either order.

We don’t make any guarantees for the order of execution of action callbacks. XHR responses may return in a different order than the order in which the XHR requests were sent due to server processing time.

Don’t rely on each background action being sent in its own request as that behavior isn’t guaranteed and it can lead to performance issues. Remember that the motivation for background actions is to isolate long-running requests into a separate request to avoid slowing the response for foreground actions.

Note

Multiple actions sent in the same boxcar are processed in one transaction. If you see an error for “uncommitted work pending”, it’s possible that a later action can’t be completed due to uncommitted work for an earlier action in the same transaction. For example, if the first action updates a record, an Apex callout in a second action can’t be completed due to the uncommitted work from the first action. If two actions must be executed sequentially, the component must orchestrate the ordering. The component can enqueue the first action. In the first action’s callback, the component can then enqueue the second action.

Framework-Managed Request Throttling

The framework throttles foreground and background requests separately. This means that the framework can control the number of foreground requests and the number of background actions running at any time. The framework automatically throttles requests and it’s not user controlled. The framework manages the number of foreground and background XHRs, which varies depending on available resources.

Even with separate throttling, background actions might affect performance in some conditions, such as an excessive number of requests to the server.

Setting Background Actions

To set an action as a background action, call the setBackground() method on the action object in JavaScript.

// set up the server-action action
var action = cmp.get("c.serverEcho");
// optionally set actions params
//action.setParams({ firstName : cmp.get("v.firstName") });
// set as a background action
action.setBackground();

A background action can’t be set back to a foreground action. In other words, calling setBackground to set it to false will have no effect.

Note