Skip to main content

Executive operations

An Executive operation represents a particular process instance that is being executed. All information related to a process being executed is associated with its operation.

An operation is identified by its name. This name is returned when creating a new operation, i.e., by loading a process into the Executive. All service calls related to a specific process must pass along this name.

info

Currently, the Executive supports at most one active operation. Before starting another operation the existing one must be stopped and deleted. When you implement a client, do not assume that there will always be only a single operation. We may support multiple parallel operations in the future.

Operation state​

The operation is either live or done (indicated by its done boolean flag).

The operation's metadata contains a RunMetadata proto. This has a field operation_state. It denotes the operation's state more precisely.

The operation can be in one of the following states:

ACCEPTED
The process has been loaded successfully and execution can start.
PREPARING
The process has been requested to start executing. The solution is being prepared to execute the process.
RUNNING
The process is currently executing.
SUSPENDING
A SuspendOperation call has been received and the Executive is awaiting running nodes to complete.
SUSPENDED
The process was successfully paused, no more actions are running.
CANCELING
The user has requested cancellation of the running operation. Running nodes are being aborted.
SUCCEEDED
The process has completed successfully.
FAILED
The process has failed. The error field in the Operation proto contains more specific information.
CANCELED
The cancellation requested by the user was completed.

Typical operation lifecycle​

An operation is created with CreateOperation, which loads a process into the Executive. The service call returns an Operation proto that includes a name used to refer to that operation in the subsequent calls. A created operation is still idle, i.e., ACCEPTED.

Start the operation with StartOperation call. The operation_state will transition to RUNNING.

While executing, the operation will eventually transition to either the SUCCEEDED or FAILED state. After the operation completes, you can delete it to create a new operation.

Detailed operation lifecycle​

The initial step is always to call CreateOperation to load an operation.

The StartOperation call supports options that determe how the operation runs. For example, step-wise execution (automatically suspends execution after starting the next action), starting at a specific node (other than the root node of the behavior tree in the process, useful for debugging), or executing in preview or fast-preview mode.

At any time, you can retrieve an operation and its state and metadata using the GetOperation service call. Generally, calls to this function should be infrequent, at most twice per second. To reduce the amount of data transferred, use GetOperationView. The caller can also use WaitOperation to wait until an operation completes execution (or a caller-configurable timeout is reached). This is indicated by the done flag becoming true.

An operation can be paused using SuspendOperation. This instructs the Executive to start no further nodes; already running nodes are allowed to complete so as to not introduce partial executions with unforeseen side effects. The state of the operation will be SUSPENDING and eventually SUSPENDED (or SUCCEEDED or FAILED if the process succeeded or failed while it was suspending). A suspended operation can be resumed using ResumeOperation.

An operation can also be cancelled using CancelOperation. Similar to suspension, no new actions will be started, but already running nodes will be canceled, where possible (e.g., by calling CancelOperation on each running skill). This operation transitions to CANCELED as soon as all running skills have finished. Canceled operations cannot be resumed.

Eventually, the operation completes unless it contains a non-ending loop (for example a continuous process); in that case you must explicitly cancel or suspend the operation. If the execution of a process fails, the error field in the Operation proto contains more detailed information.