6.1. ProcActionsFragment

The ProcActionsFragment is designed to work with process actions. After the fragment 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 ProcActionsFragment must be linked with the ProcInstance. The linking is performed during fragment initialization.

An example of fragment initialization:

procActionsFragment.initializer()
        .setBeforeStartProcessPredicate(() -> {
            getScreenData().getDataContext().commit();
            return true;
        })
        .setAfterStartProcessListener(() -> {
            notifications.create()
                    .withCaption(messageBundle.getMessage("processStarted"))
                    .withType(Notifications.NotificationType.HUMANIZED)
                    .show();
        })
        .init(PROCESS_CODE, getEditedEntity());

  • The initializer() method returns an object that is used for fragment 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 fragment is linked to it, otherwise a new ProcInstance object is created.

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

procActionsFragment.initializer()
        .standard()
        .init(PROCESS_CODE, getEditedEntity());

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 ProcActionsFragment.

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

Process life cycle

  • initializer() – returns a new instance of fragment 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 canceled.

  • 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 fragment 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 canceled.

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.

ProcActionsFragment API

addActionButton – initializer

Initializer API

init – setAfterCancelProcessListener – setAfterClaimTaskListener – setAfterCompleteTaskListener – setAfterStartProcessListener – setBeforeCancelProcessPredicate – setBeforeClaimTaskPredicate – setBeforeCompleteTaskPredicate – setBeforeStartProcessPredicate – setButtonWidth – setCancelProcessEnabled – setClaimTaskEnabled – setCompleteTaskActionProcessVariablesSupplier – setCompleteTaskActionScreenParametersSupplier – setCompleteTaskEnabled – setStartProcessActionProcessVariablesSupplier – setStartProcessActionScreenParametersSupplier – setStartProcessEnabled – setTaskInfoEnabled