Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
MDMS v2 provides APIs for defining schemas, searching schemas, and adding master data against these defined schemas. All data is now stored in PostgreSQL tables instead of GitHub. MDMS v2 currently also includes v1 search API for fetching data from the database in the same format as MDMS v1 search API to ensure backward compatibility.
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.
Create schema: MDMS v2 introduces functionality to define your schema with all validations and properties supported by JSON schema draft 07. Below is a sample schema definition for your reference -
To create a basic schema definition, use the following keywords:
$schema: specifies which draft of the JSON Schema standard the schema adheres to.
title and description: state the intent of the schema. These keywords don’t add any constraints to the data being validated.
type: defines the first constraint on the JSON data.
Additionally, we have two keys which are not part of standard JSON schema attributes -
x-unique: specifies the fields in the schema utilizing which a unique identifier for each master data will be created.
x-ref-schema: specifies referenced data. This is useful in scenarios where the parent-child relationship needs to be established in master data. For example, Trade Type can be a parent master data to Trade Sub Type. In the example above, the field path represents the JsonPath of the attribute in the master data which contains the unique identifier of the parent which is being referenced. Schema code represents the schema under which the referenced master data needs to be validated for existence.
Search schema: MDMS v2 has API to search schema based on the tenantid, schema code, and unique identifier.
Create data: MDMS v2 enables data creation according to the defined schema. Below is an example of data based on the mentioned schema:
Search data: MDMS v2 exposes two search APIs - v1 and v2 search where v1 search API is completely backward compatible.
Update data: MDMS v2 allows the updation of master data fields.
Fallback functionality: Both the 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.
/mdms-v2/schema/v1/_create - Takes RequestInfo and SchemaDefinition in the request body. SchemaDefinition has all attributes which define the schema.
/mdms-v2/schema/v1/_search - Takes RequestInfo and SchemaDefSearchCriteria in the request body and returns schemas based on the provided search criteria.
/mdms-v2/v2/_create/{schemaCode} - Takes RequestInfo and Mdms in the request body where the MDMS object has all the information for the master being created and it takes schemaCode as path param to identify the schema against which data is being created.
/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.
/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.
/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 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.
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.
Prior Knowledge of Java/J2EE, Spring Boot, and advanced knowledge of operating JSON data would be an added advantage to understanding the service.
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.
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.
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.
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”
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.
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.
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.
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.
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.
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
Example config JSON for “Billing Service”
For creating a new master in MDMS, create the JSON file with the master data and configure the newly created master in the master config file.
Before proceeding with the configuration, make sure the following pre-requisites are met -
User with permission to edit the git repository where MDMS data is configured.
After adding the new master, the MDMS service needs to be restarted to read the newly added data.
The new JSON file needs to contain 3 keys as shown in the below code snippet. The new master can be created either State-wise or ULB-wise. Tenant ID and config in the master config file determine this.
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.
Each master contains the following data and the keys are self-explanatory
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.
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.
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.
After adding the new tenant, the MDMS service needs to be restarted to read the newly added data.
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.
Naming Convention for Tenants Code
“Code”:“uk.citya” is StateTenantId.ULBTenantName"
Localization should be pushed for ULB grade and ULB name. The format is given below.
Localization for ULB Grade
Localization for ULB Name
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.
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.
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.
These data can be used to validate the incoming data.
After adding the new module data, the MDMS service needs to be restarted to read the newly added data.
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.
The new module can be added below the existing modules in the master config file.
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.
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.
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.
For deploying the changes(adding new data, updating existing data or deletion) in MDMS, the MDMS service needs to be restarted.
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.
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.
Configure master data management service
The MDMS 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. Instead of writing APIs and creating tables in different services to store and retrieve data that is seldom changed, the MDMS service keeps them in a single location for all modules and provides data on demand with the help of no more than three lines of configuration.
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
Adds master data for usage without the need to create master data APIs in every module.
Reads data from GIT directly with no dependency on any database services.
| Environment Variables | Description |
|---|---|
Deploy the latest version of the MDMS-service
Note: This video will give you an idea of how to deploy any Digit-service. Further you can find the latest builds for each service in out latest release document here.
Add conf path for the file location
Add master config JSON path
Note : See the Reference Docs for the values of conf path and master config.
The MDMS service provides ease of access to master data for any service.
No time spent writing repetitive codes with no business logic.
To integrate, the host of egov-mdms-service should be overwritten in the helm chart
egov-mdms-service/v1/_search should be added as the search endpoint for searching master data.
MDMS client from eGov snapshots should be added as mvn entity in pom.xml for ease of access since it provides MDMS request pojos.
Steps to migrate MDMS data to enable use of workbench UI v1.0
Follow the steps below to migrate the MDMS data to enable the use of Workbench UI v1.0.
Follow the steps below to generate the schema for Workbench UI v1.0:
Clone the migration utility: Start by cloning the migration utility from this .
Clone the MDMS Repository: Start by cloning the MDMS repository on your local machine.
Configure application.properties: Open the application.properties file in the workbench utility and configure it as follows:
Add the hostname of the environment.
Add the MDMS cloned folder path in the egov.mdms.conf.path.
Add master-config.json in masters.config.url.
Specify the output folder path for the created schema in master.schema.files.dir.
Port-forward MDMSv2 Service: Port-forward the MDMSv2 service to port 8094.
Run the Curl Command:
This command generates the schema and saves it in the path specified by master.schema.files.dir.
After generating the schema, you may need to update it with additional attributes:
Add x-unique Attribute: This defines unique fields in the schema.
Add x-ref-schema Attribute: Use this attribute if a field within MDMS data needs to refer to another schema.
Set Default Value for a Field: Use the default keyword to set default values.
To migrate the schema, use the following curl command:
To migrate data for a specific master/module name, use the following curl command:
Here is an example of a schema:
NOTE: To migrate data for a specific master/module name, use the following code changes in migrateMasterData
Follow the steps below to adopt the new MDMS -
Define the schema for the master that you want to promote to MDMS v2.
Ensure that the schema has a unique field (a unique field can also be composite) to enforce data integrity.
In case the data does not have unique identifiers e.g. complex masters like the one , consider adding a redundant field which can serve as the unique identifier.
Use the following API endpoint to create a schema - /mdms-v2/schema/v1/_create
Search and verify the created schema using the following API endpoint - /mdms-v2/schema/v1/_search
Once the schema is in place, add the data using the following API endpoint - /mdms-v2/v2/_create/{schemaCode}
Verify the data by using the following API endpoint - /mdms-v2/v2/_search
Learn how to setup DIGIT master data.
Reference - JSON Schema - Creating your first schemaNow, properties can be added under the schema definition. In JSON Schema terms, properties is a validation keyword. When you define properties, you create an object where each property represents a key in the JSON data that’s being validated. You can also specify which properties described in the object are required.
Reference - JSON Schema - Creating your first schema
| Input Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Input Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Input Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Input Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Output Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Output Field | Description | Mandatory | Data Type |
|---|---|---|---|
| Title | Description |
|---|---|
| Description |
|---|
| Description |
|---|
| Description |
|---|
To enable tenants the above data should be pushed in tenant.json file. Here "ULB Grade" and City "Code" are important fields. ULB Grade can have a set of allowed values that determines the ULB type, (, Municipality (municipal council, municipal board, municipal committee) (Nagar Parishad), etc). City "Code" has to be unique to each tenant. This city-specific code is used in all transactions. Not permissible to change the code. If changed we will lose the data of the previous transactions done.
"logoId": "", Here the last section of the path should be "/<tenantId>/logo.png". If we use anything else, the logo will not be displayed on the UI. <tenantId> is the tenant code ie “uk.citya”.
| Description |
|---|
Please check the link to create a new master
| Description |
|---|
ex: ///common-masters/ Here “pb” is the tenant folder name.
ex: ///TradeLicense/ Here “pb” is the tenant folder name and “TradeLicense“ is the module name.
ex: ////TradeLicense/ Here “amritsar“ is the ULB name and “TradeLicense“ is the module name. All the data specific to this module for the ULB are configured inside this folder.
| Description |
|---|
| Description |
|---|
| Title |
|---|
| Title |
|---|
tenantId
Unique id for a tenant.
Yes
String
filePath
file-path on git where master data is to be created or updated
Yes
String
masterName
Master Data name to be created or updated
Yes
String
masterData
content to be written on to the Config file
Yes
Object
tenantId
Unique id for a tenant
Yes
String
moduleDetails
module for which master data is required
Yes
Array
mdms
Array of modules
Yes
Array
apiId
unique API ID
Yes
String
ver
API version - for HTTP based request this will be same as used in path
Yes
String
ts
time in epoch format: int64
Yes
Long
action
API action to be performed like _create, _update, _search (denoting POST, PUT, GET) or _oauth etc
Yes
String
DID
Device ID from which the API is called
No
String
Key
API key (API key provided to the caller in case of server to server communication)
No
String
msgId
Unique request message id from the caller
Yes
String
requestorId
UserId of the user calling
No
String
authToken
//session/jwt/saml token/oauth token - the usual value that would go into HTTP bearer token
Yes
String
apiId
unique API ID
Yes
String
ver
API version
Yes
String
ts
response time in epoch format: int64
Yes
Long
resMsgId
unique response message-id (UUID) - will usually be the correlation id from the server
No
String
msgId
message-id of the request
No
String
status
status of request processing -
Enum: SUCCESSFUL (HTTP 201) or FAILED (HTTP 400)
Yes
String
code
Error Code will be a module-specific error label/code to identify the error. All modules should also publish the Error codes with their specific localized values in localization service to ensure clients can print locale-specific error messages. An example of an error code would be UserNotFound to indicate User Not Found by User/Authentication service. All services must declare their possible Error Codes with a brief description in the error response section of their API path.
Yes
String
message
English locale message of the error code. Clients should make a separate call to get the other locale description if configured with the service. Clients may choose to cache these locale-specific messages to enhance performance with a reasonable TTL (May be defined by the localization service based on tenant + module combination).
Yes
String
description
Optional long description of the error to help clients take remedial action. This will not be available as part of the localization service.
No
String
params
Some error messages may carry replaceable fields (say $1, $2) to provide more context to the message. E.g. Format related errors may want to indicate the actual field for which the format is invalid. Client's should use the values in the param array to replace those fields.
No
Array
egov.mdms.conf.path
The default value of folder where master data files are stored
masters.config.url
The default value of the file URL which contains master-config values
egov-mdms sample data - https://github.com/egovernments/egov-mdms-data/tree/DEV/data - Connect to preview [Download this and refer it's path as conf path value]
master-config.json - https://github.com/egovernments/egov-mdms-data/blob/DEV/master-config.json - Connect to preview [Refer to this path as master config value]
tenantId
Serves as a Key
moduleName
Name of the module to which the master data belongs
MasterName
The Master Name will be substituted by the actual name of the master data. The array succeeding it will contain the actual data.
