Customizing sign-off backend

This page describes how to customize the workflows for managing the sign-off process definition and sign-off process instances.

For a description of how the Sign-Off Module is setup, see General principles.

Objects to customize

In the sign-off module there are two types of objects being managed:

• Sign Off Process Definition
• Sign Off Process Instance

Sign-Off Process Definition

The workflows for managing the sign-off process definitions may not need to be customized, with the default workflows being sufficient for simple use. There are four workflows included in sign-off-process-definition.bpmn, these can be used as examples and adapted as needed.

Workflow	Details
Create	This workflow is used when creating a new sign-off process definition in the UI. It allows saving the object until it is ready to be published. It can be used through the following methods in the workflows service: create: start the workflow process instance save/publish/delete: perform a user action Additionally, the workflow uses the signOffProcessDefinitionCreate bean to perform the object creation in persistent storage.
Update	This workflow is used when updating an existing (published) sign-off process definition in the UI. It only uses the update method to start the workflow, there are no other user steps in the workflow. Additionally, the workflow uses the signOffProcessDefinitionUpdate bean to perform the update task in persistence storage.
Delete	This workflow is used when deleting or archiving an existing (published) sign-off process definition. It only uses the archive method to start the workflow, there are no other user steps in the workflow. Additionally, the workflow uses the signOffProcessDefinitionDelete bean to perform the update task in persistence storage.
Import	This workflow is used when uploading a CSV file containing multiple sign-off process definitions. In the upload method, an instance of the workflow is created for each line in the CSV file. There are no other user steps in the workflow. Additionally, the workflow uses the signOffProcessDefinitionImport bean to perform the update task in persistence storage.

Sign-Off Process Instance

The workflows for managing the sign-off process instances are precisely the workflows for performing the sign-off. There are three sample workflows for this:

• simple in sign-off-process-simple.bpmn

• 4-eyes in sign-off-process-four-eyes.bpmn

• 4-eyes-kpi in sign-off-process-four-eyes.bpmn

The names simple, 4-eyes, and 4-eyes-kpi can be used in the Workflow Type field of the sign-off process definition objects. These are connected to the process definition name in the .bpmn file using the sign-off.workflow-types map in application.yml, new workflows can be added here. For more information, see the configuration file application.yml

The two workflows are both started using the initiate() method in SignOffProcesInstanceWorkflowService. This determines the workflow type, and hence process definition name, from the sign-off process definition object, and starts the appropriate workflow.

Additionally, the initiate() method will add workflow parameters – for example, lists of users – from the sign-off process definition object to the workflow as variables. These variables are then available for use in the workflow process instance.

The 4-eyes-kpi workflow is a sample workflow illustrating how automated approval can be done using KPIs provided.

The workflow is identical to the 4-eyes workflow, except for the fact that at the initiation of the sign-off task, the statuses of the KPIs defined in the sign-off task are retrieved from the application server. If the status of all those KPIs is 1 (i.e. green), the sign-off task is automatically approved without the intervention of the manager user.

In order to retrieve the KPIs from the application server, a REST call is used: IApplicationSignOff.fetchKPIs. That REST call needs to be added to the application server as part of the project-specific implementation tasks.

The data retrieved via the call to IApplicationSignOff.fetchKPIs are processed to determine whether the sign-off tasks should be automatically approved or not. In the sample implementation, the sign-off task is automatically approved if the statuses of all the KPIs present in the definition of the sign-off tasks are equal to 1 (i.e. the statuses are all green).

Event Listeners

Activiti event listeners are registered using Spring beans. The class SignOffProcessEventHandlers contains a couple of examples.

Notification Email

The Spring bean taskCreatedListener in SignOffProcessEventHandlers can be used to send notification emails. The method onTaskCreatedEvent() will need to be updated to send the emails, currently this method is called whenever the workflow process instance enters a user task. It then extracts relevant information about the task, including:

• Which users and groups can execute the task
• Information about the task
• The object being managed by the workflow
• The status of the workflow process instance

This information can then be sent to the user. However, this will require customizations similar to the following:

• Convert the Spring users and groups into email addresses.
• Use a template to construct the email (subject and body) from the information collected.
• Connect to an email server to send the email.