Asynchronous operation states

Applies To: Dynamics CRM 2013

After asynchronous operations are added to the asynchronous queue, they exist in a well-defined state. An asynchronous operation can be waiting to run, it can be running, or it can be completed. There are also other possible states before the operation is eventually deleted from the queue. The states define the life cycle of the asynchronous operation.

In This Topic

States for asynchronous operations

Retrieve and update AsyncOperation states

States for asynchronous operations

The state of the asynchronous operation can be altered through three means: by the platform as part of regular queue processing, by the user interacting with the Microsoft Dynamics CRM Web application, or by a Web service call that alters the asynchronous operation. As a developer you can retrieve the current state of any asynchronous operation that you have access to and also change the state.

The following table lists the states, and the statuses for each state, of an AsyncOperation.

The supported states are defined in the AsyncOperationState enumeration. In the early bound AsyncOperation class, the state is available in the AsyncOperation.StateCode attribute while the status is available in the AsyncOperation.StatusCode attribute. For more information, see the AsyncOperation entity metadata. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download.. The statuses are shown in the Microsoft Dynamics CRM Web application in the Status Reason field in System Jobs grid. By selecting any of the menu items in the More Actions menu in System Jobs, you can interactively alter the state of an asynchronous operation. Allowed actions include the following: Cancel, Resume, Postpone, and Pause.

The following diagram shows the asynchronous operation state transitions that are supported.

Notice that an asynchronous operation can only transition from one state to another along specific paths as shown in the diagram. Some paths are initiated by the user interacting with the Microsoft Dynamics CRM Web application while other paths are initiated by the Microsoft Dynamics CRM platform as part of regular asynchronous queue processing or because of a Web service call. For example, an asynchronous operation cannot transition directly from a Suspended state to a Locked state.

A locked state indicates that the AsyncOperation instance is being used by the asynchronous service. While it is locked it cannot be used by another instance of the service. This ensures that the instance is not executed more than once, for example by two different asynchronous services.

Retrieve and update AsyncOperation states

Monitoring and updating the state of an asynchronous operation is typically done interactively through the System Jobs grid in the Microsoft Dynamics CRM Web application. However, you can also use the SDK to write code that performs those same tasks.

Read the state of an asynchronous operation

1. Retrieve an AsyncOperation by name using the RetrieveMultiple method or by ID using the Retrieve method.

2. Read the AsyncOperation.StateCode attribute.

Change the state code

1. Modify the retrieved state code attribute to a new value according to the allowed operation states. You could also change the AsyncOperation.PostponeUntil attribute.

2. Call Update to change the value of those attributes in the database.

The previous operations can also be performed by using the Execute method with the appropriate request messages. Attributes of AsyncOperation other than AsyncOperation.StateCode and AsyncOperation.PostponeUntil should be considered read-only.

Recurring system jobs

You cannot cancel, pause, or resume most system jobs. Refer to the following list that identifies some of these restricted system jobs. The value in the first column is the value of the OperationType attribute of the AsyncOperation entity.

For the complete list of supported asynchronous operation types, see the AsyncOperation entity metadata. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download.

See Also

Asynchronous service in Microsoft Dynamics CRM 2013
AsyncOperation (system job) entity
Dependency and execution order in asynchronous operations