CUBA Platform. BPM subsystem

A newer version is available at the documentation home.

Preface

This document is the user manual for the CUBA Platform business process management subsystem.

Target Audience

This manual is intended for developers who use the CUBA platform to create applications with business processes management functionality. It is assumed that the reader is familiar with the Developer’s Manual, which is available at https://www.cuba-platform.com/manual.

Additional Materials

This manual, as well as other documentation on the CUBA platform, are available at https://www.cuba-platform.com/manual.

CUBA business process management subsystem is based on the Activiti framework, therefore general knowledge on the framework is beneficial. See http://www.activiti.org to learn more about the Activiti framework.

An executable process description employs the BPMN 2.0 notation. Consequently, it is assumed that the reader is familiar with the notation. More information about BPMN 2.0 specification can be found at http://www.bpmn.org.

Feedback

If you have any suggestions for improving this manual, please contact Technical Support at http://www.cuba-platform.com/support/topics.

When reporting errors in the documentation, please indicate the chapter and surrounding text to point the error.

1. Quick Start

In this chapter, we will create a small project to demonstrate how to use the business processes subsystem. As an illustration we will implement a contract approval process software.

Commonly an approval process involve the following steps:

A user creates the Contract object, defines actors and initiates an approval process.
An actor with the Controller role receives the task to validate an attached contract.
If the validation is passed then the contract is transferred to the users with the Manager role assigned, otherwise the process will be terminated with Not valid state.
After the associated managers approve or reject the contract it turns, respectively, into the Approved or Not approved state.

1.1. Creating the Project

Create a new project in Cuba Studio:
- Project name: bpm-demo
- Project namespace: demo
- Root package: com.company.demo

Open the project properties window (Project properties section, Edit button).
Activate the BPM subsystem in the Base projects list.

Press OK button at the project properties page. The system will ask you for the confirmation. Agree.

1.2. Creating the Data Model

Go to the Entities tab and press New entity. The class name is Contract.

Create the following entity attributes:

number (String type)
date (Date type)
state (String type)

Go to the Instance name tab. In the Name pattern field enter the value Contract %s and add the number attribute to Name pattern attributes.

Press the OK button to save the entity.

1.3. Standard screens creation

In the Entities section of navigator panel select the Contract entity and click the Create standard screens button. Default values of the screen creating window suits us, so just click Create.

1.4. Creating Business Logic Beans

1.4.1. ApprovalHelper Bean

The updateState() method of the ApprovalHelper bean will be invoked from the contract approval process for setting a contract state.

Method parameters:

entityId - contract entity identifier
state - contract state

Open the project in an IDE. A simple way to do it is to use an IDE button from any section of the Studio navigator, e.g. Project properties.

Create a package com.company.demo.core in the core module. Create ApprovalHelper class in this package.

ApprovalHelper.java

package com.company.demo.core;

import com.company.demo.entity.Contract;
import com.haulmont.cuba.core.EntityManager;
import com.haulmont.cuba.core.Persistence;
import com.haulmont.cuba.core.Transaction;
import javax.annotation.ManagedBean;
import javax.inject.Inject;
import java.util.UUID;

@ManagedBean("demo_ApprovalHelper")
public class ApprovalHelper {

    @Inject
    private Persistence persistence;

    public void updateState(UUID entityId, String state) {
        Transaction tx = persistence.getTransaction();
        try {
            EntityManager em = persistence.getEntityManager();
            Contract contract = em.find(Contract.class, entityId);
            if (contract != null) {
                contract.setState(state);
            }
            tx.commit();
        } finally {
            tx.end();
        }
    }
}

1.5. Creating the Database and Running the Application

Press the Generate DB scripts button of the Entities navigator section. In the database manager window press the Create database button.

Start the server with Run → Start application server command.

Open the application in a browser at http://localhost:8080/app or just click the link in the bottom of Studio navigator panel.

1.6. Creating the Process

1.6.1. Creating the Process model

The final version of process model will look like this:

Let’s look at the sequence of steps to create the model.

Open the screen BPM → Process models in the running application web interface and press Create. Enter the model name Contract approval and press OK. A new browser tab Model editor will be opened.

Tip	If the model editor tab didn’t appear, ensure that the browser haven’t blocked the new popup window.

Select the Process roles property in the model properties panel. The process roles edit window will be opened.

There are two types of actors participate in the process: a manager and a controller. Create two roles: Controller and Manager.

Drag and drop the Start event node from the Start Events group to the workspace. We need to display a form to select the process actors when the process starts. Select the start event node. Select the Start form in its properties panel - a form selection window will be opened. Select Standard form in the Form name field. Then add two form parameters:

procActorsVisible with true value indicates that a table for process actors selection will be displayed on the form.
attachmentsVisible with true value indicates that a table for attachments upload will be displayed on the form.

Add the User task node from an Activities group to the model. Name it Validation.

Select this node and assign the controller value to the Process role property at the properties panel. This is how we defined that the task will be assigned to a process actor with controller role.

Next select the Task outcomes property. The window for task outcomes edit will be opened. Outcomes define possible users actions when users receive tasks. Create two outcomes: Valid and Not valid. Define the Standard form for both outcomes. Add form parameter commentRequired=true for the Not valid outcome, because we want to make a user add a comment in case of invalid contract.

Depending on the controller’s decision we have to send the contract to managers approval or to finish the process with the Not valid state. The Exclusive gateway node from the Gateways group is used to control the process flow. Add it to the workspace and then add two more elements: Script task with Set 'Not valid' state name and User task with Approval name. Name the flow to the Script task as Not valid and the flow to the User task should be named Valid.

Select the Not valid flow. Expand the Flow outcome dropdown list from the properties panel. It shows outcomes from the tasks before the gateway. Select the Not valid value.

Now, if the Not valid outcome is selected, a transition to this flow will be performed.

The Valid flow should be marked as the default flow (if no other flows condition are true). Select the Valid flow and tick the Default flow property.

Next select the Exclusive gateway and open its Flow order property editor. Make sure that the Not valid flow goes on the first place in a list. If it is not true then change the flows sequence.

Let’s move to the Set 'Not valid' state node. We need to set the state property of the Contract entity to the Not valid value. Select the node. Set the Script format property value to groovy. Click on the Script property field - the script editor will be opened. Copy and paste the following code there:

import com.company.demo.entity.Contract

def em = persistence.getEntityManager()
def contract = em.find(Contract.class, entityId)
contract.setState('Not valid')

You are allowed to use the process variables and platform objects persistence and metadata (see CUBA Platform. Developer’s Manual) in scripts. An entityId variable is created on process start and stores an identifier of the linked entity.

After the contract state is changed, the process should be finished. Let’s add an End event node from the End events group to the workspace and link the node with the Set 'Not valid' state.

Let’s go back to the Approval task. Define the manager process role for it like we did for the first task. In order the task to be assigned to many managers simultaneously set its Multi-instance type property to Parallel.

Create two task outcomes: Approve and Reject (Task outcomes property). For both outcomes set the Standard form form and set commentRequired parameter to true for the Reject outcome.

After the approval is completed, or Approved either Not approved status should be assigned to the contract depending on the approval result. Add an Exclusive gateway node after the Approval task. Add two Service task after the exclusive gateway: Set 'Approved' state and Set 'Not approved' state. They will do the same thing as the Script task we added earlier, but in another way. They will invoke a Spring bean method. Name the flow to the Set 'Approved' state as Approved, and name the flow to the Set 'Not approved' state as Not approved.

Select the Not approved flow node and select the Reject value in the Flow outcome list. Now if at least one of the managers performs the Reject action then this outcome will be initiated. Select the Approved flow node and check the Default flow checkbox. This means that if no other flow is initiated then this flow will be used.

Set the flow order for the Exclusive gateway like we did for the previous one. Select the Exclusive gateway and open the Flow order property editor. Not approved should be processed first.

Let’s go back to the Service task. Select the Set 'Approved' state node and set its Expression property to the following value:

${demo_ApprovalHelper.updateState(entityId, 'Approved')}

Apply the following script for the Set 'Not approved' state:

${demo_ApprovalHelper.updateState(entityId, 'Not approved')}

Activiti engine is integrated with the String framework, so we can access Spring managed beans by their names. entityId is a process variable that stores an identifier of the contract which is linked to the process. Its value is set on a process start.

Link both Service tasks with the End event and press the save model button. The model is ready and we can move to the model deployment.

1.6.2. Process Model Deployment

The model deployment process consists of the following steps:

Generating a process XML in BPMN 2.0 notation from the model.
Deploying the process to Activiti engine internal tables.
Creating a ProcDefinition object that relates to the Activiti process.
Creating ProcRole objects for process roles defined in the model.

Select the model in the list on the Process models screen. Press the Deploy button. The model deployment window will be displayed. The model is deployed for the first time, so the Create new process option is selected. You will be able to deploy the model to existing processes for further model changes. Click OK. The process definition is created.

Open the screen BPM → Process Definitions. Open the 'Contract approval' item for editing. The Code field value is contractApproval. Remember this value. We will use it to identify the process definition later in this chapter.

1.7. Adapting Screens to the Process

In this section, we will add an ability to work with the contract approval process to the contract editor screen.

1.7.1. Contract Editor Screen Layout

Find the contract-edit.xml screen in the Screens panel in Studio and open the screen for editing. Go to the XML tab and completely replace its content with the following code:

contract-edit.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<window xmlns="http://schemas.haulmont.com/cuba/window.xsd"
        caption="msg://editCaption"
        class="com.company.demo.web.contract.ContractEdit"
        datasource="contractDs"
        focusComponent="fieldGroup"
        messagesPack="com.company.demo.web.contract">
    <dsContext>
        <datasource id="contractDs"
                    class="com.company.demo.entity.Contract"
                    view="_local"/>
        <collectionDatasource id="procAttachmentsDs"
                              class="com.haulmont.bpm.entity.ProcAttachment"
                              view="procAttachment-browse">
            <query><![CDATA[select a from bpm$ProcAttachment a
            where a.procInstance.entityId = :ds$contractDs order by a.createTs]]></query>
        </collectionDatasource>

    </dsContext>
    <layout expand="windowActions" spacing="true">
        <fieldGroup id="fieldGroup" datasource="contractDs">
            <column width="250px">
                <field id="number"/>
                <field id="date"/>
                <field id="state" editable="false"/>
            </column>
        </fieldGroup>
        <groupBox id="procActionsBox"
                  caption="msg://process"
                  orientation="vertical"
                  spacing="true"
                  width="AUTO">
            <frame id="procActionsFrame" screen="procActionsFrame"/>
        </groupBox>
        <groupBox caption="msg://attachments"
                  width="700px"
                  height="300px">
            <table id="attachmentsTable"
                   height="100%"
                   width="100%">
                <columns>
                    <column id="file.name"/>
                    <column id="author"/>
                    <column id="type"/>
                    <column id="comment" maxTextLength="50"/>
                </columns>
                <rows datasource="procAttachmentsDs"/>
            </table>
        </groupBox>
        <frame id="windowActions" screen="extendedEditWindowActions"/>
    </layout>
</window>

Go to the Layout tab. The resulting screen layout is shown below:

The screen contains a FieldGroup for contract editing, a frame for displaying process actions, and a table with process attachments.

1.7.2. Contract Editor Controller

Go to the Controller tab and replace its content with the following code:

ContractEdit.java

package com.company.demo.web.contract;

import com.company.demo.entity.Contract;
import com.haulmont.bpm.entity.ProcAttachment;
import com.haulmont.bpm.gui.procactions.ProcActionsFrame;
import com.haulmont.cuba.gui.app.core.file.FileDownloadHelper;
import com.haulmont.cuba.gui.components.AbstractEditor;
import com.haulmont.cuba.gui.components.Table;

import javax.inject.Inject;

public class ContractEdit extends AbstractEditor<Contract> {

    private static final String PROCESS_CODE = "contractApproval";

    @Inject
    private ProcActionsFrame procActionsFrame;

    @Inject
    private Table<ProcAttachment> attachmentsTable;

    @Override
    protected void postInit() {
        FileDownloadHelper.initGeneratedColumn(attachmentsTable, "file");
        initProcActionsFrame();
    }

    private void initProcActionsFrame() {
        procActionsFrame.initializer()
                .setBeforeStartProcessPredicate(this::commit)
                .setAfterStartProcessListener(() -> {
                    showNotification(getMessage("processStarted"), NotificationType.HUMANIZED);
                    close(COMMIT_ACTION_ID);
                })
                .setBeforeCompleteTaskPredicate(this::commit)
                .setAfterCompleteTaskListener(() -> {
                    showNotification(getMessage("taskCompleted"), NotificationType.HUMANIZED);
                    close(COMMIT_ACTION_ID);
                })
                .init(PROCESS_CODE, getItem());
    }
}

Press OK to save the changes.

Let’s examine the controller code in details.

The ProcActionsFrame is the frame that displays process actions available at the moment. During the frame initialization, a related ProcInstance object search is performed based on two parameters (process code and entity instance). If the ProcInstance object is not found then a new instance is created and the frame displays a start process button. If the related process instance is found then an uncompleted process task for the current user is searched and the buttons for process task actions are displayed. See ProcActionsFrame for details.

In the contract editor the process actions frame initialization is performed in the initProcActionsFrame() method. The main part of the method is the invocation of the init(PROCESS_CODE, getItem()). The PROCESS_CODE stores a process code (contractApproval - we saw this value during the model deployment, see Process Model Deployment). The second argument getItem() is the current contract.

We also defined an additional business logic that is related to process actions:

setBeforeStartProcessPredicate adds the check that is performed before the process is started. An editor commit is performed and if the commit fails the process won’t start
setAfterStartProcessListener shows the notification and closes the contract editor after the process start
setBeforeCompleteTaskPredicate invokes the editor commit before the process action. If the commit fails the action won’t be performed
setAfterCompleteTaskListener shows the notification and closes the contract editor after the process action is performed

1.7.3. Localized Messages File

In Studio, open the messages.properties file from a package with contract screens. Replace its content with the following text:

browseCaption = Contract browser
editCaption = Contract editor
attachments = Attachments
process = Contract approval
processStarted = Process started
taskCompleted = Task completed

1.8. Working With the Application

Hot deploy mechanism is enabled in Studio by default, so all changes in screens should be already sent to the application server. If Hot Deploy is disabled then restart the server in Studio with the Run → Restart application server command.

1.8.1. Creating Users

We have to create test users for the process demonstration. Open the Administration → Users screen and create 3 users:

1.8.2. Creating the Contract and Starting the Process

Open the contract list Application → Contracts and create a new contract. Fill Number and Date fields, and click Save button.
Click Start process button, the start process form should appear. During the model creation we defined the Standard form with attributes procActorsVisible=true and attachmentsVisible=true for the Start event node. That’s why now we see the form with the process actors and attachments tables.
Enter a comment and add actors: the controller is norman and the two managers are pierce and roberts.
Add an attachment by using an Upload button from the attachments table.

Press OK. Now the process is started.

1.8.3. Controller Validation Stage

When a process reaches the User task node, a ProcTask object is created. This object is linked to the particular process actor. The BPM subsystem has a screen for displaying the uncompleted tasks for the current user. Open it: BPM → Process tasks.

We see that the user norman has one uncompleted task Validation of the Contract approval process. Select it and click the Open entity editor button. The contract edit screen will appear:

The current user (norman) has an uncompleted task (ProcTask), so the procActionsFrame displays available process actions. When we were defining the Validation UserTask node, we set two possible outcomes: Valid and Not valid. That’s why two buttons are added to the procActionsFrame.

Click the Valid button. In the opened window enter the following comment:

Click OK.

After the successful validation the contract should go to managers parallel approval.

1.8.4. Manager Approval Stage

Open the current task list BPM → Process tasks. There is the Approval task there.

Select the task and this time click the Open process instance button. The system screen for working with the process instance will be opened.

It displays the information about the process start time, initiator, attachments list, actors list, process instance tasks list. The screen also allows you to open the linked entity editor and execute a process action.

Pay attention to the Tasks table. The previous task Validation has been completed with the Valid outcome, and two new Approval tasks were created for managers pierce and roberts.

Approve the contract pressing the Approve button.

Then log in as roberts. Open the contract from the list Application → Contracts.

User roberts has an uncompleted task, so the procActionsFrame displays Approve and Reject actions. Click the Reject button.

When we were defining the Reject outcome in the model designer, we set a commentRequired form parameter to true, therefore you see that the comment is required in the task complete form. Enter the comment and press OK.

One of the managers has rejected the contract, so the Not approved state should be assigned to the contract. Let’s check it. Open the contract.

The approval process is completed with the Not approved state.

2. Data Model

Note	Attributes which names start with *act prefix are references to the Activiti identifiers.

ProcModel - the process model. Model attributes:
- name - the model name.
- description - the model description.
- actModelId - ID of a model from Activiti engine, stored in ACT_RE_MODEL table.
ProcDefinition - the process definition. Entity attributes:
- name - the process name.
- code - the process code. It can be used to determine an entity instance from the application code.
- actId - ID of a process from Activiti.
- active - defines, whether a new process instance start is allowed for the current ProcDefinition.
- procRoles - collection of objects that defines process actors.
- model - the reference to a model.
ProcRole - the process role. Objects of this type are created automatically on process deployment. ProcRole defines a process actor type. Entity attributes:
- name - the role name.
- code - the role code. It can be used by an application for a role identification.
- order - the order number. It can be used by an application to display roles in an appropriate order.
- procDefinition - the reference to a process definition.
ProcInstance - the process instance. ProcInstance can be started both with a link to a project entity and without a link. For example, the contract approval process instance can be linked with a contract entity. Entity attributes:
- description - the description of a process instance.
- startDate - the process instance start date.
- endDate - the process instance end date
- startedBy - the user who started a process.
- active - the indicator that shows if a process was started but hasn’t been completed yet.
- cancelled - the indicator that shows if a process was canceled.
- actProcessInstanceId - the identifier of the corresponding ProcessInstance from Activiti.
- startComment - the comment on process start.
- cancelComment - the comment on process cancel.
- entityName - the linked entity name.
- entityId - the linked entity ID.
- entityEditorName - the screen name that will be used to edit the linked entity.
- procTasks - the process tasks collection.
- procActors - the process actors collection.
- procAttachments - the process attachments collection.
ProcActor - the process participant. The entity defines an executor with a particular role for a process instance. Entity attributes:
- user - the reference to a user.
- procInstance - the reference to a process instance.
- procRole - the reference to a process role.
- order - the order number. The field is used to define the order of actors for a sequential task for multiple users.
ProcTask - the process task. Objects of this type are automatically created when a process reaches the User task node. Entity attributes:
- name - the task name.
- startDate - the task start date.
- claimDate - the claim date. The field is used in a case of a task without an explicit process actor.
- endDate - the task end date.
- outcome - the task completion result.
- comment - the task completion comment.
- procActor - the executor.
- actTaskId - the Activiti task ID. This field is used to report the Activiti engine about task completion.
- actExecutionId - the Activiti execution ID. This field is used for process variables read/write.
- actTaskDefinitionKey - in a process XML it is an id attribute of the UserTask element. It is used for building a name of a variable that stores the task result ([task_id]_result). See Transitions Depending on Task Outcomes.
- cancelled - the identifier that shows if the task was completed on process cancelation.
- candidateUsers - the list of possible process actors for a group task.
- procInstance - the reference to a process instance.
ProcAttachment - the process attachment. Entity attributes:
- file - the reference to FileDescriptor.
- type - the attachment type (ProcAttachmentType).
- comment - the comment.
- author - the reference to the author of an attachment.
- procInstance - the reference to a process instance.
- procTask - the optional reference to a process task.
ProcAttachmentType - the attachment type. Entity attributes:
- code - the attachment type code.
- name - the attachment type name.

3. Functionality

The BPM subsystem employs the Activiti Engine for business processes execution. The modified editor from Activiti Explorer is used to model processes using BPMN 2.0 notation. In addition to Activiti framework capabilities, the BPM subsystem provides additional functionality which is described in this section. A description of the Activiti framework is out of this manual scope and can be found at http://www.activiti.org/userguide/.

3.1. BpmActivitiListener

The BpmActivitiListener event listener is automatically added to the process when a model is created. BpmActivitiListener implements the ActivitiEventListener interface (see http://www.activiti.org/userguide/#eventDispatcher). The listener is responsible for creating and modifying BPM entities when some process events occur (e.g. a user task entering, process cancelation, task completion, etc). This is the listener that creates ProcTasks objects and sets the endDate value for a ProcInstance.

3.2. Process Roles

Process roles define process actor types, e.g. operator or manager. To open the process roles editor select the Process roles property in the model properties panel. Information about the roles will be written to the process XML (extensionElements section of the process element) during the model deployment.

Process roles definition

<process id="testProcess" name="Test process">
    <extensionElements>
         <cuba:procRoles>
            <cuba:procRole name="Manager" code="manager"/>
            <cuba:procRole name="Operator" code="operator"/>
        </cuba:procRoles>
    </extensionElements>
</process>

3.3. Start Process Form

To define a form that will be displayed on the process start, use the Start form property of the Start event node. Read mode about forms at the Process forms section.

Process start form definition

<startEvent id="startEvent">
  <extensionElements>
    <cuba:form name="standardProcForm">
      <cuba:param name="procActorsVisible" value="true"></cuba:param>
    </cuba:form>
  </extensionElements>
</startEvent>

3.4. User Task

To define the task assignee, select one of the process roles in the Process role property of the User task node. When a process reaches the User task, process actors with the given role will be found among all the process actors, and the task will be assigned to them.

Process role from a task

<userTask id="managerApproval" name="Manager approval">
    <extensionElements>
        <cuba:procRole>manager</cuba:procRole>
    </extensionElements>
</process>

If you want the task to be assigned to multiple users, then set Parallel or Sequential value to the Multi-instance type property of the User task node.

Set the Claim allowed property if you don’t want the task to be immediately assigned to the particular user, but to appear in the list of available tasks for the group of users. Then, one of the candidates will be able to claim the task. Task candidates are defined amongst process actors with the corresponding Process role property.

A task without an explicit executor

<userTask id="managerApproval" name="Manager approval">
    <extensionElements>
        <cuba:claimAllowed>true</cuba:claimAllowed>
    </extensionElements>
</process>

3.5. Task Outcomes

Commonly, a user is expected to make a decision on the task, e.g. to approve or to reject the contract. The next route through the process depends on this decision. The Task outcomes property of the User task node is used to define the list of outcomes. The name and from, that should be displayed when an outcome is selected, can be defined for each outcome spearately. The parameters that should be passed to the form can be defined as well (see Process forms).

Task outcomes

<userTask id="managerApproval" name="Manager approval">
    <extensionElements>
        <cuba:outcomes>
            <cuba:outcome name="approve">
                <cuba:form name="standardProcessForm">
                    <cuba:param name="commentRequired">true</cuba:param>
                    <cuba:param name="attachmentsVisible">true</cuba:param>
                </cuba:form>
            </cuba:outcome>
            <cuba:outcome name="reject">
                <cuba:form name="someOtherProcessForm">
                </cuba:form>
            </cuba:outcome>
        </cuba:outcomes>
    </extensionElements>
</process>

3.6. Transitions Depending on Task Outcomes

Unlike jBPM, BPMN 2.0 notation doesn’t provide the way to define multiple outcomes for a User task. To make a process to be continued on a required flow node, the Exclusive gateway is used. Its outgoing flows have conditions that operate with the results of the preceding task. When a user completes the task, its result is written to the process variable with the name generated as [taskId]_result. The variable type is ProcTaskResult.

Methods of ProcTaskResult class:

int count(String outcomeName) - returns the number of users who completed the task with the given outcome.
boolean exists(String outcomeName) - returns true if there are users who completed the task with a given outcome.

The resultant object of the task completion is used in the Flow condition expression of gateway outgoing flows.

Example:

Let’s suppose that the approval task was assigned to multiple uses in parallel. There are 2 outcomes defined for the task: approve and reject. When all users have completed the task, the process goes to the exclusive gateway. We want to implement the following behavior: if anyone choses the reject option then go to the Rejected flow; if everyone approved the task then go to the Approved flow.

Defining a Condition in a Flow Outcome Field

The simplest way to define the flow condition is to select the name of the previous task outcome in the Flow outcome property of the flow node. The flow will be activated if there was at least one task completion with the selected outcome.

Defining a Complex Condition for the Flow Node

If you need to implement more complex condition for the outcome, you can define it in the Flow condition field. For example, "More than 5 users selected the Reject option" condition looks like following:

${approval_result.count('reject') > 5}

3.6.1. Flow Order

Please notice that the flow order must be defined. Otherwise, Activiti could process the default flow before the flows with explicit conditions. To define the flow order use the Flow order property of the Exclusive gateway node.

3.7. Script Evaluation

The Script task node is used to evaluate a script. The system analyzes the content of the Script property value. If the value is a valid file path and the file exists, then the script from the file will be executed, otherwise the Script field will be evaluated.

Note that you are allowed to use persistence and metadata objects for scripting.

3.8. Middleware Beans Methods Invocation

The Service task node is used to invoke a service method. Activiti engine is integrated with the Spring framework, so you can access middleware beans by their names. To invoke a managed bean method put the following expression to the Expression field:

${beanName.methodName(processVarName, 'someStringParam')}

You can use process variables as method arguments, including the variables automatically created on process start (entityId, bpmProcInstanceId, etc. as described in ProcessRuntimeService).

3.9. Completing a Task by Timer

To complete a task after a certain time interval, you should:

Add the Boundary timer event node to the task node.
Draw the flow from the timer node to the other required node.
Define an expression for the time interval in the Time duration property of the timer node. For example PT15M is an expression for 15 minutes interval.
Set the Cancel activity property to true. That will cancel the current task when the timer is fired.
In the Timer outcome property define the task outcome that should be used when the task is completed by the timer.

Defining an outcome for the timer

<boundaryEvent id="managerApprovalTimer" cancelActivity="true" attachedToRef="managerApproval">
    <extensionElements>
        <cuba:outcome>approve</cuba:outcome>
    </extensionElements>
</boundaryEvent>

By default, the Job executor for processing timers is disabled. To enable it, set an application property bpm.activiti.asyncExecutorEnabled = true.

3.10. Localization

A process may contain localized messages that are used to display task or outcomes in the user interface.

To open the localized messages editor, select the Localization property in the model properties panel.

To localize the task name, create a record with the task id as a key.

To localize the task outcome name, create a record with an expression like TASK_ID.OUTCOME_NAME as a key.

To localize the process role name, create a record with a role code as a key.

Localized messages

<process id="testProcess" name="Test process">
    <extensionElements>
        <cuba:localizations>
            <cuba:localization lang="en">
                <cuba:msg key="key1" value="value1"/>
                <cuba:msg key="key2" value="value2"/>
            </cuba:localization>
            <cuba:localization lang="ru">
                <cuba:msg key="key1" value="value1"/>
                <cuba:msg key="key2" value="value2"/>
            </cuba:localization>
      </cuba:localizations>
    </extensionElements>
</process>

3.11. Submodels

A Sub model node of the Structural group allows using an existing model as a part of a new model. While deploying a process submodel elements are being inserted to the current model, and a process XML is produced from the result of this concatenation.

3.12. Custom Elements in Model Designer

BPM subsystem allows creating custom elements for process model designer. Basically, a custom element is ServiceTask that saves the developer from the necessity of typing long expressions for method invocation, like this ${app_MyBean.someMethod(argument1, 'argument2')}. Below is an example of custom element creation.

Suppose, there is a middleware bean with the app_DiscountManager name. There is a makeDiscount(BigDecimal discountPercent, UUID entityId) method in the bean. The method updates the contract amount by subtracting the discount.

In this example, we will create a custom model element, that will invoke the method. The discount percent will be defined as a parameter of a model element.

Open the model elements editor with the menu item BPM → Model Elements Editor.

Click the Add group button and enter the group name - Discounts.

Select the created group and click the Add element button.

Enter the following values for element properties:

Title: Contract discount
Element ID: contractDiscount
Icon: click the Upload button and select the icon file (optional)
Bean name: select the app_DiscountManager
Method name: select the makeDiscount

Warning

The Bean name lookup contains only beans that implements an interface. The Method name lookup contains methods of implemented interfaces.

The Method arguments table will contain method arguments. You can change a caption and an argument default value.

Save the elements set by clicking the Save button.

Open the process model editor (BPM → Process Models). There are the Discounts group and the Contract discount element in the elements list. Drag and drop the new element to the model and select it. You’ll see that fields for discount percent and process variable name for entity identifier appeared.

Tip	`entityId` is a name of the process variable. This process variable is added automatically to each process that is linked to the entity. The variable stores an entity identifier, you can use it in any method calls.

During the process deployment a custom element will be transformed to a serviceTask:

<serviceTask id="sid-5C184F22-6071-45CD-AEA9-1792512BBDCE" name="Make discount" activiti:expression="${app_DiscountManager.makeDiscount(10,entityId)}"></serviceTask>

The elements can be exported to the ZIP archive and then restored from the archive. It may be useful when new elements are created on a developer’s machine and then imported to the production server. Import and export are performed with the corresponding buttons on the elements editor screen.

The Reset button removes all custom groups and elements and reverts the elements set to its initial state.

4. Main Services

The chapter contains only general description of the services. Detailed service methods description is available in Java classes documentation.

4.1. ProcessRepositoryService

It serves to work with process definitions. The service is used to:

load a process definition from XML
undeploy a process from Activiti engine
transform the JSON model to BPMN XML

To access the service functionality on middleware layer use the ProcessRepositoryManager bean.

4.2. ProcessRuntimeService

It serves to work with process instances. The service methods allows to:

start a process
cancel a process
complete a task
assign a task to the user

When a process is started the following process variables are automatically created:

bpmProcInstanceId - ProcInstance object ID
entityName - linked entity name
entityId - linked entity ID

To access the service functionality on middleware layer use the ProcessRuntimeManager bean.

4.3. ProcessFormService

The service is used to provide information about:

task outcomes
forms that should be displayed for outcomes
forms to appear on process start and cancel

To access the service functionality on middleware layer use the ProcessFormManager bean.

4.4. ProcessMessagesService

The service is used to access the localized messages which are defined in the process.

To access the service functionality on middleware layer use the ProcessMessagesManager bean.

4.5. ModelService

The service is used to create and update models in Activiti internal tables. Also it serves to work with the JSON representation of the model.

5. UI Components

5.1. ProcActionsFrame

The ProcActionsFrame is used for working 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 if the process is started and the current user has an active task
the cancel process button
the task information panel (name and creation date)

The predicative listener can be assigned to each of the process actions in order to check if the action can be performed (e.g. predicate commits an editor and if the commit failed, a process action is not performed). The post-action listener can also be defined (e.g. listener will close the editor and show the 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 starts. 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.

Other methods used for customizing the frame are described in the class javadoc.

5.2. Process forms

5.2.1. ProcForm Interface

When you declare user task outcomes or the start event node in the model editor it is possible to set a form that will be displayed to the user. The form should implement the ProcForm interface. The methods of the ProcForm interface:

String getComment() - returns the value that will be written to the comment field of the ProcTask object or to the startComment field of the ProcInstance if the form is displayed on a process start.
Map<String, Object> getFormResult() - returns a list of objects that will be added to process variables after the form commit.

5.2.2. A List of Forms for a Process Model Designer

A list of forms available in a process model designer is built according to the configuration files that are defined in a bpm.formsConfig application property. To add a new process form do the following:

Create and register a screen for the form. Screen controller must implement the ProcForm interface.
Create an XML file with custom forms description. Put it under the src directory of the web or the gui module.
app-bpm-forms.xml
```
<?xml version="1.0" encoding="UTF-8"?>
<forms xmlns="http://schemas.haulmont.com/cuba/bpm-forms.xsd">
    <form name="myCustomForm" defult="true">
        <param name="someParam" value="hello"/>
        <param name="otherParam"/>
    </form>
</forms>
```
myCustomForm is a screen id.

The above configuration also describes available form parameters with their names and default values.

A form with a default="true" attribute will be used as the default form in the model.
Override a bpm.formsConfig property in the web-app.properties file.
```
bpm.formsConfig = bpm-forms.xml app-bpm-forms.xml
```

Appendix A: Application properties

bpm.activiti.asyncJobExecutorEnabled: Possible values: true or false. Defines whether Job Executor for timers and asynchronous tasks is enabled. The default value is false.