☰
Navigation :

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 Atoti Sign-Off is set up, see General principles.

Objects to customize

In Atoti Sign-Off 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.

Signals

Signals are a way of notifying all running processes of an event. Atoti Sign-Off sends two types of signals:

  • SERVER_DOWN: this is sent when Atoti Sign-Off detects that an application server, such as MR or FRTB, has stopped responding. This signal is only sent to processes which relate to the particular application server that has stopped responding.
  • SERVER_UP: this is sent when Atoti Sign-Off detects that an application server, such as MR or FRTB, has recommenced responding. This signal is only sent to processes which relate to the particular application server that has recommenced responding.

Atoti Sign-Off detects changes to the status of application servers by polling at regular intervals. The characteristics of this polling can be configured through application properties specified in the application.yml file.

The three sample workflows respond to these signals. When they receive the SERVER_DOWN signal, if the task is in an INITIATED or PENDING state, it will be transitioned to an AWAIT_SERVER_RESTART state. This prevents changes being made until the server restarts. When the SERVER_UP signal is received, the task moves to the RE_APPLY_ADJUSTMENTS state and all previous adjustments are applied to the application server. Once this has been done the task transitions back to the INITIATED state.

Custom workflows can also listen for and respond to these signals. Please see the Activiti documentation for details on catching a signal.