Activiti Integration

This document shows how to write a new Activiti business process and how to integrate it into ArkCase.

Activiti business processes are based on the Business Process Modeling Notation (BPMN) standard.  ArkCase does use Alfresco’s extensions to this standard.  For extensive details, see the Activiti User Guide: https://www.activiti.org/userguide.

Write an Activiti Business Process

If you are an ArkCase administrator, you can create a new process by clicking the “Create New Model” button on the Admin / Workflows / Workflow Configuration page.  This button opens Alfresco’s Activiti Modeler in a new window.  If you are not an ArkCase administrator, you can open the same page yourself: https://activiti.alfresco.com/activiti-app.  Login with your Alfresco portal account.  If you don’t have an account on activiti.alfresco.com, or you prefer to use your own environment, you can download a Docker container from here: https://hub.docker.com/r/alfresco/process-services; from the instructions on this page, you can be up and running in just a few minutes.

After login you will be on this page:

Click on “App Designer”.  This is where you maintain your business process models.  You will see a list of your existing models, if any, like so:

From this page, click “Create Process” to start a new process; or “Import Process” to import an existing bpmn20.xml file you already have; or click on any of your existing processes.

For easy integration with ArkCase, you can use a restricted set of BPMN constructs.

• User tasks, assigned to specific ArkCase users
• Service tasks, for calling ArkCase Spring beans
• Exclusive gateways, to guide the path of the business process based on user actions.

ArkCase provides a set of process variables to every business process started from ArkCase. You can refer to these process variables in your task names, exclusive gateways, and Spring bean calls.

User Tasks

Set the assignee to a specific user name, a specific group name, or to a process variable (the process variables provided by ArkCase are described in a subsequent section).  Do not use Activiti’s user system.

The task name will appear in ArkCase.  You can use placeholders in the task name: “Review ${documentType}”.  The placeholder (in this example, “documentType”) is replaced by the corresponding process variable.

If the business process has to follow a certain path based on the outcome of this user task, then setup a process-level form variable with an enumeration of the possible outcomes.

How to Add an Enumeration Form Variable to a User Task

Click on Variables in the process metadata section at the bottom of the modeler window:

Click the + sign to add a variable:

You will see the following form:

• Variable name: This must end with “Outcome”.
• Variable type: choose string. It seems the modeler no longer lets you directly model enum values.  You will add the enum values in a later step, after you download the bpmn20.xml file.

Exclusive Gateways

To use exclusive gateways, first setup form variables with outcomes as described above.  Then, connect the user task to an exclusive gateway, and base the outgoing connectors from the exclusive gateway on the value of the outcome.  For example, connect a User Task with outcomes of “Accept” or “Reject” to an exclusive gateway, and from the exclusive gateway create a path for when the outcome is “Accept”, and another path for when the outcome is “Reject”, as shown below:

In the above process, the user task “Approver(s) Review Request” has an outcome variable.  The path that is followed from the exclusive gateway depends on the value of the outcome variable.

Service Tasks

Service tasks must call a Spring bean.  The bean must be in the core ArkCase application context, or in your ArkCase extension’s context if you are working on an extension.  All of the Spring beans are copied at startup time to a folder under the ArkCase user’s home folder.  A registry of available beans will be provided in a separate document.

To specify the Spring expression, click on the Expression field in the service task’s metadata panel, and enter a Spring Expression Language expression, like this:

#{arkCaseTranscribeService.notifyMultiple(IDS, ‘OWNER_OF_MEDIA’, ACTION)}

In the above, “IDS” and “ACTION” refer to process variables, which ArkCase provides to the business process.

Process Variables Provided by ArkCase

• approvers: a list of user names. In your process model, you can use this list to setup a sequential or parallel approval process.  This is what you will receive when your task is started from business rules.
• reviewers: a list of user names. In your process model, you can use this list to setup a sequential or parallel approval process.  This is what you will receive when your task is started from the doc-tree.
• candidateGroups: a list of group names, provided when the task is started from the doc tree. Use this value in the candidate groups field of your user tasks.
• assignee: the first task assignee; this is provided when the task is started from the doc tree. Use this value in the “assignee” field of your user tasks.
• taskName: for models with a single task, you can use this value as the task name. In this way a single generic model could serve many different business needs, if each such need only requires a different set of approvers (see “approvers” above) and task name.
• documentAuthor: the user who created the document which the process is attached to.
• pdfRenditionId: for processes started by forms submitted from the Frevvo forms engine, this is the document ID of the PDF rendition of the form.
• documentType: this is actually the title of the parent container; and not the document type at all.
• PARENT_OBJECT_NAME: name of the parent container (the case file, document repository, complaint, task).
• PARENT_OBJECT_TYPE: type of the parent container
• PARENT_OBJECT_ID: id of the parent container.
• OBJECT_NAME: name of the document which the process is attached to.
• taskDueDateExpression: an ISO date expression, representing when the tasks will be due. Use this value in the “dueDate” field of the user tasks in your process model.  Provided when the business process is started from business rules.
• dueDate: a specific date; provided when the process is started from the doc tree. Use this value in the “dueDate” field of the user tasks in your process model.
• taskPriority: numeric task priority; it should range from 1 to 100. Use this value in the “priority” field of the user tasks in your process model.

Add the New Business Process to ArkCase

From the Activiti modeler, close the visual design window, then open your model from the model list, and click the download button.  This will download a bpmn20.xml file to your local desktop.

If you need enumerated outcome variables to control the flow of the process, you must add them to the XML file yourself. Open the bpmn20.xml file in a text editor, and search for your form propery name (since it must end with “Outcome” it shouldn’t be hard to find).  Ensure the XML looks like this:

<userTask id=”approverReviewsDocument” name=”Review ${taskName}”

<extensionElements>

<activiti:formProperty id=”reviewOutcome” name=”Review Outcome” type=”enum” required=”true”>

                    <activiti:value id=”APPROVE” name=”Approve Document”></activiti:value>

                    <activiti:value id=”SEND_FOR_REWORK” name=”Send for Rework”></activiti:value>

                </activiti:formProperty>

</extensionElements>

<multiInstanceLoopCharacteristics isSequential=”false” activiti:collection=”reviewers”

activiti:elementVariable=”currentReviewer”>

<completionCondition>${ (nrOfCompletedInstances == nrOfInstances) || reviewOutcome == ‘SEND_FOR_REWORK’}

</completionCondition>

</multiInstanceLoopCharacteristics>

</userTask>

In the above example, the bold part is the critical part.  Make sure the formProperty id ends with “Outcome”.  Make sure the type is “enum”.  Add an “activiti:value” element for each enumerated value. The id (APPROVE and SEND_FOR_REWORK in the example) is what you will base your exclusive gateway paths on (follow one path for APPROVE, another path for SEND_FOR_REWORK).  The name (“Approve Document”, “Send for Rework”) is what will appear in the ArkCase user interface.

You must be an administrator to add the business process to ArkCase.  Open the Admin / Workflow / Workflow Configuration page.  Click the “Upload New BPMN” button, and select your bpmn20.xml file and provide a description.  After upload, your process should appear in the list of all the processes.

ArkCase UI Integration

The new process may be launched either on-demand from the doc-tree, or automatically whenever a document of a certain type is added to ArkCase.

On-demand From the Doc Tree

The administrator must add the process to the businessProcessTypes lookup:

1. Open the Admin / Application / Lookups Configuration page.
2. Under “Choose Lookup”, choose “businessProcessTypes”.
3. Click the + sign in the businessProcessTypes grid. The key must be the same value is the “id” attribute of your bpmn20.xml file’s “process” element.  For example, if your bpmn20.xml file has a process element like so: “<process id=”acmDocumentWorkflow” name=”ACM Document Approval Process” isExecutable=”true”>”, then the key must be “acmDocumentWorkflow”. The value will appear in the ArkCase user interface, and can be any text that makes sense.

After the businessProcessTypes lookup is modified, users can launch the process like so:

1. Open the case file, doc repository, complaint, task, or whichever container has the document you’re interested in
2. Expand the container doc tree until you find the document
3. Right click, “New Task”, then you will see this:

The select box under “Business Process Type” will show a list of the available business processes. These are the business processes defined in the businessProcessTypes lookup, as described above.

Automatically Whenever a Document of a Certain Type is Added

The administrator must configure the form business process rules.

Open the Admin / Form/Workflow Link / Link Forms/Workflows page.  Add a new line to the spreadsheet that should appear there.  You must set the value for “Is Buckslip Process” to true, whether or not it is actually a buckslip process.

After this, whenever a document of the selected type is added to ArkCase, the specified business process will be started.