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

API Overview

Base URL: project-factory/v1/

Endpoint: /data/_create

• Method: POST

Request Structure:

• Body Parameters:

  • RequestInfo: Object Containing RequestInfo

  • ResourceDetails: Details of a given Resource

    • type: Type of resource to create (e.g., boundarywithTarget)

    • tenantId: Tenant

    • fileStoreId: FileStoreId of Target Upload Sheet

    • action: Action to perform (e.g., validate for target upload)

    • hierarchyType: Name of Boundary Hierarchy

    • campaignId: CampaignId

    • additionalDetails: Additional details (optional)

Response Structure:

• Success Response:

  • ResponseInfo: Object Containing ResponseInfo

  • ResourceDetails: Details of the created resource

Flow:

1. Client Initiates Request:

   • The client sends a POST request to /data/_create endpoint with action: validate.

2. Validation of Request:

   • Resource Details Validation:

     • Check if request.body.ResourceDetails exists and is not empty.

     • Throw a validation error if missing or empty with the message "ResourceDetails is missing or empty or null".

   • Schema Validation:

     • Validate request.body.ResourceDetails against createRequestSchema.

   • Hierarchy Type Validation:

     • Validate hierarchyType in request.body.ResourceDetails using validateHierarchyType function.

   • Tenant ID Validation:

     • Ensure that request.body.ResourceDetails.tenantId matches request.body.RequestInfo.userInfo.tenantId.

     • Throw a validation error if they do not match with the message "tenantId is not matching with userInfo".

3. Different Tab Headers Validation:

   • Validate whether headers are according to the template across all tabs of different districts.

4. Target Sheet Validation:

   • All validations will be on Sheets other than the ReadMe Sheet and Boundary Data Sheet.

   • Immediate validations:

     • District Tabs Validation:

       • Validate whether all district tabs are present in the Target Sheet uploaded.

     • Empty Sheet Validation:

       • Throw a validation error if any Target Sheet is empty.

     • Root (District) level boundary validation:

       • Throw a validation error if the root column (District) is empty in any row.

   • Validations for each row:

     • Boundary Codes Validation:

       • Check for missing or empty boundary codes in any row of any sheet.

       • Check for boundary code columns to be of type string.

       • Check for the presence of more than one boundary code in a given row of a given Target Sheet.

       • Check for duplicacy of the boundary code within the given Target Sheet.

     • Boundary Targets Validation:

       • Ensure that Target values are not missing and are positive numbers less than 1 Million.

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

Overview

The documentation details 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.

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

    • type: Type of 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 the database.

     • Further creation process happens in the background.

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

   • If action is 'validate':

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

     • Further creation process happens in the background.

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

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

   • Fail case: If validation or creation fails, set the status to 'failed' and persist in the database 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:

parseLogic: [
    {
        sheetColumn: "A",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_CODE",
        resultantPath: "id",
        type: "string"
    },
    {
        sheetColumn: "B",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_NAME",
        resultantPath: "name",
        type: "string"
    },
    {
        sheetColumn: "C",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_TYPE",
        resultantPath: "usage",
        type: "string"
    },
    {
        sheetColumn: "D",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_STATUS",
        resultantPath: "isPermanent",
        type: "boolean",
        conversionCondition: {
            "Permanent": "true",
            "Temporary": ""
        }
    },
    {
        sheetColumn: "E",
        sheetColumnName: "HCM_ADMIN_CONSOLE_FACILITY_CAPACITY",
        resultantPath: "storageCapacity",
        type: "number"
    },
    {
        sheetColumn: "F",
        sheetColumnName: "HCM_ADMIN_CONSOLE_BOUNDARY_CODE_MANDATORY"
    }
]

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.

{
    "sheetColumn": "D",
    "sheetColumnName": "HCM_ADMIN_CONSOLE_FACILITY_STATUS",
    "resultantPath": "isPermanent",
    "type": "boolean",
    "conversionCondition": {
        "Permanent": "true",
        "Temporary": ""
    }
}

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 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: The client sends a POST request to /data/_search.

2. Request Content: Includes RequestInfo and SearchCriteria.

3. Validation: The server validates request structure and content.

4. Response Creation: The server creates a response with info and resource details.

5. Response Dispatch: Sends response back to client.

6. Error Handling: If errors occur, generate an error response and send 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: Aftern receiving the request, the server validates the request structure and parameters.

3. Generate Data Process:

   • Validation: The server validates the generated request.

   • Data Processing:

     • Fetch Data: Fetches existing data from the database.

     • Modify Data: Modify 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 generated 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, generate an error response and send 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 a 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.

Template Properties

General Rules

• Locked Headers: The headers in the templates for each data type (user, facility, target) are locked and cannot be changed.

• Sheet Protection: Certain sheets within the templates will have specific locked areas to ensure data integrity.

• README Sheet: Each type of template includes a README sheet which is read-only and locked.

Target Template

• Editable Columns: You can only modify the 'Target' column. All other columns are locked and cannot be edited.

Facility Template

• Adding Rows: You are allowed to add new rows to create new facilities.

• Editable Columns: You can modify the "Boundary Code" and 'Usage' columns.

• Locked Sheets: The boundary data sheet within the facility template is locked and cannot be modified.

• Dropdown Columns: The following columns are dropdowns:

  • Facility Type

  • Facility Status

  • Facility Usage

• Facility Usage: Facility usage can be 'Active' or 'Inactive'. Active facilities are used in the campaign and require a boundary code to map.

User Template

• Adding Rows: You are allowed to add new rows.

• Locked Sheets: The boundary data sheet within the user template is locked and cannot be modified.

• Dropdown Columns: The following columns are dropdowns:

  • Role

  • Employment Type

Data for Dropdowns

• The data for the dropdown columns comes from the mdms (Master Data Management System) under the adminSchema master.

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 latest resource, ensuring that only one result is fetched.

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

The documentation details the API endpoints for creating, updating, and searching project type campaigns. It includes request and response structures, validation steps, and flow diagrams.

Create Campaign

Endpoint

POST /project-type/create

Request Structure

Body Parameters

• RequestInfo: Object containing RequestInfo.

• CampaignDetails: Object containing the details of the campaign to be created.

• tenantId: Tenant identifier.

• hierarchyType: Type of hierarchy.

• action: Action type (create or draft).

• boundaries: Array of boundaries.

• resources: Array of resources.

• projectType: Type of the project.

• deliveryRules: Array of delivery rules.

• Additional request info

Response Structure

Success Response

• ResponseInfo: Object containing ResponseInfo.

• CampaignDetails: The created campaign details.

Flow

Client Initiates Request

The client initiates a createCampaign request to the Project Factory Service.

Validation of Request

If the action is 'create':

1. The Project Factory Service validates the request schema.

2. It also validates the uniqueness of the campaign name in the database.

3. If the campaign name exists, an error is thrown.

If the action is 'draft':

1. The Project Factory Service validates the request schema.

2. It also validates the uniqueness of the campaign name in the database.

3. If the campaign name exists, an error is thrown.

Boundary and MDMS Validation

For both 'create' and 'draft' actions:

1. The Project Factory Service validates the request for hierarchy type and boundaries with the Boundary Service.

Campaign Creation

If the action is 'create':

1. The Project Factory Service validates the request for data resources.

2. It enriches the CampaignDetails and sets the status to 'creating'.

3. The CampaignDetails are persisted in the database.

4. For each resource data, the Project Factory Service creates resources through the /project-factory/v1/data/_create API.

5. It enriches boundaries for project creation and creates projects for each boundary with the Health Project Service.

6. The enriched CampaignDetails are persisted in the database.

7. The CampaignDetails object is sent to a Kafka topic for project mappings.

8. If the campaign status is not "created", project mappings are performed through the /project-factory/v1/project-type/createCampaign API and the status is updated to 'created'.

9. If the campaign status is already 'created', an error is thrown, and the status is updated to 'failed'.

If the action is 'draft':

1. The CampaignDetails are enriched, and the status is set to 'drafted;.

2. The enriched CampaignDetails are persisted in the database.

Response

The Project Factory Service sends the response back to the client.

Flow Diagram

Update Project Type Campaign

Endpoint

POST /project-type/update

Request Structure

Body Parameters

• RequestInfo: Object containing RequestInfo.

• CampaignDetails: Object containing the details of the campaign to be updated.

• id: Unique identifier of the campaign.

• tenantId: Tenant identifier.

• hierarchyType: Type of hierarchy.

• action: Action type (create or draft).

• boundaries: Array of boundaries.

• resources: Array of resources.

• projectType: Type of the project.

• deliveryRules: Array of delivery rules.

Response Structure

Success Response

• ResponseInfo: Object containing ResponseInfo.

• CampaignDetails: The updated campaign details.

Flow

Receive Request

The ProjectFactoryService receives an updateCampaign request from the Client.

Validate Request Schema

The received request schema is validated to ensure it matches the expected format.

Check Campaign Existence

The system checks if the campaign specified in the request exists in the database.

Conditional template generation call

• If boundaries are different from campaign in db, call:

  • Facility template generate

  • User template generate

  • Target template generate

• If delivery conditions are different, call:

  • Target template generate

Check Campaign Status

If the campaign exists, the system checks its status in the database.

Handle Drafted Status

If the campaign status is 'drafted':

1. Validate Boundaries: Validate the request for hierarchyType and boundaries.

3. Enrich Campaign Details: Enrich the campaign details and set the status to 'updating'.

4. Update Campaign Details: Update the campaign details in the database.

5. Update Resource Data: Update each resource data associated with the campaign through the /project-factory/v1/data/_update API.

6. Enrich Boundaries: Enrich the boundaries for the project update.

7. Update Projects: Update projects associated with each boundary.

8. Persist Changes: Persist the updated campaign details in the database.

9. Send to Kafka Topic: Send the updated CampaignDetails object to the Kafka topic for project mappings.

10. Listen to Kafka: Listen for updates from the Kafka topic to get the updated CampaignDetails object for project mappings.

Handle Campaign Status

If the campaign status is not 'created':

1. Do project mapping through /project-factory/v1/project-type/createCampaign API.

2. Enrich the CampaignDetails and set the status to 'created'.

3. Update the CampaignDetail in the database.

Handle Project Mapping Error

If the campaign status is 'created':

1. Throw an error indicating that the project is already mapped for this campaign.

2. Enrich the CampaignDetails and set the status to 'failed'.

3. Update the CampaignDetail in the database.

Handle Non-Drafted Status

If the campaign status is not 'drafted', the system throws an error indicating that only drafted campaigns can be updated.

Send Response

The ProjectFactoryService sends a response to the Client based on the outcome of the update operation.

Flow Diagram

Search Project Type Campaign

Endpoint

POST /project-type/search

Request Structure

Body Parameters

• RequestInfo: Object containing RequestInfo.

• CampaignDetails: Object containing the search criteria for campaigns.

• tenantId: Tenant identifier.

• ids: Array of campaign IDs to search for.

• startDate: The start date for the search.

• endDate: End date for the search.

• projectType: Type of the project.

• campaignName: Name of the campaign.

• status: Status of the campaign.

• createdBy: Creator of the campaign.

• campaignNumber: Number of the campaign.

• campaignsIncludeDates: Flag to include campaigns based on dates.

• pagination: Object containing pagination settings.

  • limit: Maximum number of results to return.

  • offset: Offset for paginated results.

  • sortOrder: Sort order for results (asc/desc).

  • sortBy: Field to sort results by.

Response Structure

Success Response

• ResponseInfo: Object containing ResponseInfo details.

• CampaignDetails: Array containing details of matching campaigns.

• totalCount: Total number of matching campaigns.

Flow

Client Initiates Request

The client sends a searchCampaign request to the Project Factory Service.

Validation of Request

The Project Factory Service validates the request schema and search criteria.

Search Campaigns

• The Project Factory Service constructs a search query based on the provided criteria.

• It checks if there are specific search fields like start date, end date, campaign name, etc.

• Depending on the campaignsIncludeDates flag, the service adjusts the search conditions accordingly.

  • If campaignsIncludeDates is true:

    • It shows only those campaigns whose start date is on or before the provided start date and whose end date is on or after the provided end date.

  • If campaignsIncludeDates is false:

    • It shows only those campaigns whose start date is on or after the provided start date and whose end date is on or before the provided end date.

• The service executes the constructed query to retrieve matching campaign details from the database.

Response

The Project Factory Service sends the response back to the client.

• The response contains the matching campaign details along with the total count, if applicable.

Flow Diagram

Search Process Tracks

Endpoint

POST /project-type/getProcessTrack

Request Structure

Query Parameters:

• campaignId: Unique ID of the campaign.

Response Structure

Success Response:

• ResponseInfo: Object containing ResponseInfo details.

• processTrack: Array containing process tracks of the matching campaign.

Flow

1. Client Initiates Request

   • The client sends a request to retrieve process tracks for a specific campaign by providing the campaignId.

2. Validation of Request

   • The Project Factory Service validates the provided campaignId to ensure it meets the expected format and constraints.

3. Fetch Process Tracks

   • The Project Factory Service constructs a query to fetch process tracks associated with the provided campaignId.

   • The service executes the query against the database to retrieve the process tracks.

4. Response

   • The Project Factory Service formats the retrieved process tracks and packages them into the response.

   • The response includes the ResponseInfo and an array of processTrack details.

5. Send Response to Client

   • The Project Factory Service sends the response back to the client containing the process track details for the specified campaign.

Steps and Statuses in Campaign Creation

processTrackTypes (Steps)

This defines various types of process tracks, each representing a specific stage or action in the campaign creation process. These types can be used to categorize and identify different steps or activities within the campaign workflow. Here's what each type represents:

• validation: Represents the validation stage of the campaign creation process, where data or conditions are checked for correctness.

• triggerResourceCreation: Indicates the step where resources are created based on triggers or conditions.

• facilityCreation: Refers to the creation of facilities or resources required for the campaign.

• staffCreation: Involves the creation of staff members necessary for the campaign.

• targetAndDeliveryRulesCreation: Represents the creation of rules related to targets and delivery mechanisms (project creation step).

• confirmingResourceCreation: Involves confirming that resources have been successfully created.

• prepareResourceForMapping: The stage where resources are prepared for mapping to projects.

• validateMappingResource: Represents the validation of resources after they have been mapped.

• staffMapping: Involves mapping staff to projects.

• resourceMapping: Represents the mapping of various resources to projects.

• facilityMapping: Refers to mapping facilities to projects.

• campaignCreation: Represents the creation of the campaign itself (final step).

• error: Indicates that an error occurred during the campaign creation process.

processTrackStatuses

This object defines different statuses that a process track can have, reflecting the state or progress of a particular step in the campaign creation process. Here are the statuses and their meanings:

• inprogress: Indicates that the process or task within the campaign creation process is currently ongoing and has not yet been completed.

• completed: Represents that the process or task within the campaign creation process has been successfully finished.

• toBeCompleted: Refers to processes or tasks within the campaign creation process that are scheduled or pending completion in the future.

• failed: Signifies that the process or task within the campaign creation process encountered an error or failed to execute as intended.

Flow Diagram

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.

Here are the articles in this section:

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:

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.

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

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

Click on the following links to learn more:

Below are the configurations needed for successfully setting up the campaign module:

MDMS Configuration

• citymodule needed to run campaign module in an environment:

  Link:

• roleactions config needed for the user for all campaign access

  Link:

• actionTest config needed for sidebar action and user access for services

  LINK:

  To enable action in the sidebar, add navigationUrl and path to the object

Refer to the below id's link in QA:

• roles need to be added in roles

• Boundary Schema config needs to be added for boundary sheet validation:
• Facility Schema config needs to be added for facility sheet validation:
• User schema config needs to be added for user sheet validation:
• Hierarchy config needs to be added to define lowset hierarchy in boundary selection:

Devops Configuration

• Global configuratio needs to be added to environments.
• Helm chart needs to be added in devops.

Localisation

In the 'Delivery Details' step, users encounter 3 screens:

• Delivery Dates

• Cycle Configuration

• Delivery

1. Campaign Dates

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

2. Cycle Configuration Screen

On this screen, users specify the number of cycles and deliveries. The number of cycles must be at least 1 and can be up to 5. Once the user has defined the number of cycles and deliveries, they can proceed to enter the start and end dates for each cycle.

The number of cycles and deliveries are configurable based on project type. We can configure it in MDMS:

If data is configured, a user will see the number of cycles and deliveries as per the configuration. A user, however, can increase or decrease if they find it necessary.

The validations added for the start date and the end date of the cycles should not overlap to each other.

After filling in all the cycle details, a user can click on 'Next' and move to the Delivery rules screen. Clicking on 'Next' enables a user to store the cycle data in the local storage.

3. Delivery Screen

On this screen, users fill in all the delivery details (adding delivery rules, adding conditions in delivery rules, adding products in the delivery rules) of each cycle and delivery which the user has selected in the cycle details screen.

The delivery screen can also be configured based on project type. A user can configure the number of delivery conditions, their attributes, and products. If the data is configured correctly, a user can see the data preloaded in delivery rules and the user can change, remove, or add, if they find it necessary.

A user can add delivery rules up to 5. A user can add conditions in each delivery rule with attribute options having height, weight, gender, and age. For Project type, LLIN-mz configuration is passed in delivery rules in which two fixed attributes are present for the bednet campaign.

After filling in all the delivery rules details, when a user clicks on next, the data will be stored in the localStorage as well as in the draft API. The delivery rules data will be validated in the preview screen.

Reference files:

Select or Create a Product

If you click on configure resources on the delivery screen, a pop-up appears where a user can either select or create a product:

Product Screen: When a user clicks on "Add Products to be delivered", a pop-up screen will appear with a list of product variants where a user can add the products and the number of counts in the delivery rules.

A user can add multiple products to the product screen after clicking on "add more resources" When the user clicks on confirm resources, products will be added to the delivery rules. The user can remove the products as well.

If the product is not present, a user can click on "Add New Product" to create a new product and variant, and subsequently add delivery rules. Clicking on "Add New Product" will open the create product screen.

Users can enter product names, product variants, and product types which are sourced from MDMS data. Additionally, a user can create multiple products using the "Add Products" button. After clicking on 'Confirm,' the product will be created, followed by the creation of product variants.

After successful creation, users will be directed to a success response screen.

Guide on Setting Up Delivery Configuration.

Here you can find the config of delivery based on project type.

The following is the structure of the delivery configuration:

• projectType: This will be the type of the project. If the selected project type is present in the MDMS, then we use that config.

• attrAddDisable: if this is true, we are restricting a user that they cannot add any attribute.

• deliveryAddDisable: if this is true, a user cannot add any further delivery rule conditions.

• cycleConfig: This will be an object containing cycles and deliveries. This refers to the number of cycles and deliveries that will be shown in the cycle screen.

• deliveryConfig: This will be an array of objects, each object representing one delivery condition.

Adding product config is a careful job, adding the wrong product in the config will cause issues while creating a product.

In Value, the product variant ID should be added in the value which will be getting in the below API:product/variant/v1/_search

The name will consist of the name of the product and the variant of the product separated with "-"

for name: product/v1/_search

for variant: product/variant/v1/_search

FilePath:

Reference links:

MDMS:

HOOKS:

New changes

We have added Delivery type at each delivery conditions showing the delivery type of the campaign.

It is configurable in mdms for the SMC project type. We can add default delivery type at each conditions.

deliveryConfig: It will contain default data of all deliveries.

conditionConfig: It will contain default data of each delivery condition of each deliveries

deliveryType: Default value of delivery type.

API Details

New Feature:

A info card is been added in both the screens in the delivery details. Which states the criteria of delivery as recommended by WHO.

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

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 resource upload details consists of 3 types of uploads:

• Upload Target Data

• Facility Upload

• User Upload

1. Upload Target Data

This screen will come after a user selects the boundaries.

When a user clicks on the download template button, an Excel will get downloaded which will contain readMe, Boundary Data sheet along with the sheets with districts, where the user has to fill the target at the lowest level. After the file is uploaded, it will go for validation. Once validated, a user can go to the next page, where the user can delete the file and move to the next page to upload facility date.

2. Upload Facility Data

This screen will come after the target upload screen.

In this screen, when a user clicks on the download template, an Excel get downloaded that contains readMe, Facility sheet, and BoundaryData sheet. A user has to fill in the boundary codes and from that sheet, the user has to fill in the facility sheet.

3. Upload User Data

This screen will appear after the facility Details screen.

When a user clicks on the download template, an Excel gets downloaded that consists of with readMe, User Sheet and BoundaryData. The user has to fill the user sheet only.

All the 3 downloads are happening through the Generate and Download APIs. For the Generate API, the following hook is used: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/hooks/useGenerateIdCampaign.js

This hook will return the ID which is stored in the local storage according to the type:

HCM_CAMPAIGN_MANAGER_UPLOAD_ID

Next, /project-factory/v1/data/_download is used to download the template.

Schema Validation

After uploading the templates, UI validation is done through schema stored in the MDMS: Schema Data link : https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/mz/health/hcm-admin-console/adminSchema.json

Schema Module = adminSchema Below is the admin schema-

 "SchemaDefinitions": [
        {
            "id": "92fb3b53-adfe-44e9-ab27-da3209b5e0f1",
            "tenantId": "mz",
            "code": "HCM-ADMIN-CONSOLE.adminSchema",
            "description": null,
            "definition": {
                "type": "object",
                "title": "Comprehensive Example Schema",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "required": [
                    "$schema",
                    "title",
                    "campaignType"
                ],
                "x-unique": [
                    "title",
                    "campaignType"
                ],
                "properties": {
                    "title": {
                        "type": "string"
                    },
                    "$schema": {
                        "enum": [
                            "http://json-schema.org/draft-07/schema#"
                        ],
                        "type": "string",
                        "default": "http://json-schema.org/draft-07/schema#"
                    },
                    "properties": {
                        "type": "object",
                        "properties": {
                            "enumProperties": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "required": [
                                        "name",
                                        "description"
                                    ],
                                    "properties": {
                                        "enum": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        },
                                        "name": {
                                            "type": "string"
                                        },
                                        "isUnique": {
                                            "type": "boolean"
                                        },
                                        "hideColumn": {
                                            "type": "boolean"
                                        },
                                        "isRequired": {
                                            "type": "boolean"
                                        },
                                        "description": {
                                            "type": "string"
                                        },
                                        "orderNumber": {
                                            "type": "integer",
                                            "minimum": 1
                                        },
                                        "errorMessage": {
                                            "type": "string"
                                        },
                                        "freezeColumn": {
                                            "type": "boolean"
                                        }
                                    },
                                    "minProperties": 1
                                },
                                "minItems": 1
                            },
                            "numberProperties": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "required": [
                                        "name",
                                        "description"
                                    ],
                                    "properties": {
                                        "name": {
                                            "type": "string"
                                        },
                                        "type": {
                                            "enum": [
                                                "number"
                                            ],
                                            "type": "string"
                                        },
                                        "maximum": {
                                            "type": "number"
                                        },
                                        "minimum": {
                                            "type": "number"
                                        },
                                        "isUnique": {
                                            "type": "boolean"
                                        },
                                        "hideColumn": {
                                            "type": "boolean"
                                        },
                                        "isRequired": {
                                            "type": "boolean"
                                        },
                                        "multipleOf": {
                                            "type": "number"
                                        },
                                        "description": {
                                            "type": "string"
                                        },
                                        "orderNumber": {
                                            "type": "integer",
                                            "minimum": 1
                                        },
                                        "errorMessage": {
                                            "type": "string"
                                        },
                                        "freezeColumn": {
                                            "type": "boolean"
                                        },
                                        "exclusiveMaximum": {
                                            "type": "boolean"
                                        },
                                        "exclusiveMinimum": {
                                            "type": "boolean"
                                        }
                                    },
                                    "minProperties": 1
                                },
                                "minItems": 1
                            },
                            "stringProperties": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "required": [
                                        "name",
                                        "description"
                                    ],
                                    "properties": {
                                        "name": {
                                            "type": "string"
                                        },
                                        "type": {
                                            "enum": [
                                                "string"
                                            ],
                                            "type": "string"
                                        },
                                        "pattern": {
                                            "type": "string",
                                            "format": "regex"
                                        },
                                        "isUnique": {
                                            "type": "boolean"
                                        },
                                        "maxLength": {
                                            "type": "integer",
                                            "minimum": 0
                                        },
                                        "minLength": {
                                            "type": "integer",
                                            "minimum": 0
                                        },
                                        "hideColumn": {
                                            "type": "boolean"
                                        },
                                        "isRequired": {
                                            "type": "boolean"
                                        },
                                        "description": {
                                            "type": "string"
                                        },
                                        "orderNumber": {
                                            "type": "integer",
                                            "minimum": 1
                                        },
                                        "errorMessage": {
                                            "type": "string"
                                        },
                                        "freezeColumn": {
                                            "type": "boolean"
                                        }
                                    },
                                    "minProperties": 1
                                },
                                "minItems": 1
                            },
                            "additionalProperties": {
                                "type": "boolean"
                            }
                        },
                        "additionalProperties": false
                    },
                    "campaignType": {
                        "type": "string"
                    }
                },
                "description": "A simplified JSON Schema example based on data type.",
                "additionalProperties": false
            },
            "isActive": true,
            "auditDetails": {
                "createdBy": "8b110055-330f-4e7b-b4c0-f618f29b9d47",
                "lastModifiedBy": "8b110055-330f-4e7b-b4c0-f618f29b9d47",
                "createdTime": 1718169189364,
                "lastModifiedTime": 1718169189364
            }
        }
    ]

By using AJV Validation , we are validating the headers of the facility sheet. We are also doing some basic validations for the data such as-

• Facility Type can only be Warehouse/Health Facility

• Facility Name can only be string

• Facility Status can only be Temporary or Permanent etc.

Apart from this, we are also validating sheet names in all the 3 uploads.

For target validation, we use schema only for validating the header of the target and boundary codes. Here, we also validate the target at the lowest level, where the value should be between:

targetValue <= 0 || targetValue >= 100000000

Validation API Call:

Before calling we are using base time out which is fetched from the MDMS

https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/mz/health/hcm-admin-console/baseTimeOut.json

Reference Links:

For the backend validation, we use the following hook: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/hooks/useResourceData.js

The screens are using the given below components for upload and validation-

Bulk upload: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/BulkUpload.js

Preview component: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/XlsPreview.js

File screen: - https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/UploadData.js

API Details

New Features:

A new popup has been added which display the option to download the template in all the three upload screens.

Use Case :

when the user comes after clicking next on the delivery screen and the file is not uploaded then this pop up is displayed.

The Summary screen provides users with a comprehensive view of all campaign details entered.

Users can review the entirety of their campaign information. If the campaign status is marked as 'drafted,' users can either edit the existing data or submit it. After submission, the campaign is created, initiating the 'create' action.

For campaigns in a 'draft' status, the summary screen serves as the final step of the campaign setup process, giving users the option to edit or submit the details before finalisation.

If the campaign is successfully created while in the 'draft' status, users are directed to a success screen.

After the API call, the data undergoes restructuring to present delivery rules based on the cycle and delivery details.

FilePath: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/CampaignSummary.js

Implementing error cards and screens

If campaign data is incomplete and user tries to create a campaign, then we are showing all the erros in the respective card specifyig the error to the user. User can make the change by using errors button or clicking on edit button showing in the card.

Errors card Implementation:

We are adding all the errors as per screen name in an array and passing the erros as a props in ViewComposer component.

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

API Details:

For draft status only:

Overview

My campaign screen allows users to see the list of campaigns that are in Ongoing, Completed, or Draft status. Users can search campaign by using the campaign name or campaign type. Users can also see a summary of the campaign and complete the campaign creation if it is draft status.

The list of statuses showing in "My Campaign" screen are:

1. Ongoing

2. Completed

3. Drafts

4. Failed

5. Upcoming

User actions

After clicking on the My Campaign link from the HCM Campaign module card, the user lands on the My Campaign screens where the user can see all the lists of campaigns of each action in the tab.

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

On my campaign screen, we are sending the payload:

• Campaigns with an end date that has passed the current date are marked as 'Completed'.

• Campaigns with a status of 'Started' and no end date, or with an end date in the future, are labeled as 'Ongoing'."

• The logic is written in UICustomizations.js

• File path: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/configs/UICustomizations.js

Clicking on campaigns other than draft status will redirect to the summary page of the campaign where the user can see the complete details of the respective campaign.

File Path: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/components/CampaignSummary.js

Ongoing Campaign Filtering

For the ongoing campaign filtering functionality, we are utilizing the campaignsIncludeDates parameter set to true. The startDate and endDate parameters are both set to the current date. This configuration ensures that the API will return any campaign where the specified startDate or endDate falls within the campaign's defined start and end dates. Additionally, the campaign status is filtered to include campaigns with statuses of created or creating.

Parameters

• campaignsIncludeDates: This boolean parameter is set to true to enable date range filtering.

• startDate: The start date for the filter, set to today's date.

• endDate: The end date for the filter, also set to today's date.

• status: The campaign status filter, including the statuses created and creating.

Implementation

To filter the ongoing campaigns based on the criteria mentioned above, ensure that your request payload includes the following parameters:

{ 
   "campaignsIncludeDates": true, 
   "startDate": "", // Use the current epoch date dynamically 
   "endDate": "2024-05-23", // Use the current epoch date dynamically 
   "status": ["created", "creating"] 
}

Logic Explanation

• campaignsIncludeDates = true: This activates the date range filtering feature.

• startDate and endDate = today: By setting both the start and end dates to today's date, the filter will capture any campaigns that are active today.

• status = ["created", "creating"]: Filters the campaigns to only include those that are currently in the created or creating status.

Completed Campaign Filtering

For filtering completed campaigns, we use a similar approach with a slight modification to the date parameters and status. Specifically, we will set the endDate parameter to yesterday's date. This configuration ensures that the API returns campaigns that have ended as of yesterday. The statuses to filter will remain creating and created.

Parameters

• endDate: The end date for the filter, is set to yesterday's date.

• status: The campaign status filter, including the statuses creating and created.

Implementation

To filter the ongoing campaigns based on the criteria mentioned above, ensure that your request payload includes the following parameters:

{
   "endDate": "", // Use the yesterday epoch date dynamically 
   "status": ["created", "creating"] 
}

Logic Explanation

1. endDate = yesterday: By setting the end date to yesterday's date, the filter will capture any campaigns that have ended by the end of the previous day.

2. status = ["created", "creating"]: Filters the campaigns to include only those that were in the created or creating status when they ended.

When a user clicks on completed campaign, they will be redirected to the summary page displaying the campaign details. The success toast message will appear If user credential sheet is generated successfully. User can view or download the sheet from the user credential card or download button which appears at the top.

Upcoming Campaign Filtering

For filtering upcoming campaigns, we use a different approach by setting the campaignsIncludeDates parameter to false and specifying the startDate parameter to tomorrow's date in epoch format. This configuration ensures that the API returns campaigns scheduled to start tomorrow. The statuses to filter will remain creating and created.

Parameters

• campaignsIncludeDates: This boolean parameter is set to false as we are not filtering based on a date range but rather a specific start date.

• startDate: The start date for the filter, set to tomorrow's date in epoch format.

• status: The campaign status filter, including the statuses creating and created.

Implementation