1 of 57

Low Level Design

The articles in this section include:

Registries

Registries in DIGIT are trusted data stores that manage core entities like individuals, households, facilities, and products. They provide APIs to create, update, and search these records, ensuring consistent and reusable data across all services.

Individual

Overview

The Individual Registry is a core component of the DIGIT platform’s registry system. The registry offers APIs to create, update, delete, and search individual records—either individually or in bulk.

API Spec

Sequence Diagrams

Household

Overview

The Household Registry is a core microservice in DIGIT’s registry framework, enabling the management of households and their members within the Health Campaign Management (HCM) context. It provides structured APIs for CRUD operations and search capabilities, both at the household level and for individual household members.

API Spec

Sequence Diagrams

Product

Overview

The Product Registry serves as one of the foundational registries, used to manage products and their variants within the Health Campaign Management (HCM) framework.

API Spec

Sequence Diagrams

Facility

Overview

The Facility Registry manages facility-related data within the HCM system. It supports the key operations of creating, updating, deleting, and searching for facilities, along with their bulk counterparts.

API Spec

Sequence Diagrams

Attendance

Description of the attendance service

Overview

The Attendance Service is a comprehensive back-end solution designed to support health campaigns by providing efficient and transparent attendance management. It facilitates the streamlined tracking of health campaign workers, volunteers, and contractors, ensuring accurate participation records and enabling informed decision-making.

Note: Deletion of attendees from the system is not recommended, even in cases where participation in the campaign has ceased. Attendance records should instead reflect the status of absent for all days following the departure. This practice ensures the integrity of attendance data, preserves historical records, and supports accurate reporting and auditing processes.

Key functionalities include:

Expense

Overview

The Expense service allows users to capture the details for expense bills and payments.

API Specifications

Base path: /health-expense/bill/

API Contract Link

The API specification is available . To view it in the Swagger editor, click below.

Data Model

DB Schema Diagram

Web Sequence Diagrams

Persister

Persister configuration:

Services

Services are the functional building blocks of DIGIT, each designed as a microservice to handle a specific piece of business logic. They sit on top of registries, integrate via APIs and events, and together enable scalable, modular health campaign systems.

Project

Overview

The Project Service orchestrates the logic around managing projects. It forms the bridge between high-level campaign workflows and underlying entity registries.

API Spec

Stock

Overview

The Stock Service is responsible for managing stock and inventory workflows. It handles all operations related to stock records and their reconciliation in health campaigns.

API Spec

Sequence Diagrams

Referral

Overview

The Referral Service manages both referrals and side effects linked to health campaign beneficiaries.

API Spec

Sequence DIagrams

Muster Roll

Overview

The Muster Roll service aggregates attendance logs from the attendance service based on some rules and presents an attendance aggregate for a time period (week or month) per individual. This can then be used to compute payments or other semantics.

Dependencies

Code

API Specifications

Base Path: /health-muster-roll

API Contract Link

Data Model

DB Schema Diagram

Web Sequence Diagrams

Master Data

Expense Calculator

Overview

The expense calculator is an implementation-specific service that works in tandem with the expense service. This service holds all the specific business logic for computing expenses and calls the billing service with the correct payload to create a bill. Once the bill is generated, Excel and PDF are generated by the calculator service.

There are three types of bills in HCM:

Wage bill - generated from an approved muster roll and to be paid to wage seekers on completion of work

API Specifications

Base path: /health-expense-calculator/v1/

The API specification is available . To view it in the Swagger editor, click below.

Dependencies

DIGIT backbone services
Persister
MDMS
Attendance

Master Data

Worker rates

Sequence Diagrams

DB Diagram

MDMS data

Attendance

Update & approve attendance

Overview

The Proximity Supervisor Flow for managing attendance registers is designed to provide supervisors with a seamless experience for selecting projects, viewing associated attendance records, and managing the details effectively. The flow emphasises ease of navigation, quick access to project and register information, and actionable steps to edit or approve attendance records.

Features

Project Selection: Enables supervisors to pick a specific project to manage.
Registers Inbox: Displays filtered attendance registers for selected boundaries.
View Attendance: Provides detailed attendance information for campaigns and projects.
Edit Attendance: Allows supervisors to update attendee records.

Role

Description

Each step in this flow ensures user-friendly interactions and adheres to the necessary validation rules and role-based permissions for supervisors and project managers.

Note: In Payments version 0.1, each user will be associated with only one project.

Sequence Diagram

Select Project

Overview

The Select Project allows supervisors to select a project and view or manage attendance registers associated with that project.

Interface Elements

Register Inbox

Overview

Enables supervisors to view attendance registers filtered by selected boundaries (e.g., district).

Interface Elements

Generate Bill

Overview

The Campaign Supervisor Flow is designed to streamline the management of attendance registers and bill generation processes for supervisors overseeing specific projects and boundaries. This flow ensures efficient selection, filtering, and approval of registers and simplifies the generation and tracking of bills. It focuses on clear workflows, actionable feedback, and validation mechanisms to enhance usability and accuracy.

Features

Project and Bill Aggregation Selection: Supervisors select a project and boundary aggregation level to narrow down the scope for attendance registers and billing.
Registers Filtering and Bill Generation: Enables supervisors to filter registers based on boundaries, view attendance data, and generate bills only when all registers are approved.
Bill Management (My Bills): Provides a centralised view of all generated bills, with tools for searching, filtering, and downloading them in preferred formats.

Role

Responsibility

This structured approach empowers supervisors to manage attendance registers and related billing tasks with ease while adhering to necessary validations and role-based permissions.

Sequence Diagram

Project & Bill Aggregation

Overview

This is the initial screen where the user selects:

Project: The specific project they are managing.
Bill Aggregation Level: The boundary level at which the bill should be generated (Country, Province, or District).

My Bills

The "My Bills" section serves as a centralised dashboard for campaign supervisors to view and manage all bills associated with their assigned projects. By default, the dashboard displays all bills related to the projects under their supervision. Supervisors can search for specific bills or filter them using date ranges or by bill ID.

Interface Elements

Search Filters

Bill ID: Enter a specific Bill ID.
Date Range: Select a start and end date to filter bills within a specific time frame.

Enumeration

Overview

Enumeration changes include capturing additional information for household, individual and member linking as children or other relationships. To capture the additional details, we are rendering the new checklists and capturing the details.

Key Features

Beneficiary IDGen

Overview

The Beneficiary IDGenId feature is to link a unique ID to an individual. UniqueId’s are fetched from the server with the unique DeviceId and user.

Key Feature

Fetching UniqueID’s from the server with device and user combination
Added new ID_TYPE - UNIQUE_BENEFICIARY_ID to link individuals
Added search with UNIQUE_BENEFICIARY_ID

Sequence Diagram

Role: DISTRIBUTOR

Transit Post

Overview

The Transit Post Package is a Flutter module designed to streamline transit post operations, such as selecting posts, scanning resources, and tracking deliveries. Built for seamless integration in larger logistics and delivery systems, it leverages Bloc for robust state management and uses reactive forms for capturing user input efficiently. The module is structured for reusability, testability, and separation of concerns via repository patterns.

V1 Deprecated Data Apis

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.

Response Structure

ResponseInfo: Object containing response information.
ResourceDetails: Array containing the details object of the searched resource.

Flow

Client Request: The client sends a POST request to /data/_search.
Request Content: Includes RequestInfo and SearchCriteria.
Validation: The server validates request structure and content.
Response Creation: The server creates a response with info and resource details.

Flow Diagram

Download Data API

Endpoint

Endpoint: /data/_download
Method: POST

Target Data Upload API

Base URL: project-factory/v1/

Endpoint: /data/_create

Method: POST

Request Structure

Manage Campaign APIs

The section of 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 API Endpoints

Endpoint

POST /project-type/create

Request Structure

Update Campaign API Endpoints

Endpoint

POST /project-type/update

Request Structure

Search Project Type Campaign Endpoints

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.

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.

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

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

Create Campaign

Overview

This document outlines the flow for creating a campaign using various services in the system. The process involves interactions between multiple services, including the Project Factory, Project Service, Boundary Service, Facility Service, HRMS Service, MDMS Service, FileStore Service, and the database. This flow ensures that the required resources are validated and correctly set up before finalizing the campaign creation.

Admin Console

Initiate Campaign Creation
- The Client sends a request to the CampaignManager to create a campaign with all required and valid resources.
Fetch Boundary Relationship
- The CampaignManager requests the BoundaryService to fetch the boundary relationship based on the hierarchy type.
- The BoundaryService responds with the relevant boundary relationship data.
Fetch Project Type Master
- The CampaignManager requests the MDMSService to fetch the project type master data.
- The MDMSService responds with the project type master.
Validate Resource Files
- The CampaignManager checks the Database to see if the input resource files have already been validated.
- The Database responds with the validation status of the files.
Validation Check
- The CampaignManager checks if all file templates and data are validated:
  - If validation is successful, the CampaignManager informs the Client that the campaign creation process has started, and the user needs to track the status using an ID.
Resource File Retrieval
- The CampaignManager interacts with the FileStoreService to search for the resource based on the filestoreid.
- The FileStoreService responds with the valid resource files.
Process Resource Data
- The CampaignManager processes the retrieved sheets and identifies any resource data that needs to be created.
Facility Data Creation
- The CampaignManager sends a request to the FacilityService to create facility data.
- The FacilityService responds that the facilities have been created successfully.
Employee Data Creation
- The CampaignManager sends a request to the HRMSService to create employee data.
- The HRMSService responds that the employees have been created successfully.
Project Data Creation
- The CampaignManager sends a request to the ProjectService to create project data with a parent-child relationship based on the project type and delivery configuration.
- The ProjectService responds that the projects have been created successfully.
Project-Facility Mapping Creation
- The CampaignManager sends a request to the ProjectService to create mappings between projects and facilities.
- The ProjectService responds that the project-facility mappings have been created successfully.
Project-Staff Mapping Creation
- The CampaignManager sends a request to the ProjectService to create mappings between projects and staff.
- The ProjectService responds that the project-staff mappings have been created successfully.
Update Campaign Creation Status
- The CampaignManager updates the Database with the status of the campaign creation process.

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.

Response Structure

ResponseInfo: Object containing response information.
GeneratedResource: Array containing the details object of the generated resource.

Flow

Client Request: The client sends a POST request to /v1/data/_generate.
Request Validation: After receiving the request, the server validates the request structure and parameters.
Generate Data Process:
- Validation: The server validates the generated request.

Flow Diagram

Data to Sheet Parsing Logic

Fetch Required Columns from MDMS:
- Use callMdmsData to get type schema columns in the correct order.
Define Headers:

Adding a New Column to the Generated Sheet

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

Search Schema Details
- Locate the type schema from the HCM-ADMIN-CONSOLE.adminSchema schema in the workbench.
Identify Column Type

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:

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.

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:

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

Data for Dropdowns

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

Update Ongoing Campaign

Overview

This document details the low-level design for handling campaign creation and update flows when a parent campaign is present. The system supports hierarchical campaigns, boundary inheritance, resource template generation, and robust retry mechanisms. This design aims to ensure data consistency, correct parent-child relationships, and efficient error recovery.

Data Model Changes

Database: Campaign Details Table

New Columns
- isActive (boolean): Indicates if the campaign is currently active.
- parentId (string): References the parent campaign’s unique ID, if any.

Request Validation Logic

Parent Campaign Validation

If parentId is present in the request:
- On create action:
  - Parent campaign (parentId

Boundary Management Logic

For child campaigns:
- The boundaries array in the request must contain only new boundaries.
- Existing boundaries are fetched from the parent campaign.
- Merged boundaries = parent boundaries + new boundaries (for use in template/resource generation).

Resource & Template Generation

On Campaign Creation (with Parent Campaign)

Generate templates for all three types: boundary, user, facility.
If actionInUrl = create and parentId is present, templates are generated freshly using both parent and new boundaries.

On Campaign Update

For newly added boundaries, create new projects/resources only for those.
If existing targets are updated, call update on the respective project with new target mappings.
Facility and user sheets can be edited: updating these updates related mappings (ProjectFacility, ProjectStaff).

Retry Mechanism

If campaign creation or update fails, a retry API allows the process to restart from the failure point.
Retry is stateful and resumes based on the persisted CampaignDetails and status.

Retry API Example:

Campaign Object Structure

See below for sample fields (simplified):

After each update and once the campaign is in the "Created" state, templates are consolidated for future updates.

Update & Multiple Update Handling

After a campaign reaches the "Created" state:
- Uploaded template sheets (Facility, User, Target) are consolidated back to the initial format.
- Any subsequent update is handled as the first update (fresh diff against the current state).

Edit Mappings in Update Flow

In the update flow, facility mappings to boundary codes can be edited and toggled (active/inactive).
Updates propagate to ProjectFacility and ProjectStaff mapping tables.

Sequence Flow

Request received with or without parentId.
Validation:
- If parentId present, validate parent state as per action.

Error & Edge Case Handling

Validation Errors:
- If the parent campaign is not in the required state, reject the request.
- If new boundaries overlap with the parent, reject or merge as per the business rule.
Retry Errors:

Points to consider:

All actions logged with audit details (user, timestamp).
Only authorised roles can create/update hierarchical campaigns.

Sample Payload

Multiple updates to a Campaign

Once the ongoing campaign is updated and reaches the "Created" state, the updated sheet templates (i.e., Facility, User, and Target) are consolidated back into the format used during the initial "Create" flow.
This ensures that when you attempt to update the campaign again, it will be treated as the first update.

Retry API Payload

Campaign Process flow

🔄 Simplified Parent-Child Campaign Management Design Flow

Core Principle

At any point in time, only one campaign—either the parent or its successfully completed child—should be considered active and operational. A parent campaign remains active until a child campaign completes successfully and takes over its role.

1️⃣ Initial Child Campaign Creation

Validation:
- Before creating a new child campaign, verify whether the parent already has a child campaign with:
  - isActive: true
- If such a child exists, reject the request

2️⃣ During Child Campaign Processing (Update Phase)

The child campaign continues with:
- isActive: true
- status reflecting progress (e.g., inprogress, validating)
The parent campaign remains:

3️⃣ On Successful Child Campaign Completion

Once the child campaign is fully processed and marked status: 'completed':
- Child remains isActive: true
- Parent's isActive is updated to false
Why: This marks the official handoff. The child becomes the sole operational campaign, and the parent is retired from active use.

4️⃣ Cancelling a Child Campaign

If a child campaign is needed to be cancelled:
- Set its isActive: false
Why: The child is clearly marked as non-operational. The parent continues as the active campaign, and a new child can be initiated later.

5️⃣ On Failed Child Campaign Creation/Update

If a failure occurs during child creation/update:
- Keep isActive: true
- Set status: 'failed'
- Parent remains isActive: true

🔍 Campaign Search Functionality

Approach: Enhance the existing searchProjectTypeCampaignService and searchProjectCampaignResourcData.

Proposed Changes:

File: src/server/config/models/searchCampaignDetails.ts

Add:
- isChildCampaign?: boolean
- parentId?: string

File: src/server/utils/campaignUtils.ts → buildSearchQuery()

Modify query generation:
- If isChildCampaign === true, add AND parentId IS NOT NULL
- If isChildCampaign === false, add AND parentId IS NULL
- If parentId is specified, add AND parentId = $X

🔎 How to Search

1. All child campaigns:

{

"tenantId": "yourTenantId",

"isChildCampaign": true

}

2. Currently active (parent or completed child):

{

"tenantId": "yourTenantId",

"isActive": true,

"status": "completed" // optional

}

3. Cancelled or inactive child campaigns:

{

"tenantId": "yourTenantId",

"isChildCampaign": true,

"isActive": false

}

4. Parent campaigns not yet replaced:

{

"tenantId": "yourTenantId",

"isChildCampaign": false,

"isActive": true

}

⚙️ Code-Level Integration

✅ Max One Active Child Validation

In createProjectTypeCampaignService or processBasedOnAction:
- Query for existing active children (isActive: true) before proceeding.

✅ Deactivating Parent After Child Completion

On child status transition to completed:
- Fetch parent campaign
- Set isActive = false
- Persist the update ( via Kafka)

✅ Campaign Cancellation API

Endpoint: POST /project-factory/v1/project-type/cancel-campaign

Purpose: Cancels a campaign by setting:

isActive = false
status = "cancelled" The update is sent via Kafka.

🔧 Request Body

🟢 Success Response (200)

Returns updated campaign with:

isActive: false
status: "cancelled"

🔁 Idempotency

Safe to call multiple times. Same result is returned.

🧩 Internals

Validates inputs
Fetches campaign
Updates status
Produces to Kafka topic

Manage Boundary APIs

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

Excel Format - Boundary Bulk Upload

The Excel sheet should be formatted as follows:

Country

Província

Distrito

Posto Administrativo

Localidade

Aldeia

Unique Code Generation

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

Boundary

Code

If there are two districts (boundaries at the same level) with the same name (for example, BLR) under different parent-level boundaries, 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.

Returns:

Updated element codes map.

Steps:

Initialise Column Data:
- Initialise an array to store column data.
Extract Unique Elements:
- Iterate through each row of the boundary list.

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 the provided boundary codes.

Steps:

Convert Boundary Map:
- Change the boundary map to a list of objects with key and value.
Prepare Request:

Boundary Relationship Creation

`Create Boundary Relationship`

Purpose:

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

Steps:

Convert Boundary Map:
- Transform the boundary map into a list of {key, value} objects.
Initialise Request:

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:

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

Integration with Microplan

/project-factory/v1/project-type/fetch-from-microplan

Overview

This document describes the web flow for updating an existing campaign by integrating the existing microplan with the console. This process involves the integration of several backend services to update the data in the facility, target, and user sheet in the existing campaign object.

Services Used

Core Services
Plan Service
Census Service

Sequence Flow

Initiate Request: The request body for the microplan integration will be:
Validations: This request validates whether the campaignId and planConfigurationId exist in the system or are invalid.
Update Facility Sheet: The process begins by searching for the facility associated with the planConfigurationId, which provides details about the facility code and the linked service boundaries. Next, a facility sheet is generated for the campaign. Once the facility sheet is obtained, the service boundaries are populated within the sheet where the specific facility code is present.

The sample data for filling the target sheet is:

Here, the type of the target sheet is constructed as Target-<projectType> of the campaign.

to: This specifies the key to be extracted from the census object.
from: These are the keys representing the headers that need to be enriched in the generated sheet.

This mapping ensures that the data from the census object is correctly aligned and populated into the appropriate headers in the target sheet. After populating the worksheet with data from the census objects, the file is uploaded to the filestore. Next, the sheet is validated using the Validate API with the type boundaryWithTarget. Once the validation is completed, the campaign object is updated with the newly generatedfilestoreId and resourceId. We get data from the census search as follows:

Update User Sheet: The process begins by fetching the plan associated with the planConfigurationId and retrieving the boundaries from the campaign details, specifically those of type LOCALITY. Next, for each locality, the count of all roles is obtained from the plan search response. This role count is then enriched in the corresponding sheet for that locality.

To map the roles and their requirements for determining the role count in the plan facility response, the predefined MDMS schema for the target is utilised. In this schema:

to: Represents the role to be mapped.
from: Specifies an array of keywords that must be present in the key to identify the role.

This ensures accurate and efficient mapping and population of role-related data in the sheet. Also used -

Added a field consolidateUsersAt in the schema to filter for boundaries based on a particular hierarchy; Example: LOCALITY Sample Data:

Sample MDMS data:

After populating the sheet with the appropriate information, the sheet is validated by calling the Validate API with the type userWithBoundary. Once the validation is successful, the campaign object is updated accordingly. We get the data to fill in this sheet from this API:

Conclusion

This document outlines the process for updating an existing campaign by integrating a microplan through the admin console. It involves validating the campaignId and planConfigurationId and updating the facility, target, and user sheets using data from backend services.

Facility Sheet: Generated using facility details from the planConfigurationId, enriched with service boundaries, validated, and updated in the campaign object.
Target Sheet: Created by mapping census data to boundary codes using the MDMS schema. The sheet is populated, validated, uploaded, and updated in the campaign object.
User Sheet: Locality boundaries are fetched, role counts are calculated and enriched using the MDMS schema, and the sheet is validated before updating the campaign object.

This integration ensures accurate, automated updates and efficient campaign management.

Manage Data APIs

This section of the documentation details APIs for creating, searching, generating, and downloading data, including request/response structures, flows, and error handling. Campaign Creation V2 Flow – Documentation

Overview

The Campaign Creation V2 flow improves upon the earlier V1 implementation by introducing a type-aware, config-driven, and extensible architecture for handling Excel-based data uploads.

This change simplifies how Excel sheets are parsed, validated, transformed, and annotated, making the flow scalable and easier to maintain.

V1 vs V2 – Key Differences

🛠️ API: POST /v2/data/_process

🔹 Purpose

Processes uploaded Excel files for validation-type sheets. This API is exposed to the client UI through role-action mapping.

🔹 Supported Types

🔹 Sample Payload

🔹 Processing Behavior

Sheet Parsing: Extracts data from each sheet using configured schema.
Data Transformation: Applies field-level or row-level transformations (e.g., date parsing, ID lookup).
Validation: Enforces rules defined in MDMS.
Error Annotation: Errors are annotated row-wise and can be returned in response or in the processed Excel file.

🔄 API: POST /v2/data/_process-any

🔹 Purpose

Processes any sheet type (both validation and data entry).

Internal Use Only – this API is not exposed via role-action mapping. It is used internally by services like project-factory-service.

🔹 Differences from /v2/data/_process

🔹 Sample Payload

Same structure as /v2/data/_process, e.g.,

✅ When to Use Which API?

🔐 Role Access Mapping

🧠 Internal Flow – How Processing Works

The V2 system uses a dynamic, type-based processing mechanism to ensure clean separation of concerns and better maintainability.

🔧 Step 1: Type-Based Class Resolution

The system uses the type field in the request to determine the processing class:

const className = `${ResourceDetails?.type}-processClass`;

This maps to a file like

processFlowClasses/userValidation-processClass.ts

processFlowClasses/facility-processClass.ts

🔄 Step 2: Dynamic Class Import and Execution

const { TemplateClass } = await import(classFilePath);

const sheetMap = await TemplateClass.process(ResourceDetails, wholeSheetData, localizationMap);

Each class implements a static process() method that:

Accepts the parsed sheet data
Performs transformation + validation
Returns a SheetMap object with data, errors, and annotations

🧩 Inside Each Type Class

Each class (e.g., userValidation-processClass) encapsulates all logic for that type:

Data cleanup or enrichment
Business rule validation
Conditional field logic
Return of structured, annotated sheet data

🌟 Why This Approach?

📄 Campaign Template Generation V2 Flow – Documentation

🧾 Overview

The Template Generation V2 flow is an upgrade over the earlier /v1/data/_generate implementation. It enables a loosely coupled, type-driven, and config-based Excel template generation system, ensuring better maintainability and extensibility.

The legacy endpoint:

http

POST /v1/data/_generate

has now been replaced with:

http

POST /v2/data/_generate

🔁 V1 vs V2 – Key Differences

⚙️ Earlier most things were hardcoded. Now, ~80% is config-driven via MDMS or file-based config, and ~20% uses dynamic functions for specialized transformation logic.

🛠️ API: POST /v2/data/_generate

🔹 Purpose

Generates Excel templates for campaign resource types such as user, facility, boundary, etc., using MDMS-driven config and dynamic logic. UI integrates with this endpoint to export downloadable templates for upload flows.

🔹 Required Query Parameters

🔹 Sample cURL Request

🔧 Internal Flow – How Generation Works

🔹 Step 1: Type-Based Class Resolution

const className = `${responseToSend?.type}-generateClass`;

let classFilePath = path.join(__dirname, '..', 'generateFlowClasses', `${className}.js`);

if (!fs.existsSync(classFilePath)) {

classFilePath = path.join(__dirname, '..', 'generateFlowClasses', `${className}.ts`);

}

Expected files (per type):

user-generateClass.ts
facility-generateClass.ts
boundary-generateClass.ts

🔄 Step 2: Dynamic Import and Execution

const { TemplateClass } = await import(classFilePath);

const sheetMap = await TemplateClass.generate(ResourceDetails, localizationMap);

Returns an object with:

✅ Sheet Name(s)
✅ Header Row(s)
✅ Pre-filled Data (if any)
✅ Column metadata (dropdowns, styles, widths)

🔃 Transform Configuration (transformConfigs)

This configuration defines how API response data maps to Excel sheets and how sheet uploads map back to request payloads.

🔹 Driven By

MDMS config
File-based transformConfigs
Optional dynamic transformation functions (transformBulkX, transformX)

🧩 Sample: employeeHrms

HRMS Config

🧩 Sample: Facility

🔹 Field Properties

🌟 Why This Approach?

🔁 Retry Mechanism During Campaign Creation

🧾 Overview

The retry mechanism allows safe re-triggering of campaign creation only if the campaign is in a drafted or failed state. It uses the existing /v1/project-type/update API with action: "create" inside CampaignDetails. There is no dedicated retry API.

⚠️ Not fully idempotent 🔁 Re-uses creation API ✅ Works only for failed/drafted campaigns

🚫 When Retry Does NOT Work

If the campaign is already created and active, and a retry (action: "create") is attempted, it will throw an error.
Only campaigns in the following statuses are allowed to be re-processed:

["drafted", "failed"]

🚀 Retry API (Same as Create)

http

CopyEdit

POST /project-factory/v1/project-type/update

🔹 Required Query Params

📦 Sample Request Body

{

"RequestInfo": {

"apiId": "Rainmaker",

"authToken": "your-auth-token",

"userInfo": {

"uuid": "user-uuid",

"roles": [{ "code": "CAMPAIGN_MANAGER", "tenantId": "mz" }],

"tenantId": "dev"

}

"CampaignDetails": {

"campaignId": "5c845eb8-f8b2-43d0-a301-8e24692499f1",

"campaignNumber": "HCMP-CAM-00001",

"action": "create",

...

}

📊 Internal Tables Used

📁 eg_cm_campaign_data — Sheet Row Status

Tracks each data row uploaded from sheet.

export const dataRowStatuses = {

failed: "failed",

completed: "completed",

pending: "pending"

}

🔗 eg_cm_campaign_mapping_data — Mapping Status

Stores mapping status per row and boundary.

export const mappingStatuses = {

toBeMapped: "toBeMapped",

mapped: "mapped",

toBeDeMapped: "toBeDeMapped",

deMapped: "deMapped"

}

🧩 eg_cm_campaign_process_data — Process Flow Status

Tracks which steps of campaign creation are done/pending/failed.

CopyEdit

export const processStatuses = {

failed: "failed",

pending: "pending",

completed: "completed"

}

👇 Process Names

export const allProcesses = {

facilityCreation: "CAMPAIGN_FACILITY_CREATION_PROCESS",

userCreation: "CAMPAIGN_USER_CREATION_PROCESS",

projectCreation: "CAMPAIGN_PROJECT_CREATION_PROCESS",

facilityMapping: "CAMPAIGN_FACILITY_MAPPING_PROCESS",

userMapping: "CAMPAIGN_USER_MAPPING_PROCESS",

resourceMapping: "CAMPAIGN_RESOURCE_MAPPING_PROCESS",

userCredGeneration: "CAMPAIGN_USER_CRED_GENERATION_PROCESS"

}

🔁 Retry Logic Summary

✅ Final Notes

This approach provides partial re-execution based on current statuses.
Helps in recovery from partial failure (e.g., during bulk upload).
Prevents overwriting already created resources.
Make sure to validate campaign status before retrying.

📘 Document: App Config & Localisation Setup During Campaign Creation

🧩 Overview

When a new campaign is created using the /project-factory/v1/project-type/create API, the backend asynchronously triggers:

Creation of campaign-specific MDMS module configs
Copying of base localisations to campaign-localised keys

This happens in the background and does not block the campaign creation response.

⚙️ Trigger Point

API Endpoint

bash

CopyEdit

POST /project-factory/v1/project-type/create

Trigger Logic

CopyEdit

createAppConfig(tenantId, campaignNumber, campaignType); // No await

createAppConfig(...) runs without await
The API returns immediately while config generation runs in parallel

🔧 Internal Flow: createAppConfig(...)

1. Fetch Enabled Template Modules

From schema: HCM-ADMIN-CONSOLE.FormConfigTemplate

CopyEdit

const templateModules = (templateResponse?.mdms || [])

.map(item => item?.data || [])

.flat()

.filter(module => !module?.disabled);

✔️ Only modules where disabled !== true are processed.

2. Localisation Copy

For each module:

Base Key: hcm-base-{moduleName}-{campaignType}
Target Key: hcm-{moduleName}-{campaignNumber}

For each locale:

Fetch localisation entries using the base key
Replace module with the new target key
Upload entries in chunks of 100

await localisation.createLocalisation(chunk, tenantId);

🧩 RequestInfo is not passed 💡 Failures are logged but do not interrupt other locale uploads

3. Insert MDMS Module Config

Target schema: HCM-ADMIN-CONSOLE.FormConfig

Each module:

Is enriched with:
project: campaignNumber
isSelected: true
Is posted to MDMS v2 API:

CopyEdit

await httpRequest(mdms_create_or_update_url, requestBody);

🧱 Module configs are associated with the campaign being created.

✅ Summary Table

📝 Additional Notes

Ensures every campaign has its own set of configuration modules and localised messages
Localisation is cloned and renamed from base templates for each campaign
This system supports high performance and reliability through async background execution

Low Level Design

Registries

Individual

Overview

API Spec

Sequence Diagrams

Household

Overview

API Spec

Sequence Diagrams

Product

Overview

API Spec

Sequence Diagrams

Facility

Overview

API Spec

Sequence Diagrams

Attendance

Overview

Expense

Overview

API Specifications

API Contract Link

Data Model

DB Schema Diagram

Web Sequence Diagrams

Persister

Related Topics

Services

Project

Overview

API Spec

Stock

Overview

API Spec

Sequence Diagrams

Referral

Overview

API Spec

Sequence DIagrams

Muster Roll

Overview

Dependencies

Code

API Specifications

API Contract Link

Data Model

DB Schema Diagram

Master Data

Related Topics

Expense Calculator

Overview

API Specifications

Dependencies

Master Data

Sequence Diagrams

DB Diagram

MDMS data

Related Topics

Attendance

Overview

Features

Sequence Diagram

Select Project

Overview

Interface Elements

Register Inbox

Overview

Interface Elements

Generate Bill

Overview

Features

Sequence Diagram

Project & Bill Aggregation

Overview

My Bills

Enumeration

Overview

Key Features