Process API Usage
The major components of the Process API are as follows:
ProcessRegistrationManagerProcessStateManagerProcessActionManagerProcessExecutionManagerProcessExecutorImplementations
Please reference the following sections for further details on each component.
ProcessRegistrationManager
The ProcessRegistrationManager is responsible for registering Process instances. At the time of registration, the processType must be provided. This identifies the ProcessExecutor that is capable of handling the process's execution.
Additionally, the registration manager provides you with the ability to register unique processes. This means that if there is an active process with the same processType and processParams, then the request to register the new process will be denied.
ProcessStateManager
Simply put, the ProcessStateManager is used to maintain the state of a registered process and record data points throughout the process's execution.
It gives the capability to record a process's running, paused, resumed, stopped, and completed states. Each of these state-recording methods are backed by state-checking logic to ensure that the change is valid. Please note the ProcessCompletionSubstatusType used for recording completion. ProcessStatusType#COMPLETED simply indicates that the process is in a final state, whereas the ProcessCompletionSubstatusType indicates how it got to that final state - i.e. was the process stopped or did it finish organically?
Additionally, it provides you with the ability to record the process's execution progress and make note of any data that you wish to record for the process.
ProcessActionManager
The ProcessActionManager serves as an API for making start, pause, resume, and stop actions against a registered process. Just like the ProcessStateManager, each of these actions includes validation logic to ensure that requesting state changes are valid.
The start and resume actions pass directly to the ProcessExecutionManager to begin execution. All of the other actions set a requested state (PAUSE_REQUESTED or STOP_REQUESTED) to identify that a state change has been made against the executing process.
Asynchronous Process Execution with the Jobs and Events Module
When the Jobs and Events module is included in your project, all process execution will be triggered asynchronously in a separate thread. In this case, we make use of the overriding SystemEventProcessActionManagerImpl.java. Instead of going directly to the ProcessExecutionManager to begin execution, we attach the process's id to a System Event of type PROCESS_EXECUTION. That System Event is then picked up by the ProcessExecutionSystemEventConsumer, the processId is plucked from the event, and passed into the ProcessExecutionManager. This allows us to execute the process completely in the background without tying up any of our current threads.
For these intermediary states between calls to the ProcessActionManager and consumption of the System Event, we make use of the START_REQUESTED and RESUME_REQUESTED states. When the process is passed to the ProcessExecutionManager, we proceed as normal.
Specifying System Event Parameters
To provide System Event information such as the event's EventWorkerType or EventScopeType, you should include a ProcessParam with its name set to ProcessParam.EventingParam.WORKER_TYPE or ProcessParam.EventingParam.SCOPE_TYPE. When a System Event is created for a process, these parameters will be passed into the System Event builder.
ProcessExecutionManager
The ProcessExecutionManager is used to establish and document the execution context prior to passing the process to the ProcessExecutor. It starts by declaring the capabilities of the executor, records whether the process is being started or resumed, and then begins the process's execution. When we return from execution, the ProcessExecutionManager sets a default completion state, if it hasn't already been done by the ProcessExecutor.
ProcessExecutor Implementations
ProcessExecutor Capabilities (Stoppable vs Pausable/Resumable)
If you wish for your ProcessExecutor implementation to be stoppable or pausable/resumable through the Admin interface, then your ProcessExecutor must also implement the StoppableExecutor or ResumableExecutor interfaces. These indicator interfaces are used by the ProcessExecutionManager to determine the executor's capabilities. Note that if a process is pausable/resumable, then it is also considered stoppable.
The application of the StoppableExecutor and ResumableExecutor interfaces should not be treated as a panacea. It is up to you to implement the necessary mechanism for stopping or pausing/resuming the process. We found that stopping, pausing, and resuming is most easily done for processes that can be executed in batches. If a request to pause comes in, you can record the progress according to the last executed batch and later pickup where you left off. For an example of how this can be done, see the HelloWorldProcessExecutor.java.
To check whether or not a request to stop or pause has been made, ProcessStateManager#shouldContinueProcessExecution(Long processId) should be used.
Admin Interactions
In the Admin interface, you are given visualization of both active and past process executions. For active executions, you are able to perform actions based on their ProcessExecutor's capabilities. Behind the scenes, these interactions lead directly to calls against the ProcessActionManager API.
Process State Diagram
To get a better understanding of the different states of a process and how each of the previously mentioned resources are used to manage the process, see the Process State Diagram.
Process-Aware System Events and Scheduled Jobs
For more information on how to track your System Events and Scheduled Jobs using the Process API, see the Process-Aware System Events and Scheduled Jobs document.