Making Your Jobs and Events Process-Aware

Before diving into this document, you should first explore the Process API documentation to get a better understanding of the Process module's design and capabilities.

Process-Aware System Events

To make an existing System Event process-aware, there are two aspects that you need to tackle: event creation and consumption/execution.

Event Creation

Instead of directly creating a System Event, you should now register a process using the ProcessRegistrationManager. The process type can be set to the System Event type and provide any parameters needed for execution. Normally, these parameters would be attached to the SystemEvent as SystemEventDetails, to later be used by the SystemEventConsumer. With a process, they are stored as ProcessParams that will be used by a ProcessExecutor.

When ProcessActionManager#start(Long processId) is called for the process, it is attached to a System Event of type PROCESS_EXECUTION. This causes the event to be picked up by the ProcessExecutionSystemEventConsumer and eventually passed to the associated ProcessExecutor.

By importing the blProcessActionManager bean via Spring, you'll receive the overriding SystemEventProcessActionManagerImpl resource. This guarantees that a SystemEvent is used to trigger the execution of the process, while providing the benefits of process execution tracking.

Event Consumption/Execution

To take advantage of the Process API and visualization, you need to execute your work in the context of a ProcessExecutor. This means that you need to take the existing SystemEventConsumer and refactor it into a ProcessExecutor. Overall, the two are not all that different. The main difference is where you get runtime data from - SystemEventDetails vs ProcessParams.

When refactoring, feel free to keep the ProcessExecutor's process type the same as your SystemEventConsumer's event type. This will be absolutely fine, as long as your registered processes have the same type and will guarantee that these processes are passed to the correct ProcessExecutor.

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.

Process-Aware Scheduled Jobs

Making Scheduled Jobs process-aware is very similar to the process of making System Events process-aware. Again, we need to focus on how the execution is triggered and where the execution takes place.

Triggering a Process-Aware Scheduled Job

When a Scheduled Job is triggered by either ScheduledJobService#runScheduledJobNow(Long jobId, BindingResult result) or MasterIntervalJobWorkerImpl#execute(JobExecutionContext jobExecutionContext), ProcessExecutionManager#hasRegisteredExecutorOfType(String jobType) is called to determine whether the job should be executed as a SystemEvent or a Process. From this method, we can gather a couple pieces of information. First, we are checking to see whether or not the ProcessExecutionManager has a registered ProcessExecutor of the provided type. Second, the type that we're checking for is the Scheduled Job's type.

In order for a Scheduled Job to be executed in a process-aware context you must refactor the existing SystemEventConsumer into a ProcessExecutor, thus satisfying the first portion of the ProcessExecutionManager#hasRegisteredExecutorOfType(String jobType) check. To satisfy the second portion, you must ensure that the Scheduled Job type matches the ProcessExecutor's type.

Behind the scenes, each execution of the Scheduled Job will register and maintain a process that begins its asynchronous execution via a System Event.