About HCM Console

The Health Campaign Management (HCM) app has achieved remarkable success, and we want to build on this momentum. While setting up a campaign currently involves considerable developer support, we are turning this into an opportunity for improvement. In this regard, we are introducing the HCM Console, an innovative solution designed to empower users to create and manage campaigns effortlessly, enhancing overall efficiency and streamlining the process.

Who is the HCM Console for?

HCM Console is designed for individuals familiar with the on-ground execution of health campaigns. These users understand key terms like cycles, deliveries, doses, boundaries, and campaign hierarchies. However, they are not expected to be tech-savvy, and we aim to eliminate the need for them to grasp technical concepts like JSON files, schemas, APIs, MDMS, services, or intricate UI/UX designs. In short, HCM Console prioritises intuitive user experience with extensive guidance throughout the campaign creation and execution process.

Key Features

Version 0.1 focuses on empowering users to:

• Initiate campaigns: A clear landing page will provide easy access to the "Setup Campaign" and "My Campaign" options.

• Define campaign details: A dedicated page will allow users to customise crucial campaign parameters.

• Set delivery rules: Users can establish delivery rules, including options to record side effects, reasons for refusal, and referrals.

• Utilise Excel data: An upload functionality will enable seamless import of facility and user data from Excel sheets.

• Review and confirm: Clear review and success screens will guide users through the final steps of campaign creation.

• Save drafts: Users can conveniently save incomplete campaigns as drafts for completion later.

These features, cumulatively, will allow users to create the core structure of their campaigns within version 0.1. Subsequent releases will introduce advanced functionalities like the form engine for customising individual and household registration forms, and enhanced data capture functionalities for side effects, refusals, and referrals. It is important to note that the HCM app will continue to support these advanced features in the interim, and the impel team will be responsible for any necessary changes or customisations until their official release within the Campaign Manager.

By introducing the HCM Console, we aim to significantly reduce the time and effort required to set up campaigns within the HCM app, empowering users to take greater ownership and expedite campaign implementation. This user-centric approach translates to enhanced campaign efficiency, allowing our team to focus on further optimising and scaling the HCM app for even greater impact.

Here are the articles in this section:

• User Interface Design

• Create New Campaign

• My Campaign

Here are the articles in this section:

High Level Design

Low Level Design

Here are the articles in this section:

• User manual

• Functional Specifications

Click here to know more.

This allows users to fill in all the campaign details and create a new campaign.

Click on the following links to learn more:

In the Campaign Details stepper, there are 2 screens:

• Campaign Type

• Campaign Name

1. Campaign Type

This is the first screen when the user clicks on the set-up campaign. In this screen, a user can select the campaign type and the beneficiary will be prepopulated from the MDMS. It is a mandatory field to set up a campaign.

Here, the dropdown will show the list of campaign types that are present in the MDMS. We will fetch the MDMS data from:

MDMS:

File Path:

2. Campaign Name

This screen comes after the campaign type. This step is crucial for saving your campaign as a draft, as the name serves as a unique identifier. After clicking on 'Next', the name will be saved and the user can check from the draft.

File Path:

This screen asks a user to fill in the start and end date of the campaign.

FilePath:

This screen allows the user to create a new hierarchy and then upload the boundary data in bulk.

1. Upload Boundary Screen

This screen allows the user to select the hierarchy. According to that, a template is downloaded in which the user needs to fill in the boundary data. If the hierarchy type is not present, then the user can make a new hierarchy using this screen.

1. Create Boundary Hierarchy

The user needs to give a hierarchy name, and levels according to the hierarchy.

UI Validation: Headers should be according to the template downloaded.

API Details

Find the links below:

Overview

This release will let the user - who is a System Administrator - set up campaigns on the HCM App and will reduce the current setup time for a given campaign from about 15 days to about 2-3 days.

Release Highlights

Known Issues

Some of the known issues related to this release are:

1. Usability of the Excel templates: The usability of the Excel templates for setting targets, facility data, and user data could be improved as the inputs in the Excel from the users are not restricted in the sheet and could lead to errors.

Upcoming Release Features

1. Decentralising the data setup process.

2. Changing dates for ongoing campaigns from the Console.

3. Allowing users to configure app features.

These sheets have been created based on following assumptions :

Url - https://unified-qa.digit.org

locale - en_MZ

msgId - 1710912592752|en_MZ

hierarchy Type - ADMIN

project Type - LLIN-mz

Steps

1. Import environment variable file and collection file in Postman.

1. Successful run scenario:

• With a valid range of numbers in the 'Target' column.

Example:

1. Negative run scenario:

• With an empty 'Target' column.

Example:

• With invalid values in the 'Target' column (max, min, date, negative, zero, decimal values).

1. Collection runner result - Passed.

This screen allows a user to select different boundary details required for the campaign creation. Here, we show the boundary types based on the hierarchy type which is present in the MDMS, MDMS file path : https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/mz/health/hcm-admin-console/hierarchyConfig.json

If we want to fetch the hierarchy type from the MDMS, use the following API:

 const reqCriteria = {
    url: `/boundary-service/boundary-hierarchy-definition/_search`,
    changeQueryName: `${hierarchyType}`,
    body: {
      BoundaryTypeHierarchySearchCriteria: {
        tenantId: tenantId,
        limit: 2,
        offset: 0,
        hierarchyType: hierarchyType,
      },
    },
  };

To fetch the hierarchy definition, this is mentioned in the setUpCampaign page: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js

After calling the hierarchy, the response is stored in the session storage under the name:

HCM_CAMPAIGN_MANAGER_UPLOAD_ID

After it is stored, we can use it in the "Selecting Boundaries" component to show the different boundary types present: The FilePath for it is the following: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/SelectingBoundaries.js The boundary type in the screen is shown upto the lowest hierarchy level which is also configured from the MDMS. The options in the hierarchy is shown using the following:

const reqCriteriaBoundaryTypeSearch = Digit.CustomService.getResponse({
          url: "/boundary-service/boundary-relationships/_search",
          params: {
            tenantId: tenantId,
            hierarchyType: hierarchy,
            boundaryType: boundaryType,
            parent: parentCode,
          },
          body: {},
        });

In the selection boundary screen, we show options according to parent boundary type using the above API. Some validations for this screen:

• All the boundary types in the screen are mandatory.

• Lower level boundary type is mandatory if a user has selected the above levels

After the boundaries are selected, the Generate API is called with a delay of 3 seconds when the user clicks on next, using the following hook: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/hooks/useGenerateIdCampaign.js

Handling boundary data API performance:

We have impemented Parallel API calls have been implemented for boundary data search to optimise the performance better. We have added all the API search from the loop and calling parallel calls at once and storing the respective data in respective boundaryType.

For the next time when we are making boundary search api calls, we are checking locally whether data is present otherwise calling the API search only for the required data to optimise it better.

All the above mentioned logic have been added in useParallelSearch.js hook.

Link: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/hooks/useParallelSearch.js

API Details

The logic for the step-by-step screens, stepper functionality, storing data in localStorage, creating/updating campaigns, and restructuring API data back into localStorage is all managed within SetupCampaign.js.

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js

All screens are present in the given configuration. Link: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/configs/CampaignConfig.js

In the configuration:

• stepCount represents the step number. Multiple configuration objects can share the same stepCount.

• skipAPICall: If this is set to true, the API call for the screen is skipped.

• sessionData: Local storage data is passed in custom props, allowing for custom logic to be added to the screens as needed.

export const CampaignConfig = (totalFormData, dataParams) => {
  return [
    {
      form: [
        {
          stepCount: "1",
          key: "1",
          name: "HCM_CAMPAIGN_TYPE",
          body: [
            {
              isMandatory: false,
              key: "projectType",
              type: "component",
              skipAPICall: true,
              component: "CampaignSelection",
              withoutLabel: true,
              disable: false,
              customProps: {
                module: "HCM",
                sessionData: totalFormData,
              },
              populators: {
                name: "projectType",
              },
            },
          ],
        },
        ``````

In setup campaign, we have functions to perform specific logic.

• loopAndReturn: This function takes the delivery rule conditions coming from API response and restructure the data in local storage format.

• cycleDataRemap: This function takes the delivery rules data coming from API response and return array of object of start date and end date based on cycles.

• reverseDeliveryRemap: This function take the deliveryConditions from API response and return the structure of delivery data.

• groupByTypeRemap: This function create the local structure of boundaries.

• updateUrlParams: This function is using to update the url.

New Campaign & Implementing Local Storage

• In a new campaign, we update the total form when a user clicks on next after entering the data.

• After updating the total form data, we store the data in localStorage.

• We also call the API to draft the data in case a user wants to come back and resume the campaign.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L545

Draft Campaign & Data Fetching

• When a user clicks on the draft campaign, he/she can fetch campaign data from the response.

• After getting a response, one can restructure the data in screen format and store in the local storage.

• After updating, the user is redirected to the last screen where additional details are stored in response.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L327

Stepper

• Based on screens, a user can filter the configuration and show the the stepper based on the configuration.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L1159

Table of Contents:

Background

Target Audience

Objectives

Assumptions and Validations

Role-Action Mapping

Specifications

Risk and Limitation

Out of Scope

Design

Background

As the adoption of the HCM app is beginning to increase, a significant piece of feedback we have received is that setting up any campaign on the HCM app currently demands a minimum of two weeks of development effort. There is a consensus that the lead time for campaign setup needs to be shortened.

The concept involves transforming the HCM app into a SaaS-like product, featuring a console that empowers the admin user, in this case, the campaign manager, to effortlessly create and execute campaigns on the HCM app. The Campaign Manager product will offer the admin user the flexibility to select and customise specific components of the HCM app according to their preferences.

Target Audience

The user persona for this product is anyone who knows how a given health campaign works on the ground. They have a decent understanding of terms and concepts such as Cycles, Deliveries, Doses, Boundaries, Hierarchy, and other Campaign-related terminologies.

The challenge is around the ability of the user to use and understand technology. The user is not tech-savvy and is not expected to know concepts of JSON Files, Schemas, APIs, MDMS, Services, and any other such terms. The user is also not expected to be well-versed in high-fidelity UX/UI and needs every bit of hand-holding possible during the process of creating and running a campaign.

Objectives (of this release)

1. Reduce set-up time for new campaigns.

2. Reduce dependence on engineering resources for setting up a new campaign.

3. Provide the power to the end user for customising campaigns.

Assumptions and Validations

Role-Action Mapping

Specifications

Risk and Limitations

1. Boundary data: If the boundary data is updated regularly, then the analytics for the long-term will not have data sanity.

2. Users might have issues uploading multiple Excel sheets for targets, facility, and user data.

Out of Scope for v0.1:

1. Boundary data mapping and hierarchy changes through UI will not be allowed. If the user wants to edit/add new boundary data, it will be raised through the L1 team.

2. Editing of campaign data, once the campaign is live through the HCM Console UI, is not allowed. The changes will have to be routed through the implementation team.

3. Language selection for the app will not be a part of this release.

Design

Click here to learn more.

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

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

Overview

Project-factory assists users in generating the seed data essential for the campaign creation process in DIGIT HCM and in establishing relationships between all resources. The Project Factory Service manages project-type campaigns by handling the creation, updating, searching, and campaign setup processes. This documentation details the available APIs, their endpoints, request and response structures, and internal processing flows.

Pre-requisites

• Knowledge of JavaScript (preferably ES6).

• Knowledge of Git or any version control system.

• Knowledge of RESTful web services.

• Knowledge of the Kafka and Postgres.

• Knowledge of eGov-mdms service, eGov-persister, eGov-idgen, eGov-indexer, and eGov-user will be helpful.

Base URL

project-factory/v1/

APIs Overview

Create Campaign

TO DO add other information

DB DIAGRAM

Swagger :

Configs and helm chart details :

• Persister config : https://github.com/egovernments/configs/blob/UNIFIED-UAT/health/egov-persister/project-factory-persister.yml Helm chart details : https://github.com/egovernments/DIGIT-DevOps/blob/unified-env/deploy-as-code/helm/charts/health-services/project-factory/values.yaml

• Configure the role CAMPAIGN_MANAGER for project-factory in the ‘ACCESSCONTROL-ROLES’ module.

• Configure the action id(s) with the corresponding role code ‘ACCESSCONTROL-ROLEACTIONS’ module.

• For Project Factory Service Role-Action mappings are as follows in the Dev environment.

Additional APIs being used are:

• Configure all the MDMS data for project factory service as done in the QA environment.

Data to configure :

• Attribute Config

• Boundary Schema

• Delivery Config

• Facility Schema

• Gender Config

• Mail Config

• Operator Config

• Product Type

• User Schema

Refer to the following:

https://github.com/egovernments/egov-mdms-data/tree/UNIFIED-QA/data/mz/health/hcm-admin-console

IdGen Config:

Make sure the id format is configured in the ‘IdFormat.json’ file of the ‘common-masters’ module.

Below is what is currently configured in the QA environment.

{
    "format": "CMP-[cy:yyyy-MM-dd]-[SEQ_EG_CMP_ID]",
    "idname": "campaign.number"
}

Environment variables Below are the variables that should be configured well before deployment of the project factory service build image.

• Add these ‘db-host’,’db-name’,’db-url’,’domain’ and all the digit core platform services configurations (Idgen ,persister, filestore, etc.) in respective environments yaml file.

• Add project factory service related environment variables’ value like the way it's done in the QA environment yaml file. (Search for project-factory)

• https://github.com/egovernments/DIGIT-DevOps/blob/unified-env/deploy-as-code/helm/environments/unified-qa.yaml

• https://github.com/egovernments/DIGIT-DevOps/tree/unified-env/deploy-as-code/helm/charts/health-services/project-factory

• Heath-hrms, health-project, health-individual and facility should have specified heap and memory limits as mentioned below

heap: "-Xmx256m -Xms256m"
memory_limits: 512Mi

• Make sure to add the DB(Postgres and flyway) username & password in the respective environment secret yaml file the way it's done here.

• Make sure to add the digit core services related secrets are configured in the respective environment secret file the way it's done here.

• Click here for localisation details.

• Click here to get the Postman Collection

These sheets have been created based on following assumptions:

URL - https://unified-qa.digit.org

locale - en_MZ

msgId - 1710912592752|en_MZ

hierarchy Type - ADMIN

project Type - LLIN-mz

Steps

1. Import the environment variable file and collection file in Postman.

1. Successful run scenario:

• When a user adds valid data to the user file.

Example:

• When a user uploads a valid sheet with a missing row in between

Example:

1. Negative run scenarios:

• With an empty "Name of the Person (Mandatory)" column.

Example:

• With less than 2 letters in "the "Name of the Person (Mandatory)" column.

Example:

• Without phone number.

Example:

• With invalid values in the phone number column.

Example:

• With the same phone number.

Example:

• Without data in the role column.

Example:

• Without data in the Employment Type column.

Example:

• With an empty Boundary Code column.

Example:

• With invalid values in the Boundary Code column.

Example:

Test Run collection -Passed

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": "[email protected]",
            "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.

These sheets have been created based on following assumptions :

Url -

locale - en_MZ

msgId - 1710912592752|en_MZ

hierarchy Type - ADMIN

project Type - LLIN-mz

1. Import environment variable file and collection file in Postman:

1. Successful run scenarios:

• Valid file with correct values in all columns.

Example:

• With a valid file with a missing row in between.

Example:

1. Negative run scenarios:

• With an empty "Facility Usage" column.

Example:

• With all inactive values for the "Facility usage" column.

Example:

• With an empty "Boundary Code" column.

Example:

• With duplicate names in the "Facility Name" column.

Example:

• With an empty "Facility Name" column.

Example:

• With an invalid value in the "Facility Name" column.

• With an empty "Facility Type" column.

• With an empty "Facility Status" column.

• With empty and invalid values in the 'Capacity' column (max, min, date, negative, zero values).

• With empty and invalid values in the "Boundary Code" column.

1. Collection runner result -passed:

The HCM Console will help admins set up a campaign on the Digit HCM App. This will help an admin to reduce the campaign setup time which is about 15 days (without the console) to less than 3 days to less than 3 hours (with the console). Further, v0.1 of HCM Console will also aim at reducing the dependencies on the implementation team for setting up campaigns and campaign data on the DIGIT HCM app and provide this capability directly to the end user.

Key Features

Ability to set up a campaign with the following features:

• Homepage with "Setup Campaign" and "My Campaign" CTAs

• Campaign details page

• Boundary details

• Delivery details

• Excel upload for targets, facility, and user data setup

• Review and success screens

• Ability to save campaigns as draft

User Role

Who can use HCM Console?

User Flow: Steps to Use HCM Console

You must first select the language before you can log in. Currently, 3 languages are supported for the HCM Console. They are:

• English

• Portuguese

• French

Select the preferred language and click on 'Continue' to go to the login page.

(Note: Getting an account on HCM Console: The admin will have their account created by the implementation team and will be provided with a username and password to log in to the account.)

On the login page, add the "User Name", 'Password', and the 'City' you are working in to log in to HCM Console.

Once you log in, follow the steps shown below to set up a campaign using HCM Console or view the ones already set up:

Homepage (Setup Campaign and My Campaign): After logging in, you will see 2 actions you can perform on the homepage. You can click on “My Campaigns” or “Setup Campaigns”.

My Campaign:

If you click on “My Campaigns” you will see:

a. A list of all the campaigns that the admin has created until now for future dates, past dates, or current dates, including drafted campaigns. There can be 5 statuses in which a campaign can be in, which are:

1. Ongoing

2. Completed

3. Upcoming

4. Drafts

5. Failed

b. There will be 5 columns for each campaign:

1. Campaign Name

2. Campaign Type

3. Beneficiary Type

4. Campaign Start Date

5. Campaign End Date

If you click on the name of the campaign, you will be redirected to the summary page.

(Note: The admin can input a partial search on the "My Campaign" page where if the admin adds only the first 2 letters of a campaign, the results should show all the campaign names containing those 2 letters in the search bar. If the campaign is in draft, the admin can start editing from the review page. For completed and ongoing campaigns, the admin will have a view-only experience.)

Setup Campaign:

If you click on “Setup Campaign” you will see the basic Campaign Details page. There are 7 actions you can perform when you click on Setup Campaign:

1. Campaign Details

2. Boundary Details

3. Delivery Details

4. Target Details

5. Facility Details

6. User Details

7. Summary.

Each action and its steps are explained below:

1. Campaign Details

On the Campaign Details page, you will see a list of questions which you will have to answer:

Which is the type of campaign you want to run? (This is a mandatory field for moving to the next screen).

This question will allow you to select any one of the preloaded campaign types. If there are campaigns that are not there in the list, they will first need to be added from the backend with data that has been agreed upon by stakeholders. Based on the selected campaign, the following data will be prefilled in the next steps:

1. Beneficiary Type (Campaign details step)

2. Number of Cycles and Deliveries in each Cycle (Delivery step)

3. Product delivered in each delivery for each cycle based on the corresponding delivery parameters (Age, Weight, Height, Gender) (Rule Engine Step)

Once you select the campaign type, click on 'Next'.

What is the name of your campaign? (This is a mandatory field for moving to the next screen): The answer to this question will be used as the name of the campaign for the reference purpose of the user.

(Note: The campaign will automatically be saved as a draft once you provide a unique name for the campaign.)

Once you enter the "Name of the Campaign", click on 'Next'. You will move on to the Boundary Details page.

2. Boundary Details

This step will enable you to select the existing boundary data in the system. (This is a mandatory field for moving to the next screen). The boundary data will have to be set up in the system beforehand at the time of instance creation and the same boundary data should be reused by the user for all campaigns in a given instance.

(Note: If you have not selected boundaries, you will not be allowed to move on to the next steps. For example: If the boundary data is set up for Mozambique, the user will see the whole boundary mapping for Mozambique that is available on the system. If there is a need for change, we will provide the contact information for the L1 team to update the boundary and the L1 team will update the boundary data.)

The boundary selection for a campaign will happen through a mapped checkbox field as shown below. There is a drop-down-based selection for each level of the hierarchy:

(Note: If a given boundary is selected in one level of the hierarchy, the next level will show boundaries mapped to only the ones selected in the previous level. You will not be able to make any selection at a given level without selecting the boundaries in the level above. If you are creating a new boundary data by raising a request with the L1 team, the UI will have only the updated boundary hierarchy type.)

After you have selected the country, province, district, and post administrative, click on ‘Next’. This will take you to the Delivery Details page for the campaign.

3. Delivery Details

On the delivery details page, you will configure the following:

1. Campaign start and end dates

2. Number of cycles and number of deliveries in each cycle of the campaign

3. Configuring dates for each cycle

4. Configuring parameters for delivery rules

5. Configuring resources for delivery

Select the start date and end date of the campaign and click on ‘Next’.

(Note: The start and end dates of the campaign will define the window in which the campaign will remain active on the system and the users of the app will be allowed to login only during the selected campaign dates.)

You will come to the screen that shows the number of cycles and deliveries in each cycle of the campaign (These are mandatory fields for moving to the next screen): You will see the number of cycles and deliveries pre-configured based on the campaign type selected by the user in the first step. If you choose to increase or decrease the number of cycles, you can do so. The maximum number of cycles and deliveries can be up to 5.

Dates for each cycle (These dates are non-mandatory for moving to the next screen): You will add the start and end dates for each cycle. If you do not add these dates, you can still move to the next screen by clicking on 'Next'.

The next page is on Configure Conditions for Delivery:

Conditions for Individual-based Campaigns:

You will see all the conditions pre-configured for the selected individual-based campaign, but you can choose to change the conditions if needed.

Based on the number of cycles and deliveries in each cycle, you will see the exact number of tabs for cycles and deliveries. If you go back and reduce the number of cycles or deliveries, the last cycle/delivery will be deleted first and all the rules will also be deleted along with it.

Selecting Attributes: After this, you will have to configure conditions using the following attributes:

• Age (in months)

• Weight (in kgs)

• Height (in cms)

• Gender (Male or Female) - When this attribute is selected, you can only select “Equals To” in the operator field and the input field should be set to Male and Female only as a single dropdown selection.

If you want to configure a condition having multiple attributes, you can click on “Add More Attributes” which will open up the selector block again.

Selecting Operators: You can choose to select the following operators to set rules:

• IN BETWEEN (if this is selected, you should see 2 input boxes for value)

• GREATER THAN

• GREATER THAN EQUAL TO

• LESS THAN EQUAL TO

• LESS THAN

• IS EQUAL TO

Configuring Resources: Once you have selected all the attributes, operators, and values basis which the deliveries have to be made, you can click on configure resources which will open a pop-up that will have the following:

• Product to be delivered

• Count for each product - This is a numeric counter only and cannot be 0.

• Add resources CTA to add multiple resources for the rule being configured.

• Can’t find your product in the list? Add New Product as subtext.

• The “Confirm Resources” button to confirm selected resources for a given rule.

If you are not able to find the product variant of your desired choice, you will be allowed to create a new product. If you click on “Can't fnd your product on the product list?”, you are redirected to a new tab where you will fill the following fields.

1. Product Name: Should be the name of the resource. (Alphanumeric with a limit of 100).

2. Product Type: Dropdown which can have the following options: Medicine, Bednet, Tonic.

3. Product Variant: Ideally this should have the grammage of the formulation (Alphanumeric with a limit of 100).

Once you have saved the new product by selecting “Confirm Addition of Products”, you will see a success message. You will also be redirected to the rule setting page, where you will see the new product added in the “Product to be Delivered" dropdown.

(Note: If the admin has added some products already (let’s say 4) and then plans on adding a new product to the list after he/she has added the new product(s) and gets redirected to the “Delivery Rules” page, the admin will still see the 4 products previously added in the pop-up.)

Conditions for Household-based Campaigns:

Currently, we only support LLIN bednet campaigns as a household-based campaign. In this case, the user will only have to configure 2 attributes:

• Number of beneficiaries per bednet

• Maximum number of bednets per household

(Note: The add new condition button for bednet campaigns will be disabled and will have only 2 attributes in the dropdown, that is, the number of beneficiaries per bednet, and the maximum number of bednets per household.)

Once you have set the delivery rules, and clicked on ‘Next’, you will move to the Target Details page.

4. Target Details

Here, you will set targets for the campaign by default at the lowest level of the hierarchy structure (This is a non-mandatory step for moving to the next screen). This will be achieved by an Excel upload as explained below:

To set targets, click on “Download Template” in the pop-up that appears as soon as you arrive on this screen. You will download the template having all the boundaries in the Excel with an empty column for setting targets.

(Note: Each campaign will have its own target setting template: For example, bednet campaign will have its own template, and SMC campaign will have its template.)

The first tab/sheet will be the “Read Me” tab and will have the information on how you can set the targets for each village selected in the boundary selection screen.

The district-wise sheets will have the following structure:

Target Data Template (Bednet Campaign)

Target Data Template (SMC Campaign)

(Note: All the villages in the Excel will be listed based on the district they belong to, with one tab for each district having a list of the villages under them. For example, if you have selected 20 districts, you will see 20 tabs (one for each district) having all the villages belonging to that particular district. Target numbers assigned for a given boundary are for the complete campaign and not just for each cycle.)

Once you have uploaded the targets, click on 'Next' to move to the Facility Details page.

5. Facility Details

Setting up the facility data will include downloading and uploading the list of facilities (This is a non-mandatory step for moving to the next page):

Case 1: Facility Data is not created in the system:

• You will see a pop-up to download the Excel sheet.

• The facility Excel file will be downloaded when you click on the ‘Download’ button. The template for the Excel is here.

• The Excel will have 2 sheets: 1) List of Available Facilities, 2) List of Campaign Boundaries. The second sheet will have the list of campaign boundaries with boundary codes which you can copy to the first sheet to assign boundaries to facilities.

• In the case where there is no facility data available in the facility registry , the “List of Available Facilities” sheet will have no data but will have 7 column headers to capture facility details which are:

• When there is no facility data in the system, you need to add the Facility Name (must be unique), Facility Type (Warehouse/Health Facility), Facility Status (Temporary/Permanent), Capacity (Number input), Boundary Codes which are associated with a given facility and Facility Usage Status (Active/Inactive).

• If a facility is associated with 2 or more boundaries, add all the boundary codes for that facility in the boundary code column separated by commas.

• The entry of "Active" or "Inactive" in the column "Facility Usage" will decide if a given facility in the registry will be used in the campaign or not. If a facility is set to "active" the facility will be used in the campaign or else it will not.

• Each facility can be assigned multiple facility types. If a given facility has multiple types, add each type separated by commas as shown here: Warehouse, Health Facility.

• The facility will be created at the hierarchical level to which the boundary code is associated. The facility to boundary code mapping shows that the facility serves these boundaries and not that it is present there physically.

• You can then upload the populated Excel sheet and move to the next step.

Case 2: Facility data exists in the system:

• You will see a pop-up to download the Excel sheet.

• The facility Excel file will be downloaded when you click on the ‘Download’ button. The template for the Excel is here.

• The Excel will have 2 sheets: 1) List of Available Facilities, 2) List of Campaign Boundaries. The second sheet will have the list of campaign boundaries.

• As there are facilities that already exist in the Facility Registry, the user will see this list of facilities in the "List of Available Facilities" sheet with all the columns in the sheet already prefilled.

• The user can set an existing facility to 'Active' or 'Inactive' under the Facility Usage Status column without changing any other column inputs for the given facility based on whether the facility will be used in the campaign or not. Any existing facility being used in a campaign should be set to active, if it is not being used in the campaign it should be set to inactive.

• When there is new facility data that needs to be added to the system, you need to add a new line item with the following columns filled out: Facility Name (must be unique), Facility Type (Warehouse/Health Facility), Facility Status (Temporary/Permanent), Capacity (Number input), Boundary Codes and Facility Usage Status (Active/Inactive).

• Once you upload the Excel sheet, click on ‘Next’ to move to the User Details page.

6. User Details

(Note: This is a non-mandatory step for moving to next screen. The data for users will not be saved in the system and the system admin will have to keep uploading the information for users every time they create a new campaign.)

• You will see a pop-up to download the Excel sheet on this page.

• The Excel template will have 2 sheets: 1) Create List of Users, 2) List of Campaign Boundaries. The second sheet will have the list of campaign boundaries with boundary codes which you can copy to the first sheet to assign boundaries to users.

• The link to the user data upload excel is here

• The "Create List of Users” sheet will have the following column headers:

• Create a line item for every user.

• If there is a user who is mapped to multiple boundaries, the system admin will have to add the boundary codes to all the boundaries that the user is mapped to by separating them by commas.

• You must enter all columns in the given sheet as shown above, where all columns are mandatory. The username and password for each user added as a separate line item will be generated at the time when the campaign is successfully created.

• The user credentials will be created and available for download as an Excel file on the campaign details page with all the columns filled by the user and the username and credentials for each user.

Once you have uploaded the user data, click on 'Next' to go to the Summary page.

7. Summary

Once all details have been added and saved, you can see the information collected in all the previous steps on the summary page. You can click on the files attached in each step and see the preview of the file attached. You can also edit any one of those sections.

You can edit a campaign's start date if it has passed but the campaign is in the draft stage. If the campaign is created, the dates can only be changed if the campaign start date has not passed.

Once you are satisfied with all the information, click on “Create Campaign”. The success screen will show that the campaign data has been captured successfully. It will take some time to create the campaign on the system, including the user credentials.

You can click on “Go to My Campaigns” where you can view the campaign in the ‘Upcoming’ tab and click on it.

Once you click on the campaign, you will see the summary page where the user credentials can be downloaded.

The documentation details of APIs for creating, searching, generating, and downloading data, including request/response structures, flows, and error handling.

Create Data

Endpoint

• Endpoint: /data/_create

• Method: POST

Request Structure

• Body Parameters:

  • RequestInfo: Object containing request information.

  • ResourceDetails: Object containing the details of the resource to be created or validated.

    • type: Type of the resource (boundary, facility, user, boundaryWithTarget).

    • tenantId: Tenant identifier.

    • fileStoreId: File store identifier.

    • action: Action type (create or validate).

    • hierarchyType: Type of hierarchy.

    • campaignId: Campaign identifier.

    • additionalDetails: Additional details object (optional).

Response Structure

• Success Response:

  - ResponseInfo: Object containing response information.

  - ResourceDetails: Array containing the detail objects of the created or validated resource.

Flow

1. Client Initiates Request: The client sends a createData request to the Project Factory Service.

2. Validation of Request: The Project Factory Service validates the request schema and the provided resource details.

3. Processing the Request:

   • If action is 'create':

     • Enrich resource details, set status to "data-accepted", and persist in DB.

     • Further creation process happens in the background.

     • After successful creation, set the status to 'completed' and persist resource details in DB.

   • If action is 'validate':

     • Enrich resource details, set the status to "validation-started", and persist in DB.

     • Further creation process happens in the background.

     • If file data is invalid, set the status to 'invalid' and persist in DB.

     • After successful creation, set the status to 'completed' and persist resource details in DB.

   • Fail case: If validation or creation fails, set the status to 'failed' and persist in DB with the error cause in additional details.

4. Response: The Project Factory Service sends the response back to the client containing the resource details and status.

Flow Diagram

Parsing Logic from sheet:

The getSheetData function retrieves and processes data from an Excel sheet, validating the structure according to the configuration provided in createAndSearchConfig. The key part of this process is the parseArrayConfig.parseLogic configuration, which specifies how to parse and validate the columns in the sheet. Here's a detailed explanation of how the function works, including the parsing logic:

Parsing Logic Using parseArrayConfig.parseLogic

The parseArrayConfig.parseLogic configuration specifies how each column in the sheet should be processed. Here's how the parsing logic works:

Column Configuration

Each column configuration specifies:

• sheetColumn: The column letter in the sheet.

• sheetColumnName: The expected name of the column in the sheet.

• resultantPath: The path where the value will be stored in the resultant JSON.

• type: The expected type of the value (e.g., string, number, boolean).

• conversionCondition: Optional conditions for converting values.

Validating Column Names

During the validation step, the function checks that the first-row value matches the expected column name.

Processing Rows

When mapping the rows to JSON, the function uses the resultantPath to place the values in the correct location in the JSON object. It converts values according to the specified type and conversionCondition.

Example Conversion

For a column configuration with type: "boolean" and conversionCondition, the function would convert "Permanent" to true and "Temporary" to an empty string.

In summary, the getSheetData function retrieves and processes data from an Excel sheet, validating the structure and content according to the createAndSearchConfig configuration. The parseArrayConfig.parseLogic part of the configuration specifies how each column should be validated and processed into the resultant JSON format.

Search Data API

Endpoint

• Endpoint: /data/_search

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• SearchCriteria: Object containing search criteria.

  • id: (Optional) ID of the resource.

  • tenantId: Tenant identifier.

  • type: (Optional) Type of the resource (boundary, facility, user, boundaryWithTarget).

  • status: (Optional) Status of the resource.

Response Body Structure

• ResponseInfo: Object containing response information.

• ResourceDetails: Array containing the details object of the searched resource.

Flow

1. Client Request: Client sends a POST request to /data/_search.

2. Request Content: Includes RequestInfo and SearchCriteria.

3. Validation: Server validates request structure and content.

4. Response Creation: Server creates response with info and resource details.

5. Response Dispatch: Sends response back to client.

6. Error Handling: If errors occur, generates error response and sends it.

Flow Diagram

Generate Data API

Endpoint

• Endpoint: /data/_generate

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• Query Parameters:

  • type: Type of the resource for which data needs to be generated.

  • tenantId: Tenant identifier.

  • hierarchyType: Type of hierarchy.

  • forceUpdate: (Optional) Boolean indicating whether to force update existing data.

Response Structure

• ResponseInfo: Object containing response information.

• GeneratedResource: Array containing the details object of the generated resource.

Flow

1. Client Request: The client sends a POST request to /v1/data/_generate.

2. Request Validation: Upon receiving the request, the server validates the request structure and parameters.

3. Generate Data Process:

   • Validation: The server validates the generate request.

   • Data Processing:

     • Fetch Data: Fetches existing data from the database.

     • Modify Data: Modifies the retrieved data as necessary.

     • Generate New ID: Generates a new random ID and sets the file store ID to null.

     • Expire Old Data: Marks existing data status as expired.

     • Generate New Data: Generates new data based on the request parameters.

     • Update and Persist: Updates and persists the generate request along with the new data.

   • Force Update Logic:

     • If the forceUpdate parameter is set to true:

       • Search and Update: Searches for existing data of the specified type and updates the existing data information.

     • If the forceUpdate parameter is not provided or set to false:

       • Fetch Existing Data: Retrieves already persisted data from the database of the specified type.

4. Response Creation: After processing the request, the server creates a response containing the details of the generated resource.

5. Response Dispatch: The server sends the generated response back to the client.

6. Error Handling: If errors occur, generates an error response and sends it.

Flow Diagram

Data to Sheet Parsing Logic

1. Fetch Required Columns from MDMS:

   • Use callMdmsData to get type schema columns in the correct order.

2. Define Headers:

   • MDMS schema required columns are headers and ensures column orders.

3. Localise Headers:

   • Use getLocalizedHeaders with localizationMap.

4. Localise Sheet Name:

   • Use getLocalizedName with localizationMap and generate sheet.

Adding a New Column to the Generated Sheet

To add a new column to the Generated sheet, follow these steps:

1. Search Schema Details

   • Locate the type schema from the HCM-ADMIN-CONSOLE.adminSchema schema in the workbench.

2. Identify Column Type

   • Determine the column type based on the properties defined in the schema:

     • stringProperties for string-based columns.

     • numberProperties for numeric-based columns.

     • enumProperties for enumerated columns.

3. Define New Column

   • Add the new column to the schema under the appropriate properties section:

     • String Column: Include attributes such as name, type, maxLength, minLength, isUnique, isRequired, description, and orderNumber.

     • Number Column: Include attributes such as name, type, maximum, minimum, isRequired, description, orderNumber, and errorMessage.

     • Enum Column: Include attributes such as name, enum, isRequired, description, and orderNumber.

4. Ensure Column Uniqueness

   • Ensure that the isUnique property is correctly set for string columns to enforce uniqueness.

5. Column Visibility (Future Implementation)

   • Note that hideColumn and freezeColumn features will be implemented in the next version.

Sheet Data Validation:

This process is sufficient for validating the new column in the Generated sheet.

Column Change Reflection in APIs

If there's a need to reflect the column in APIs, follow these additional steps:

1. Update createAndSearch.ts File

   • Modify the createAndSearch.ts file under the defined type parseLogic object.

   • Integrate the new column into the appropriate data structures used for API operations.

   • Example :

     • sheetColumn: A

     • sheetColumnName: HCM_ADMIN_CONSOLE_FACILITY_CODE

     • resultantPath: id

     • type: string

     • Mapping: Data from column A (HCM_ADMIN_CONSOLE_FACILITY_CODE) in the sheet will be mapped to id in the API data.

By following these steps, you can successfully add and validate a new column in the Generated sheet and ensure its reflection in the associated APIs.

Download Data API

Endpoint

• Endpoint: /data/_download

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• Type: (Optional) Type of the resource being downloaded.

• TenantId: Tenant identifier.

• HierarchyType: Type of hierarchy.

• Id: (Optional) ID of the resource being downloaded.

• Filters: (Optional) Additional filters for the download request.

Response Structure

• ResponseInfo: Object containing response information.

• ResourceDetails: Array containing the details object of the downloaded resource.

Flow

1. Client Request: The client sends a POST request to download data.

2. Request Validation: Upon receiving the request, the server validates the request structure and parameters.

3. Data Download Process:

   • Validation: Validate the download request.

   • Fetch Data: Fetch existing data of the specified type from the data host service.

   • Processing: Process the retrieved data as necessary.

4. Response Creation: After processing the request, the server creates a response containing the details of the downloaded resource.

5. Response Dispatch: The server sends the generated response back to the client.

6. Error Handling: If errors occur during the process, an error response is generated and sent.

Flow Diagram