ProcActionsFrame - CUBA Platform. BPM subsystem

5.1. ProcActionsFrame

The ProcActionsFrame is designed to work with process actions. After the frame is initialized, the following components will be automatically displayed:

the start process button, in case if the process is not started yet
the buttons for task outcomes, in case the process is started and the current user has an active task
the cancel process button
the task information panel (name and creation date)

A predicate can be assigned to each of the process actions in order to check if the action can be performed (e.g. the predicate commits an editor, and if the commit failed, the process action is not performed). The post-action listener can also be defined (e.g. the listener will close the editor and show a notification).

The ProcActionsFrame must be linked with the ProcInstance. The linking is performed during frame initialization.

An example of frame initialization:

procActionsFrame.initializer()
        .setBeforeStartProcessPredicate(this::commit)
        .setAfterStartProcessListener(showNotification(getMessage("processStarted"), NotificationType.HUMANIZED))
        .init(PROCESS_CODE, entity);

The initializer() method returns an object that is used for frame initialization.
The setBeforeStartProcessPredicate method sets the predicate that will be evaluated before the process start. If the predicate returns false then the process start will be interrupted.
The setAfterStartProcessListener method defines a listener that will be invoked after the process start action is performed.
The init method has two parameters: process code and entity instance. When this method is invoked, a search for the ProcInstance object that is related with the entity instance and has a reference to the ProcDefinition with the given code is performed. If the ProcInstance exists then the frame is linked to it, otherwise a new ProcInstance object is created.

The easiest way to initialize the ProcActionsFrame is to use the standard() initializer:

procActionsFrame.initializer()
        .standard()
        .init(PROCESS_CODE, entity);

The standard initializer does the following:

creates predicates that commit entity editor before start process and complete task actions
creates listeners that show notifications like "Process started" or "Task completed" and refresh the ProcActionsFrame

Below is the list of methods used for customizing the frame.

Process life cycle

initializer() - returns a new instance of frame initializer.

init() - tries to find the process instance by the specified process code and the entity reference. If the process instance is not found then a new one is created. Then the UI for available actions for the current user and the process instance is initialized.

Process configuration

setStartProcessEnabled() - defines whether the process can be started.

setCancelProcessEnabled() - defines whether the process can be cancelled.

setCompleteTaskEnabled() - defines whether the task can be completed.

setClaimTaskEnabled() - defines whether the task can be assigned to a user by himself.

setTaskInfoEnabled() - defines whether the layout with the localized task name and its start date is enabled.

setButtonWidth() - sets the width of the action control button. The default value is 150 px.

addActionButton() - allows adding a custom button to the frame alongside with buttons that were automatically generated.

Predicates

setBeforeStartProcessPredicate() - sets the predicate that will be evaluated before the process start. If the predicate returns false then the process start will be interrupted.

setBeforeCompleteTaskPredicate() - sets the predicate that will be evaluated before the task completion. If the predicate returns false then the task completion will be interrupted.

setBeforeClaimTaskPredicate() - sets the predicate that will be evaluated before the task is claimed to a user. If the predicate returns false then the task assignment will be interrupted.

setBeforeCancelProcessPredicate() - sets the predicate that will be evaluated before the task cancellation. If the predicate returns false then the task will not be cancelled.

Process and task listeners

setAfterStartProcessListener() - defines a listener that will be invoked after the process start action is performed.

setAfterCompleteTaskListener() - defines a listener that will be invoked after the task complete action is performed.

setAfterClaimTaskListener() - defines a listener that will be invoked after the task claim action is performed.

setAfterCancelProcessListener() - defines a listener that will be invoked after the process cancel action is performed.

Variables and parameters suppliers

setStartProcessActionProcessVariablesSupplier() - sets the process variables suppliers. Process variable suppliers return a map of process variables that must be added to Activiti process instance on process start.

setCompleteTaskActionProcessVariablesSupplier() - sets the process variables suppliers. Process variable suppliers return a map of process variables that must be added to Activiti process instance on task completion.

setStartProcessActionScreenParametersSupplier() - sets the process form screen parameters suppliers. These screen parameters suppliers return a map of screen parameters that will be passed to the process form displayed by StartProcessAction.

setCompleteTaskActionScreenParametersSupplier() - sets the process form screen parameters suppliers. These screen parameters suppliers return a map of screen parameters that will be passed to the process form displayed by CompleteTaskAction.