This section provides a detailed and comprehensive view of the micro planning system's internal mechanics. The LLD focuses on providing API specifications, sequence diagrams and database schema. This section serves as a blueprint for developers and engineers to implement the system accurately.

The Microplanning system is designed to allow users to generate, validate, and approve micro plans across various geographic boundaries. The system's architecture includes services for handling population data, plan estimates, employee assignments and facility linkages. The system is scalable, secure, and optimised for local and national-level campaigns.

High Level Design

Low Level Design

Overview

The Facility Catchment Mapper is responsible for mapping health facilities to their respective geographic catchment areas (e.g., villages, districts) using data provided via an API. This mapping ensures that each facility is associated with a specific community, enabling efficient distribution of resources during health campaigns.

Responsibilities:

• Assign health facilities to geographic catchment areas (e.g., villages, localities).

• Ensure each village or locality is mapped to an appropriate facility.

• Review and update facility assignments when necessary based on campaign requirements.

Steps

Workflow for Facility Catchment Flow

Below are the detailed steps for the facility catchment mapping process.

Step 1: Log in to the Platform

• Actor: Facility Catchment Mapper

• Objective: Access the facility catchment management dashboard.

• Process: The Facility Catchment Mapper logs into the microplanning platform using their credentials and navigates to the facility catchment module.

• Outcome: The system displays a list of available campaigns and their linked facilities retrieved from the API.

Step 2: View Facility Data via Plan Facility

• Actor: Facility Catchment Mapper

• Objective: Access the list of facilities linked to the microplan, pulled from the Plan Facility.

• Process:

  • The system retrieves the list of facilities linked to the current campaign and displays them in the catchment mapping dashboard.

  • The data from the Plan Facility includes key attributes such as:

    • Facility Name

    • Facility Type (e.g., clinic, hospital)

    • Capacity (e.g., beds, vaccine storage)

    • Facility Status (active/inactive)

    • Facility Location (latitude and longitude)

• Outcome: The Facility Catchment Mapper can view all the facilities available for mapping in real time.

Step 3: Assign Facilities to Catchment Areas

• Actor: Facility Catchment Mapper

• Objective: Map each facility to a corresponding catchment area (e.g., village, district).

• Process:

  • Catchment Area Mapping:

    • Each facility is mapped to a specific administrative boundary (village, district, etc.).

    • Facility location (latitude and longitude) is used to cross-reference and ensure the correct geographic catchment area is assigned.

  • Mapping Considerations:

    • Ensure each catchment area is assigned to the most appropriate or nearest facility based on geographic proximity.

    • Avoid conflicts where multiple facilities are mapped to the same geographic area, unless required by the campaign.

• Outcome: Each facility is successfully assigned to its respective catchment area, ensuring proper resource allocation during campaign execution.

Step 4: Validate Catchment Area Assignments

• Actor: Facility Catchment Mapper

• Objective: Ensure the accuracy and validity of facility assignments to catchment areas.

• Process:

  • The system highlights any potential mapping errors or overlaps, such as:

    • Unmapped villages or localities.

    • Facilities assigned to incorrect or multiple areas.

  • The Facility Catchment Mapper reviews and resolves these issues before finalizing the assignments.

  • Validation checks include:

    • Ensure each village or locality is mapped to exactly one facility.

    • Verify that all mandatory fields (facility name, type, status, location) are populated.

• Outcome: The mapping is validated, and all errors are corrected before approval.

Step 5: Approve and Save Facility Catchment Mapping

• Actor: Facility Catchment Mapper

• Objective: Finalize and approve the facility catchment mapping.

• Process:

  • Once all assignments are validated, the mapper approves the mappings.

  • The system saves the approved mappings, and the data is made available for use in microplan resource estimation and campaign execution.

• Outcome: Facility catchment mapping is finalized and stored in the system, ensuring proper facility allocation for the upcoming health campaign.

Key Considerations for Facility Catchment Mapping:

1. Geographical Accuracy:

   • Facilities must be assigned to the correct administrative boundaries based on their geographic coordinates.

2. Avoiding Overlap:

   • Each catchment area (village, locality, etc.) should be mapped to only one facility unless otherwise required by the campaign's objectives.

3. Handling Missing Facilities:

   • If a catchment area does not have a mapped facility, it must be flagged for review and resolution before the campaign begins.

Web Sequence Diagrams

Here are the articles in this section

Overview:

Census management service handles population data and its validation/approval.

API Specification:

Census Management API Specification

Sequence Diagrams:

Census Management APIs

Database Schemas:

Service Architecture:

Overview of Services:

1. Plan Management - Handles micro plan setup, micro plan employee assignments, micro plan facility linkage, micro plan estimations and its validation/approval.

2. Census Management - Handles population data and its validation/approval.

3. Resource Generator - Utility service which reads population and facility excel files uploaded by the user to generate population records and plan facility linkages in the system.

4. Project Factory - Utility service which exposes APIs to generate population data upload template and facility data upload template.

Service Interactions:

Overview:

Plan management service handles micro plan setup, micro plan employee assignments, micro plan facility linkage, micro plan estimations and its validation/approval.

API Specification:

Plan Management API Specification

Sequence Diagrams:

Plan Configuration APIs

Plan Employee Assignment APIs

Plan Facility APIs

Plan Management APIs

Database Schemas

HCM Microplan Web - Navigation Overview

The HCM Microplan Web platform is designed to be easy to use, giving administrators and supervisors simple access to the tools they need for setting up microplans, managing data. The navigation is divided into two main sections: Set Up Microplan and Supervisor Flow.

Set Up Microplan

This section is intended for system administrators and users responsible for the initial setup of the microplan, configuration, and data management. The available options under this section include:

• Microplan Details: Configuration of the fundamental details of the microplan, including objectives, timelines, and other key parameters.

• Boundary Selection: Define and select the geographical boundaries (countries, provinces, districts, etc.) relevant for the microplan.

• Data Management: Manage the population data and other datasets needed for the microplan, including data entry, updates, and validation.

• Microplan Assumptions: Specify the assumptions that will guide the microplan, including factors like updated registry data, user roles, and collection methodology.

• Formula Configuration: Set up formulas and calculations used for resource distribution, target population estimates, or other metrics within the microplan.

• User Tagging: The User Tagging Screen enables the Microplan admin to assign various roles to registered users, linking them to specific tasks and responsibilities within the microplan.

• Summary Screen: The Summary Screen is a critical page in the microplan setup process, where system administrators and program managers can review, validate, and edit the data configured for the microplan. It provides.

User Management

This section allows administrators to manage users, assign roles, and control access levels for those interacting with the system. This ensures the security and integrity of the platform, with specific permissions for different types of users (e.g., system administrators, data collectors, reviewers).

Supervisor Flow

This section is tailored to supervisors who oversee the implementation and validation of the microplan. Key functionalities under this flow include:

• My Microplan: A personalized dashboard where supervisors can view and manage the microplan assigned to them.

• Select Activity: Choose specific activities related to the microplan that need to be validated or reviewed.

• Validate and Approve Population Data: Validate the collected population data and approve it for further processing and execution of the health campaign.

• Assign Facility to Villages: Assign health facilities to specific villages or regions, ensuring resources and health services are properly allocated.

Here are the articles in the section:

Microplan Details

Boundary Selection

Data Management

Microplan Assumptions

Formula Configuration

Once the system administrator completes the microplanning setup, including defining campaign boundaries, configuring facilities, and assigning roles, the Supervisor Flow begins.

The Supervisor Flow for managing microplans enables supervisors to track, edit, validate, and finalise microplans associated with public health campaigns. Each microplan provides specific details about campaigns, statuses, and associated actions, ensuring effective campaign execution.

The table below outlines roles, their corresponding role codes, and descriptions of responsibilities for supervisors:

Overview

The Microplan Estimation Approver plays a critical role in ensuring the accuracy and approval of resource estimation for health campaigns. This user is responsible for reviewing the resource estimations generated by the system, validating assumptions, and approving or rejecting the final microplan estimations. The goal is to ensure that the estimated resources (e.g., vaccines, bednets, medical personnel) align with the actual needs of the campaign, based on the validated population and facility data.

Responsibilities:

• Review and validate resource estimation formulas.

• Approve or reject microplan resource estimations.

• Adjust estimation parameters and assumptions if necessary.

• Ensure that the approved resource estimation aligns with the campaign's needs.

Steps

Workflow for Microplan Estimation Approver Flow

This section details the steps in the microplan estimation approval process.

Step 1: Log in to the Platform

• Actor: Microplan Estimation Approver

• Objective: Access the microplan estimation dashboard.

• Process: The microplan Estimation Approver logs into the platform using their credentials, granting access to the estimation review and approval module.

• Outcome: The system displays a list of microplans that require review, with detailed estimations ready for approval.

Step 2: Review Resource Estimation

• Actor: Microplan Estimation Approver

• Objective: Review the resource estimations generated by the system for the current campaign.

• Process:

  • The system presents the resource estimation calculations based on the uploaded population and facility data.

  • The estimations are divided into key resources such as:

    • Vaccines: Estimated based on population size and target population.

    • Bednets: Calculated for campaigns like malaria prevention.

    • Personnel: Estimated based on the required workforce for each facility and catchment area.

• Outcome: The microplan estimation approver has a comprehensive overview of the resources estimated for the campaign, with breakdowns by resource type.

Step 3: Review and Validate Assumptions

• Actor: Microplan Estimation Approver

• Objective: Ensure that the assumptions used for resource estimations are accurate and reasonable.

• Process:

  • The system displays key assumptions that drive the resource estimation formulas, such as:

    • Target Population: Number of people eligible for the intervention (e.g., children aged 3-11 months for SMC campaigns).

    • Resource Allocation: Number of resources (e.g., bednets, vaccines) per person or household.

    • Distribution Strategy: House-to-house, fixed post, or a combination of both.

  • The approver cross-checks these assumptions with known data and campaign requirements.

  • If any assumptions seem inaccurate or unreasonable, the Microplan Estimation Approver can modify assumptions for list of specific boundaries

• Outcome: The assumptions used for resource estimation are validated, and any necessary corrections are made.

Step 4: Approve or Reject the Microplan Estimation

• Actor: Microplan Estimation Approver

• Objective: Make the final decision to approve or reject the resource estimation for the campaign.

• Process:

  • After reviewing the resource estimation, the Microplan Estimation Approver selects Approve or Reject.

    • Approve: Confirms that the estimation is valid and the required resources are accurately calculated. Once approved, the estimation becomes final and is locked for campaign execution.

    • Reject: If the estimation is inaccurate, the approver provides feedback and requests a re-evaluation of the data or assumptions.

  • The system prompts the approver to provide reasons for rejection, which are communicated to the appropriate team for corrections.

• Outcome: Once approved, the resource estimation is finalized, and the required resources are allocated for the campaign. If rejected, the estimation returns to the appropriate team for review and modification.

Web Sequence Diagram

Data Approver Flow

The Data Approver is responsible for validating population data collected by data collectors. The role primarily ensures that population data used for microplan resource estimation is accurate and consistent with predefined rules. Data approvers play a crucial role in identifying discrepancies and ensuring the validity of population numbers before final approval.

Responsibilities:

• Validate population data collected from the field.

• Identify discrepancies in population estimates.

• Approve or flag data for further review and corrections.

Note : In the current version we are not including data collectors. Population data uploaded in the system admin flow will be sent for approval

Steps

Workflow for Data Approver Flow

The following describes the step-by-step workflow for the Data Approver:

Step 1: Log in to the Platform

• Actor: Data Approver

• Objective: Access the data review dashboard.

• Process: The Data Approver logs into the microplanning platform with their credentials.

• Outcome: The system displays all pending data that needs to be validated.

Step 2: Review Submitted Population Data

• Actor: Data Approver

• Objective: View population data collected by Data Collectors.

• Process:

  • The Data Approver navigates to the population data review section.

  • The system presents the population data per administrative level (village, district, etc.).

  • Data is compared against previously uploaded data or other authoritative sources for discrepancies.

• Outcome: The Data Approver views all population-related information for selected regions, including:

  • Total Population

  • Target Population (e.g., children aged 3-11 months and 12-59 months for SMC campaigns)

  • Latitude and Longitude (if available)

Step 3: Identify Discrepancies

• Actor: Data Approver

• Objective: Identify and highlight any discrepancies in the population data.

• Process:

  • The Data Approver can manually review records to ensure the accuracy of the data.

• Outcome: The system flags any discrepancies for further review, such as:

  • Significant deviations from earlier data (e.g., a village's population is reported as 5,000 when the previous figure was 2,000).

Step 4: Modify and Correct Data (If necessary)

• Actor: Data Approver

• Objective: Make necessary corrections to flagged data before approval.

• Process:

  • If the Data Approver identifies errors or discrepancies, they may either:

    • Request corrections from the Data Collector.

    • Manually correct the data in the system, if they have the necessary authority and information.

  • Corrections may involve:

    • Adjusting total population numbers.

    • Updating target population estimates.

    • Correcting missing or incorrect geographic data (e.g., coordinates).

• Outcome: The flagged data is corrected and updated in the system, ready for re-validation.

Step 5: Approve Population Data

• Actor: Data Approver

• Objective: Final approval of population data for use in resource estimation.

• Process:

  • Once all discrepancies are resolved, the Data Approver selects the data records for final approval.

  • The system allows bulk approval or individual record validation based on user preferences.

• Outcome: Approved population data is locked and made available for further processes, such as microplan resource estimation.

Step 6: Monitor Data Changes

• Actor: Data Approver

• Objective: Continuously monitor any changes to population data during the campaign.

• Process:

  • The system provides alerts if any new data is submitted or if there are significant changes to previously approved data.

  • Data Approvers can review and re-approve any updates or revisions during the campaign.

• Outcome: All data changes are tracked, ensuring continuous data integrity throughout the microplanning process.

Web Sequence Diagrams

System Administrator Flow

The System Administrator is responsible for setting up the entire microplanning platform, which includes defining campaign boundaries, configuring facilities, and assigning roles. This user operates at the national or country level and ensures all configurations align with campaign objectives.

Steps

1. Capture Campaign Details:

   • Actor: System Administrator/Program Manager

   • Objective: Configure campaign information.

   • Process:

     • Select Disease: Choose the disease for the campaign (e.g., malaria).

     • Campaign Type: Select from options like Bednets or SMC (Seasonal Malaria Chemoprevention).

     • Resource Distribution Strategy: Choose between Fixed post, House-to-House, or a combination of both.

     • Next/Back: Proceed to the next screen or return to the previous step.

   • Validation:

     • All fields are mandatory before proceeding.

2. Naming the Microplan:

   • Actor: System Administrator/Program Manager

   • Objective: Assign a unique name to the microplan.

   • Process:

     • Auto-Suggested Name: The system provides a default name based on the format: Country-Disease-CampaignType-MonthLast2DigitsOfYear.

     • User Input: Option to modify the name while following a strict naming convention.

   • Validation:

     • The name must be unique and follow specific guidelines (e.g., minimum 3 characters, no special characters except _() ).

3. Select Campaign Boundaries:

   • Actor: System Administrator/Program Manager

   • Objective: Choose the geographic administrative boundaries (country, province, district, village, etc.).

   • Process:

     • Multi-Select Dropdowns: Select from a multi-select list of administrative divisions.

     • Validation: All fields are mandatory.

4. Upload Population Data:

   • Actor: System Administrator/Program Manager

   • Objective: Upload population data required for resource estimation.

   • Process:

     • Download Template: Download a pre-configured Excel template.

     • Input Data: Enter total and target population, village coordinates, etc.

     • Upload: After filling in the template, upload it back to the system.

   • Validation:

     • Ensure data integrity (e.g., total population must be greater than zero, population data must be whole numbers).

5. Upload Facility Data:

   • Actor: System Administrator/Program Manager

   • Objective: Set up facilities to be used during the campaign.

   • Process:

     • Download Facility Template: Fill out the downloaded template with facility details (e.g., facility type, capacity, geographic coordinates).

     • Upload and Validate: Once filled, upload the template.

   • Validation:

     • Mandatory fields such as facility name, type, and capacity must be filled in.

6. Manage Microplan Assumptions:

   • Actor: System Administrator/Program Manager

   • Objective: Configure assumptions for calculating required resources.

   • Process:

     • Set parameters like population density and distribution strategy.

   • Validation:

     • Input values must be numerical.

7. Access Control and Role Configuration:

   • Actor: System Administrator

   • Objective: Define and assign roles and permissions (e.g., Data Collectors, Microplan Approvers).

   • Process:

     • Configure roles and assign them to specific users.

     • Define user boundaries and access hierarchies.

Web Sequence Diagrams

Overview

This page displays a tailored list of microplans that the logged-in supervisor is tagged to. Supervisors can manage these microplans within their jurisdiction, ensuring campaign activities are effectively tracked and validated.

Key Features:

• Microplans Access: Supervisors will see a list of microplans they are tagged to. This ensures that supervisors can only view and manage the microplans relevant to their role and responsibilities.

• filterUniqueByPlanConfig Parameter: The filterUniqueByPlanConfig parameter is used here to return all the microplans associated with the logged-in supervisor. This guarantees that only relevant data is displayed.

• Jurisdiction-Based Access: Supervisors have jurisdiction based on the hierarchy they belong to. For example, a district-level supervisor can access microplans for their district, while a province-level supervisor can access microplans specific to their province.

Sample Hierarchy

Interface Elements

Header Section

• Title: My Microplans represents the section for managing microplans.

• Tabs:

  1. All: Displays all microplans.

  2. Completed Setup: Lists microplans with finalized setup.

  3. Validation in Progress: Microplans undergoing validation.

  4. Microplan Finalised: Displays finalized microplans.

Search Functionality

• Search Bar: Allows filtering microplans by name.

• Clear Button: Resets the name search to display all microplans.

Microplan Table

The table lists the microplans in a tabular format. Each row represents a microplan, and the columns provide detailed information:

Actions for Each Microplan

Process Steps

Step 1: Access My Microplans

• Objective: View and manage microplans.

• Process: Navigate to the My Microplans section.

• Outcome: A list of all microplans is displayed, with tabs for status-based filtering.

Step 2: Search for a Microplan

• Objective: Locate a specific microplan.

• Process: Use the search bar to input the microplan name. Click Clear to reset the search.

• Outcome: Filtered results display matching microplans.

Step 3: Perform Actions

• Based on the status, perform the following actions:

  • Completed Setup: Click Start Validation to begin validating the microplan.

  • Validation in Progress: Click Edit to modify the microplan details.

  • Microplan Finalised: Click Download Estimations to save related data.

Endpoints

citymodule needed to run campaign module in an environment:Link: https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-QA/data/mz/tenant/citymodule.json

{
      "module": "Microplan",
      "code": "Microplan",
      "active": true,
      "order": 1,
      "tenants": [
        {
          "code": "mz"
        }
      ]
    }

Refer to the below ID's link in QA:

• roles need to be added in rolesLink:

The following roles have been added in the MDMS:

MICROPLAN_ADMIN
ROOT_FACILITY_CATCHMENT_MAPPER
FACILITY_CATCHMENT_MAPPER
ROOT_POPULATION_DATA_APPROVER
POPULATION_DATA_APPROVER
ROOT_PLAN_ESTIMATION_APPROVER
PLAN_ESTIMATION_APPROVER

The following actions are added to the MDMS, the actions are mapped to roles using rolesactions.js

The following are the actions Idsmapped to the roles

1639 1758 1765 1914 1915 1916 1917 1918 1919 
1920 1921 1922 1923 1924 1925 1926 1927 1928 
1929 1930 1931 1932 1933 1934 1935 1936 1937 
1938 1939 1940 1941 1942 1943 1944 1945 1946 
1947 1948 1949

Link for reference:

Each of the action id is a path for a specific action

The actions are defined in

The "hcm-microplanning" module in the application leverages various master data configurations to drive the microplanning and resource distribution functionalities. These configurations are crucial for ensuring that the system adheres to the right structure and rules for microplan creation, distribution strategy, and other related operations.

Master Details for "hcm-microplanning":

The following master details are part of the hcm-microplanning module

Each of the master will access their respective master data in the mdms.

hcm.microplanning.MicroplanNamingConvention, hcm.microplanning.MicroplanNamingRegex
hcm.microplanning.ResourceDistributionStrategy, hcm.microplanning.RolesForMicroplan
hcm.microplanning.HypothesisAssumptions, hcm.microplanning.RuleConfigureOutput
hcm.microplanning.RuleConfigureInputs, hcm.microplanning.AutoFilledRuleConfigurations
hcm.microplanning.RuleConfigureOperators, hcm.microplanning.RegistrationAndDistributionHappeningTogetherOrSeparately
hcm.microplanning.HierarchyConfig, hcm.microplanning.VillageRoadCondition
hcm.microplanning.VillageTerrain, hcm.microplanning.SecurityQuestions
hcm.microplanning.FacilityType, hcm.microplanning.FacilityStatus
hcm.microplanning.VehicleDetails, hcm.microplanning.ContextPathForUser
hcm.microplanning.DSSKPIConfigs, hcm.microplanning.HierarchySchema

Description of the master details:

1. Microplan Naming Convention - Defines the naming structure for microplans, ensuring consistency in naming across the system.

2. Microplan Naming Regex - Provides a regular expression used for validating microplan naming conventions.

3. Resource Distribution Strategy - Describes the strategy for resource allocation, ensuring resources are distributed effectively and according to predefined rules.

4. Roles for Microplan - Contains data related to the roles and permissions associated with the microplan process, ensuring appropriate access control.

5. Hypothesis Assumptions - Defines the assumptions used in the creation of hypotheses for microplanning, guiding the analysis process.

6. Rule Configure Output - Contains configurations related to the output of rules, guiding how the rules should be structured and the expected results.

7. Rule Configure Inputs - Contains configurations for the inputs required by rules, ensuring that the correct data is fed into the rule engine.

8. Auto-Filled Rule Configurations - Specifies the auto-filled configurations used by the system for rules, automating parts of the rule configuration process.

9. Rule Configure Operators - Defines the operators used in rule configurations, specifying the operations available for rule evaluation.

10. Registration and Distribution Happening Together or Separately - Specifies whether registration and distribution activities occur together or separately, affecting process flow.

11. Hierarchy Config - Contains the configuration data for the hierarchy structure, defining different levels of hierarchy and their relationships.

12. Village Road Condition - Captures the road conditions in different villages, which may affect resource distribution and microplanning strategies.

13. Village Terrain - Describes the terrain of various villages, helping in the planning of distribution strategies based on geographical factors.

14. Security Questions - Specifies the set of security questions used for user authentication and verification.

15. Facility Type - Defines the types of facilities available within the microplanning system, ensuring proper categorization.

16. Facility Status - Specifies the status of various facilities (e.g., operational, under construction), which helps in planning and distribution.

17. Vehicle Details - Contains information on available vehicles, used for the transportation of resources within the planning scope.

18. Context Path for User - Defines the user-specific context, ensuring the correct path is followed within the system based on the user's role and access.

19. DSS KPI Configs - Defines the configurations for the Key Performance Indicators (KPIs) used by the Decision Support System (DSS), guiding decision-making processes.

20. HierarchySchema: Defines the order of the boundaries

  {
    "type": "microplan",
    "group": [
      "MALARIA"
    ],
    "hierarchy": "MICROPLAN",
    "department": [],
    "lowestHierarchy": "VILLAGE",
    "highestHierarchy": "COUNTRY",
    "splitBoundariesOn": "DISTRICT"
  }
]

These master details are accessed and managed via the BASE_MASTER_DATA schema code to maintain data consistency, accuracy, and facilitate smooth operations within the hcm-microplanning module.

DevOps Configuration

• Global configuration needs to be added to environments.Link: https://github.com/egovernments/DIGIT-DevOps/blob/unified-env/deploy-as-code/helm/environments/unified-health-uat.yaml

• MDMS Data is fetched from: https://github.com/egovernments/egov-mdms-data/tree/UNIFIED-DEV/data/mz/health/hcm-microplanning

Refer here to learn more about the setup environment.

Localisation

The microplan creation process is organised into multiple steps using a stepper for better navigation. The first step in this process is Microplan Details, divided into two sections: Campaign Details and Microplan Details. This document provides an overview of these sections.

1. Campaign Details

The Campaign Details section collects critical information about the campaign to set up the microplan.

Header

• Title: Enter the campaign details Guides users to input required campaign information.

• Description: Please enter the required details to proceed with the microplan setup. Explains the purpose of this section.

Localisation: Both the title and description are fully translatable into multiple languages.

Fields

1. Disease Identified for the Campaign

• Description: Select the disease targeted for the campaign.

• Field Type: Dropdown

• Default Value: Malaria

• Mandatory: Yes

• Usage: Use the dropdown or type to filter options.

Localization: The label is translatable.

2. Type of Campaign

• Description: Specify the type of campaign.

• Field Type: Dropdown

• Default Value: None (user must select a value)

• Mandatory: Yes

• Usage: Select the type from the dropdown.

Localization: The label and options are localizable.

3. Resource Distribution Strategy

• Description: Choose a strategy for distributing resources.

• Field Type: Dropdown

• Default Value: None (user must select a value)

• Mandatory: Yes

• Usage: Select a strategy aligned with campaign goals.

Localization: Fully supports translations for the label and dropdown options.

User Interface

• Dropdown Menu:

  • Accepts text input for filtering options.

  • Includes a dropdown arrow icon for selection.

Validation

• Fields marked with an asterisk (*) are mandatory.

• Users must complete all required fields to proceed.

• Validation rules and error messages are localizable.

2. Microplan Details

The Microplan Details section focuses on naming the microplan for reference and identification in subsequent steps.

Fields

1. Campaign Details Summary

Displays a summary of the campaign information entered:

• Campaign Disease: Malaria

• Campaign Type: SMC Campaign

• Resource Distribution Strategy: House-to-House

2. Name of the Microplan

• Description: Provide a unique name for the microplan.

• Field Type: Text Input

• Mandatory: Yes

Microplan Naming Rules

1. The name must be between 3 and 64 characters in length.

2. Numeric values alone are not allowed.

3. Allowed special characters: -, _, (, ), &.

Naming Regex MDMS: https://unified-qa.digit.org/workbench-ui/employee/workbench/mdms-search-v2?moduleName=hcm-microplanning&masterName=MicroplanNamingRegex

• Provides the regex pattern used to validate microplan names.

Naming Convention Info MDMS: https://unified-qa.digit.org/workbench-ui/employee/workbench/mdms-search-v2?moduleName=hcm-microplanning&masterName=MicroplanNamingConvention

• It contains detailed information about naming conventions and guidelines.

Suggested Name: The system automatically suggests a microplan name based on campaign details. You can use this suggested name or provide a unique name that matches the naming rules.

Example: "Malaria-Bednet Campaign-Fixed Post & House-to-House-29 Nov 24"

Localization: Instructions and validation messages are fully translatable.

API Endpoints and Example Request Payloads

The Data Management step includes two substeps: Population Upload and Facility Upload, enabling users to upload essential data for the microplan.

Population Upload

Description: This substep allows users to upload population data for the campaign.

• Download Template: Download the template for population data.

• Boundary Dependency: The boundaries appearing in the population template are dependent on the boundaries selected in the previous Boundary Selection screen. Tabs in the template will correspond to the districts selected in that screen.

• File Upload: Drag and drop or browse to upload the filled Excel file.

Guidelines:

• Mandatory Fields: The Total Population and Target Population columns are mandatory and must be provided as whole numbers.

• Latitude & Longitude: These fields must be in Degree Decimal or Degree Minute Seconds format.

Facility Upload

Description: This substep allows users to upload facility or point-of-service information.

• Download Template: Download the template for facility data.

• Boundary Codes: The facility template will include boundary codes for the villages selected in the previous Boundary Selection screen in a single Boundary Code sheet.

• File Upload: Drag and drop or browse to upload the filled Excel file.

Guidelines:

• All fields are mandatory except for Latitude and Longitude.

• Latitude & Longitude must be in Degree Decimal or Degree Minute Seconds format.

Error Handling

Validation Process: After the file is uploaded, the system will validate the data. If any errors are found, the system will populate an Error column in the sheet, showing the errors next to the corresponding rows.

Error Preview: Clicking the View Error button will show a preview of the uploaded Excel file, highlighting the errors in the Error column next to the corresponding row.

Re-upload Process: Once the errors are corrected, users can download the validated file, make the necessary changes, and re-upload the file.

Proceeding with Valid Data: Processing will only proceed if a valid sheet with no errors is uploaded. If the sheet is valid, the system will continue to the next step.

Boundary Selection Screen Navigation Warning:

• Warning: If the user navigates back to the Boundary Selection screen, the current uploaded templates for Population and Facility will be discarded. A warning message will appear on the UI to inform the user before they proceed.

Generation and Validation from MDMS Schema

Both the generation and validation of facility and boundary data are based on a schema provided by MDMS.

• Generation: From this schema, fields are converted into columns in the respective upload templates.

• Validation: Validation is performed based on the schema, ensuring that the data adheres to the defined structure.

• Additionally, custom validations are applied to ensure data integrity.

Localization & User Interface

• Localization: All labels, instructions, and error messages are translatable into multiple languages.

• File Upload: The interface supports drag-and-drop or browse-to-upload file options.

• Validation: Validation ensures all required fields are completed and data is properly formatted. Processing will proceed only if a valid sheet with no errors is uploaded.

Here is the updated table with the adjustments:

The different roles involved in the various parts of the microplan are:

1. National Microplan Estimation Approver

2. National Facility Catchment Assigner

3. National Population Data Approver

4. Microplan Estimation Approver

5. Facility Catchment Assigner

6. Population Data Approver

Each role has its own user list (uploaded through User Management Bulk Upload), and the available jurisdictions is based on the boundaries selected in the Boundary Selection screen.

Note:

Each role will have its own screen. Here, we use the National Microplan Estimation Approver role as an example for assigning and unassigning users.

National microplan estimation approver

This screen is for assigning National microplan estimation approver to the current microplan.

Once the system administrator clicks on the ‘Assign National Microplan Estimation Approvers’ button, he/she will be prompted a pop-up to assign the users with ‘National Microplan Estimation Approver’ role to the ongoing microplan.

Here, the system admin will be able to assign/unassign a user to the ongoing microplan.

Search, Assign, Unassign Implementation

Search The search request is made via /health-hrms/employees/_search, using roles as query parameters (e.g., roles: ROOT_PLAN_ESTIMATION_APPROVER). This returns all registered users with the specified role. When the page loads, a request to /plan-service/employee/_search retrieves all users currently assigned to the current microplan.

Assign Upon clicking the assign button, the userServiceUuid from the search response (/health-hrms/employees/_search) is used as the payload, along with the jurisdiction and role. For the National Microplan Estimation Approver role, the jurisdiction is pre-selected as the national level by default.

For other roles, the jurisdiction is automatically pre-selected based on the boundaries set in the Boundary Selection screen. This information is then sent to /plan-service/employee/_create to assign the user to the current microplan.

Unassign Clicking the unassign button sets the active attribute of PlanEmployeeAssignment to false via /plan-service/employee/_create, updating the microplan accordingly.

API Flow:

The process for assigning users to each role is the same: open the roles screen and assign registered users within the appropriate jurisdiction.

Note:

Assigning users to national roles is mandatory

The Formula Configuration Screen allows users to configure resource estimation formulas based on assumptions and campaign strategies. Users can also choose whether the formula should be displayed on the Estimation Dashboard (Population Inbox Screen). Additionally, new formulas can be added as needed.

Key Features

1. MDMS Integration for Autofilled Configurations

   • The formulas on the Formula Configuration Screen are dynamically autofilled based on data from the MDMS.

   • These configurations are tailored using specific keys that define the campaign type, distribution strategies, and processes.

2. Add Formula

   • To create a new formula, click Add Formula.

   • Define the Formula Name, Inputs, and select the appropriate Operator.

   • After creating the formula, users can choose whether to display it on the Estimation Dashboard.
3. Delete Formula

   • To remove a formula, click Delete next to the relevant formula.

   • If the formula is used in the campaign, the system will prompt the user to either reuse the deleted formula or define a new one.

4. Show on Estimation Dashboard

   • If the user wants the formula to appear on the Estimation Dashboard, check the Show on Estimation Dashboard box.

   • Unchecking the box will keep the formula available for calculations but will exclude it from the dashboard view.

Example Formula Configurations

1. Total Number of Bednets per Boundary Formula: Total Number of Bednets = Target Population / Number of Persons per Bednet

   • Dependency: Relies on assumptions like Target Population and Number of Persons per Bednet.

   • Action: The user can choose to show this formula on the Estimation Dashboard by selecting the Show on Estimation Dashboard checkbox.

2. Total Number of Bales per Boundary Formula: Total Number of Bales = Total Number of Bednets / Number of Bednets per Bale

   • Dependency: Relies on Total Number of Bednets and Number of Bednets per Bale assumptions.

   • Action: The user can delete this formula or add it to the Estimation Dashboard as needed.

The Microplan Assumptions step is designed to streamline the process of defining critical campaign-related hypotheses based on the selected Resource Distribution Strategy and Campaign Type. This step consists of two substeps:

Step 1: Registration and Distribution Process Selection

This screen adapts based on the Resource Distribution Strategy chosen during the Campaign Details step.

1. Mixed Strategy:

For campaigns following the Mixed Strategy, the system prompts users to provide details for both the registration and distribution processes. However, the same method cannot be selected for both.

Prompts:

1. How is the campaign registration process happening?

   • Users are required to select from predefined options such as House-to-House, Fixed, etc.

2. How is the campaign distribution process happening?

   • Users must select a different option from the registration process, tailored to the distribution method (e.g., House-to-House, Fixed, etc.).

This distinction ensures that the two processes are appropriately differentiated and configured.

2. Fixed or House-to-House Strategy:

For these strategies, users are prompted to specify the relationship between registration and distribution processes:

Question:

• Is the registration and distribution process happening together or separately?

  • Options:

    • Together

    • Separately

The response determines how the system pre-configures subsequent assumptions.

Step 2: Assumptions Form

Once the registration and distribution process is selected, users proceed to the Assumptions Form, which dynamically adapts based on campaign-specific parameters.

Configurability of Assumptions Data (Categories and Assumptions)

The form fetches data from the MDMS and includes categories and assumptions customized according to:

• The Campaign Type (e.g., Bednets, SMC)

• The Resource Distribution Strategy (e.g., House-to-House, Fixed)

Example of some dynamic categories of Assumptions:

1. General Assumptions:

   • High-level parameters that apply to the overall campaign.

2. Registration Assumptions:

   • Assumptions specific to how and where registration activities occur.

3. Distribution Assumptions:

   • Parameters defining the methodology and logistics for distributing resources.

4. Commodities Assumptions:

   • Details about distributed items, such as the number of bednets per household.

Features of the Assumptions Form:

1. Input Values:

   • Users must input specific values for each assumption.

   • Validation Rules:

     • Assumption values must:

       • Be numerical and are mandatory. and fall within the range of 0 to 1000.

       • Contain at most two decimal places (e.g., 12.34 is valid, but 12.345 is not).

       • Adhere to a specific format, ensuring they match the pattern of a valid decimal or whole number (e.g., 123.45 or 678).

   • Tooltips:

     • Each category includes input parameters with tooltips that provide detailed information when users hover over the respective field.

2. Manage Assumptions:

   • Users can add new assumptions or delete existing ones based on campaign needs.

   • Initiate Adding an Assumption:

     • Users can click the "Add New Assumption" button from the assumptions management interface.

     • Assumption Details Input:

       • A popup/modal is displayed with the following fields:

         • Choose Assumption: A dropdown or selection box to choose an existing assumption or create a new one.

         • Assumption Name: An input field where users specify the name of the new assumption.

     • Confirmation Options:

       • Cancel: Discards the changes and closes the popup/modal.

       • Add: Saves the new assumption after passing validation checks.

• Deleting Assumption

  • Users can click the "Delete" button from the assumptions management interface.

  • Confirmation Options:

    • No: Discards the changes and closes the popup/modal.

    • Yes: Deletes the assumption.

  • Recovering deleted assumption:

    • Users can click the "Add New Assumption" button from the assumptions management interface and select the deleted assumption from the Choose Assumption dropdown.

Customization and Management:

Each assumption category and its parameters are dynamically tailored based on:

• The selected Campaign Type

• The chosen Resource Distribution Strategy

User Roles

• Actors: System Administrator / Program Manager

• Administrative Boundaries: National / Country level

Summary Screen Modules

The summary screen consists of the following modules:

1. Microplan Details Displays the core information about the microplan, such as the campaign name, disease, and resource distribution strategy. The user can review the details and make necessary edits.

2. Campaign Boundary Shows the geographical administrative boundaries, including the country, province, district, administrative post, locality, and village levels. Users can review and edit the boundary data for each geographical level.

3. Data Management Displays data templates for population and facilities. Users can download the templates or edit the uploaded files.

4. Microplan Assumptions Shows the assumptions used in the microplan setup. Users can review and adjust these assumptions as necessary.

5. Formula Configuration Displays the configured formulas used in the microplan. Users can modify the formulas if required.

6. Data Validation Ensures that the data entered meets all the required criteria and can be validated before proceeding with the microplan.

7. User Access Management Displays the users and their roles in the microplan setup. Users can manage who has access to the microplan.

Tab Filtering Implementation

Based on the tab, the respective section of setup microplan is shown.

Its implemented by using ViewComposer and passing in the pages as cards in a array called Cards.

Data for the Pages

The data displayed on the pages is retrieved from the sessionData, which is created whenever the user inputs data during the microplan setup process. As the user progresses through the setup, each section of the form they complete is captured and stored as formData.

Key Functionalities

Edit Data

• Description: Each section of the summary screen can be edited by clicking the Edit button. This will redirect the user to the corresponding section in the microplan setup for further configuration.

• Implementation: The system sets the key value for the selected section and redirects the user to the relevant page based on that key.

Download Files

• Description: The user can download files (e.g., population and facility data templates) by clicking the Download button where applicable.

• Implementation: This functionality is described in the Data Management page, where users can access and download the uploaded templates and files.

Finalize:

Once satisfied with the configuration, the user clicks Complete Setup to finalize the microplan.

When the Complete Setup button is clicked, the /plan-service/config/_update is triggered, with 'workflow:initiate' sent as the payload.

The Boundary Selection step is the second step in the microplan creation process. It allows users to define the geographic areas (boundaries) where the campaign will be conducted. Users must select boundaries at different hierarchical levels to ensure accurate targeting.

Header

• Title: Select the boundaries where you want to run the campaign Provides clear instructions for selecting the geographic regions for the campaign.

• Description: Boundaries are the administrative areas defined that you want to run a campaign in. Start selecting boundaries from the first level so that the boundaries present in the next level are available for selection. Explains the importance of hierarchical boundary selection.

• Localization: Both the title and description can be translated into multiple languages.

Fields

The following fields represent the hierarchical administrative levels for boundary selection. These levels are dynamic and depend on the hierarchy definition configured in the system. An example hierarchy could look like this:

1. Country

   • Description: Select the top-level boundary (e.g., Country) where the campaign will be conducted.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Selection of this level enables the next level in the hierarchy.

2. Province

   • Description: Select the second-level boundary (e.g., Province) within the chosen country.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Available only after selecting the country.

3. District

   • Description: Select the third-level boundary (e.g., District) within the chosen province.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Available only after selecting the province.

4. Administrative Post

   • Description: Select the next boundary level (e.g., Administrative Post) within the chosen district.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Available only after selecting the district.

5. Locality

   • Description: Select the locality boundary within the chosen administrative post.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Available only after selecting the administrative post.

6. Village

   • Description: Select the final-level boundary (e.g., Village) within the chosen locality.

   • Field Type: Dropdown

   • Mandatory: Yes

   • Usage: Available only after selecting the locality.

Note: The hierarchy structure (e.g., Country > Province > District > Administrative Post > Locality > Village) is just an example. Actual levels and labels will vary based on the specific administrative hierarchy configured in the system.

Key Points

• The number of levels and their labels (e.g., Country, Province, District) are not fixed and depend on the system's hierarchy definition.

• Users must proceed sequentially, selecting each level to unlock the next.

• Localization: All hierarchy level labels are fully translatable, allowing them to be displayed in different languages as required.

User Interface

• Dropdown Menu:

  • Hierarchical: The options in each dropdown depend on the selection made in the previous level.

  • Filtering: Text input is supported to filter options.

• Validation: Ensures selections are made sequentially and that no level is skipped.

• Localization: Error messages and validation prompts are fully translatable.

Validation Rules

• All fields marked with an asterisk (*) are mandatory.

• Users cannot proceed without completing the selection at each level.

• If boundaries are not selected down to the last level, or if any selected boundary does not have its child boundary selected, a proper error message is displayed.

Boundary Selection Overview Card

The Boundary Selection Overview Card displays details of the number of selected levels at each dynamically configured boundary level (e.g., Country, Province, District, etc.). It provides a quick summary of the selections made at each level, offering users an efficient way to track the progress of the boundary selection process.

API Endpoints and Example Request Payloads

It looks like the second update was missed. Here's the table with both updates correctly included:

Download Functionality:

• Each listed file has a dedicated Download button to save the respective data locally.

• Files are downloaded in .xlsx format.

Implementation of the files displayed :

The /project-factory/v1/data/_search will return all the files uploaded related to microplan.

API Details:

The API will return a ResourceDetails array containing all the filestore IDs related to the microplan. Each entry will include the fileStoreId, processedFilestoreId, and status

The results of the API are filtered based on whether item?.actions === 'create'
and item?.source === 'microplan'.

Status

The files are downloadable only if the status of the files are "completed",

if the status of the file is "invalid" in resouceDetails.status then the file is not downloadable.

Download Button:

Upon clicking the download button, the following Digit function is invoked using the file's .processedFilestoreId to enable the download functionality.

Digit.Utils.campaign.downloadExcelWithCustomName({ fileStoreId: item?.processedFilestoreId, customName: String(fileName) });

Once Downloaded:

The UserName and password are generated for each user in the downloaded sheet.

File Structure

The downloaded .xlsx files may include the following data fields:

• Name: The full name of the user.

• Contact Number: The user's phone number.

• Email: The user's email address.

• Roles: The designated role(s) for each user (e.g., Population Data Approver).

Navigation:

• Use the Back button to exit the download screen.

Path

The screen is accessed when user logins in as MICROPLAN_ADMIN, goes to Setup Microplan Card and clicks on the User Management link.

Usage and Navigation

This page allows the Microplan Admin to view all registered people for different microplan-related roles, uploaded using bulk upload. When clicking on the corresponding employee in the microplan, the details of the employee are shown.

Search Users

• Administrators can search for users by Name or Contact Number.

• Search supports partial string matching.

API Details

The /health-hrms/employees/_search API returns all roles related to the microplan. By default, it shows all roles, but when filtered, it only shows users with the selected roles.

Filter Users by Role

• Use the role checkboxes on the left-hand panel to filter users based on their assigned roles.

• By default all roles are shown in the table.

The roles are fetched from the mdms, module.master is hcm-microplanning.rolesformicroplan .

Link for hcm-microplanning.rolesformicroplan

When one or more checkboxes are selected for role-based filtering, the roles query string parameter is set to match the selected checkboxes for the /health-hrms/employees/_search API.

API Details

Navigation Links

The user can go to the Bulk User Data and Download User Data by clicking on the links.

The Bulk Upload Users is used to create multiple users of various roles to the Microplan.

The Download Users Data allows administrators to view and download various user templates and employee details, including user credentials created through bulk creation.

Employee Details

By clicking on the row of the table the employee details can be viewed.

Navigating to employee details

window.location.href=microplan-ui/employee/hrms/details/${tenantId}/${row}

Additional Details:

The data for the different roles are fetched from the MDMS using api call:

API Details

Flow of Uploading

1. Template generation

2. Editing template

3. Browsing and Uploading

4. Validating File

5. Submitting file

Template generation:

To fill up the details in excel sheet a template is downloadable. The template is created by using the api call to /project-factory/v1/data/_generate

The user fills up the template and making sure to fill it in a valid manner.

Validations in excel template:

• Fill in user details (Name, contact number, and email) in each sheet according to the role.

• Do not assign the same user to both the Microplan Estimation Approver and National Microplan Estimation Approver roles.

• Do not assign the same user to both the Facility Boundary Assigner and National Facility Boundary Assigner roles.

• Do not assign the same user to both the Population Data Approver and National Population Data Approver roles.

Browsing and Uploading file

When the user clicks on Browse in My Files, they can select a file of type .xlsx, .xls and only the downloaded template can be uploaded. Once the file is selected, the validation of the Excel file begins. This validation is performed using the following hook:

The file is then set in the state and validated through the below hook.

Digit.Hooks.campaign.useResourceData( uploadedFile, state?.hierarchyType, type, tenantId, id, baseTimeOut?.["HCM-ADMIN-CONSOLE"], { source: "microplan" } );

Once the status from the validation is "Completed", the processedFileStoreis extracted from the response and sent to the following hook.

Digit.UploadServices.Filefetch([processedFileStore], tenantId)

This hook returns fileUrl, which contains the URL attribute. For example, the URL might look like:

https://unified-qa-filestore.s3-ap-south-1.amazonaws.com/mz/HCM-ADMIN-CONSOLE-CLIENT/December/4/1733307220857RYETclexTL.xlsx?...

This is a pre-signed URL generated by Amazon S3 (Simple Storage Service), which provides temporary access to a specific file stored in an S3 bucket.

When the fileUrl is set, the file can be downloaded by clicking a button that uses the following hook:

Digit.Utils.campaign.downloadExcelWithCustomName({ fileStoreId: file?.filestoreId, customName: fileNameWithoutExtension }); 

When the files are selected, the following api calls are being made.

Actions is set to validate when the file is first selected its sent for payload for /project-factory/v1/data/_create

Validation of xlsx files

This hook does the validation of the xlsx file uploaded.

Digit.Hooks.campaign.useResourceData( uploadedFile, state?.hierarchyType, type, tenantId, id, baseTimeOut?.["HCM-ADMIN-CONSOLE"], { source: "microplan" } );

The error description is shown in error details.

On Submit:

The action is set to create for the payload for /project-factory/v1/data/_create

The page goes

Delete File:

When the delete button is clicked, the uploaded file is deleted.

1.Overview

When the user clicks on a facility, this popup window opens displaying essential details about the selected facility, as well as options for managing unassigned and assigned villages for this facility.

2.Interface Elements

Facility Details Card

Upon selecting a facility, a Facility Details popup will display the following:

• Facility Name: Name of the selected facility.

• Facility Type: Type of facility, such as "Warehouse" or "Health Post."

• Facility Status: Indicates whether the facility is temporary or permanent.

• Capacity: Displays the capacity of the facility (e.g., the number of bales for bednet distribution or blisters for SMC campaigns).

• Serving Population: The serving population currently being served by the facility.

• Fixed Post: Indicates if the facility is a fixed post, which is typically a permanent, stationary facility.

• Residing Village: The village where the facility is located or based.

Filter Options:

• Select Administrative Hierarchy: Dropdown menu for selecting an administrative level (e.g., Country, Province, District).

• Select Administrative Area: Dropdown menu for selecting a specific area within the hierarchy (e.g., Locality, Village).

• Search: Search for villages by name or code.

• Clear: Clears all selected filters and resets the search options.

3.Unassigned Villages and Assigned Villages

3.1.Unassigned Villages

This section allows the user to manage villages that have not yet been assigned to any facility. Users can select villages from this list and assign them to a facility.

3.2.Assigned Villages

This section displays the villages that have already been assigned to a facility. Users can manage these assignments, including unassigning a village if necessary.

Actions:

• Assign: To assign a facility to a village, select the village from the unassigned list and click the "Assign" button.

• Unassign: If a village is already assigned to a facility, users can unassign it by selecting the village and clicking the "UnAssign" button.

4.Notes:

• Unassign: Clicking on unassign button will show a alert message that you want to unassign this village from the current selected facility.

• Close: Clicking "Close" will exit the page without making any changes.

5.EndPoints:

1. Overview

The Microplan Estimation Approver screen is designed for supervisors to validate and approve microplan estimations within their assigned administrative boundaries. This screen allows approvers to validate, correct, and approve data, ensuring the integrity of the data used for resource planning.

2. User Roles

3.Interface Elements

Header Section

• Microplan Name: Displays the name of the current microplan being reviewed.

• Logged-in User: Indicates the user role and account.

Plan Estimation Data Summary (KPIs)

• All values are dynamically updated based on the real-time plan data.

• These values are sourced directly from microplan-specific KPIs, which reflect any actions taken by data approvers.

• As plan estimation data is reviewed, corrected, or approved, the values will change accordingly.

Filters and Search

• Administrative Hierarchy and Area Selection: Dropdown menus for selecting specific administrative areas (e.g., district and village).

• Search and Filter Options:

  • Workflow Status Filters:

    • Pending for validation

    • Validated

  • Assigned to Filters:

    • Assigned to me

    • Assigned to all

  • Buttons: Apply Filter, Clear

Plan Estimation Data Table

The table on the Microplan Estimation Validation Page displays key data for each village involved in the campaign, including the village name, status logs, assignee details, and facility name. It also includes important information such as road conditions, terrain, and security factors, which help assess the village’s readiness for plan activities. Additionally, the table presents validated population data, the number of households(based on selected campaign), and other critical metrics related to the plan data, ensuring that approvers have a comprehensive view of the plan estimation details before approval.

Action Buttons

• View Logs: Displays historical changes and logs related to a specific plan estimation's data.

4. Workflow for Plan Estimation Data Validation

4.1. Role-Based Permissions and Actions

Plan Estimation Approver

The Estimation Data Approver is responsible for validating plan data. Their responsibilities include:

Validating Data:

• Cross-check the uploaded data with the confirmed population to ensure accuracy.

Identifying Discrepancies:

• If discrepancies are found, the PEA can flag the data for revision.

Approval Workflow:

• The PDA at the appropriate level will see the application as pending for approval. In such cases, the PDA can validate and approve the data.

When No Data Is Assigned:

• If no data is assigned to the PEA or all data assigned to him is validated, a "Back" button is shown, allowing them to return to the previous screen.

Root Plan Estimation Approver (RPEA)

The Root plan Estimation Approver has all the functionalities of a Plan Estimation Approver and additional capabilities, such as finalizing the microplan. Their responsibilities include:

Approving or Sending Data for Correction:

• Once the plan data is validated, the RPEA can either approve it or send it back for correction if further issues are identified.

Approval Workflow:

• If someone from the below hierarchy modifies and sends the data for approval, the RPEA can approve it. For example, if a province-level user sends the data back to a district-level user, who updates and sends it back for approval, the province-level RPEA will receive the application for approval.

Finalizing Actions:

• If all the villages within the selected microplan have been validated and no further changes are required, the RPDA will see a "Finalize Actions" button at the footer of the page.

• After finalizing the plan data a success screen will be shown, indicating that microplan is finalized.

• The "Finalize Actions" button will lock the data and prevent further modifications once clicked, marking the end of the validation process for the selected microplan or district.

5.Additional Notes

• Once the plan estimation data reaches the national-level data approver and the validation is finalized, the system will disable all action buttons. The status will be set to "ESTIMATION_APPROVED" and no further changes can be made. At this point, you can download microplan estimation.

• Estimation supervisors will only see the boundaries in their inbox that fall under their jurisdiction.

6.End Points:

1.Overview

The Facility Catchment Assigner role is responsible for mapping campaign facilities/points of service (POS) to their respective catchment villages. This mapping ensures that estimation of resources for campaign can be done accurately based on the facilities/POS and the villages assigned to them.

2.User Roles

3.Key Responsibilities of the Facility Catchment Assigner

1. Assign Facilities to Villages:

   • Map facilities/POS to the villages within their assigned administrative boundaries.

2. Monitor Facility and Village Mappings:

   • Ensure that all villages and facilities are appropriately mapped for the campaign.

4.Interface Elements

Header Section

• Microplan Name:

  • Displays the name of the current microplan being worked on.

• Logged-in User:

  • Displays the role and account of the logged-in user (Facility Catchment Assigner).

Facility Assign Summary (KPIs)

The dashboard provides a summary of the facilities and villages that are part of the user's administrative boundaries.

Cards

1. Villages with Mapped Facilities/POS:

   • Displays the count of villages assigned to mapped facilities/POS within the administrative boundary.

2. Facilities with Mapped Villages:

   • Displays the count of facilities that have assigned villages in the administrative boundary.

Master Details For Search Filter Dropdowns

The following master details are part of the Facility Catchement Mapping:

• Facility Type: The type of facility (e.g., Warehouse, Health Post).

• Facility Status: Status of the facility (e.g., Permanent, Temporary).

• Residing Village: The villages where the facilities are located.

Search and Filter Options

1. Facility Search:

   • Allows the user to search for specific facilities based on partial string matches.

2. Filters:

   • Facility Type: Filters by the type of facility (e.g., Warehouse, Health Post).

   • Facility Status: Filters by the facility's status (e.g., Permanent, Temporary).

   • Is Fixed Post?: Filters by whether the facility is a fixed post or not.

   • Residing Village: Filters by the villages where the facilities are located.

Facility Details

The following details are available for each facility in the dashboard:

Assigning and Unassigning Villages to a Facility:

When the user clicks on a facility or assign button in facility row, a popup window opens displaying essential details about the selected facility, as well as options for managing unassigned and assigned villages for this facility.

5.Finalizing the Facility to Village Mapping

Once all villages are assigned to their respective facilities and the mappings are complete, the national level facility catchment assigner can finalize the assignment.

Finalization Process

1. Finalize Mapping:

   • A “Finalize facility to village assignment” button will be available to finalize the facility-to-village mapping.

   • After finalizing the facility catchment mapping a success screen will be shown, indicating that facility assignment is done.

   • Once finalized, no further changes can be made, and the microplan estimation for the campaign will be triggered.

2. Finalized Mapping View:

   • After finalization, the mapping cannot be modified, and the dashboard will display the finalized assignments for reference.

6.End Points

1. Overview

The Population Data Validation and Approval screen is designed for population data approvers to ensure the accuracy and consistency of population data submitted for villages. This screen allows approvers to validate, correct, and approve data, ensuring the integrity of the data used for resource planning.

2. User Roles

3.Interface Elements

Header Section

• Microplan Name: Displays the name of the current microplan being reviewed.

• Logged-in User: Indicates the user role and account.

Population Data Summary (KPIs)

• All values are dynamically updated based on the real-time census data.

• These values are sourced directly from microplan-specific KPIs, which reflect any actions taken by data approvers.

• As census data is reviewed, corrected, or approved, the values will change accordingly.

Filters and Search

• Administrative Hierarchy and Area Selection: Dropdown menus for selecting specific administrative areas (e.g., district and village).

• Search and Filter Options:

  • Workflow Status Filters:

    • Pending for validation

    • Pending for approval

    • Validated

  • Assigned to Filters:

    • Assigned to me

    • Assigned to all

  • Buttons: Apply Filter, Clear

Population Data Table

Action Buttons

• View Logs: Displays historical changes and logs related to a specific village's data

4. Workflow for Population Data Validation

4.1. Role-Based Permissions and Actions

Population Data Approver (PDA)

The Population Data Approver is responsible for validating population and editing data. Their responsibilities include:

Validating Data:

• Cross-check the uploaded data with the confirmed population to ensure accuracy.

Editing Data:

• Modify the village population data if discrepancies are found, with a reason logged for each change and the data is sent back for approval.

When No Data Is Assigned:

• If no data is assigned to the PDA, a "Back" button is shown, allowing them to return to the previous screen.

Root Population Data Approver (RPDA)

The Root Population Data Approver has all the functionalities of a PDA and additional capabilities, to finalize population data. Their responsibilities include:

Editing Data:

• Modify the village population data if discrepancies are found, with a reason logged for each change.

Approving or Sending Data for Correction:

• Once the population data is validated, the RPDA can either approve it or send it back for correction if further issues are identified.

Approval Workflow:

• If someone from the below hierarchy modifies and sends the data for approval, the RPDA can approve it. For example, if a province-level user sends the data back for approval, the RPDA will receive the application for approval and validation.

Finalizing Actions:

• If all the villages within the selected microplan have been validated and no further changes are required, the RPDA will see a "Finalize Actions" button at the footer of the page.

• The "Finalize Actions" button will lock the data and prevent further modifications once clicked, marking the end of the validation process for the selected microplan population data.

• After finalizing the population data a success screen will be shown, indicating that population data is finalized.

Additional Notes

• Once the population data reaches the national-level data approver and the validation is finalized, the system will disable all action buttons. The status will be set to "CENSUS_APPROVED" and no further changes can be made. At this point, users can only view the details of the data but will not be able to perform any additional actions, such as editing or approving the data.

• Population supervisors will only see the boundaries in their inbox that fall under their jurisdiction.

End Points

Overview

The document provides an interactive interface for supervisors to manage and track microplans. It displays role-based activity cards that guide users through tasks such as validating population data, assigning facilities, and approving microplan estimations. The available activities are dynamically presented based on the user’s role (Root or Normal) and the current workflow status of the microplan, ensuring that supervisors only see the actions relevant to their responsibilities at each stage of the microplan.

Interface Elements

Microplan Name Display:

A prominently displayed label at the top of the interface that shows the name of the selected microplan.

Activity Options:

Displays a list of activities as clickable items. Selecting an activity navigates the user to the corresponding detailed workflow.

Available Activities

1. Validate & Approve Population Data

• Purpose: Ensures the population data associated with the microplan is accurate and approved for further processing.

• Steps:

  1. Review uploaded population data for completeness and correctness.

  2. Approve or flag data for revision as needed.

• Roles Involved:

  • ROOT_POPULATION_DATA_APPROVER: Can review, approve, or send back population data, as well as finalised population data.

  • POPULATION_DATA_APPROVER: Can review, approve, or send back population data.

• Role-Based Access:

  • This card is visible based on the user role and the wfStatus that aligns with the data validation stage.

2. Assign Facilities to Villages

• Purpose: Assign healthcare or distribution facilities to specific villages or areas within the campaign's scope.

• Steps:

  1. Map villages to designated facilities.

  2. Confirm assignments to ensure logistical accuracy.

• Roles Involved:

  • ROOT_FACILITY_CATCHMENT_MAPPER: Assign and unassign facilities to villages, and finalise facility assignments.

  • FACILITY_CATCHMENT_MAPPER: Assign and unassign facility to villages.

• Role-Based Access:

  • This card appears only when the wfStatus indicates that facility assignment is the next step.

3. Validate & Approve Microplan Estimations

• Purpose: Review and finalise the estimated resources, population coverage, and other metrics calculated for the microplan.

• Steps:

  1. Check estimations for accuracy and alignment with campaign objectives.

  2. Approve or request adjustments as necessary.

• Roles Involved:

  • ROOT_PLAN_ESTIMATION_APPROVER: Can approve or request adjustments for microplan estimations, also finalized microplan estimation.

  • PLAN_ESTIMATION_APPROVER: Can approve or request adjustments for microplan estimations.

• Role-Based Access:

  • The card is displayed based on wfStatus of the plan configuration, indicating readiness for estimation validation.

User Actions Flow

1. Select an Activity: Choose one of the available activities depending on the current stage of the microplan.

2. Proceed to the Next Screen: Click the activity to access its detailed workflow interface.

Notes

• Role-based Permissions: Certain activities might be restricted based on user roles and permissions.

• Sequential Workflow: Activities must be completed in sequence for effective campaign execution:

  1. Validate Population Data

  2. Assign Facilities

  3. Approve Microplan Estimations

• Progress Tracking: Ensure tasks are not repeated and assignments remain aligned with campaign objectives.

API Endpoints

The system administrator can see the list of microplans on this page and perform certain actions on each microplan, if required.

Path

The screen is accessed when the user logins in as MICROPLAN_ADMIN, goes to the Microplan Setup card, and clicks on the open microplans link.

Overview

The Open Microplans screen allows the microplan admin to see all the plans that they create. Microplans are categorised by their status, such as Drafted Setup, Completed Setup, Validation in Progress, and Finalised Microplan. A mMicroplan admin can search for microplans by name and perform actions based on the microplan’s current status.

The list of statuses displayed on the Open Microplans screen includes:

• All: Default view showing all microplans created by the user.

• Drafted Setup: Microplans that have still not been completed in setup microplans.

• Completed Setup: Shows microplans for which setup is completed.

• Validation in Progress: Displays microplans that are being validated by Population approvers, facility data approvers, and estimation approvers.

• Finalized Microplan: This shows the microplans that have been fully validated and finalized.

User Actions

In the Open Microplans screen, users can:

• Search Microplan: Search for microplans using the microplan name. Fuzzy search is also available.

• Filter Microplans by Status: Use tabs to filter microplans based on their status.

• Perform Status-Specific Actions: Depending on the microplan's status, users can view, edit, or download finalised microplan estimations.

File Path

Frontend File Path:

Business Logic

How Search API works

Each of the tabs is associated with a tabId and each tabId is linked with a status, and after extracting the string query params in the URL, the payload for PlanConfigurationSearchCriteria.status is filled based on tabId.

Sample Payload:

The flow of API calls

1) /plan-service/config/_search:

This endpoint takes userUUID as the planConfigSearchCriteria and returns all the different plan objects related to the microplans created by the logged-in system admin.

2)/project-factory/v1/project-type/search

Will take the campaignId from the plan Object and the tenantId, and will give back the campaign Object(campaign name, campaign disease, campaign type, etc).

API Details

Status-Specific Actions

Based on the status of microplan different actions are available.

Each of the different tabs represents the different stages of the microplan.

Logic Explanation

1. The Edit (Drafted Microplans)

   • When the microplan status is ["DRAFT"], edit is available. Clicking on it redirects to the last edited page of the setup microplan.

2. View Summary (Setup Completed):

   • When the microplan status is ["EXECUTION_TO_BE_DONE"] or ["CENSUS_DATA_APPROVAL_IN_PROGRESS", "CENSUS_DATA_APPROVED", "RESOURCE_ESTIMATION_IN_PROGRESS"], view summary is available. Clicking on it redirects to the summary page of the setup microplan.

3. Download Microplan(Microplan Finalized):

• When the status of the microplan is ["RESOURCE_ESTIMATIONS_APPROVED"], then clicking on the download will download the microplan sheet using the hook

The field, and campaign name are extracted from the plan object and the name of the generated file is the customName.

1.Overview

When a user clicks on a village name in the Population Data Table, they are directed to the Village Details Page, which provides detailed information about the selected village.

2.Header Information

• Microplan Name: Displays the name of the microplan associated with the village.

• Displays the Hierarchy of the village.

3.Security & Accessibility

• Village Security: Provides an input field for entering security details about the village.

• Master Details :

  • Security Questions

    1. Is your village prone to civil unrest like violent protests, riots, etc.? Captures the frequency of civil unrest occurrences using the following options:

       • All the time (At least once a month): Frequent civil unrest.

       • Often (At least once a year): Civil unrest occurs occasionally but is a notable concern.

       • Rarely (Once in 2–3 years): Rare civil unrest.

       • Never: No recorded instances of civil unrest.

    2. How often do the security forces patrol the village? Measures the frequency of security patrols to ensure safety, with the following options:

       • Every day: Daily security patrols.

       • Often (At least once a week): Regular but less frequent patrols.

       • Rarely (Once in a month): Infrequent security patrols.

       • Never: No security patrols.

• Village Accessibility: Allows entering accessibility details for the village.

• Master Details :

  • Village Road Condition: Captures the type of road infrastructure present in the village. The options include:

    • Concrete: Indicates the presence of a well-paved concrete road.

    • Gravel: Represents roads made of gravel.

    • Dirt: Denotes unpaved roads made of dirt or soil.

    • No Road: Indicates the absence of any road infrastructure.

  • Village Terrain: Specifies the geographical terrain of the village. The available options are:

    • Mountain: Villages located in mountainous areas.

    • Forest: Villages surrounded by dense forest areas.

    • Plain: Villages situated in flat, open landscapes.

    • Desert: Villages located in arid, desert regions.

4.Population Data

The data displayed here can be reviewed, modified, and validated by the appropriate users, depending on their role.

Data Table:

Note : The data inside table will change based on selected campaign.

Steps

Note : the data inside table will change based on selected campaign.

Actions:

• Edit Population Data: If needed, the confirmed population data can be modified.

• Cancel: Discards any changes made to the population data.

• Submit and Validate:

  • If the Root Population Data Approver (RPDA) is logged in, they can directly validate the data.

  • If the Population Data Approver (PDA) is logged in, the data will move to the "Pending for Approval" status and will need further validation by higher-level approvers.

5.Comment Logs

• View Comment Logs: This feature displays the history of changes and comments made about the village's population data, enabling transparency and tracking.