Overview

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.

Pre-requisites

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

Key Functionalities

• 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

Deployment Details

1. Deploy the latest version of egov-workflow-v2 service.

2. 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.

3. Overwrite the egov.wf.statelevel flag (true for state level and false for tenant level).

4. Add businessService persister yaml path in persister configuration.

Configuration Details

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.

{
      "tenantId": "pb",
      "businessService": "PGR",
      "business": "pgr-services",
      "businessServiceSla": 432000000,
      "states": [
        {
          "sla": null,
          "state": null,
          "applicationStatus": null,
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "isStateUpdatable": true,
          "actions": [
            {
              "action": "APPLY",
              "nextState": "PENDINGFORASSIGNMENT",
              "roles": [
                "CITIZEN",
                "COUNTER_EMPLOYEE"
              ]
            }
          ]
        },
        {
          "sla": null,
          "state": "APPLIED",
          "applicationStatus": "APPLIED",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": false,
          "isStateUpdatable": false,
          "actions": [
            {
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "APPROVER"
              ]
            },
            {
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "APPROVER"
              ]
            }
          ]
        },
        {
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "REJECTED",
          "isStateUpdatable": false,
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true
        },
        {
          "sla": null,
          "state": "APPROVED",
          "applicationStatus": "APPROVED",
          "isStateUpdatable": false,
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true
        }
      ]
    }

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.

Integration Details

Integration Scope

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.

Integration Benefits

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.

Integration Steps

1. To integrate, the host of egov-workflow-v2 should be overwritten in the helm chart

2. /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)

3. The configuration can be fetched by calling _search API

Reference Docs

Doc Links

API List

Overview

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.

Pre-requisites

Before you proceed with the documentation, make sure the following pre-requisites are met -

• Java 8

• Kafka server is up and running

• egov-persister service is running and has a workflow persister config path added to it

• PSQL server is running and a database is created to store workflow configuration and data

Key Functionalities

• 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

Interaction Diagram

Deployment Details

1. Deploy the latest version of egov-workflow-v2 service

2. Add businessService persister yaml path in persister configuration

3. Add Role-Action mapping for BusinessService APIs

4. Overwrite the egov.wf.statelevel flag ( true for state level and false for tenant level)

5. Create businessService (workflow configuration) according to product requirements

6. Add Role-Action mapping for /processInstance/_search API

7. Add workflow persister yaml path in persister configuration

Configuration Details

Integration Details

Integration Scope

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.

Integration Benefits

• Role-based workflow

• An easy way of writing rule

• File movement within workflow roles

Integration Steps

1. To integrate, the host of egov-workflow-v2 should be overwritten in the helm chart.

2. /process/_search should be added as the search endpoint for searching workflow process Instance objects.

3. /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).

4. The workflow configuration can be fetched by calling _search API to check if data can be updated or not in the current state.

Reference Docs

Doc Links

API List

Overview

User service is responsible for user data management and providing functionality to login and logout into the DIGIT system

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

• Java 8

• The Kafka server is up and running

• Encryption and MDMS services are running

• PSQL server is running

• The Redis database is running

Key Functionalities

• Store, update and search user data

• Provide authentication

• Provide login and logout functionality into the DIGIT platform

• Store user data PIIs in encrypted form

Interaction Diagram

Deployment Details

1. Setup the latest version of egov-enc-service and egov-mdms- service

2. Deploy the latest version of egov-user service

3. Add role-action mapping for APIs

Configuration Details

The following application properties file in user service are configurable.

Integration Details

Integration Scope

User data management and functionality to log in and log out into the DIGIT system using OTP and password.

Integration Benefits

Providing the following functionalities to citizen and employee-type users

Employee:

• User registration

• Search user

• Update user details

• Forgot password

• Change password

• User role mapping(Single ULB to multiple roles)

• Enable employees to login into the DIGIT system based on a password.

Citizen:

• Create user

• Update user

• Search user

• User registration using OTP

• OTP based login

Integration Steps

• To integrate, the host of egov-user should be overwritten in the helm chart.

• Use /citizen/_create endpoint for creating users into the system. This endpoint requires the user to validate his mobile number using OTP. First, the OTP is sent to the user's mobile number and then the OTP is sent as otpReference in the request body.

• Use /v1/_search and /_search endpoints to search users in the system depending on various search parameters.

• Use /profile/_update for updating the user profile. The user is validated (either through OTP-based validation or password validation) when this API is called.

• /users/_createnovalidate and /users/_updatenovalidate are endpoints to create user data into the system without any validations (no OTP or password required). They should be strictly used only for creating/updating users internally and should not be exposed outside.

• Forgot password: In case the user forgets the password it can be reset by first calling /user-otp/v1/_send which generates and sends OTP to the employee’s mobile number. The password is then updated using this OTP by calling the API /password/nologin/_update in which a new password along with the OTP is sent.

• Use /password/_update to update the existing password by logging in. Both old and new passwords are sent to the request body. Details of the API can be found in the attached swagger documentation.

• Use /user/oauth/token for generating tokens, /_logoutfor logout and /_details for getting user information from the token.

• Multi-Tenant User: The multi-tenant user functionality allows users to perform actions across multiple ULBs. For example, employees belonging to Amritsar can perform the role of say Trade License Approver for Jalandhar by assigning them the tenant-level role of tenantId pb.jalandhar.

• Following is an example of the user:

If an employee has a role with statelevel tenantId they can perform actions corresponding to that role across all tenants.

• Refresh Token: Whenever the /user/oauth/token is called to generate the access_token along with access_token, one more token is generated called refresh_token . The refresh token is used to generate a new access_token whenever the existing one expires. Till the time the refresh token is valid, users will not have to log in even if their access_token expires since this is generated using refresh_token. The validity time of the refresh token is configurable and can be configured using the property: refresh.token.validity.in.minutes

User Data Privacy

MDM Configuration For Security Policy

There are two security policy models for user data - User and UserSelf.

In model User, the field attributes contains a list of fields from the user object that needs to be secured and the field roleBasedDecryptionPolicy is an attribute-level role-based policy. It defines visibility for each attribute.

UserSelf model contains the same structure of security policy but the User security model is used for Search API response and UserSelf is used for Create/Update API response.

The visibility of the PII data is based on the above MDMS configuration. There are three types of visibility mentioned in the config.

1. PLAIN - Show text in plain form.

2. MASKED - The returned text contains masked data. The masking pattern is applied as defined in the Masking Patterns master data.

3. NONE - The returned text does not contain any data. It contains strings like “Confidential Information”.

Plain Access Request

Any user can get plain access to the secured data (citizen’s PII) by requesting through the plainAccessRequest parameter. It takes the following parameters:

1. recordId - It is the unique identifier of the record that is requested for plain access.

2. fields - It defines a list of attributes that are requested for plain access.

Reference Docs

Doc Links

API List

Overview

DIGIT is an API-based platform where each API denotes a DIGIT resource. The primary job of Access Control Service (ACS) is to authorise end-user based on their roles and provide access to the DIGIT platform resources. Access control functionality is essentially based on below points:

Actions: Actions are events which are performed by a user. This can be an API end-point or front-end event. This is the MDMS master.

Roles: Roles are assigned to users. A single user can hold multiple roles. Roles are defined in MDMS masters.

Role-Action: Role actions are mapped between Actions and Roles. Based on roles, the action mapping access control service identifies applicable actions for the role.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

• Java 8

• MDMS service is up and running

Key Functionalities

• Serve the applicable actions for a user based on user roles (To print menu three).

• On each action performed by a user, access control looks at the roles for the user and validates actions mapping with the role.

• Support tenant-level role action - For instance, an employee from Amritsar can have the role of APPROVER for other ULBs like Jalandhar and hence will be authorised to act as APPROVER in Jalandhar.

Deployment Details

1. Deploy the latest version of the Access Control Service

2. Deploy MDMS service to fetch the Role Action Mappings

Configuration Details

Define the roles:

Add the actions (URL)

Add the role action mapping

Integration Details

Integration Scope

Any microservice which requires authorisation can leverage the functionalities provided by the access control service.

Integration Benefits

Any new microservice that is to be added to the platform will not have to worry about authorisation. It can just add its role action mapping in the master data and the Access Control Service will perform authorisation whenever the API for the microservice is called.

Integration Steps

1. To integrate with Access Control Service the role action mapping has to be configured (added) in the MDMS service.

2. The service needs to call /actions/_authorize API of Access Control Service to check for authorisation of any request.

Interaction Diagram

Reference Docs

Doc Links

API List

Overview

The objective of the PDF generation service is to bulk generate pdf as per requirement.

Pre-requisites

Before proceeding with the documentation, ensure the following prerequisites are met:

1. Install npm

2. Ensure the Kafka server is operational

3. Confirm that the egov-persister service is running and configured with a pdf generation persister path

4. Verify that the PostgreSQL (PSQL) server is running, and a database is created to store filestore IDs and job IDs of generated PDFs

Key Functionalities

• Provide a common framework to generate PDFs

• Provide flexibility to customise the PDF as per the requirement

• Provide functionality to add an image or QR code in a PDF

• Provide functionality to generate PDFs in bulk

• Provide functionality to specify the maximum number of records to be written in one PDF

External libraries used :

Interaction Diagram

Deployment Details

1. Create data config and format config for a PDF according to product requirements.

2. Add data config and format config files in PDF configuration.

3. Add the file path of data and format config in the environment yaml file.

4. Deploy the latest version of pdf-service in a particular environment.

Configuration Details

Integration Details

Integration Scope

The PDF configuration can be used by any module which needs to show particular information in PDF format that can be printed/downloaded by the user.

Integration Benefits

• Functionality to generate PDFs in bulk.

• Avoid regeneration.

• Support QR codes and Images.

• Functionality to specify the maximum number of records to be written in one PDF.

• Uploading generated PDF to filestore and return filestore id for easy access.

Integration Steps

To download and print the required PDF _create API has to be called with the required key (For Integration with UI, please refer to the links in Reference Docs)

Reference Docs

Doc Links

API List

Overview

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.

Pre-requisites

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

Key Functionalities

• 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

Deployment Details

1. Deploy the latest version of the egov-workflow-v2 service.

2. Add businessService persister yaml path in persister configuration.

3. Add role action mapping for BusinessService APIs.

4. Overwrite the egov.wf.statelevel flag (true for state level and false for tenant level).

Configuration Details

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

Integration Details

Reference Docs

Doc Links

API List

Overview

The objective of this functionality is to provide a mechanism to trigger action on applications which satisfy certain predefined criteria.

Configuration Details

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:

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 -

Overview

A core application that provides location details of the tenant for which the services are being provided.

Pre-requisites

Before you proceed with the documentation, make sure the following pre-requisites are met -

• Java 8

• PSQL server is running and the database is created

• Knowledge of egov-mdms service

• egov-mdms service is running and all the required MDMS masters are loaded in it

Key Functionalities

• The location information is also known as the boundary data of ULB

• Boundary data can be of different hierarchies - ADMIN or ELECTION hierarchy defined by the Administrators and Revenue hierarchy defined by the Revenue department.

• The election hierarchy has the locations divided into several types like zone, election wards, blocks, streets and localities. The Revenue hierarchy has the locations divided into a zone, ward, block and locality.

• The model which defines the localities like zone, ward and etc is a boundary object which contains information like name, lat, long, parent or children boundary if any. The boundaries come under each other in a hierarchy. For instance, a zone contains wards, a ward contains blocks, and a block contains locality. The order in which the boundaries are contained in each other differs based on the tenants.

Deployment Details

1. Add/Update the MDMS master file which contains boundary data of ULBs.

2. Add Role-Action mapping for the egov-location APIs.

3. Deploy/Redeploy the latest version of the egov-mdms service.

4. Fill the above environment variables in the egov-location with proper values.

5. Deploy the latest version of the egov-location service.

Configuration Details

The boundary data has been moved to MDMS from the master tables in DB. The location service fetches the JSON from MDMS and parses it to the structure of the boundary object as mentioned above. A sample master would look like below.

Integration Details

Integration Scope

The egov-location APIs can be used by any module which needs to store the location details of the tenant.

Integration Benefits

• Get the boundary details based on boundary type and hierarchy type within the tenant boundary structure.

• Get the geographical boundaries by providing appropriate GeoJson.

• Get the tenant list in the given latitude and longitude.

Integration Steps

1. To integrate, the host of egov-location should be overwritten in the helm chart.

2. /boundarys/_search should be added as the search endpoint for searching boundary details based on tenant Id, Boundary Type, Hierarchy Type etc.

3. /geography/_search should be added as the search endpoint. This method handles all requests related to geographical boundaries by providing appropriate GeoJson and other associated data based on tenantId or lat/long etc.

4. /tenant/_search should be added as the search endpoint. This method tries to resolve a given lat, long to a corresponding tenant, provided there exists a mapping between the reverse geocoded city to the tenant.

5. The MDMS tenant boundary master file should be loaded in the MDMS service.

Reference Docs

Doc Links

API List

Overview

In workflow 2.0 assignee is changed from an object to a list of objects.

Deployment Details

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:

Configuration Details

Persister Configuration

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:

Searcher Configuration

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:

Business Service Configuration

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:

UI Configuration

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 Configuration

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

1. 30 - 30*(1/3) => 20 - 30: will have green colour defined

2. 0 - 20: will have yellow colour defined

3. <0: will have red colour defined

The colours are also configured in the MDMS.

Integration Details

• 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.

Overview

Tenant represents a body in a system. In the municipal system, a state and its ULBs (Urban local bodies) are tenants. ULB represents a city or a town in a state. Tenant configuration is done in MDMS.

Pre-requisites

Before proceeding with the configuration, the following pre-requisites are met -

• Knowledge of json and how to write a json is required.

• Knowledge of MDMS is required.

• User with permission to edit the git repository where MDMS data is configured.

Key Functionalities

• On the login page, city name selection is required. Tenant added in MDMS shows in the city drop-down of the login page.

• In reports or in the employee inbox page the details related to ULB are displayed from the fetched ULB data added in MDMS.

• Modules i.e., TL, PT, MCS can be enabled based on the requirement of the tenant.

Deployment Details

After adding the new tenant, the MDMS service needs to be restarted to read the newly added data.

Configuration Details

Tenant is added in tenant.json. In MDMS, file tenant.json, under the tenant folder holds the details of the state and ULBs to be added in that state.

{
  "tenantId": "uk",  //<ReplaceWithDesiredTenantId>
  "moduleName": "tenant",
  "tenants": [ {
      "code": "uk.citya", //<state.ulbname>
      "name": "City A",  //<name of the ulb>
      "description": "City A", //<ulb description>
      "logoId": "https://s3.ap-south-1.amazonaws.com/uk-egov-assets/uk.citya/logo.png",  //<ulb logo path - To display ulb logo on login>
      "imageId": null,
      "domainUrl": "", //<ulb website url>
      "type": "CITY",
      "twitterUrl": null,
      "facebookUrl": null,
      "emailId": "complaints.citya@gmail.com",  //<ulb email id>
      "OfficeTimings": {
        "Mon - Sat": "10.00 AM - 5.00 PM"
      },
"city": {
"name": "City A",
"localName": null,
"districtCode": "CITYA",
"districtName": null,
"regionName": null,
"ulbGrade": "Municipal Corporation",
"longitude": 78.0322,
"latitude": 30.3165,
"shapeFileLocation": null,
"captcha": null,
"code": "248430"
},
"address": "City A Municipal Coronation Address",
"contactNumber": "91 (135) 2653572"
}]}

Localization should be pushed for ULB grade and ULB name. The format is given below.

Localization for ULB Grade

{
     "code": "ULBGRADE_MUNICIPAL_CORPORATION",
     "message": "MUNICIPAL CORPORATION",
     "module": "rainmaker-common",
     "locale": "en_IN"
  }

Localization for ULB Name

{
     "code": "TENANT_TENANTS_UK_HALDWANI",    
     "message": "Haldwani",
     "module": "rainmaker-tl",
     "locale": "en_IN"
}

Format of localization code for tenant name <MDMS_State_Tenant_Folder_Name>_<Tenants_Fille_Name>_<Tenant_Code> (replace dot with underscore)

Boundary data should be added for the new tenant.

Reference Docs

Doc Links

Overview

MDMS stands for Master Data Management Service. MDMS is one of the applications in the eGov DIGIT core group of services. This service aims to reduce the time spent by developers on writing codes to store and fetch master data (primary data needed for module functionality ) which doesn’t have any business logic associated with them.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

• Prior knowledge of Java/J2EE.

• Prior knowledge of Spring Boot.

• Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON, etc.

• Prior knowledge of Git.

• Advanced knowledge of how to operate JSON data would be an added advantage to understanding the service.

Key Functionalities

• The MDMS service reads the data from a set of JSON files from a pre-specified location.

• It can either be an online location (readable JSON files from online) or offline (JSON files stored in local memory).

• The JSON files are in a prescribed format and store the data on a map. The tenantID of the file serves as a key and a map of master data details as values.

• Once the data is stored in the map the same can be retrieved by making an API request to the MDMS service. Filters can be applied in the request to retrieve data based on the existing fields of JSON.

Deployment Details

• For deploying the changes in MDMS data, the service needs to be restarted.

• The changes in MDMS data could be adding new data, updating existing data, or deleting it.

Configuration Details

The config JSON files to be written should follow the listed rules

• The config files should have JSON extension

• The file should mention the tenantId, module name, and master name first before defining the data

{
  "tenantId": "uk",
  "moduleName": "BillingService",
  "{$MasterName}":[ ]
}

Example config JSON for “Billing Service”

{
  "tenantId": "pb",
  "moduleName": "BillingService",
 "BusinessService": 
 [
    {
      "businessService": "PropertyTax",
      "code": "PT",
      "collectionModesNotAllowed": [ "DD" ],
      "partPaymentAllowed": true,
      "isAdvanceAllowed": true,
      "isVoucherCreationEnabled": true
    }
]
}

Reference Docs

Doc Links

API List

Overview

Master Data Management Service is a core service made available on the DIGIT platform. It encapsulates the functionality surrounding Master Data Management. The service creates, updates and fetches Master Data pertaining to different modules. This eliminates the overhead of embedding the storage and retrieval logic of Master Data into other modules. The functionality is exposed via REST API.

Pre-requisites

Prior Knowledge of Java/J2EE, Spring Boot, and advanced knowledge of operating JSON data would be an added advantage to understanding the service.

Functionality

The MDM service reads the data from a set of JSON files from a pre-specified location. It can either be an online location (readable JSON files from online) or offline (JSON files stored in local memory). The JSON files should conform to a prescribed format. The data is stored in a map and tenantID of the file serves as the key.

Once the data is stored in the map the same can be retrieved by making an API request to the MDM service. Filters can be applied in the request to retrieve data based on the existing fields of JSON.

Setup and Usage

The spring boot application needs lombok extension added to your IDE to load it. Once the application is up and running API requests can be posted to the URL.

Configuration & Structure

The config JSON files to be written should follow the listed rules

• The config files should have JSON extension.

• The file should mention the tenantId, module name, and master name first before defining the data.

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "{$MasterName}":[ ]
}

The Master Name in the above sample will be substituted by the actual name of the master data. The array succeeding it will contain the actual data.

Example config JSON for “Billing Service”

{
  "tenantId": "pb",
  "moduleName": "BillingService",
 "BusinessService": 
 [
    {
      "businessService": "PropertyTax",
      "code": "PT",
      "collectionModesNotAllowed": [ "DD" ],
      "partPaymentAllowed": true,
      "isAdvanceAllowed": true,
      "isVoucherCreationEnabled": true
    }
]
}

API Reference Documentation

APIs are available to create, update and fetch master data pertaining to different modules. Refer to the segment below for quick details.

BasePath:/mdms/v1/[API endpoint] Method

POST /_create

Creates or Updates Master Data on GitHub as JSON files

MDMSCreateRequest Request Info + MasterDetail — Details of the master data to be created or updated on GitHub.

MasterDetail

MdmsCreateResponse Response Info

Method

POST /_search

This method fetches a list of masters for a specified module and tenantId.

MDMSCriteriaReq (mdms request) - Request Info + MdmsCriteria — Details of module and master which need to be searched using MDMS.

MdmsCriteria

MdmsResponse Response Info + Mdms

MDMS

Common Request/Response/Error Structures:

RequestInfo should be used to carry meta information about the requests to the server as described in the fields below. All DIGIT APIs will use requestinfo as a part of the request body to carry this meta information. Some of this information will be returned back from the server as part of the ResponseInfo in the response body to ensure correlation.

ResponseInfo should be used to carry metadata information about the response from the server. apiId, ver, and msgId in ResponseInfo should always correspond to the same values in the respective request's RequestInfo.

ErrorRes

All DIGIT APIs will return ErrorRes in case of failure which will carry ResponseInfo as metadata and Error object as an actual representation of the error. When the request processing status in the ResponseInfo is ‘FAILED’ the HTTP status code 400 is returned.

Overview

Configuring master data for a new module requires creating a new module in the master config file and adding master data. For better organizing, create all the master data files belonging to the module in the same folder. Organizing in the same folder is not mandatory it is based on the moduleName in the master data file.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

• User with permission to edit the git repository where MDMS data is configured.

Key Functionalities

These data can be used to validate the incoming data.

Deployment Details

After adding the new module data, the MDMS service needs to be restarted to read the newly added data.

Configuration Details

Add New Module

The master config file is structured as below. Each key in the master config is a module and each key in the module is a master.

{
  "<module1>":{
    "<master1>":{},
    "<master2>":{},
    ...
  },
  "<module2>":{
    <master3>:{},
    <master4>:{},
    ...
  },
  ...
}

The new module can be added below the existing modules in the master config file.

Create Masters Data

Please check the link to create a new master Adding New Master

Reference Docs

Doc Links

Overview

MDMS supports the configuration of data at different levels. While we enable a state there can be data that is common to all the ULBs of the state and data specific to each ULB. The data further can be configured at each module level as state-specific or ULB’s specific.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

• Prior Knowledge of Java/J2EE.

• Prior Knowledge of Spring Boot.

• Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON, etc.

• Prior knowledge of Git.

• Advanced knowledge of operating JSON data would be an added advantage to understanding the service.

Key Functionalities

• State Level Masters are maintained in a common folder.

• ULB Level Masters are maintained in separate folders named after the ULB.

• Module Specific State Level Masters are maintained by a folder named after the specific module that is placed outside the common folder.

Deployment Details

• For deploying the changes(adding new data, updating existing data or deletion) in MDMS, the MDMS service needs to be restarted.

Configuration Details

State Level Master Configuration

• The common master data across all ULBs and modules like department, designation, etc are placed under the common-masters folder which is under the tenant folder of the MDMS repository.

• The common master data across all ULBs and are module-specific are placed in a folder named after each module. These folders are placed directly under the tenant folder.

ULB Level Master Configuration

• Module data that are specific to each ULB like boundary data, interest, penalty, etc are configured at the ULB level. There will be a folder per ULB under the tenant folder and all the ULB’s module-specific data are placed under this folder.

Reference Docs

Doc Links

API List

Overview

The Indexer Service runs as a separate service. This service is designed to perform all the indexing tasks of the digit platform. The service reads records posted on specific Kafka topics and picks the corresponding index configuration from the yaml file provided by the respective module. The objective of the Indexer Service is listed below.

• To provide a one-stop framework for indexing the data to elasticsearch.

• To create provisions for indexing live data, reindexing from one index to the other and indexing legacy data from the data store.

Pre-requisites

Before you proceed with the configuration, make sure the following pre-requisites are met -

1. Prior knowledge of Java/J2EE

2. Prior knowledge of SpringBoot

3. Prior knowledge of Elasticsearch

4. Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.

5. Prior knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.

Key Functionalities

• Performs three major tasks namely: LiveIndex, Reindex and LegacyIndex.

• LiveIndex: Task of indexing the live transaction data on the platform. This keeps the es data in sync with the DB.

• Reindex: Task of indexing data from one index to the other. ES already provides this feature, the indexer does the same but with data transformation.

• LegacyIndex: Task of indexing legacy data from the tables to ES.

• Provides flexibility to index the entire object, a part of the object or an entirely different custom object all using one input JSON from modules.

• Provides features for customizing index JSON by field mapping, field masking, data enrichment through external APIs and data denormalization using MDMS.

• One-stop shop for all the es index requirements with easy-to-write and easy-to-maintain configuration files.

• Designed as a consumer to save API overhead. The consumer configs are written from scratch to have complete control over consumer behaviour.

Deployment Details

• Step 1: Write the configuration as per your requirement. The structure of the config file is explained later in the same doc.

• Step 3: Provide the absolute path of the checked-in file to DevOps, to add it to the file-read path of egov-indexer. The files are added to egov-indexer's environment manifest file for it to be read at the start-up of the application.

• Step 4: Run the egov-indexer app. Since it is a consumer, it starts listening to the configured topics and indexes the data.

Interaction Diagram

Configuration Details

API Details

a) POST /{key}/_index

Receive data and index. There should be a mapping with the topic as {key} in index config files.

b) POST /_reindex

This is used to migrate data from one index to another index

c) POST /_legacyindex

This is to run the LegacyIndex job to index data from DB. In the request body, the URL of the service which would be called by the indexer service to pick data must be mentioned.

Reference Docs

Doc Links

Overview

eGov Payment Gateway acts as a liaison between eGov apps and external payment gateways facilitating payments, reconciliation of payments and lookup of transactions' status'.

Pre-requisites

Before you proceed with the documentation, make sure the following pre-requisites are met -

• Java 8

• Kafka server is up and running

• egov-persister service is running and has pg service persister config path added in it

• PSQL server is running and the database is created to store transaction data.

Key Functionalities

• Create or initiate a transaction, to make a payment against a bill.

• Make payment for multiple bill details [multi module] for a single consumer code at once.

• Transaction to initiate a call to the transaction/_create API, various validations are carried out to ensure the sanctity of the request.

• The response includes a generated transaction id and a redirect URL to the payment gateway itself.

• Various validations are carried out to verify the authenticity of the request and the status is updated accordingly. If the transaction is successful, a receipt is generated for the same.

Payment Flow

Reconciliation

• Reconciliation is carried out by two jobs scheduled via a Quartz clustered scheduler.

• The early Reconciliation job is set to run every 15 minutes [configurable via app properties] and is aimed at reconciling transactions which were created 15 - 30 minutes ago and are in a PENDING state.

• The daily Reconciliation job is set to run once per day and is aimed at reconciling all transactions that are in a PENDING state, except for ones which were created 30 minutes ago.

Extensions

• Axis, Phonepe and Paytm payment gateways are implemented.

Configuration Details

The following properties in the application.properties file in egov-pg-service have to be added and set to default value after integrating with the new payment gateway. In the below table properties for AXIS bank, payment gateway is shown the same relevant property needs to be added for other payment gateways.

Deployment Details

1. Deploy the latest version of egov-pg-service.

2. Add pg service persister yaml path in persister configuration.

Integration Details

Integration Scope

The egov-pg-service acts as communication/contact between eGov apps and external payment gateways.

Integration Benefits

• Record every transaction against a bill.

• Record of payment for multiple bill details for a single consumer code at once.

Integration Steps

1. To integrate, the host of egov-pg-service should be overwritten in helm chart

2. /pg-service/transaction/v1/_create should be added in the module to initiate a new payment transaction, on successful validation

3. /pg-service/transaction/v1/_update should be added as the update endpoint to updates an existing payment transaction. This endpoint is issued only by payment gateways to update the status of payments. It verifies the authenticity of the request with the payment gateway and forwards all query params received from a payment gateway

4. /pg-service/transaction/v1/_search should be added as the search endpoint for retrieving the current status of a payment in our system.

Reference Docs

Doc Links

API List