Similar to the content repository, the workflow repository allows you to add listeners that get informed of every state transition, property change, task offer or warning, expired timer, and process definition update.

A workflow repository listener can be added by invoking the method WorkflowRepository#addWorkflowRepositoryListener. To assist in implementing custom listeners, the Unified API offers the class WorkflowRepositoryListenerBase, which can be used to handle selected types of events (by overriding the respective methods), or to handle all workflow events uniformly (by overriding the method #handleWorkflowRepositoryEvent)

When a listener is invoked, the same session is active that was active when the listener was registered. See Section 4.7, “Listeners”, and Section 4.9, “Sessions” for details.

Events are delivered serially to all registered listeners. That is, the next event will only be delivered after the current event was processed by all registered listeners. If you need to do any time-consuming computations, you should transfer the relevant events to a separate queue.

At the time the listener is invoked, the effect of the event is guaranteed to have reached the Unified API objects belonging to the same connection. So for example, in the method handling a TaskEnteredEvent, you can assume that isRunning returns true for the affected user task if the user has not completed the task yet. Note that the event may be significantly delayed, so the state may well have been changed in the meantime.

In contrast to the content repository, a workflow repository listener may lose events when the server connection is lost. All listeners will resume their work, but an application generally has to assume that the workflow server state has changed completely while the connection was lost. So in addition to workflow repository events, you may also want to observe connection events (see Section 4.1.3, “Connection Listener”).

When mixing reaction to events with accesses to the current repository state, it is often easier to use the cache and invalidation based programming model offered by the CoreMedia CAE (see the Delivery Developer Manual). The caching framework also handles connection failures: When the connection is reestablished, all cached values that depend on the workflow repository are automatically invalidated (or a recomputation is triggered).

The events related to process and task states can be gleaned from the state charts shown in Section 6.2, “Workflow States”. In the task state chart, an event name accepted on the transition label corresponds to an instance of Task AcceptedEvent dispatched to the workflow repository listener. Similarly, a started label in the process state diagram corresponds to a Process Started Event.

When a task is newly offered to some users, or when the offer to some users has been revoked, a TaskOfferedEvent or TaskRevokedEvent is signaled, respectively. See the subsection on user tasks in Section 6.2, “Workflow States” for more information, or see the Workflow Manual.

A ProcessCreatedEvent is signaled when a new process is created. The event indicates the performer - the user who invoked the ProcessDefinition#create method - as well as the new process' owner.

The remaining kinds of events are related to process definitions. A ProcessDefinitionCreatedEvent is sent when a process definition is uploaded, for instance using WorkflowRepository#createProcessDefinition. When a process definition is uploaded as described in Section 6.7, “Managing Process Definitions”, it supersedes any previous process definition with the same name. In addition to the identity of the created process definition, the event therefore carries information about the process definition's name, and the identity of the superseded process definition. The superseded process definition is implicitly disabled. A process definition can also be disabled or enabled explicitly by calling ProcessDefinition#enable or #disable, which causes a ProcessDefinitionEnabled event to be sent.