The updateState() method of the ApprovalHelper bean will be invoked from the contract approval process for setting a 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();
        }
    }
}

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.

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

There are 2 types of actors participate in the process: a manager and a controller. Create 2 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 2 form parameters:

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 2 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 2 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 dropdown list Flow outcome 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 2 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 2 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.

The model deployment process consists of the following steps:

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. Change the Code field value to contractApproval. We will search the process definition object by this code later in this chapter.

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.gui.contract.ContractEdit"
        datasource="contractDs"
        focusComponent="fieldGroup"
        messagesPack="com.company.demo.gui.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">
            <iframe 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>
        <iframe 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.

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

ContractEdit.java. 

package com.company.demo.gui.contract;

import com.haulmont.bpm.entity.ProcDefinition;
import com.haulmont.bpm.entity.ProcInstance;
import com.haulmont.bpm.gui.action.ProcAction;
import com.haulmont.bpm.gui.procactions.ProcActionsFrame;
import com.haulmont.cuba.core.global.*;
import com.haulmont.cuba.gui.WindowManager;
import com.haulmont.cuba.gui.app.core.file.FileDownloadHelper;
import com.haulmont.cuba.gui.components.*;
import com.company.demo.entity.Contract;
import com.haulmont.cuba.gui.components.actions.BaseAction;
import com.haulmont.cuba.gui.data.DsContext;
import com.haulmont.cuba.gui.xml.layout.ComponentsFactory;

import javax.annotation.Nullable;
import javax.inject.Inject;
import java.util.Map;

public class ContractEdit extends AbstractEditor<Contract> {

    private static final String PROCESS_CODE = "contractApproval";

    @Inject
    private DataManager dataManager;

    private ProcDefinition procDefinition;

    private ProcInstance procInstance;

    @Inject
    private ProcActionsFrame procActionsFrame;

    @Inject
    private GroupBoxLayout procActionsBox;

    @Inject
    private ComponentsFactory componentsFactory;

    @Inject
    private Table attachmentsTable;

    @Inject
    private Metadata metadata;

    @Override
    protected void postInit() {
        super.postInit();
        procDefinition = findProcDefinition();
        if (procDefinition != null) {
            procInstance = findProcInstance();
            if (procInstance == null) {
                procInstance = metadata.create(ProcInstance.class);
                procInstance.setProcDefinition(procDefinition);
                procInstance.setEntityName("demo$Contract");
                procInstance.setEntityId(getItem().getId());
            }
            initProcActionsFrame();
        }
        getDsContext().addListener(new DsContext.CommitListenerAdapter() {
            @Override
            public void beforeCommit(CommitContext context) {
                if (procInstance != null && PersistenceHelper.isNew(procInstance)) {
                    context.getCommitInstances().add(procInstance);
                }
            }
        });
        FileDownloadHelper.initGeneratedColumn(attachmentsTable, "file");
    }

    private void initProcActionsFrame() {
        procActionsFrame.setBeforeStartProcessPredicate(new ProcAction.BeforeActionPredicate() {
            @Override
            public boolean evaluate() {
                if (PersistenceHelper.isNew(getItem())) {
                    showNotification(getMessage("saveContract"), NotificationType.WARNING);
                    return false;
                }
                return true;
            }
        });
        procActionsFrame.setAfterStartProcessListener(new ProcAction.AfterActionListener() {
            @Override
            public void actionCompleted() {
                showNotification(getMessage("processStarted"), NotificationType.HUMANIZED);
                close(COMMIT_ACTION_ID);
            }
        });
        procActionsFrame.setBeforeCompleteTaskPredicate(new ProcAction.BeforeActionPredicate() {
            @Override
            public boolean evaluate() {
                return commit();
            }
        });
        procActionsFrame.setAfterCompleteTaskListener(new ProcAction.AfterActionListener() {
            @Override
            public void actionCompleted() {
                showNotification(getMessage("taskCompleted"), NotificationType.HUMANIZED);
                close(COMMIT_ACTION_ID);
            }
        });
        procActionsFrame.setCancelProcessEnabled(false);
        procActionsFrame.init(procInstance);
    }


    @Nullable
    private ProcDefinition findProcDefinition() {
        LoadContext ctx = new LoadContext(ProcDefinition.class);
        ctx.setQueryString("select pd from bpm$ProcDefinition pd where pd.code = :code")
                .setParameter("code", PROCESS_CODE);
        return dataManager.load(ctx);
    }

    @Nullable
    private ProcInstance findProcInstance() {
        LoadContext ctx = new LoadContext(ProcInstance.class).setView("procInstance-start");
        ctx.setQueryString("select pi from bpm$ProcInstance pi where pi.procDefinition.id = :procDefinition and pi.entityId = :entityId")
                .setParameter("procDefinition", procDefinition)
                .setParameter("entityId", getItem());
        return dataManager.load(ctx);
    }
}

Press OK to save the changes.

Let’s examine the controller code in details.

To start the process, we have to create an instance of the process (ProcInstance object), link it to a process definition (ProcDefinition object), and perform start. The process instance can be started both without a link to any project entity and with this link. In our case a link to the contract is mandatory.

In the beginning of the postInit() method an instance of contract approval process is searched by findProcDefinition() method, which searches for a process definition with the contractApproval code. Next, there is a check whether a ProcInstance object linked with the contract exists in the database (findProcInstance() method). If the process instance object doesn’t exist, then it is created, the relation to ProcDefinition is set, and a linked entity name and identifier are filled.

if (procInstance == null) {
    procInstance = metadata.create(ProcInstance.class);
    procInstance.setProcDefinition(procDefinition);
    procInstance.setEntityName("demo$Contract");
    procInstance.setEntityId(getItem().getId());
}

CommitListener adds the created ProcInstance object to the list of entities that will be sent to the middleware for be committed.

getDsContext().addListener(new DsContext.CommitListenerAdapter() {
    @Override
    public void beforeCommit(CommitContext context) {
        if (procInstance != null && PersistenceHelper.isNew(procInstance)) {
            context.getCommitInstances().add(procInstance);
        }
    }
});

Next, go to the initProcActionsFrame() method.

A ProcActionsFrame is a standard frame displaying the buttons with available process actions. ProcActionsFrame is linked with a ProcInstance instance. If the process is not started yet, the frame will display the start process button. If the process is started and there are active tasks for the current user, then the frame will display buttons for task completion according to the task outcomes defined in the process model. For the detailed information about ProcActionsFrame see Section 6.1, “ProcActionsFrame”.

private void initProcActionsFrame() {
    procActionsFrame.setBeforeStartProcessPredicate(new ProcAction.BeforeActionPredicate() {
        @Override
        public boolean evaluate() {
            if (PersistenceHelper.isNew(getItem())) {
                showNotification(getMessage("saveContract"), NotificationType.WARNING);
                return false;
            }
            return true;
        }
    });
    procActionsFrame.setAfterStartProcessListener(new ProcAction.AfterActionListener() {
        @Override
        public void actionCompleted() {
            showNotification(getMessage("processStarted"), NotificationType.HUMANIZED);
            close(COMMIT_ACTION_ID);
        }
    });
    procActionsFrame.setBeforeCompleteTaskPredicate(new ProcAction.BeforeActionPredicate() {
        @Override
        public boolean evaluate() {
            return commit();
        }
    });
    procActionsFrame.setAfterCompleteTaskListener(new ProcAction.AfterActionListener() {
        @Override
        public void actionCompleted() {
            showNotification(getMessage("taskCompleted"), NotificationType.HUMANIZED);
            close(COMMIT_ACTION_ID);
        }
    });
    procActionsFrame.setCancelProcessEnabled(false);
    procActionsFrame.init(procInstance);
}

The procActionsFrame.setBeforeStartProcessPredicate() method adds the check that is performed before the process start. If the contract is not saved yet, the process will not start and the warning message will be shown.

The procActionsFrame.setBeforeCompleteTaskPredicate() method invokes an editor commit and allows to complete a process action only if the editor commit was successful.

setAfterProcessStartListener and setAfterCompleteTaskListener methods will be invoked after corresponding events. They will show the notification and close the contract editor.

After all necessary listeners and predicates are set up, the initialization frame is invoked.

procActionsFrame.init(procInstance);

UI components are created during the frame initialization.

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

messages.properties
browseCaption = Contract browser
editCaption = Contract editor
attachments = Attachments
process = Contract approval
saveContract = Save the contract before starting a process
processStarted = Process started
taskCompleted = Task completed

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

Log in as norman.

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.

Wee see that the user norman has one uncompleted task Validation of the Contract approval process. Select it and click the Open process instance button. The following screen will appear:

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. We will complete a process task in another way - using procActionsFrame that we added earlier to the contract editor.

Close the Process Instance Edit screen and open the contract instance.

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 2 possible outcomes: Valid and Not valid. That’s why 2 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.

Log in as the pierce user.

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

Open the Process Instance Editor.

Pay attention to the Tasks table. The previous task Validation has been completed with the Valid outcome, and 2 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.

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

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.

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:

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.

bpm-forms.xml example. 

<?xml version="1.0" encoding="UTF-8"?>

<forms xmlns="http://schemas.haulmont.com/cuba/5.5/bpm-forms.xsd">
    <form name="standardProcForm" default="true">
        <param name="commentRequired" value="true"/>
        <param name="procActorsVisible" value="true"/>
        <param name="attachmentsVisible" value="true"/>
    </form>
    <form name="otherForm">
        <param name="someParam" value="hello"/>
    </form>
</forms>

The above 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.