Customizing sign-off backend
This page describes how to customize the workflows for managing the sign-off process definition and sign-off process instances.
note
For any customizations made in the sign-off logic, the corresponding modifications must be made in the UI. For more information, see Customizing sign-off workflow UI
For a description of how the Sign-Off Module is set up, 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.
The file is stored in the delivered source code, in /src/main/resources/processes
| 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 See Example: Setting which roles can create tasks 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. |
Example: Setting which roles can create tasks
In the default implementation, only those with the MANAGERS role can create and publish tasks. To change this configuration, set the role(s) as the value of the candidateGroups attribute in the following lines:
<userTask id="create.saved" name="SAVED" activiti:candidateGroups="USERS, MANAGERS"/>
….
<userTask id="published" name="PUBLISHED" activiti:candidateGroups="USERS, MANAGERS"/>
The roles are as defined in the SignOffSettings.ts and SecurityConfig.java configuration files.
In this example, both USERS and MANAGERS roles can create and publish tasks.
For details on the candidateGroups attribute, see the Activiti documentation.
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).
note
Tasks that can be automatically performed must have the correct permissioning definition in Activiti.
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.