Generation API for Boundary

API Overview

Base URL: project-factory/v1/

Endpoint: /data/_generate

Method: POST

Request Structure:

Body Parameters:

• RequestInfo: Object containing RequestInfo

• Query Parameters:

  • tenantId: Tenant

  • type: Type of Resource (e.g., boundary)

  • forceUpdate: Boolean type (either true or false)

  • hierarchyType: Name of Boundary Hierarchy

  • campaignId: CampaignId

Response Structure:

Success Response:

{
   "ResponseInfo": {
       "apiId": "egov-bff",
       "ver": "0.0.1",
       "ts": 1716878176955,
       "status": "successful",
       "desc": "new-response"
   },
   "GeneratedResource": [
       {
           "id": "5ef5547e-414f-4164-9c12-644716e4fa71",
           "fileStoreid": null,
           "type": "boundary",
           "status": "inprogress",
           "hierarchyType": "ADMIN",
           "tenantId": "mz",
           "auditDetails": {
               "lastModifiedTime": 1716878176947,
               "createdTime": 1716878176947,
               "createdBy": "867ba408-1b82-4746-8274-eb916e625fea",
               "lastModifiedBy": "867ba408-1b82-4746-8274-eb916e625fea"
           },
           "additionalDetails": {
               "Filters": null
           },
           "count": null
       }
   ]
}

Flow

1. Client Initiates Request:

   • The client initiates a dataGenerate request to the Project Factory Service.

2. Validation of Request:

   • Schema Validation: Validate against generateRequestSchema.

   • Tenant ID Validation: Ensure tenantId matches in query and RequestInfo.userInfo.

   • Force Update: Default to "false" if missing.

   • Hierarchy Type Validation: Validate hierarchyType for the tenantId.

3. Processing of Generate Request:

   • Fetch Data from DB:

     • Retrieve data using getResponseFromDb(request).

   • Modify Response Data:

     • Modify the fetched data with getModifiedResponse(responseData).

   • Generate New Entry:

     • Create a new entry with getNewEntryResponse(request).

   • Expire Old Data:

     • Update the status of old data to expired using getOldEntryResponse(modifiedResponse, request).

   • Persist Data Changes:

     • Call updateAndPersistGenerateRequest(newEntryResponse, oldEntryResponse, responseData, request).

       • Purpose:

         • If forceUpdate is true and data exists: Mark existing data as expired and create new data.

         • No data exists or force update is true: Generate new data.

         • If forceUpdate is false and data exists: Return the old data.

4. Boundary Data Processing:

   • Generate new Boundary Data:

     • Fetch Boundary Relationships.

     • If no boundary is found, generate an empty boundary sheet.

     • Fetch Filters from CampaignId and generate Boundary Data based on those Filters.

       • If Filters is null, it will generate the whole Boundary Data.

   • After the Boundary Sheet has been generated, append the ReadMeSheet.

   • Generate different tabs based on any boundary level configured (here District).

5. Generating Different Boundary Templates based on Campaign Type

• Based on environment variable enableDynamicTemplateFor (which will have campaign types for which u want boundary target columns to be dynamic based on the number of unique delivery conditions and not default from mdms ). i.e. ( if SMC is configured then it will have target columns based on unique delivery conditions).

• Otherwise it will fetch configurable columns from mdms present for each campaign type from schema -[HCM-ADMIN-CONSOLE.adminSchema].

• Here is a sample data from the given schema having configurable columns for Campaign SMC-

 "mdms": [
        {
            "id": "536f6de8-8c90-4631-b401-5a3beabf4893",
            "tenantId": "mz",
            "schemaCode": "HCM-ADMIN-CONSOLE.adminSchema",
            "uniqueIdentifier": "boundary.MR-DN",
            "data": {
                "title": "boundary",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "numberProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_SMC_AGE_3_TO_11",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at village level - Age 3 to 11 Months (Mandatory and to be entered by the user)",
                            "orderNumber": 2
                        },
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_SMC_AGE_12_TO_59",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at village level - Age 12 to 59 Months (Mandatory and to be entered by the user)",
                            "orderNumber": 3
                        }
                    ],
                    "stringProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_BOUNDARY_CODE",
                            "type": "string",
                            "isRequired": true,
                            "description": "Boundary Code",
                            "orderNumber": 1,
                            "freezeColumn": true
                        }
                    ]
                },
                "campaignType": "MR-DN"
            },
            "isActive": true,
            "auditDetails": {
                "createdBy": "63a21269-d40d-4c26-878f-4f4486b1f44b",
                "lastModifiedBy": "63a21269-d40d-4c26-878f-4f4486b1f44b",
                "createdTime": 1718171965428,
                "lastModifiedTime": 1718171965428
            }
        }
    ]

1. Handle Error:

   • Update status to failed, add error details, log the error, and produce a message to the update topic.

2. Downloading the generated boundary template through /data/_generate API:

   • One can get the filestoreId through the /data/_download API which will fetch from db using the id from the response of /data/_generate API.

Note:

Downloaded Template will have one ReadMe sheet, one Boundary Data Tab, and all other tabs on a number of unique districts(or whichever level configured).

Boundary Bulk Upload for Campaign

Boundary Bulk Upload Overview:

This documentation outlines the process and components of bulk uploading boundaries for a campaign. It covers the proper format of the Excel sheet, unique code generation, functions for boundary entity creation, boundary relationship creation, localisation, and API details.

Sequence Diagram

Format of Excel for Boundary Bulk Upload

The Excel sheet should be formatted as follows:

Unique Code Generation

Unique codes are auto-generated for each boundary level as follows:

If there are two districts (boundaries at the same level) with the same name (for example, BLR) under different parent-level boundary, the names will be updated to BLR, BLR-01, and so on.

getAutoGeneratedBoundaryCodes Function

Purpose:

Generate auto-generated boundary codes based on boundary list, child-parent mapping, element codes map, count map, and request information.

Parameters:

• boundaryList: List of boundary data.

• childParentMap: Map of child-parent relationships.

• elementCodesMap: Map of boundaries to its corresponding auto generated unique codes.

• countMap: Map of counts for each boundaries.

• request: HTTP request object.

Returns:

• Updated element codes map.

Steps:

1. Initialise Column Data:

   • Initialise an array to store column data.

2. Extract Unique Elements:

   • Iterate through each row of the boundary list.

   • Extract unique elements from each column.

3. Generate Boundary Codes:

   • Iterate over columns to generate boundary codes.

   • Check if the element code exists in the element codes map.

   • If not, generate a new code based on parent-child mapping and sequence.

   • Store the code of the element in the element codes map.

4. Default Code Generation:

   • Generate default code if parent code is not found.

5. Updated Element Codes Map

   Return Updated Boundary Data - Auto-Generated Code Map.

Boundary Entities Creation

Boundary entities are created chunk-wise, with each chunk consisting of 200 codes.

Create Boundary Entities

Purpose:

To create new boundary entities in the system from provided boundary codes.

Steps:

1. Convert Boundary Map:

   • Change the boundary map to a list of objects with key and value.

2. Prepare Request:

   • Set up the request details and initialise lists for boundaries and existing codes.

3. Chunk Boundary Codes:

   • Divide the boundary codes into smaller groups.

4. Fetch Existing Boundaries:

   • Check the system for existing boundary codes and collect them.

5. Identify New Boundaries:

   • Determine which boundary codes are new and add them to the list of boundaries to create.

6. Create New Boundaries:

   • If there are new boundaries, send them to the system in groups and log the results.

7. Handle Existing Boundaries:

   • Log a message if all boundaries already exist.

8. Error Handling:

   • Manage any errors that occur and provide a relevant error message.

Boundary Relationship Creation

Create Boundary Relationship

Purpose:

To create boundary relationships in the system from provided boundary codes and their parent-child mappings.

Steps:

1. Convert Boundary Map:

   • Transform the boundary map to a list of {key, value} objects.

2. Initialise Request:

   • Prepare the request details and activity messages array.

3. Fetch Existing Relationships:

   • Retrieve existing boundary relationships and extract their codes.

4. Identify and Create Relationships:

   • For each boundary code, check if it exists. If not:

     • Prepare the boundary relationship data.

     • Confirm the parent boundary creation.

     • Create the boundary relationship.

5. Handle Existing Relationships:

   • If all relationships already exist, log a validation error.

6. Attach Activity Messages:

   • Add activity messages to the request body.

7. Error Handling:

   • Catch, log, and handle errors appropriately.

Localisation Upsert of Codes

Boundary codes are localised to their corresponding names as specified in the uploaded Excel sheet.

Boundary Bulk Upload Upsertion

To add more boundaries after the initial upload, use an Excel sheet that includes existing boundary codes. New boundaries without codes will be created in the same way as the first upload.

API for Boundary Bulk Upload

API request for boundary bulk upload:

bashCopy codecurl --location 'http://localhost:8080/project-factory/v1/data/_create' \
--header 'authority: unified-dev.digit.org' \
--header 'accept: application/json, text/plain, */*' \
--header 'accept-language: en-GB,en-US;q=0.9,en;q=0.8' \
--header 'content-type: application/json' \
--header 'cookie: _ga_XBQP06FR8V=GS1.1.1691570094.3.1.1691570094.60.0.0; _ga=GA1.1.2124364284.1689669598; _ga_P1TZCPKF6S=GS1.1.1691648339.2.0.1691648339.60.0.0; __cuid=fe28d9c8c84c4d2487b9cb6c9e4cdec1; amp_fef1e8=f4a3f3ed-50f2-409b-be4f-a1ce1dbb59f2R...1hgs4r9gr.1hgs4robc.nu.1r.pp; _ga_H9YC8FEN6F=GS1.1.1701751656.77.1.1701751677.39.0.0' \
--header 'origin: https://unified-dev.digit.org' \
--header 'referer: https://unified-dev.digit.org/works-ui/employee/measurement/update?tenantId=pg.citya&workOrderNumber=WO/2023-24/000894&mbNumber=MB/2023-24/001252' \
--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: "Linux"' \
--header 'sec-fetch-dest: empty' \
--header 'sec-fetch-mode: cors' \
--header 'sec-fetch-site: same-origin' \
--header 'user-agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.36' \
--data-raw '{
    "RequestInfo": {
        "apiId": "Rainmaker",
        "authToken": "e45445a1-6891-4a76-a4e6-528e1dd24946",
        "userInfo": {
            "id": 1284,
            "uuid": "867ba408-1b82-4746-8274-eb916e625fea",
            "userName": "EMP57",
            "name": "Jagan",
            "mobileNumber": "6667776662",
            "emailId": "xyz@egovernments.org",
            "locale": "string",
            "type": "EMPLOYEE",
            "roles": [
                {
                    "name": "System Administrator",
                    "code": "SYSTEM_ADMINISTRATOR",
                    "tenantId": "mz"
                },
                {
                    "name": "Campaign Manager",
                    "code": "CAMPAIGN_MANAGER",
                    "tenantId": "mz"
                },
                {
                    "name": "Localisation admin",
                    "code": "LOC_ADMIN",
                    "tenantId": "mz"
                },
                {
                    "name": "MDMS Admin",
                    "code": "MDMS_ADMIN",
                    "tenantId": "mz"
                }
            ],
            "active": true,
            "tenantId": "mz",
            "permanentCity": "Amritsar"
        },
        "msgId": "1710912592752|en_IN",
        "plainAccessRequest": {}
    },
    "ResourceDetails": {
        "type": "boundary",
        "tenantId": "mz",
        "fileStoreId": "be52ce1a-bc25-4328-91bc-a682079abb59",
        "action": "create",
        "hierarchyType": "ADMIN",
        "additionalDetails": {},
        "campaignId": "5d721d03-bdf5-4021-86ff-107e61eb7abb"
    }
}'

Note: Ensure the API endpoint, headers, and payload are customised as per your environment and requirements.