Release Summary

DIGIT-Workbench release v1.0 is a new release with distinctive features and functions, details of which are provided below.

Functional changes

• Added new MDMS v2 API which provides the Create, Update, and Search APIs to manage master data.

• Added ability to perform Master Data CRUD operations from Workbench UI.

• Added ability to perform Localisation Data CRUD operations from Workbench UI.

Non-functional changes

• NA

New ‌Feature Additions

Document Resources and Links

Workbench UI & API Test Cases

DIGIT Workbench solution design allows system engineers to configure master data through an intuitive user-friendly interface. The solution facilitates “Self-serve code-free setup of DIGIT applications on the cloud”. It streamlines the configuration process making it easier and faster for deployment of applications on the DIGIT platform minus the hassle of coding.

With increasing implementations, the solution simplifies the setup process with intuitive screens for master data inputs. Workbench resolves the challenges of costly and time-consuming engineering capacity to implement and configure master data for products built on the DIGIT platform before going live. This helps reduce the reliance on resources equipped with high-end technical expertise on the DIGIT platform.

Problems

Workbench eliminates the need for coding to add and manage master data in the DIGIT applications.

Objectives

Enable senior implementation engineer with experience in DIGIT platforms to add and manage master and localisation data through an intuitive user interface.

Section Overview

Navigation Tips

• Click on the embedded links within the content to browse topic details.

• Use the Contents links available on the right side of the screen to move to a specific heading.

• Find the list of Related Docs links at the bottom of each page to browse through additional product details.

Contact Us

Release Chart

Context

This page offers details on role mapping, including role permissions and the process flow related to master data management.

Role Mapping

Process Flow

Key Features

Overview

MDMS v2 exposes APIs for defining schemas, searching schemas and then adding master data against these defined schemas. The data is now stored in PostgreSQL tables rather than in GitHub. MDMS v2 currently also exposes v1 search API which will fetch data from the database in the same format as MDMS v1 search API to maintain backward compatibility.

Pre-Requisites

1. Prior knowledge of Java/J2EE

2. Prior knowledge of Spring Boot

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

4. Prior knowledge of Git

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

Functionalities

1. Create schema: MDMS v2 introduces functionality to define your schema with all validations and properties supported by JSON schema draft 07.

2. Search schema: MDMS v2 has API to search schema based on the tenantid, schema code, and unique identifier.

3. Create data: MDMS v2 allows the creation of data against the defined schema.

4. Search data: MDMS v2 exposes two search APIs - v1 and v2 search where the v1 search API is entirely backward compatible.

5. Update data: MDMS v2 allows the updation of master data fields.

6. Fallback functionality: Both search APIs have fallback implemented where if data is not found for a particular tenant, the services fall back to the parent tenant(s) and return the response. If data is not found even for the parent tenant, an empty response is sent to the user.

Configuration Details

API

1. /mdms-v2/schema/v1/_create - Takes RequestInfo and SchemaDefinition in the request body. SchemaDefinition contains all attributes required to define the schema.

2. /mdms-v2/schema/v1/_search - Takes RequestInfo and SchemaDefSearchCriteria in the request body and returns schemas based on the provided search criteria.

3. /mdms-v2/v2/_create/{schemaCode} - This API endpoint is used to create the schemCode masters. It requires a "RequestInfo" in the request and utilizes the "MDMS" object within the request body to extract the necessary information for master creation. It takes the schemaCode as a path parameter to specify the schema mapped to the defined master data.

4. /mdms-v2/v2/_search - Takes RequestInfo and MdmsCriteria in the request body to return master data based on the provided search criteria. It also has a fallback functionality where if data is not found for the tenant which is sent, the services fall back to the parent tenant(s) to look for the data and return it.

5. /mdms-v2/v2/_update/{schemaCode} - Takes RequestInfo and Mdms in the request body where the MDMS object has all the information for the master being updated and it takes schemaCode as path param to identify the schema against which data is being updated.

6. /mdms-v2/v1/_search - This is a backwards-compatible API which takes RequestInfo and MdmsCriteria in the request body to return master data based on the provided search criteria and returns the response in MDMS v1 format. It also has a fallback functionality where if data is not found for the tenant which is sent, the services fall back to the parent tenant(s) to look for the data and return it.

Postman Collection

MDMS v2 APIs

Design Approach

The Workbench design introduces dynamically generated user interface screens for system users to perform key implementation tasks that typically require software code to be written by engineers.

Generic Concept of Workbench v1

The Master Data Management Service contains the standardised schemas defining the structure of data models to be used by the applications. The schemas ensure that master data management conforms to a unified data model offering consistent formats for data input.

Based on the defined schemas, dynamic forms are generated in the user interface. The forms contain embedded validation rules for data input ensuring data complies with the required formats. Once the data is validated and the entry is complete, the forms are pushed to the corresponding API endpoints. The master data is saved in the backend database.

Pre-requisites & Constraints

1. Individual master data management services are available and contain JSON schemas that define the structure of the data model.

2. The UI library for v1 is built based on the current master data structure for Health Campaign Management. Hence, the components available in this version will only address the master data types included in HCM masters.

Scope

The illustration below offers a glimpse into the features presently in the scope of the Workbench solution design. Follow the colour legend at the bottom of the visual for details of the design elements.

MDMS Master Data Homepage

Features

1. Select Master

2. Add new master data

   • Redirect to the “add master data” page

3. Search section

4. View all section

5. Navigation options

   • Add New

   • Search

   • Clear Search

   • Select an object

   • Click on edit against an object

   • Pagination navigation

6. Variations

   • First-time load

Add Master Data

Features

1. Dynamically rendered form

   • Order of fields

     • In the order of the schema

   • Labels

     • Will be the keys in the schema

   • Input field type

     • Will be dynamically generated based on the schema type

2. Add Localization

   • Default behavior - For every master data created create a localization entry too

     • Keycode - system generated

     • Locale - en_IN

     • Value - keycode

   • If the user clicks on add localization, here is the flow

3. Save

   • Save one of

   • Save and add another

4. Dependency

   • Some masters have a dependency on others to be added as a prerequisite

Data Input Fields

Render UI for adding fields

non-editable key-value

• For values that are non-editable / view-only

Text input, mandatory

• For all text input fields

• If mandatory then the key label will be highlighted and a prompt shown for violation upon submission

Text input, validation

• If there are any validations then the key label will be highlighted and a prompt shown for violation upon submission

Dropdown for referenced master data

• If referencing another master data set then the drop-down should show the list of objects from the referenced set

  • The text that will be displayed will be the <title of object> from the master data that is referenced; The same as the first column in the view/search results section

Boolean selection

• For all boolean data types in the schema

Input, Date type

• Where the input type is the date

• Any validations should restrict the range of the calendar.

  • Example: If a date outside a given range of dates is selected raise a prompt for the same; Alternately restrict the selection of such a date too

Object

• Card for all “object” data types

• The length of the card will depend on the fields inside the object

• All fields/properties of the object will be rendered in the UI

• The fields inside the box will use the same components as above

• All arrays will have the same UI component

• The user should be able to minimize the array, and in a minimized state be able to see the title of the array

• All array boxes will have a +Add “title of the array” button to add new entities to the array itself

  • No order for removing entities added to the array

• Until the whole form is saved, any object in the array can be edited/removed

Array of objects

• All arrays will have the same UI component

• The user should be able to minimize the array, and in a minimized state be able to see the title of the array

• All array boxes will have a +Add “title of the array” button to add new entities to the array itself

  • No order for removing entities added to the array

• Until the whole form is saved, any object in the array can be edited/removed

• Each object box ll have the properties of the “Object” UI component as detailed in the object section

  • The fields inside each array will be the same and will be rendered based on the properties/keys in the object schema

Add Localisation

Add localisation for master data while creating master data

Features

1. Add localisation

   • Code - system generated

   • Select Language - select from the list of “locale”s in the tenant

   • Text - Mandatory field

2. Adding localisation for multiple languages

   • Repeat the same process by selecting each language

Search Master Data

Features

1. Search

   • Search fields

     • Search fields will be custom-defined for each master - Some master data objects have objects/array of objects inside them, search parameter cannot be a value in this hierarchy; Example: productVariantId inside resources for a projectType master data

     • Type of search fields

       • Text

       • Selection - If the property in the master data object has a reference then the search input will also be a selection-based dropdown

     • Labels for the search fields will be picked from the value of the key of the property that is selected

2. Clear search - Will clear the entered values in the search input boxes and also the results to default

3. View Search results

   • Search results

     • Default - By default will load all the objects in the corresponding master

   • Order of listing - Search results will be listed in ascending order(A-Z) of the first column when the page loads

   • List of columns to be displayed- Will be customized for each master

   • Sorting - Sorting will be available for every column

4. Variations - No results found

View All

Features

1. Columns

   • List of columns to be shown - Will be custom-defined for each master

   • Order of columns - Will be custom-defined for each master

2. Rows

   • Number of items in the row - As per the DIGIT UI design system

   • Edit option - Every row object will have an edit icon, that will redirect to the “Update” page for the corresponding object

View One

Features

1. View the object’s details - Page layout will be the same as the “add new” page - except all fields will be non-editable

2. Navigation options - Update

Edit & Update Master Data

Features

1. Object details

   • The page will be rendered as the add new page - except there won’t be an option for “Save and Add Another”

   • Disable

2. Navigation options

   • Save

MDMS v2 Specifications -

Figma screens for the UI are available . Refer to them to understand the Workbench UI.

Background

Implementing products built on the DIGIT platform requires engineering capacity to set up the system and configure master data before going live. The increasing demand for implementations of DIGIT applications triggered the need for low-cost and high-velocity solutions to manage these implementations.

Implementation Process Overview

Implementation refers to the process of deploying applications built on the DIGIT platform in a new business context or geographical location. The deployment steps include system setup, master data configuration and customisation. The implementation process ensures the application workflows are tailored fit to meet the requirements of the local or regional policies for smooth functioning.

Examples of DIGIT implementations -

Problems

The current implementation process for DIGIT applications faces two primary challenges.

1. Skilled personnel - The implementation requires experienced engineers who are familiar with the DIGIT platform. This proves both expensive while limiting the number of implementations that can be handled at a time.

2. Cost and time constraints - Since the number of experienced engineers is limited, it poses limitations on the number of implementations that can be handled simultaneously. The result is longer timeframes for going live and increased costs.

Objective

Enable a non-tech/low-tech user to set up one or more DIGIT applications on a fully managed cloud infra with the ability to customise the application, features and registries to their context, all through an intuitive UI without writing a single line of code.

Solution

The Workbench solution is designed to meet the rising demand for low-cost, rapid implementations of DIGIT products. It simplifies the setup process by enabling senior engineers familiar with DIGIT to manage and configure master data through a user-friendly interface easily. The Workbench addresses the requirements of high demand for implementations in regions with limited DIGIT expertise and tight go-live timelines. The goal is to streamline the process and allow quicker, code-free deployments.

The Workbench user interface enables users to set up a new account with DIGIT services. It provides system users with a dynamically generated UI to perform key implementation tasks that typically require software code to be written by engineers.

End-state flow:

Key Components / Abilities

1. Generate forms (UI) based on schema and push data entered in the forms to corresponding API endpoints

2. Open to access for all services

3. UI to add/remove fields from the registries

4. UI to update forms

5. Spin up a DIGIT service from a web portal

Pre-requisites

1. Standardized JSONSchema for services

2. UI-Schema Library

3. UI-templates for forms

4. Codified rules for updating registry structure

5. UI to initiate “primary-tenant”

6. Deploy selected services

7. UI to trigger the installer

8. Master-tenant creation and management

9. Delineation of tenants

Maturity Model

The table below outlines the distinctive phase of development of the Workbench solution.

Overview

The Manage Master Data screen allows users to manage master data. Navigate to the Manage Master Data from the home screen card.

Manage Master Data - User Role

• MDMS_ADMIN

   {
     "name": "MDMS_ADMIN",
     "code": "MDMS_ADMIN",
     "tenantId": "pg"
  }

• For the provided role, it is necessary to include all role action mappings associated with master data in MDMS.

Overview

Add Master Data Flow

• An action button is available on the search master data screen to add master data.

• Clicking on the action button redirects users to the add master data screen.

• The Add Master Data screen renders a form through which the user can enter master data.

• Once the form is submitted, the validations are run as specified in the schema. If the validations are passed, the Create API is called and the respective toast message is shown as relevant to the response received from the Create API.

Role Action Mapping To Access Create API

• As of now, role actions have to be defined for every schema. Let us take an example of a schema code "Trade.Details"

• The Create API URL for the above schema will look like this "/mdms-v2/v2/_create/Trade.Details"

• Hence for this URL, the role action mapping has to be added to the MDMS_ADMIN role.

• Similarly, for other masters, add role action mapping to the same role "MDMS_ADMIN".

Create Master Data API

Refer to the curl below:

curl 'http://localhost:3000/mdms-v2/v2/_create/Trade.Validations' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Accept-Language: en-US,en;q=0.9' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Origin: http://localhost:3000' \
  -H 'Referer: http://localhost:3000/workbench-ui/employee/workbench/mdms-add-v2?moduleName=Trade&masterName=Validations' \
  -H 'Sec-Fetch-Dest: empty' \
  -H 'Sec-Fetch-Mode: cors' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36' \
  -H 'sec-ch-ua: "Chromium";v="116", "Not)A;Brand";v="24", "Google Chrome";v="116"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "Windows"' \
  --data-raw '{"Mdms":{"tenantId":"pb","schemaCode":"Trade.Validations","uniqueIdentifier":null,"data":{"name":"sfd","dropdownField":"90-100"},"isActive":true},"RequestInfo":{"apiId":"Rainmaker","authToken":"5bbfa93c-adc2-42b2-992e-a708a83cb2cf","userInfo":{"id":80234,"uuid":"aeb85b37-c996-4218-bdca-1b00cc268f2f","userName":"WBQA","name":"LOC","mobileNumber":"9999991942","emailId":null,"locale":null,"type":"EMPLOYEE","roles":[{"name":"MDMS ADMIN","code":"MDMS_ADMIN","tenantId":"pb"},{"name":"Super User","code":"SUPERUSER","tenantId":"pb"},{"name":"Localisation admin","code":"LOC_ADMIN","tenantId":"pb"},{"name":"Employee","code":"EMPLOYEE","tenantId":"pb"}],"active":true,"tenantId":"pb","permanentCity":null},"msgId":"1694161641687|en_IN","plainAccessRequest":{}}}' \
  --compressed

Sample request body:

{
    "Mdms": {
        "tenantId": "pb",
        "schemaCode": "Trade.Validations",
        "uniqueIdentifier": null,
        "data": {
            "name": "sfd",
            "dropdownField": "90-100"
        },
        "isActive": true
    },
    "RequestInfo": {
        "apiId": "Rainmaker",
        "authToken": "5bbfa93c-adc2-42b2-992e-a708a83cb2cf",
        "userInfo": {
            "id": 80234,
            "uuid": "aeb85b37-c996-4218-bdca-1b00cc268f2f",
            "userName": "WBQA",
            "name": "LOC",
            "mobileNumber": "9999991942",
            "emailId": null,
            "locale": null,
            "type": "EMPLOYEE",
            "roles": [
                {
                    "name": "MDMS ADMIN",
                    "code": "MDMS_ADMIN",
                    "tenantId": "pb"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb"
                },
                {
                    "name": "Localisation admin",
                    "code": "LOC_ADMIN",
                    "tenantId": "pb"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb"
                }
            ],
            "active": true,
            "tenantId": "pb",
            "permanentCity": null
        },
        "msgId": "1694161641687|en_IN",
        "plainAccessRequest": {}
    }
}

Overview

This guide details the steps to promote a master to MDMS v2. It includes defining a schema with a unique identifier, creating the schema via an API endpoint, and verifying the created schema. Once verified, data can be added and searched using corresponding API endpoints.

Steps

1. Define a schema for the master that you want to promote to MDMS v2.

2. Ensure that the schema has a unique field (a unique field can also be composite) which enforces the data being added against that schema to be unique.

3. If the data does not have the scope for having unique identifiers. For example - complex masters like - https://github.com/egovernments/health-campaign-mdms/blob/QA/data/default/health/project-task-configuration.json - consider adding a redundant field which can serve as the unique identifier.

4. Hit the following API endpoint to create schema in the system - /mdms-v2/schema/v1/_create

5. Now that the schema has been created, verify the created schema by searching for it using the following API endpoint - /mdms-v2/schema/v1/_search

6. Once the schema is in place, data can be created against the created schema using the following API endpoint - /mdms-v2/v2/_create/{schemaCode}

7. Once the data is created, data can be verified by searching it by using the following API endpoint - /mdms-v2/v2/_search

The users have two options on the View Master Data screen -

1. Disable/Enable Master Data

2. Edit Master Data

Disable/Enable Master Data

• This option is dynamic, if the master data is currently disabled(computed through the "isActive" flag present in every master data) Enable option is shown and vice-versa.

• Update Master data API is called with the updated value of "isActive" flag and a respective toast message is shown to the user

• As soon as the API responds, this option is updated according to the new value of "isActive" flag.

• Pls refer to the end of this page for updated API details

Edit Master Data

• When the user clicks on this option, the screen redirects to the Edit master data screen.

• This screen is similar to the add master data screen, but all the fields are pre-populated with previous data.

• Users can make changes to the master data.

• Once the user clicks on the Submit button, validations are run in UI (specified in schema). If the validations are passed update master data API is called and a toast message is shown. After 5 seconds the user is automatically redirected to the view screen, where the updated data is reflected.

• If the validations fail, the respective error message is shown below the target field for which validations failed.

• The same role action mapping rules apply here as mentioned in the Add Master data page.

Update Master Data API

Refer to the curl below to update the master data API. It is very similar to the Create Master Data. (Notice the URL is unique to the schema for which the master data belongs, similar to add).

curl 'http://localhost:3000/mdms-v2/v2/_update/Trade.Validations' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Accept-Language: en-US,en;q=0.9' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Origin: http://localhost:3000' \
  -H 'Referer: http://localhost:3000/workbench-ui/employee/workbench/mdms-edit?moduleName=Trade&masterName=Validations&uniqueIdentifier=sfd' \
  -H 'Sec-Fetch-Dest: empty' \
  -H 'Sec-Fetch-Mode: cors' \
  -H 'Sec-Fetch-Site: same-origin' \
  -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36' \
  -H 'sec-ch-ua: "Chromium";v="116", "Not)A;Brand";v="24", "Google Chrome";v="116"' \
  -H 'sec-ch-ua-mobile: ?0' \
  -H 'sec-ch-ua-platform: "Windows"' \
  --data-raw '{"Mdms":{"id":"661b4560-a0ec-4930-a8c2-c84d643b361f","tenantId":"pb","schemaCode":"Trade.Validations","uniqueIdentifier":"sfd","data":{"name":"sfd","dropdownField":"70-90"},"isActive":true,"auditDetails":{"createdBy":"aeb85b37-c996-4218-bdca-1b00cc268f2f","lastModifiedBy":"aeb85b37-c996-4218-bdca-1b00cc268f2f","createdTime":1694161642579,"lastModifiedTime":1694161642579}},"RequestInfo":{"apiId":"Rainmaker","authToken":"5bbfa93c-adc2-42b2-992e-a708a83cb2cf","userInfo":{"id":80234,"uuid":"aeb85b37-c996-4218-bdca-1b00cc268f2f","userName":"WBQA","name":"LOC","mobileNumber":"9999991942","emailId":null,"locale":null,"type":"EMPLOYEE","roles":[{"name":"MDMS ADMIN","code":"MDMS_ADMIN","tenantId":"pb"},{"name":"Super User","code":"SUPERUSER","tenantId":"pb"},{"name":"Localisation admin","code":"LOC_ADMIN","tenantId":"pb"},{"name":"Employee","code":"EMPLOYEE","tenantId":"pb"}],"active":true,"tenantId":"pb","permanentCity":null},"msgId":"1694163335209|en_IN","plainAccessRequest":{}}}' \
  --compressed

Sample request body for update:

{
    "Mdms": {
        "id": "661b4560-a0ec-4930-a8c2-c84d643b361f",
        "tenantId": "pb",
        "schemaCode": "Trade.Validations",
        "uniqueIdentifier": "sfd",
        "data": {
            "name": "sfd",
            "dropdownField": "70-90"
        },
        "isActive": true,
        "auditDetails": {
            "createdBy": "aeb85b37-c996-4218-bdca-1b00cc268f2f",
            "lastModifiedBy": "aeb85b37-c996-4218-bdca-1b00cc268f2f",
            "createdTime": 1694161642579,
            "lastModifiedTime": 1694161642579
        }
    },
    "RequestInfo": {
        "apiId": "Rainmaker",
        "authToken": "5bbfa93c-adc2-42b2-992e-a708a83cb2cf",
        "userInfo": {
            "id": 80234,
            "uuid": "aeb85b37-c996-4218-bdca-1b00cc268f2f",
            "userName": "WBQA",
            "name": "LOC",
            "mobileNumber": "9999991942",
            "emailId": null,
            "locale": null,
            "type": "EMPLOYEE",
            "roles": [
                {
                    "name": "MDMS ADMIN",
                    "code": "MDMS_ADMIN",
                    "tenantId": "pb"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb"
                },
                {
                    "name": "Localisation admin",
                    "code": "LOC_ADMIN",
                    "tenantId": "pb"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb"
                }
            ],
            "active": true,
            "tenantId": "pb",
            "permanentCity": null
        },
        "msgId": "1694163335209|en_IN",
        "plainAccessRequest": {}
    }
}

Overview

This page provides details about the Workbench UI configuration required to enable it in any environment.

DevOps Configuration

In the DevOps repository of your organization, locate the following "deploy-as-code/helm/environments/unified-dev.yaml". Inside the environment YAML file used to deploy the Core platform, please add the following block of code:

workbench-ui:
  custom-js-injection: |
    sub_filter.conf: "
      sub_filter  '<head>' '<head>
      <script src={{INSERT_YOUR_AWS_BUCKET_NAME}}/globalConfigs.js type=text/javascript></script>';"

A dev environment sample file is linked here. Note that you will have to modify this for your deployment.

Global Configuration

This section contains a config that applies globally to all UI modules. These need to be configured before configuring the service-specific UI.

Steps to create a globalconfig.js file:

1. Create a config file (globalconfigs.js) with the below-mentioned configurations (refer code below).

2. Configure all the images/logos required in the S3 and add links as footerBWLogoURL, footerLogoURL.

3. Mention the state tenant ID as stateTenantId.

4. If any user roles have to be made invalid add as invalidEmployeeRoles.

5. Then push this global config file into your S3 bucket as globalconfigs.js.

6. Mention the globalConfigs file URL in your Environment config .

var globalConfigs = (function () {
  var stateTenantId = 'pg' // statetenantId
   var gmaps_api_key = '<<INSERT_GMAP_GENERATED_TOKEN>>';
   var contextPath = 'workbench-ui'; 
   var configModuleName = 'commonMuktaUiConfig'; 
   var centralInstanceEnabled = false;
   var footerBWLogoURL = '{{INSERT_YOUR_AWS_BUCKET_NAME}}/digit-footer-bw.png';
   var footerLogoURL = '{{INSERT_YOUR_AWS_BUCKET_NAME}}/digit-footer.png';
   var digitHomeURL = 'https://www.digit.org/';
   var xstateWebchatServices = 'wss://dev.digit.org/xstate-webchat/';
   var assetS3Bucket = '{{INSERT_YOUR_AWS_BUCKET_NAME}}';
   var invalidEmployeeRoles = ["CBO_ADMIN","STADMIN","ORG_ADMIN","ORG_STAFF","SYSTEM"] 

 
   var getConfig = function (key) {
     if (key === 'STATE_LEVEL_TENANT_ID') {
       return stateTenantId;
     }
     else if (key === 'GMAPS_API_KEY') {
       return gmaps_api_key;
     }
     else if (key === 'ENABLE_SINGLEINSTANCE') {
       return centralInstanceEnabled;
     } else if (key === 'DIGIT_FOOTER_BW') {
       return footerBWLogoURL;
     } else if (key === 'DIGIT_FOOTER') {
       return footerLogoURL;
     } else if (key === 'DIGIT_HOME_URL') {
       return digitHomeURL;
     } else if (key === 'xstate-webchat-services') {
       return xstateWebchatServices;
     } else if (key === 'S3BUCKET') {
       return assetS3Bucket;
     } else if (key === 'CONTEXT_PATH'){
	return contextPath;
     } else if (key === 'UICONFIG_MODULENAME'){
	return configModuleName;
     } else if (key === 'INVALIDROLES'){
	return invalidEmployeeRoles;
     }
   };
 
 
   return {
     getConfig
   };
 }());

Localisation Configuration

All strings localised per module are provided in this sheet linked here. To translate the UI into other languages, please follow this sheet and provide appropriate translations in your language.

Reference Links

Figma screens for the UI are here. Refer to them to understand the Workbench UI.

We have the following flows in Manage Localization Data

1. Search Localizations

2. Edit Localizations

3. Add and Bulk upload

Role required to manage localizations

"LOC_ADMIN"

Sample JSON:

{
   "name": "Localisation admin",
   "code": "LOC_ADMIN",
   "tenantId": "pb"
}

Adding Localizations

• From the search screen user can navigate to add localization screen by clicking the action button

• In this screen user can specify the locale(language) and module in which messages have to be upserted

• Once the language and module is selected a table is rendered in which user can add the keycode and the respective message. In one go, we can upsert upto 50 messages in this table.

• These messages will be upserted into the default locale as well.

• After adding the messages user can click on the "Save" action button. Upon success, a relevant toast message is shown and the table is cleared.

• In case of failure, an error toast message is shown listing the list of errors due to which the messages could not be upserted.

API for adding localizations

Same API is utilized for edit and bulk upload as well.

Refer the below curl:

curl --location 'http://localhost:3000/localization/messages/v1/_upsert' \
--header 'Accept: application/json, text/plain, */*' \
--header 'Accept-Language: en-US,en;q=0.9' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/json;charset=UTF-8' \
--header 'Origin: http://localhost:3000' \
--header 'Referer: http://localhost:3000/workbench-ui/employee/workbench/localisation-add' \
--header 'Sec-Fetch-Dest: empty' \
--header 'Sec-Fetch-Mode: cors' \
--header 'Sec-Fetch-Site: same-origin' \
--header 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36' \
--header 'sec-ch-ua: "Chromium";v="116", "Not)A;Brand";v="24", "Google Chrome";v="116"' \
--header 'sec-ch-ua-mobile: ?0' \
--header 'sec-ch-ua-platform: "Windows"' \
--data '{"tenantId":"pb","messages":[{"code":"sdf","message":"dsf","locale":"default","module":"rainmaker-test","id":0}],"RequestInfo":{"apiId":"Rainmaker","authToken":"5bbfa93c-adc2-42b2-992e-a708a83cb2cf","userInfo":{"id":80234,"uuid":"aeb85b37-c996-4218-bdca-1b00cc268f2f","userName":"WBQA","name":"LOC","mobileNumber":"9999991942","emailId":null,"locale":null,"type":"EMPLOYEE","roles":[{"name":"MDMS ADMIN","code":"MDMS_ADMIN","tenantId":"pb"},{"name":"Super User","code":"SUPERUSER","tenantId":"pb"},{"name":"Localisation admin","code":"LOC_ADMIN","tenantId":"pb"},{"name":"Employee","code":"EMPLOYEE","tenantId":"pb"}],"active":true,"tenantId":"pb","permanentCity":null},"msgId":"1694166894795|en_IN","plainAccessRequest":{}}}'

Tenant Module Localization

• State level users can upsert localizations to all modules

• City level users can only upsert to module specific to the tenantId (eg -> pg.citya)

• Some examples of city module localizations

       {
            "code": "PG_CITYA_ADMIN_B2",
            "message": "Ward Two",
            "module": "rainmaker-pg.citya",
            "locale": "en_IN"
        },
        
        {
            "code": "PG_CITYA_ADMIN_B3",
            "message": "Ward Three",
            "module": "rainmaker-pg.citya",
            "locale": "en_IN"
        }

Overview

From the search master data screen users can click on any of the rows in the results table, this will redirect the UI to the View master data screen.

Rendering View Master Data Screen Logic

• Before loading the View screen, we fetch the schema and the data using the schema code and unique Identifier respectively. Curls for search schema and search data can be referred from the Add Master Data page.

• Schema response is used to render the form, similar to add form, and the data response is used to prefill the values in the form. The only difference here is that all the fields are disabled, unlike the add screen.

• The same role action mapping rules apply here as defined in the Add Master Data page.

• In the View screen, we have an action button with two options

  1. Edit Master Data

  2. Disable Master Data

• The above actions are covered in the Update Master Data page.

Overview

This page provides the steps to search localisation data.

Steps

Navigate to the Manage Localisation screen from the home screen card. This opens the search localisation screen.

The following parameters are available for searching localizations

1. locale -> this field is mandatory. This dropdown is populated based on this mdms https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-UAT/data/pg/common-masters/StateInfo.json

2. module -> list of modules present in this mdms https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/pg/common-masters/StateInfo.json

3. keycode -> code of a specific message. It is a string-type parameter

Search Results

We have the following columns for localisation search results:

1. Module name

2. Key code

3. Default value -> message stored in default locale

4. Text -> message stored

5. Action -> Edit action to update message in that particular localisation

A note on the default value in the results

While adding localisations, by default all the messages will be updated in the locale mentioned by the user as well as in the "default" locale. The message updated in this locale is considered the default message. While updating the message default locale message remains unchanged.

Search API For Localisations

Localisation search API is an open API. Refer to the curl given below:

curl --location 'https://qa.digit.org/localization/messages/v1/_search?locale=en_IN&tenantId=pb' \
--header 'Content-Type: application/json' \
--data '{
     "RequestInfo": {
       "apiId" : "emp",
       "ver" : "1.0",
       "ts" : "10-03-2017 00:00:00",
       "action" : "create",
       "did" : "1",
       "key" : "abcdkey",
       "msgId" : "20170310130900",
       "requesterId" : "rajesh",
       "authToken" : "{{authToken}}",
       "userInfo" : {
         "id" : 1
       }
   }
}'

• Search for the desired language and module using the provided search functionality. The language and module are derived from MDMSv2.

• For example, if you are searching for the language ‘English’ and the module ‘rainmaker-common’, Once you perform the search, all relevant results will be displayed below.

Refer to the screenshot below:

Overview

This documentation outlines the process for replacing the egov-mdms-service with MDMS V2, which is database-driven and offers enhanced API capabilities for CRUD operations (Create, Read, Update, and Disable). By renaming the context path of MDMS V2 to egov-mdms-service, we ensure that core and other services can seamlessly interact with the new MDMS service without requiring changes.

Key Changes

1. MDMS V2:

   • Database-based: Stores master data in a database rather than static files in a GitHub repository.

   • CRUD APIs: Allows users to dynamically interact with the master data through APIs for adding, updating, and disabling records.

   • Backward Compatibility: MDMS V2 retains compatibility with MDMS V1 search APIs, allowing services using egov-mdms-service to function without changes.

2. egov-mdms-service:

   • File-based: Managed master data as static JSON files stored in a GitHub repository.

   • Limited Interaction: Primarily served data without allowing user modification through APIs.

Migration Steps

1. Rename MDMS V2 Context Path

Rename the context path of MDMS V2 to egov-mdms-servicein your environment. This ensures that all existing core and dependent services will seamlessly point to the new MDMS V2 without the need for any modifications.

• For example, if MDMS V2 is running on /mdms-v2, change it to /egov-mdms-service in the environment configurations.

2. Remove Existing egov-mdms-service

Delete the existing egov-mdms-service setup:

• Pods: Remove the running pods related to the old egov-mdms-service.

• Service: Delete the service definition.

• Ingress: Remove or update the ingress to redirect to the new MDMS V2.

3. Deploy MDMS V2 with Configuration

Deploy or redeploy MDMS V2 with the updated context path (/egov-mdms-service) and database configurations enabled.

Ensure the following configurations are set:

• Database connection (for master data storage)

• API configurations (for CRUD operations)

• Backwards compatibility enabled (for V1 search APIs)

4. Restart Zuul Gateway

Once MDMS V2 is deployed and running, restart the Zuul Gateway (or any API gateway) to ensure that it picks up the new routing mappings to the renamed MDMS service (egov-mdms-service).

5. Restart Dependent Services

Restart all core and dependent services with configuration changes enabled so that they point to the newly deployed MDMS V2. This ensures that the services can now interact with the updated APIs provided by MDMS V2.

Use the below scripts to add default data for the roles and security policy so that user service will get started and we can proceed with adding more data.

Data Migration Process

Data migration is a separate and essential activity that must be handled master by master. The migration process includes:

1. Schema Creation:

   • For each master, ensure that the necessary schema is created in the database.

   • Verify that the structure aligns with the expected format in MDMS V2.

2. Data Migration:

   • Migrate data master by master into the corresponding database tables.

   • Ensure that the migrated data is valid and adheres to the schema.

I have attached the default MDMS data and schema that were created in UAT. This can be used to load the default MDMS for the HCM Product & Console. It can be imported into any environment, and you can change the tenant from 'mz' by using the 'find and replace' function. After that, delete any unnecessary masters and add new ones according to your use case.

Additional Notes

• Backward Compatibility: Since MDMS V2 supports the V1 search APIs, all core and dependent services will continue to function normally without modification.

• Database Configuration: Ensure that database replication and backups are in place, especially during the migration, to prevent data loss.

• Service Downtime: Depending on your infrastructure, plan for potential service downtime while removing the old egov-mdms-service and deploying MDMS V2.

• The migration to MDMS V2 is successfully completed in the Unified UAT environment.

• All MDMS data for -

  • HCM (including HCM Prod and HCM Console)

  • Sanitation

  • Core Master Data

  is migrated.

Database Dump & Schema Information

A database dump containing all the necessary schemas and data will be provided. This includes:

• Core-related master data.

• Health and Console-related masters.

You can filter the Core-related data from the dump and update your database accordingly for future environments.

Conclusion

By following this migration guide, you can seamlessly transition from egov-mdms-service to the more dynamic and API-driven MDMS V2. The new system enhances user interaction while maintaining compatibility with existing services, ensuring a smooth integration into the ecosystem.

Overview

Search Master Data Flow

• Users can click on the specific master name from the dropdown on the Manage Master Data screen to select the master data.

• Users are redirected to the Search Master Data screen (of the selected master) screen as soon as a master is selected.

• By default, the data present in that master is shown in the Results table.

• Users can search master data using the following input parameters -

  1. Field

  2. Value

  3. is Active

Note -> Search with field and value is considered as one parameter. Make sure to enter both in order to search master data.

• 'isActive' is a Boolean parameter which results in either active or inactive master data. All master data contain this field by default.

• For the time being, master data search is allowed with string fields and the isActive flag.

• Search results are filtered by string type and isActive before getting rendered in the table.

Search Schemas API

The master and module dropdowns on the manage master screen are populated on the basis of the responses from the schema search. Refer to the below curl for details:

Use the below parameters to search for the schemas -

1. tenantId

2. limit

3. offset

4. codes -> list of schema codes

Search Master Data For Specific Schema API

Users are redirected to the search master data screen once a specific master is selected from the manage master data screen.

Refer to the below API curl to search for the master data -

The parameters here are used to search for the master data. Refer to the request body object below.

The "data" object holds the field-value pairs used to search for master data within a specific master. The "uniqueIdentifier" is a backend-generated ID for each master data.

MDMS Changes

Config Changes

DevOps Changes

Localisation Changes

If you are visiting the screen and it is not localized, the screen will appear as in the screenshot below.

• You can localize it with these simple steps:

• We have an option to upload Excel sheets (XLSX, XLS) and upsert bulk messages.

• From the "Add Localization" screen, there is an option to Bulk upload. See the image below.

• Upon clicking the bulk upload option, the user can select an Excel file from the file system.

• Copy all the locale code and give the corresponding message to display, module, and locale.

• Paste this data into an Excel spreadsheet and save it as an XLSX file.

• See the screenshot provided for reference for excel file.

Conditions for valid excel file

Excel file can contain multiple sheets, every sheet must have these four columns:

1. code

2. message

3. locale

4. module

• Upload this XLSX file to the project UI.

• After uploading, log out and log back in to see the UI localized.

Now see the UI, it will be as given below:

Editing localizations

• From the Search screen itself user can update localization messages

• Only message text can be edited, we are not allowed to change locale, module and code of the message.

• There is a fixed action column in the results table.

• Upon clicking the edit icon a modal is opened from where user can add the updated message

• User can click on the submit button, a respective toast is shown and the search results are refetched and rendered with the updated message.

• API used here is same as add localization.

• Select the edit icon in the action column, update the text as needed, and then click submit to save your changes.

Steps to follow to create a new Master -

1. Create a schema using Postman (API) - Schema( ) can be constructed by inputting the required JSON Object Below is the sample cURL to create a schema.

1. Add actions-test and roleactions for search, create, and update. Below is the sample code for the actions-test for the schema mentioned above::

Here is the sample code for the roleactions::

1. Push the localization messages using the rainmaker-schema module to the schema's name(on the Add Master Data page and sidebar), tooltips, and all the fields on the UI. Example::