Configure escalation flows based on predefined criteria
The objective of this functionality is to provide a mechanism to trigger action on applications which satisfy certain predefined criteria.
Looking at sample use cases provided by the product team, the majority of use cases can be summarised as performing action ‘X’ on applications in state ‘Y’ and have exceeded the state SLA by ‘Z’ days. We can write one query builder which takes this state ‘Y’ and SLA exceeded by ‘Z’ as search params and then we can perform action X on the search response. This has been achieved by defining an MDMS config like below:
In the above configuration, we define the condition for triggering the escalation of applications. The above configuration triggers escalation for applications in RESOLVED state which have exceeded stateSLA by more than 1.0 day and this triggers the escalation by performing CLOSERESOLVEDCOMPLAIN on the applications. Once the applications are escalated the processInstances are pushed on the pgr-auto-escalation topic. We have done a sample implementation for pgr-services, where we have updated the persister configuration to listen on this topic and update the complaint status accordingly.
The auto escalation for businessService PGR will be triggered when the following API is called:
Note: The businessService is a path param. (For example, if the escalation has to be done for tl-services NewTL workflow the URL will be 'http://egov-workflow-v2.egov:8080/egov-workflow-v2/egov-wf/auto/NewTL/_escalate').
These APIs have to be configured in the cron job config so that they can be triggered periodically as per requirements. Only the user with the role permission AUTO_ESCALATE can trigger auto escalations. Hence, create the user with statelevel AUTO_ESCALATE role permission and then add that user in the userInfo of the requestInfo. This step has to be done because the cron job does internal API calls and ZUUL will not enrich the userInfo.
For setting up an auto-escalation trigger, the workflow must be updated. For example, to add an auto escalate trigger on RESOLVED state with action CLOSERESOLVEDCOMPLAIN in PGR businessService, we will have to search the businessService and add the following action in the actions array of RESOLVED state and call update API.
Suppose an application gets auto-escalated from state ‘X' to state 'Y’, employees can look at these escalated applications through the escalate search API. The following sample cURL can be used to search auto-escalated applications of the PGR module belonging to Amritsar tenant -
Deploy workflow 2.0 in an environment where workflow is already running
In workflow 2.0 assignee is changed from an object to a list of objects.
To accommodate this change a new table named 'eg_wf_assignee_v2' is added that maps the processInstaceIds to assignee UUIDs. To deploy workflow 2.0 in an environment where workflow is already running assignee column needs to be migrated to the eg_wf_assignee_v2 table.
The following query does this migration:
Persister config for egov-workflow-v2 is updated. Insert query for the table eg_wf_assignee_v2 is added in egov-workflow-v2-persister.yml.
The latest updated config can be referred to from the below link:
The employee inbox has an added column to display the locality of the applications. This mapping of the application number to locality is fetched by calling the searcher API for the respective module. If a new module is integrated with workflow its searcher config should be added in the locality searcher yaml with module code as a name in the definition. All the search URLs and role action mapping details must be added to the MDMS.
The format of the URL is given below:
Sample request for TL:
The searcher yaml can be referred from the below link:
For sending back the application to citizens, the action with the key 'SENDBACKTOCITIZEN' must be added. The exact key should be used. The resultant state of the action should be a new state. If pointing to an existing state the action in that state will be visible to the CITIZEN even when the application reaches the state without Send Back as the workflow is role-based.
To update the businessService for Send Back feature, add the following state and action in the search response at required places and add call businessService update API. This assigns the UUID to the new state and action and creates the required references. The Resubmit action is added as optional action for counter employees to take action on behalf of the citizen.
State json:
Action json:
Each item in the above dropdown is displayed by adding an object in the link below -
For example:
{
"id": 1928,
"name": "rainmaker-common-tradelicence",
"url": "quickAction",
"displayName": "Search TL",
"orderNumber": 2,
"parentModule": "",
"enabled": true,
"serviceCode": "",
"code": "",
"path": "",
"navigationURL": "tradelicence/search",
"leftIcon": "places:business-center",
"rightIcon": "",
"queryParams": ""
}
id , url, displayName, navigationURL
Mandatory properties.
The value of the URL property should be “quickAction” as shown above.
Accordingly, add the role-actions:
{
"rolecode": "TL_CEMP",
"actionid": 1928,
"actioncode": "",
"tenantId": "pb"
}
SLA slots and the background colour of the SLA days remaining on the Inbox page are defined in the MDMS configuration as shown above.
For example: If the maximum SLA is 30 then, it has 3 slots
30 - 30*(1/3) => 20 - 30: will have green colour defined
0 - 20: will have yellow colour defined
<0: will have red colour defined
The colours are also configured in the MDMS.
For API /egov-workflow-v2/egov-wf/process/_transition: The field assignee of type User in ProcessInstance object is changed to a list of 'User' called assignees. User assignee --> List<User> assignees
For Citizen Sendback: When the action SENDBACKTOCITIZEN is called on the entity the module has to enrich the assignees with the UUIDs of the owners and creator of the entity.
Create and modify workflow configuration
Each service integrated with egov-workflow-v2 service needs to first define the workflow configuration which describes the workflow states, the action that can be taken on these states, the user roles that can perform those actions, SLAs etc. This configuration is created using APIs and is stored in the DB. The configuration can be created at either the state level or the tenant level based on the requirements.
Before you proceed with the configuration, make sure the following pre-requisites are met -
egov-workflow-v2 service is up and running
Role action mapping is added for the BusinessService APIs
Create and modify workflow configuration
Configure state level as well BusinessService level SLA
Control access to workflow actions from the configuration
Validates if the flow defined in the configuration is complete during the creation
Deploy the latest version of egov-workflow-v2 service.
Add role action mapping for BusinessService APIs (preferably add _create and update only for SUPERUSER. Search can be added for CITIZEN and required employee roles like TL__CEMP etc.
Overwrite the egov.wf.statelevel flag (true for state level and false for tenant level).
Add businessService persister yaml path in persister configuration.
Create the businessService JSON based on product requirements. Following is a sample json of a simple 2-step workflow where an application can be applied by a citizen or counter employee and then can be either rejected or approved by the approver.
Once the businessService json is created add it in the request body of _create API of workflow and call the API to create the workflow.
To update the workflow first search the workflow object using _search API and then make changes in the businessService object and then call _update using the modified search result.
States cannot be removed using _update API as it will leave applications in that state in an invalid state. In such cases first, all the applications in that state should be moved forward or backward state and then the state should be disabled through DB directly.
The workflow configuration can be used by any module which performs a sequence of operations on an application/entity. It can be used to simulate and track processes in organisations to make them more efficient and increase accountability.
Integrating with workflow service provides a way to have a dynamic workflow configuration which can be easily modified according to the changing requirements. The modules don’t have to deal with any validations regarding workflow such as authorisation of the user to take an action if documents are required to be uploaded at a certain stage etc. since it will be automatically handled by egov-workflow-v2 service based on the defined configuration. It also automatically keeps updating SLAs for all applications which provide a way to track the time taken by an application to get processed.
To integrate, the host of egov-workflow-v2 should be overwritten in the helm chart
/egov-workflow-v2/egov-wf/businessservice/_search should be added as the endpoint for searching workflow configuration. (Other endpoints are not required once workflow configuration is created)
The configuration can be fetched by calling _search API
Note: All the APIs are in the same Postman collection therefore the same link is added in each row.
Configure workflows for a new product
Workflow is defined as a sequence of tasks that has to be performed on an application/Entity to process it. The egov-workflow-v2 is a workflow engine which helps in performing these operations seamlessly using a predefined configuration. We will discuss how to create this configuration for a new product in this document.
Before you proceed with the configuration, make sure the following pre-requisites are met -
egov-workflow-v2 service is up and running
Role action mapping is added for business service APIs
Create and modify workflow configuration according to the product requirements
Configure State level as well BusinessService level SLA to efficiently track the progress of the application
Control access to perform actions through configuration
| Attributes | Description |
|---|---|
Deploy the latest version of the egov-workflow-v2 service.
Add businessService persister yaml path in persister configuration.
Add role action mapping for BusinessService APIs.
Overwrite the egov.wf.statelevel flag (true for state level and false for tenant level).
The Workflow configuration has 3 levels of hierarchy:
BusinessService
State
Action
The top-level object is BusinessService which contains fields describing the workflow and a list of States that are part of the workflow. The businessService can be defined at the tenant level like pb.amritsar or at the state level like pb. All objects maintain an audit sub-object which keeps track of who is creating and updating and the time of it.
Each state object is a valid status for the application. The State object contains information about the state and what actions can be performed on it.
The action object is the last object in the hierarchy, it defines the name of the action and the roles that can perform the action.
The workflow should always start from the null state as the service treats new applications as having null as the initial state. eg:
In the action object whatever nextState is defined, the application will be sent to that state. It can be to another forward state or even some backward state from where the application has already passed (generally, such actions are named SENDBACK)
SENDBACKTOCITIZEN is a special keyword for an action name. This action sends back the application to the citizen’s inbox for him to take action. A new State should be created on which Citizen can take action and should be the nextState of this action. While calling this action from the module assignees should be enriched by the module with the UUIDs of the owners of the application
For integration-related steps, refer to the document Setting Up Workflows.
Note: All the APIs are in the same Postman collection therefore the same link is added in each row.
Configure workflows as per requirements
Workflows are a series of steps that moves a process from one state to another state by actions performed by different kind of Actors - Humans, Machines, Time based events etc. to achieve a goal like onboarding an employee, or approve an application or granting a resource etc. The egov-workflow-v2 is a workflow engine which helps in performing these operations seamlessly using a predefined configuration.
Before you proceed with the documentation, make sure the following pre-requisites are met -
Java 17
Kafka server is up and running
service is running and has a yml added yo .
PostgreSQL server is running and a database is created to store workflow configuration and data
Always allow anyone with a role in the workflow state machine to view the workflow instances and comment on it
On the creation of workflow, it will appear in the inbox of all employees that have roles that can perform any state transitioning actions in this state.
Once an instance is marked to an individual employee it will appear only in that employee's inbox although point 1 will still hold true and all others participating in the workflow can still search it and act if they have the necessary action available to them
If the instance is marked to a person who cannot perform any state transitioning action, they can still comment/upload and mark to anyone else.
Overall SLA: SLA for the complete processing of the application/Entity
State-level SLA: SLA for a particular state in the workflow
Add BusinessService Persister YAML path in persister configuration
Add Role-Action mapping for BusinessService APIs
Overwrite the egov.wf.statelevel flag ( true for state level and false for tenant level)
Create businessService (workflow configuration) according to product requirements
Add Role-Action mapping for /processInstance/_search API
Add workflow persister yaml path in persister configuration
The workflow configuration can be used by any module which performs a sequence of operations on an application/Entity. It can be used to simulate and track processes in organisations to make it more efficient too and increase accountability.
Role-based workflow
An easy way of writing rule
File movement within workflow roles
To integrate, the host of eGov-workflow-v2 should be overwritten in the helm chart.
/process/_search should be added as the search endpoint for searching workflow process Instance objects.
/process/_transition should be added to perform an action on an application. (It’s for internal use in modules and should not be added in Role-Action mapping).
The workflow configuration can be fetched by calling _search API to check if data can be updated or not in the current state.
Note: All the APIs are in the same Postman collection therefore the same link is added in each row.
| Title |
|---|
| Title |
|---|
| Title |
|---|
| Title |
|---|
| Environment Variables | Description |
|---|
the latest version of eGov-workflow-V2 service
Note: This video will give you an idea of how to deploy any Digit-service. Further you can find the latest builds for each service in out latest here.
For configuration details, refer to the links in .
| Title |
|---|
| Title |
|---|
tenantId
The tenantId (ULB code) for which the workflow configuration is defined
businessService
The name of the workflow
business
The name of the module which uses this workflow configuration
businessServiceSla
The overall SLA to process the application (in milliseconds)
state
Name of the state
applicationStatus
Status of the application when in the given state
docUploadRequired
Boolean flag representing if document are required to enter the state
isStartState
Boolean flag representing if the state can be used as starting state in workflow
isTerminateState
Boolean flag representing if the state is the leaf node or end state in the workflow configuration. (No Actions can be taken on states with this flag as true)
isStateUpdatable
Boolean flag representing whether data can be updated in the application when taking action on the state
currentState
The current state on which action can be performed
nextState
The resultant state after action is performed
roles
A list containing the roles which can perform the actions
auditDetails
Contains fields to audit edits on the data. (createdTime, createdBy,lastModifiedTIme,lastModifiedby)
egov.wf.default.offset | The default value of offset in search |
egov.wf.default.limit | The default value of limit in search |
egov.wf.max.limit | The maximum number of records that are returned in search response |
egov.wf.inbox.assignedonly | Boolean flag if set to true default search will return records assigned to the user only, if false it will return all the records based on the user’s role. (default search is the search call when no query params are sent and based on the RequestInfo of the call, records are returned, it’s used to show applications in employee inbox) |
egov.wf.statelevel | Boolean flag set to true if a state-level workflow is required |
