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

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