Technical Documentation: Update Campaign Flow

Overview

This document outlines the flow for updating an existing 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. The update flow ensures that the required resources are validated and updated correctly before finalizing the campaign update.

Actors and Participants

• Client: The entity (user or system) initiating the campaign update request.

• CampaignManager (Project Factory): The main controller managing the campaign update process.

• ProjectService: Manages project-related operations, including data creation and mapping updates.

• BoundaryService: Handles fetching of boundary relationships based on hierarchy types.

• FacilityService: Responsible for creating and updating facility-related data.

• HRMSService: Manages the creation and updating of employee data.

• MDMSService: Provides master data such as project types.

• FileStoreService: Manages the storage and retrieval of resource files.

• Database: Stores campaign-related data and status updates.

Sequence Flow

1. Initiate Campaign Update

   • The Client sends an update request to the CampaignManager with all required and valid resources.

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

3. Fetch Project Type Master

   • The CampaignManager requests the MDMSService to fetch the project type master data.

   • The MDMSService responds with the project type master.

4. Validate Resource Files

   • The CampaignManager queries the Database to check if the input resource files have already been validated.

   • The Database responds with the validation status of the files.

5. Fetch Parent Campaign Object

   • The CampaignManager queries the Database to fetch the parent campaign object based on the parentCampaignId.

   • The Database responds with the parent campaign object.

6. 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 update process has started, and the user needs to track the status using an ID.

     • If validation fails, the CampaignManager returns an error message, indicating which validation failed, and the user must resubmit the request.

7. Deactivate Parent Campaign

   • The CampaignManager updates the Database to mark the parent campaign object as inactive.

8. Retrieve Resource Files

   • The CampaignManager interacts with the FileStoreService to search for the resource based on the filestoreid.

   • The FileStoreService responds with the valid resource files.

9. Process Resource Data

   • The CampaignManager processes the retrieved sheets to identify any resource data that needs to be created.

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

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

12. Search for Parent Project

    • The CampaignManager sends a request to the ProjectService to search for the previous or parent project.

    • The ProjectService responds with the project object.

13. Create New Projects for Added Boundaries

    • The CampaignManager copies the project content from the parent project while creating new projects for newly added boundaries.

    • The CampaignManager sends a request to the ProjectService to create project data for newly added boundary data and map it according to its parent.

    • The ProjectService responds that the projects have been created successfully.

14. Update Facility Data

    • The CampaignManager identifies what exact data needs to be updated for facilities.

    • The CampaignManager sends a request to the ProjectService to create project-facility mapping if any new facilities are added.

    • The ProjectService responds that the project-facility mapping has been created successfully.

    • The CampaignManager sends a request to the ProjectService to search for the previous project-facility mapping.

    • The ProjectService responds with the project-facility mapping data.

    • The CampaignManager sends a request to the ProjectService to update the project-facility mapping.

    • The ProjectService responds that the project-facility mapping has been updated successfully.

15. Update Staff Data

    • The CampaignManager identifies what exact data needs to be updated for staff.

    • The CampaignManager sends a request to the ProjectService to create project-staff mapping if any new staff are added.

    • The ProjectService responds that the project-staff mapping has been created successfully.

    • The CampaignManager sends a request to the ProjectService to search for the previous project-staff mapping.

    • The ProjectService responds with the project-staff mapping data.

    • The CampaignManager sends a request to the ProjectService to update the project-staff mapping.

    • The ProjectService responds that the project-staff mapping has been updated successfully.

16. Update Campaign Status

    • The CampaignManager updates the Database with the campaign update status.

Error Handling

• Validation Failure: If any validation step fails (e.g., invalid data in resource files or missing required resources), the CampaignManager sends an error message to the Client, indicating the failure. The user is required to fix the issues and resubmit the request.

• Service Errors: If any of the service interactions (e.g., BoundaryService, MDMSService, ProjectService) return an error, the CampaignManager stops the process and informs the Client of the failure, specifying the nature of the error.

• Database Errors: If the Database fails to update the campaign update status or mark the parent campaign as inactive, appropriate error handling and logging mechanisms should be triggered to handle the failure.

API Sequence Diagram

Conclusion

This document provides a comprehensive overview of the update campaign flow, detailing each step and interaction between different services and the database. The flow ensures proper validation and updating of necessary resources, while error handling mechanisms provide robustness to the process.

Click here to know more.

Technical Documentation: Create Campaign Flow

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.

Actors and Participants

• Client: The entity (user or system) initiating the campaign creation request.

• CampaignManager (Project Factory): The main controller managing the campaign creation process.

• ProjectService: Manages project-related operations, including data creation and mapping.

• BoundaryService: Handles fetching of boundary relationships based on hierarchy types.

• FacilityService: Responsible for creating facility-related data.

• HRMSService: Manages the creation of employee data.

• MDMSService: Provides master data such as project types.

• FileStoreService: Manages the storage and retrieval of resource files.

• Database: Stores campaign-related data and status updates.

Sequence Flow

1. Initiate Campaign Creation

   • The Client sends a request to the CampaignManager to create a campaign with all required and valid resources.

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

3. Fetch Project Type Master

   • The CampaignManager requests the MDMSService to fetch the project type master data.

   • The MDMSService responds with the project type master.

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

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

     • If validation fails, the CampaignManager returns an error message, indicating which validation failed, and the user must resubmit the request.

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

7. Process Resource Data

   • The CampaignManager processes the retrieved sheets and identifies any resource data that needs to be created.

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

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

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

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

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

13. Update Campaign Creation Status

    • The CampaignManager updates the Database with the status of the campaign creation process.

Error Handling

• Validation Failure: If any validation step fails (e.g., invalid data in resource files), the CampaignManager sends an error message to the Client, indicating the failure. The user is required to fix the issues and resubmit the request.

• Service Errors: If any of the service interactions (e.g., BoundaryService, MDMSService) return an error, the CampaignManager stops the process and informs the Client of the failure, specifying the nature of the error.

• Database Errors: If the Database fails to update the campaign creation status, appropriate error handling and logging mechanisms should be triggered to handle the failure.

API Sequence Diagram

Conclusion

This document provides an overview of the create campaign flow, detailing each step and interaction between different services and the database. The flow ensures proper validation and creation of necessary resources, while error handling mechanisms provide robustness to the process.

Technical Design Document: Manage Resources API Flows

Overview

This document outlines the various API flows and interactions for the Project Factory, focusing on resource data creation with retry logic, template generation, campaign update flows, and data search and download processes. The aim is to manage and automate various aspects of resource and campaign data efficiently using the Project Factory services.

Project Factory Resources Data Create with Retry Logic

Description: This flow describes how the Project Factory handles resource data creation with retry logic. It ensures data consistency and reliability by retrying operations if failures occur.

Sequence of Operations:

1. Client Request Initiation:

   • The client sends a request to the Project Factory with filestoreid and type.

2. MDMS Service Interaction:

   • Project Factory retrieves the type schema from the MDMS Service.

   • MDMS Service returns the schema, which is then validated.

3. Data Validation:

   • The Project Factory validates the data against the MDMS schema.

   • If validation is successful, it informs the client that data processing has started.

   • If validation fails, an error message is returned, and the user must resubmit.

4. File Handling:

   • The Project Factory requests a file download from the FileStore Service.

   • Upon receiving the file, JSON data is created from the file of the desired type.

5. Data Creation and Retry Logic:

   • Data is validated according to the schema.

   • Normal Create:

     • Data is created in the respective service, and status is tracked.

     • A loop continues until retry attempts exceed the maximum retries, or no failed data remains.

   • Bulk Create with Retry:

     • Data is created in the respective service, and the status is checked.

     • A search is conducted using the generateApi search.

     • The loop continues under the same conditions as the normal create process.

6. Database Update:

   • The file is enriched with the created ID and sent back to the FileStore Service.

   • The updated file is received, and data is persisted in the database with a status of 'created' and the processed filestoreid.

Template Generate API Flow (forceUpdate = true)

Description: This flow is triggered when a client sends a generate request with forceUpdate = true. It checks for existing data and creates a new row with the status inProgress if necessary.

Sequence of Operations:

1. Client Request Initiation:

   • The client sends a generate request with the specified type and forceUpdate = true.

2. Validation and Data Check:

   • The Project Factory validates the type against predefined types and hierarchytype.

   • A check is performed to see if previous data exists. If it does, the data is marked as expired.

3. Database and Response:

   • A new row is created with null fileStoreId and status inProgress.

   • The database is updated, and a success response is sent back to the client.

4. Data Fetch and Storage:

   • The Project Factory fetches the template from the MDMS Service based on the type.

   • Data is consolidated and stored in the FileStore Service, which returns a filestoreid.

   • The database is updated with the new filestoreid.

Template Generate API During Update Campaign Flow (forceUpdate = true)

Description: This flow is initiated when a generate request is sent due to a boundary change in an ongoing campaign.

Sequence of Operations:

1. Boundary Change Trigger:

   • The Project Factory sends a generate request with campaignId, type, and forceUpdate = true.

2. Validation and Data Check:

   • The type is validated against predefined types and hierarchytype.

   • Previous data is checked, and if found, marked as expired.

   • The campaign is searched in the database based on the provided campaignId and its parent campaign ID.

3. Database and Response:

   • A new row is created with null fileStoreId and status inProgress.

   • The database is updated, and a response is provided.

4. File Update and Data Consolidation:

   • The Project Factory fetches file details from the FileStore Service using the parent campaign object.

   • The sheet is updated, freezing all the data.

   • If new boundaries are added, boundary relation data is fetched.

   • Data is consolidated, and stored in the FileStore, and the database is updated with the new filestoreid.

Project Factory Resources Data Search and Download

Description: This flow allows the client to search and download resource data based on a provided ID and type.

Sequence of Operations:

1. Client Request Initiation:

   • The client sends a request with the id and type.

2. Database Query:

   • The Project Factory checks the created resource based on the provided ID.

   • The corresponding resource details row is fetched from the database.

3. Response to Client:

   • The Project Factory sends back the created resource response to the client.

API Sequence Diagrams

During Create flow

During Update Flow

Conclusion

The outlined API flows are crucial for handling resource data creation, management, and retrieval efficiently. They ensure data consistency, integrity, and seamless interaction between various services, making the Project Factory a robust system for managing campaign data. Implementing the retry logic, data validation, and template generation processes helps maintain a reliable and scalable architecture.

Technical Documentation: Create Campaign Web Flow

Overview

This document details the web flow for creating a new campaign using the Admin Console. The process involves interactions between various services, including the Project Factory, Boundary Service, MDMS Service, FileStore Service, and the Admin Console. This flow ensures that all necessary data is collected, validated, and processed to create a campaign successfully.

Actors and Participants

• User: The person interacting with the Admin Console to set up and create a campaign.

• CampaignManager (Admin Console): The main interface that the user interacts with to manage campaign creation.

• ProjectFactory: Handles the creation and management of campaign objects and validation processes.

• BoundaryService: Provides information about boundary hierarchy and relationships.

• MDMSService: Supplies master data such as project types, hierarchy configurations, and operator details.

• FileStoreService: Manages the storage and retrieval of files related to the campaign.

Sequence Flow

1. Campaign Setup Initialization

• User: Initiates the process by visiting the Admin Console to set up a new campaign.

• CampaignManager: Receives the request to set up a campaign and starts interacting with various services to gather necessary information.

2. Fetch Master Data

• CampaignManager sends a request to MDMSService to fetch required master data, including:

  • Project types

  • Hierarchy type configuration

  • Operator templates

  • Other necessary templates

• MDMSService responds with the requested master data, which is used to configure the campaign.

3. Fetch Boundary Information

• CampaignManager requests BoundaryService to fetch boundary hierarchy definitions based on the selected hierarchy type.

  • BoundaryService responds with the boundary hierarchy definition.

• CampaignManager requests BoundaryService to fetch boundary relationship data based on the selected hierarchy type.

  • BoundaryService responds with the boundary relationship data.

4. User Data Input

• User: Fills in the required data such as boundary delivery configuration and other campaign-specific details within the Admin Console.

• CampaignManager: Sends the user-filled information to ProjectFactory to create a campaign object and stores it with an initial action status of "draft".

5. Template Generation

• ProjectFactory: Automatically triggers the generation of templates for different resources, including:

  • Target templates

  • Facility templates

  • User templates

6. Template Download and Storage

• User: Downloads the generated templates for each resource type through the Admin Console.

• CampaignManager: Sends a request to FileStoreService to store the downloaded files.

  • FileStoreService responds with a filestoreid that uniquely identifies the stored file.

7. Data Validation

• CampaignManager: Sends the data and the filestoreid to ProjectFactory for validation.

  • ProjectFactory responds with a unique validation ID as the validation process may take some time.

• CampaignManager: Periodically checks the status of the validation using the unique validation ID.

8. Validation Outcome

• ProjectFactory:

  • If validation is successful:

    • Responds with a success message.

    • CampaignManager: Displays a success message to the user, indicating that they can proceed to the next step.

  • If validation fails:

    • Responds with an error message detailing the validation failure.

    • CampaignManager: Displays the error message to the user, prompting them to correct the errors and re-upload the files.

9. Final Campaign Creation

• User: Once all required data is filled in and validated, the user reviews the summary of the campaign data and clicks on the "Create Campaign" button.

• CampaignManager: Sends a final request to ProjectFactory with the campaign creation API, marking the action as "create".

10. Campaign Creation Outcome

• ProjectFactory:

  • If the creation is successful:

    • Responds with a success message indicating that the campaign creation has started.

    • CampaignManager: Displays a success message to the user, confirming the campaign creation.

  • If the creation fails:

    • Responds with an error message detailing the failure.

    • CampaignManager: Displays the error message to the user, prompting them to correct any issues and try again.

Error Handling

• Validation Failures: If validation fails at any stage (e.g., during file validation or input data checks), the CampaignManager will notify the user of the specific issues. The user must resolve these issues and re-upload the necessary data to proceed.

• Service Errors: If any of the services (e.g., BoundaryService, MDMSService, ProjectFactory) encounter an error during processing, the CampaignManager will display an error message, detailing the problem and suggesting corrective actions.

Web Sequence Diagram

Conclusion

This document outlines the end-to-end flow for creating a new campaign using the Admin Console. It ensures that the user provides all required information, and that data is validated and processed correctly to create the campaign. This structured approach minimizes errors and ensures that all campaigns are set up with the required accuracy and completeness.

Campaign Creation and Retry Mechanism Documentation

Overview

This documentation outlines the Campaign Creation process, including the sequence of steps, status tracking, and a retry mechanism that allows the process to resume from the point of failure without restarting the entire workflow. The process is divided into multiple stages, with a system to handle failures and retries. Each step in the process involves a request and campaign object, which are passed to the main function for processing.

Key Components

1. Hard Configuration (Process Flow Configuration)

2. Campaign Creation and Retry Mechanism Design

3. Full Mechanism Workflow

4. Main Campaign Creation Function

5. Retry Logic identifiers

1. Hard Configuration (Process Flow Configuration)

The Process Flow Configuration defines the sequence of processes that occur during the campaign creation. This configuration serves as the blueprint for the campaign workflow, ensuring that each process is executed in the correct order.

Process Flow Configuration (JSON format):

{

"Project Creation": "Facility Creation",

"Facility Creation": "User Creation",

"User Creation": "Facility Mapping",

"Facility Mapping": "User Mapping",

"User Mapping": "Product Mapping",

"Product Mapping": "End"

}

Description of the Flow:

• Project Creation: Initialization of the campaign project.

• Facility Creation: Generation of facilities linked to the project.

• User Creation: Creation of users after facility setup.

• Facility Mapping: Mapping of facilities to the respective projects.

• User Mapping: Linking users to the respective projects.

• Product Mapping: Mapping products to the respective projects.

• End: Final step marking the completion of the campaign creation.

2. Campaign Creation and Retry Mechanism Design

2.1 Status Tracking Table

The Status Tracking Table monitors the progress of each process step for a specific campaign, capturing whether a process has started, completed, or failed. This table helps retry the failed steps.

Structure:

Columns:

• id : primary key

• CampaignId: Unique identifier for the campaign.

• ProcessName: The name of the current process being tracked.

• Status: The current status of the process (Started, Completed, Failed).

3. Full Mechanism Workflow

3.1 Starting Campaign Creation

• CampaignId Creation: A new CampaignId is generated for the campaign. The system checks the Status Tracking Table to ensure no existing entry for the campaign.

• Process Initialization: If the campaign does not exist, the first process step (Project Creation) begins.

3.2 Process Execution

The campaign creation proceeds through the following steps:

• Project Creation

• Facility Creation

• User Creation

• Facility Mapping

• User Mapping

• Product Mapping

• End: Marks the final step, indicating the campaign has been fully processed.

After each step, the Status Tracking Table is updated to reflect the process status and associated information .

3.3 Handling Failures

1. Failure Detection

• If a process fails during campaign creation, the Status Tracking Table is updated to reflect the Failed status for the affected process.

2. State Persistence

• At the time of failure, the current state of the CampaignObject is serialized and persisted into the campaign details table. This ensures that the system retains the latest state of the campaign, which can be used to resume the process during a retry.

3. Retry Trigger

• When the client triggers a retry, the following steps occur:

• 1. The system queries the Status Tracking Table to identify the failed process.

  2. The previously persisted CampaignObject state is retrieved.

  3. The system resumes the campaign creation process starting from the failed step, using the stored state to ensure consistency.

Retry Logic:

• The campaignId is used to get latest campaignObject and retry with proper param.

• The campaign resumes from the failed step, and once successful, the status is updated.

3.4 Completion

Once all steps are successfully completed, the End process is marked as "Completed." The CampaignId is marked as fully processed, completing the campaign creation process.

4. Main Campaign Creation Function

Function: createCampaign

Function Responsibility:

The createCampaign function is the central component responsible for orchestrating the entire campaign creation process. It:

• Accepts three parameters:

  • currentProcessName: Identifies the specific step in the campaign creation flow.

  • campaignId: The unique identifier for the campaign being created.

  • request: Represents the incoming request data required for the process.

• Uses a switch-case structure to determine and execute the corresponding action based on the provided currentProcessName.

Process Execution Flow

1. Validation Phase:

• Before invoking the createCampaign function, all required validations (e.g., input data checks, resource availability) must be successfully completed.

• This ensures that the campaign creation process is initiated only with valid and consistent data.

2. Execution Phase:

• After validation, the createCampaign function is invoked with the following parameters: currentProcessName, campaignId, and request.

• Based on the value of currentProcessName, the function performs the corresponding action (e.g., project creation, facility creation).

• It updates the Status Tracking Table with the progress or result of the process.

3. Failure Handling:

• If a failure occurs during any step:

  • The state of the campaign (identified by campaignId) is persisted in the Status Tracking Table.

  • The failure status is recorded.

  • The function exits gracefully, allowing the retry mechanism to resume from the failed step.

Function Implementation

public void createCampaign(String currentProcessName, String campaignId, Request request) {
    switch (currentProcessName) {
        case "Project Creation":
            // Handle Project Creation
            createProject(campaignId, request);
            break;

        case "Facility Creation":
            // Handle Facility Creation
            createFacility(campaignId, request);
            break;

        case "User Creation":
            // Handle User Creation
            createUser(campaignId, request);
            break;

        case "Facility Mapping":
            // Handle Facility Mapping
            mapFacility(campaignId, request);
            break;

        case "User Mapping":
            // Handle User Mapping
            mapUser(campaignId, request);
            break;

        case "Product Mapping":
            // Handle Product Mapping
            mapProduct(campaignId, request);
            break;

        case "End":
            // Final step, mark as completed
            completeCampaign(campaignId, request);
            break;

        default:
            throw new IllegalArgumentException("Unknown process: " + currentProcessName);
    }
}

Parameters:

• currentProcessName: The name of the current process being executed (e.g., "Project Creation").

• campaignId: The unique identifier of the campaign being processed.

• request: The request object that carries additional parameters or data necessary for the processing.

The createCampaign function dynamically handles each process in the campaign creation sequence and can resume from the point of failure when necessary.

Campaign Creation and Update Flow

1. Fetching Entity Data Based on Campaign ID:

• New Campaign Creation:

  • If the campaign is newly created, fetch the entity data using only the current campaignId.

  • This is determined by checking if the parentCampaignId is null. If it’s null, it indicates a new campaign creation, and only the current campaignId will be used to fetch the related data.

• Campaign Update (with Parent Campaign):

  • If the campaign is being updated (i.e., the parentCampaignId is a valid value), fetch entity data using both the current campaignId and the parentCampaignId.

  • This allows for fetching both the updated campaign's data and the parent campaign's data to apply any changes or updates properly.

2. Handling Campaign Status (Active/Inactive):

• Campaign Activation/Deactivation:

  • Before starting the createCampaign process, check if the campaign needs to be activated or deactivated.

  • If the campaign is being deactivated, update its status accordingly and ensure that no new actions are performed for the campaign.

  • If the campaign is being activated, ensure all dependencies and related data are in the correct state for an active campaign.

  • Activation or deactivation will happen before the main logic of campaign creation starts or at the "End" stage, depending on the campaign's status and any changes made.

3. Handling Other Info Persistence:

• Any additional campaign-related information, such as configurations, metadata, or settings, will be handled either at the start of the campaign creation process or at the "End" switch case.

• This ensures that all necessary data is persisted and that updates to campaign details are completed before finalizing the campaign.

Logic for createProject

About Entity table

The campaignProject table is used to store information about the projects related to a specific campaign. It keeps track of the project’s status, its target data, and the associated boundary.

Table Columns:

1. id: A unique identifier for each record (Primary Key).

2. projectId: The ID of the project linked to the campaign.

3. campaignNumber: The campaign number associated with the project.

4. boundaryCode: A code representing the geographical boundary for the project.

5. isActive: A flag indicating whether the project is active (true) or inactive (false).

Steps

1. Delete Projects

1. Fetch all active projects (isActive = true) associated with the parentCampaignId(if present) from the campaignProject table.

2. Compare the boundaryCode of each project in the database with the boundaries listed in the target sheet.

3. For any project in the database whose boundaryCode is not present in the target sheet:

• Fetch the project details from the Project Service.

• Update the project in the Project Service by setting its parent to null, and inactive, effectively removing its association.

• Mark the corresponding row in the campaignProject table as isActive = false. And then add new rows associated with current campaignId and projects.

2. Update Projects

• Compare Target Data:

  • Compare the target data from the target sheet with the targets JSON stored in the database.

• Identify Differences:

  • If there is a discrepancy between the target data in the target sheet and the stored targets JSON, proceed to the next steps.

• Fetch Project Details:

  • Retrieve the project details from the Project Service using the relevant project identifier.

• Update Project Data:

  • Update the project in the Project Service with the new target data.

• Update CampaignProject Data:

  • Update the targets JSON column in the campaignProject table for the current campaignNumber, ensuring the new targets data is reflected correctly.

3. Create Projects

• Check if Project Exists:

  • For each row in the target sheet with a boundaryCode, check if a project with the same boundaryCode exists in the campaignProject table for the given parentCampaignNumber, regardless of whether isActive is true or false.

• Project Exists with isActive = false:

  • If a project with the same boundaryCode exists but has isActive = false:

    1. Compare the target data in the target sheet with the targets JSON stored in the database for that project.

    2. If there is a difference between the target data:

       • Fetch the project details from the Project Service.

       • Update the project in the Project Service with the new target data using the Project Update API.

       • Update the targets JSON in the campaignProject table to reflect the new target data.

       • Set isActive = true for the project in the campaignProject table to mark it as active.

       • Additionally, create a new row in the campaignProject table with the current campaignId and the newly activated project.

• Project Does Not Exist:

  • If no project with the specified boundaryCode exists in the campaignProject table for the given parentCampaignId:

    1. Use the Project Create API to create a new project with the data from the target sheet.

    2. Insert a new row into the campaignProject table with the following details:

       • campaignNumber: Current campaign number.

       • projectId: From the newly created project.

       • boundaryCode: From the target sheet.

       • targets JSON: From the target sheet.

       • isActive: Set to true.

Logic for createFacility

About Entity table

The campaignFacility table is used to track facilities associated with a specific campaign. It contains the following columns:

• id: A unique identifier for each record.

• facilityId: The unique ID of the facility.

• campaignNumber: The campaign number, the facility is associated with.

• boundaryCode: A code representing the geographical location or boundary of the facility.

• isActive: A flag indicating whether the facility is active (true) or inactive (false).

These columns help manage and track facilities in relation to campaigns, enabling efficient updates, deletions, and creations based on the campaign's requirements.

Steps

1. Delete Facility:

Logic:

• For each facility marked as inactive in the sheet:

  1. Search for active facilities in the campaignFacility table that match the facilityId and parentCampaignNumber.

  2. If matching records are found, set isActive = false to deactivate those facilities.

2. Update Facility:

Logic:

• Check for Boundary Change:

  1. For active facilities in the sheet that have a facilityId, check if the boundaryCode has changed compared to the existing records in the campaignFacility table.

  2. If a boundary change is detected:

     • Create a new row in the campaignFacility table with the updated boundaryCode, setting isActive = true and associating it with the current campaignNumber.

  3. No other updates are needed beyond the boundary code change.

3. Create Facility:

Logic:

• Check for New Facility in Sheet (Active Facility):

  1. For each row in the sheet, if facilityUsage is active and a facilityId is provided:

     • If the facilityId is provided:

       • Check if the facility already exists in the campaignFacility table.

         • If the facility exists and isActive = false, update isActive = true and create a new row for the current campaignId.

         • If the facility does not exist, create a new row in the campaignFacility table with the relevant details: facilityId, campaignNumber, boundaryCode, status, capacity.

     • If no facilityId is provided:

       • Create a new facility using the Facility Create API.

       • After creating the facility, insert a new record into the campaignFacility table with the relevant details: facilityId, campaignNumber, boundaryCode, status, capacity.

Logic for createUser

About Entity table

The campaignUser table is used to track users associated with a specific campaign. It contains the following columns:

• id: A unique identifier for each record.

• userserviceid: The service ID of the user user for mapping.

• campaignNumber: The campaign number, the user is associated with.

• phoneNumber: The phone number of the user.

• Role: The role of the user within the campaign.

• boundaryCode: A code representing the geographical boundary or location of the user.

Steps

1. Delete User:

Logic:

• For each user marked as inactive in the sheet:

  1. Search for active users in the campaignUser table that match the userserviceid and parentCampaignNumber.

  2. If matching records are found, set isActive = false to deactivate those users.

2. Update User:

Logic:

• Check for Boundary Code Change:

  1. For users in the sheet that are active and have a userserviceid, check if the boundaryCode has changed compared to the existing records in the campaignUser table.

  2. If a boundary code change is detected:

     • Mark the old record as inactive (isActive = false) and associate it with the current campaignNumber.

     • Create a new record with the same userserviceid, the new boundaryCode, and set isActive = true.

• No Other Update Use Cases:

  • Currently, there are no other update use cases for user data beyond the boundary code change.

3. Create User:

Logic:

• Check for New User in Sheet (Active User):

  1. For each row in the sheet, check if the usage is active and whether a userserviceid is provided:

     • If a userserviceid is provided:

       • Check if the user already exists in the campaignUser table.

         • If the user exists and isActive = false, set isActive = true and update the boundaryCode in the new row for the current campaignNumber.

         • If the user does not exist, create a new record in the campaignUser table with the relevant details: userserviceid, campaignNumber, name, phoneNumber, role, employment, boundaryCode.

     • If no userserviceid is provided:

       • Create a new user using the Employee Create API.

       • After the user is created, insert a new record into the campaignUser table with the relevant details: userserviceid, campaignNumber, name, phoneNumber, role, employment, boundaryCode.

Logic for mapFacility

Steps:

1. Retrieve Data:

   • Fetch all projects from the campaignProject table for the current campaignNumber.

   • Fetch all facilities, both active and inactive, from the campaignFacility table.

2. Handle Active Facilities:

   • For each active facility:

     • Extract the boundaryCode of the facility.

     • Match the boundaryCode with the boundary codes of the projects in the campaignProject table to find the associated projectId.

3. Check for Existing Mapping (Active Facilities):

   • Use the facilityId and projectId to search for an existing mapping in the project-service.

   • If no existing mapping is found, make a create mapping API call to the project-service to create a new mapping between the facility and the project.

4. Handle Inactive Facilities:

   • For each inactive facility:

     • Extract the boundaryCode of the facility.

     • Match the boundaryCode with the boundary codes of the projects in the campaignProject table to find the associated projectId.

5. Check for Existing Mapping (Inactive Facilities):

   • Use the facilityId and projectId to search for an existing mapping in the project-service.

   • If the mapping exists, make an update mapping API call to the project-service to deactivate the mapping (i.e., mark it inactive).

Overview of Actions:

• For Active Facilities:

  • Search for a mapping between the facility and the project.

  • If no mapping is found, create a new mapping.

• For Inactive Facilities:

  • Search for a mapping between the facility and the project.

  • If the mapping exists, update the mapping to make it inactive.

Logic for mapUser

Steps:

1. Retrieve Data:

   • Fetch all users from the campaignUser table for the current campaignNumber.

   • Fetch all active and inactive users from the system.

2. Handle Active Users:

   • For each active user:

     • Extract the boundaryCode of the user.

     • Match the boundaryCode with the boundary codes of the projects in the campaignProject table to find the associated projectId.

3. Check for Existing Mapping (Active Users):

   • Use the userId and projectId to search for an existing mapping in the project-service (or similar mapping service).

   • If no existing mapping is found:

     • Make a create mapping API call to the mapping service to establish a new mapping between the user and the project.

4. Handle Inactive Users:

   • For each inactive user:

     • Extract the boundaryCode of the user.

     • Match the boundaryCode with the boundary codes of the projects in the campaignProject table to find the associated projectId.

5. Check for Existing Mapping (Inactive Users):

   • Use the userId and projectId to search for an existing mapping in the project-service.

   • If the mapping exists, make an update mapping API call to the mapping service to deactivate the mapping (i.e., mark it inactive).

Overview of Actions:

• For Active Users:

  • Search for a mapping between the user and the project.

  • If no mapping is found, create a new mapping.

• For Inactive Users:

  • Search for a mapping between the user and the project.

  • If the mapping exists, update the mapping to make it inactive.

Logic for mapProduct

Steps:

1. Retrieve Product and Project Data:

   • Get a list of all products with pvarId from the deliveryRules of the campaignProject table.

   • Retrieve all projectIds related to the given campaignNumber from the campaignProject table.

2. Generate Product-Project Combinations:

   • Create a list of combinations with each pvarId paired with the corresponding projectId.

3. Check for New Mappings:

   • For each pvarId x projectId combination:

     • Search the mapping service (e.g., project-service) to check if the mapping between the product (pvarId) and the projectId already exists.

     • If no mapping exists:

       • Make a create mapping API call to the mapping service to establish a new mapping between the product and the project.

4. Delete Existing Extra Mappings:

   • Check for products that are missing from campaignNumber but exist in parentCampaignNumber.

   • Make their pvarId x projectId combinations.

   • Make extra mappings inactive via the mapping update API.

5. Retry Logic identifiers

1. Project Retry:

   • The retry mechanism for a project will be based on the target boundary code. If a failure occurs, the system will attempt to retry the project creation or update by matching the target boundary code associated with the project.

2. User Retry:

   • The retry mechanism for a user will be based on the phone number. In the event of a failure, the system will retry the process by identifying the user through their unique phone number, ensuring that the retry logic targets the correct user entry.

3. Facility Retry:

   • The retry mechanism for a facility will be based on a combination of the facility name, status, facility type, and capacity. In the future, this retry logic can be expanded to use a generated unique facility name or other identifiers to better target specific facilities during retry operations.

Notes

• Sheet Columns as Table Columns We might need to use sheet columns as table columns to reduce coupling between sheets and to generate all data related to a campaign for parent-to-child updates.

• Facility Retry Identifier The facility retry identifier should be updated to have a standard identifier for retries.

• Campaign ID vs. Campaign Number Since we receive parentCampaignId, having entity tables with a column as campaignId could be beneficial.

Tunings Required for 0.4

1. Request Handling:

   • Requests should be made only at the Controller level, avoiding internal service layers for such calls. This will ensure better separation of concerns and improve the overall structure of the codebase.

2. Strict Model Enforcement:

   • Strict models must be enforced consistently throughout the codebase. This will ensure better validation, predictability, and reduce the likelihood of errors or inconsistencies.

File Organization

1. Utility and Helper Files:

   • Utility and helper files should follow specific naming conventions and responsibilities to maintain clarity and ensure proper organization:

     • campaignUtils: Exclusively handles campaign-related utilities.

     • microplanUtils: Exclusively handles microplan-related utilities.

Enhancements

1. Locale Issue in Uploads:

   • A solution needs to be designed and finalized for handling locale-specific uploads. The solution will include a signature or unique identifier embedded within the generated template. This signature will ensure that the template can accept only the locale and campaignId for specific campaign . This enhancement can be scoped as a 0.4 enhancement to provide better internationalization support for users in different regions, ensuring that the correct locale-specific data is handled during the upload process.

2. Auto Migration on Build:

   • Introduce automatic database migrations during the execution of yarn run dev or yarn prod. This can be scoped as a 0.4 enhancement to streamline both the deployment process and the development workflow.

Technical Documentation: Update Campaign Web Flow

Overview

This document describes the web flow for updating an existing campaign using the Admin Console. The process involves interactions between the user and several backend services, ensuring the campaign data is updated correctly and validated before finalizing changes.

Actors and Participants

• User: The person interacting with the Admin Console to update an existing campaign.

• CampaignManager (Admin Console): The primary interface that the user uses to manage and update campaign information.

• ProjectFactory: Responsible for handling the creation and updating of campaign objects and validating the data.

• BoundaryService: Provides the boundary hierarchy definitions and relationship data necessary for the campaign.

• MDMSService: Supplies master data such as project types, hierarchy configurations, and other templates.

• FileStoreService: Manages the storage and retrieval of files related to the campaign.

Sequence Flow

1. Initiating Campaign Update

• User: Begins the update process by selecting an existing campaign from the "My Campaign" screen within the Admin Console.

• CampaignManager: Receives the request to update a specific campaign and retrieves the campaign object using its unique ID.

2. Fetching Campaign Data

• CampaignManager sends a request to ProjectFactory to fetch the campaign object based on the provided campaign ID.

  • ProjectFactory responds with the campaign object containing the current campaign details.

3. Fetching Boundary Information

• CampaignManager requests BoundaryService to fetch boundary hierarchy definitions based on the campaign's hierarchy type.

  • BoundaryService responds with the boundary hierarchy definition.

• CampaignManager requests BoundaryService to fetch boundary relationship data based on the hierarchy type.

  • BoundaryService responds with the boundary relationship data.

4. User Data Input

• User: Updates the necessary fields, such as boundary delivery configuration and other campaign-specific details, using the Admin Console.

• CampaignManager: Sends the updated information to ProjectFactory to create or update the campaign object, storing it with an action status of "draft".

5. Template Generation

• ProjectFactory: Automatically triggers the generation of templates for different resources, including:

  • Target templates

  • Facility templates

  • User templates

6. Template Download and Storage

• User: Downloads the generated templates for each resource type via the Admin Console.

• CampaignManager: Sends a request to FileStoreService to store the downloaded files.

  • FileStoreService responds with a filestoreid that uniquely identifies the stored file.

7. Data Validation

• CampaignManager: Sends the data and the filestoreid to ProjectFactory for validation.

  • ProjectFactory responds with a unique validation ID, as the validation process may take some time.

• CampaignManager: Periodically checks the validation status using the unique validation ID.

8. Validation Outcome

• ProjectFactory:

  • If validation is successful:

    • Responds with a success message.

    • CampaignManager: Displays a success message to the user, indicating that they can proceed to the next step.

  • If validation fails:

    • Responds with an error message detailing the validation failure.

    • CampaignManager: Displays the error message to the user, prompting them to correct the errors and re-upload the files.

9. Final Campaign Update

• User: Once all required data is filled in and validated, the user reviews the summary of the campaign data and clicks on the "Update Campaign" button.

• CampaignManager: Sends a request to ProjectFactory with the campaign update API, marking the action as "update".

10. Campaign Update Outcome

• ProjectFactory:

  • If the update is successful:

    • Responds with a success message, indicating that the campaign update has started.

    • CampaignManager: Displays a success message to the user, confirming that the campaign has been updated successfully.

  • If the update fails:

    • Responds with an error message detailing the failure.

    • CampaignManager: Displays the error message to the user, prompting them to correct any issues and try again.

Error Handling

• Validation Failures: If validation fails at any stage (e.g., during file validation or input data checks), the CampaignManager will notify the user of the specific issues. The user must resolve these issues and re-upload the necessary data to proceed.

• Service Errors: If any of the services (e.g., BoundaryService, ProjectFactory) encounter an error during processing, the CampaignManager will display an error message, detailing the problem and suggesting corrective actions.

Web Sequence Diagram

Conclusion

This document outlines the flow for updating an existing campaign using the Admin Console. The structured sequence ensures that any changes to the campaign are thoroughly validated and processed, minimizing errors and ensuring the integrity of the campaign data. By following this flow, users can confidently update campaigns, knowing that all necessary steps are taken to verify and finalize their changes.

Technical Documentation: Checklist Management Web Flow

Overview

This document outlines the web flow for managing checklists within a campaign context, including viewing existing and creating new checklists. The process involves interaction between the user and various backend services to ensure the correct retrieval, creation, and modification of checklists associated with specific campaigns.

Actors and Participants

• User: The individual interacting with the checklist management UI to view, create, and modify checklists.

• Checklist View UI (CurrentScreen): This is the user interface for viewing existing checklists and initiating the creation of new ones.

• Checklist Create UI (CurrentScreen): The user interface for creating and configuring checklists.

• Service Request Service (ServiceRequestService): Manages service requests and updates related to checklists.

• MDMS Service (MDMSAPI): Provides master data management services for roles, checklist types, and other configurations.

• Localisation Service (LOCAPI): Manages the localization of checklist questions.

Sequence Flow

Checklist Viewing Flow

1. Access Checklist View UI

   • The user accesses the Checklist View UI after a campaign has been created.

2. Fetching Configured Service Requests

   • CurrentScreen sends a request to ServiceRequestService to fetch configured service requests.

     • ServiceRequestService filters and returns checklists using the campaign name, role, and type, or just the campaign name (if the service is enhanced).

   • ServiceRequestService returns the relevant checklists to CurrentScreen.

3. Display Checklists

   • CurrentScreen displays the checklists received from ServiceRequestService to the User.

4. Creating a New Checklist

   • The user clicks on "Create Checklist" in the Checklist View UI.

   • CurrentScreen sends a request to MDMSAPI to fetch role and checklist type master data relevant to the campaign type.

   • MDMSAPI returns the master data to CurrentScreen.

   • The user selects the desired role and checklist type.

   • CurrentScreen redirects to the checklist creation screen based on the selected campaign name, role, and type.

5. Enable/Disable Checklist

   • The user clicks on the enable/disable option for any checklist.

   • CurrentScreen sends an update call to ServiceRequestService to toggle the active/inactive status of the checklist.

   • ServiceRequestService returns the updated response.

   • CurrentScreen updates the checklist status based on the response.

Checklist Creation Flow

1. Access Checklist Create UI

   • The user accesses the Checklist Create UI.

   • CurrentScreen parses URL query parameters to determine the campaign name, role, and checklist type.

2. Fetching Draft Service Requests

   • CurrentScreen sends a request to MDMSAPI to fetch draft service requests based on the role and type.

   • MDMSAPI returns the configured draft service requests.

3. Loading Default Checklist Questions

   • CurrentScreen checks if there is a template available for the checklist and loads default checklist questions.

4. User Interaction for Checklist Questions

   • Users can add, delete, or modify any checklist questions in the UI.

   • The user clicks on "Create" to finalise the checklist.

5. Generating Unique Codes and Creating Service Requests

   • CurrentScreen generates a unique code for every checklist question.

   • CurrentScreen sends a create service request with the list of all questions to ServiceRequestService.

   • ServiceRequestService returns a successful response indicating that the checklist has been created.

6. Localisation of Checklist Questions

   • CurrentScreen sends a request to LOCAPI to create localisation for all checklist questions.

     • Each question is assigned a generated code, a user-entered message, and is associated with the hcm-checklist module.

   • LOCAPI processes the localisation request and returns a response.

7. Completion and Feedback

   • CurrentScreen displays a toast notification to the User indicating the successful creation of the checklist.

   • User is redirected back to the Checklist View screen, where they can see the newly created checklist.

Error Handling

• Service Request Failures: If a service request fails at any point, the CurrentScreen will display an error message to the User. Users must resolve the issues and retry the operation.

• Validation Errors: During checklist creation, if validation errors are detected, the CurrentScreen will notify the User with specific details, and the user must correct the issues before proceeding.

Web Sequence Diagram

Conclusion

This documentation provides a comprehensive overview of the checklist management process within a campaign. The structured sequence ensures that all checklist-related activities are handled correctly, from viewing existing checklists to creating and localizing new ones. By adhering to this flow, users can manage checklists efficiently, ensuring consistency and accuracy in their campaign management activities.

Template dummy data for configure rules-

{
  "checklistConfig": [
    {
      "tabType": "referral",
      "rulesConfig": [
        {
          "ruleNumber": 1,
          "conditions": [
            {
              "code": "SN1",
              "values":
                "SHORTAGES"
              
            },
            {
              "condition": 2,
              "isRequired": true,
              "code": "SN2",
              "values": [
                "HOSPITALS",
              ]
            }
          ]
        },
        {
          "ruleNumber": 2,
          "conditions": [
            {
              "condition": 1,
              "isRequired": true,
              "code": "SN3",
              "values": [
                "YES"
              ]
            },
            {
              "condition": 2,
              "isRequired": true,
              "code": "SN4",
              "values": [
                "YES"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Output data format

{
  "checklistConfig": [
    {
      "tabType": "referral",
      "rulesConfig": [
        {
          "ruleNumber": 1,
          "conditions": [
            {
              "id": "2d4a7b1e-1f2f-4a8a-9672-43396c6c9a1c",
              "condition": 1,
              "isRequired": true,
              "code": "Is the child administered for the first time?",
              "values": [
                "YES",
                "NO",
                "NOTSELECTED"
              ],
              "answer": [
                "YES"
              ]
            },
            {
              "id": "2d4a7b1e-1f2f-4a8a-9672-43396c6c9a1c",
              "condition": 1,
              "isRequired": true,
              "code": "Is the child administered for the second time?",
              "values": [
                "YES",
                "NO",
                "NOTSELECTED"
              ],
              "answer": [
                "NO"
              ]
            }
          ]
        },
        {
          "ruleNumber": 2,
          "conditions": [
            {
              "id": "2d4a7b1e-1f2f-4a8a-9672-43396c6c9a1c",
              "condition": 1,
              "isRequired": true,
              "code": "Is the child sick?",
              "values": [
                "YES",
                "NO",
                "NOTSELECTED"
              ],
              "answer": [
                "NO"
              ]
            }
          ]
        }
      ]
    },
    {
      "tabType": "delivery",
      "rulesConfig": [
        {
          "ruleNumber": 1,
          "conditions": [
            {
              "id": "4add5323-fc98-4e71-a783-27dbb922c99f",
              "condition": 2,
              "isRequired": true,
              "code": "Is the child having fever?",
              "values": [
                "YES",
                "NO",
                "NOTSELECTED"
              ],
              "answer": [
                "YES"
              ]
            }
          ]
        },
        {
          "ruleNumber": 2,
          "conditions": [
            {
              "id": "4add5323-fc98-4e71-a783-27dbb922c99f",
              "condition": 2,
              "parentId": null,
              "isRequired": true,
              "code": "Is child above 5 years?",
              "values": [
                "YES",
                "NO",
                "NOTSELECTED"
              ],
              "answer": [
                "YES"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Points logic

This will be written in the wrapper For the points assignment for the questions, we will calculate on the basis of Screen Type and/or condition AND/OR Conditions Points assigned for each referral = 100

X = 100/ no of rules

Points for each ques = x/no of conditions in each rule

Limitations

If same ques is available for one than one referral flow, then point assigned to them will be equal for more than one flow, that will cause discrepancy in the app, Possible solutions to this

1) if the points are the same for a ques for more than one flow then , we can introduce a variable for flow preference in the app, if points are same then go with the flow preference.

2) Or we can put validation from the console side , that question cannot be repeated more than once

FLOW

Data required for the api This transform of data will happen in a wrapper

{
  "tenantId": "mz",
  "code": "SMC Campaign.ELIGIBILITY.DISTRIBUTOR",
  "isActive": true,
  "additionalFields": {
    "schema": "ServiceDefinition",
    "version": 1,
    "fields": [
      {
        "key": "precedenceFlow",
        "value": "SMC1.YES"
      },
      {
        "key": "flow",
        "value": [
          "TO_ADMINISTER",
          "BENEFICIARY_REFUSED",
          "BENEFICIARY_REFERRED"
        ]
      }
    ]
  },
  "attributes": [
    {
      "tenantId": "mz",
      "code": "Is the child administered for the first time?",
      "dataType": "SingleValueList",
      "values": [
        "YES",
        "NO",
        "NOTSELECTED"
      ],
      "isActive": true,
      "required": true,
      "order": 1,
      "additionalFields": {
        "schema": "ServiceAttribute",
        "version": 1,
        "fields": [
          {
            "key": "pointsMapping",
            "value": {
              "YES": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NO": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 50
              },
              "NOTSELECTED": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              }
            }
          }
        ]
      }
    },
    {
      "tenantId": "mz",
      "code": "Is the child sick?",
      "dataType": "SingleValueList",
      "values": [
        "YES",
        "NO"
      ],
      "isActive": true,
      "required": true,
      "order": 2,
      "additionalFields": {
        "schema": "ServiceAttribute",
        "version": 1,
        "fields": [
          {
            "key": "pointsMapping",
            "value": {
              "YES": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NO": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 50
              }
            }
          }
        ]
      }
    },
    {
      "tenantId": "mz",
      "code": "Is the child having fever?",
      "dataType": "SingleValueList",
      "values": [
        "YES",
        "NO",
        "NOTSELECTED"
      ],
      "isActive": true,
      "required": true,
      "order": 3,
      "additionalFields": {
        "schema": "ServiceAttribute",
        "version": 1,
        "fields": [
          {
            "key": "pointsMapping",
            "value": {
              "YES": {
                "TO_ADMINISTER": 50,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NO": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NOTSELECTED": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              }
            }
          }
        ]
      }
    },
    {
      "tenantId": "mz",
      "code": "Is child above 5 years?",
      "dataType": "SingleValueList",
      "values": [
        "YES",
        "NO",
        "NOTSELECTED"
      ],
      "isActive": true,
      "required": true,
      "order": 4,
      "additionalFields": {
        "schema": "ServiceAttribute",
        "version": 1,
        "fields": [
          {
            "key": "pointsMapping",
            "value": {
              "YES": {
                "TO_ADMINISTER": 50,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NO": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              },
              "NOTSELECTED": {
                "TO_ADMINISTER": 0,
                "BENEFICIARY_REFUSED": 0,
                "BENEFICIARY_REFERRED": 0
              }
            }
          }
        ]
      }
    }
  ]
}

Template Creation Process

We will create this template with all generic formatting, with headers, and use these templates throughout the project-factory for adding data to these templates for different types of data i.e.(user, target, and facility).

We will create this template with all generic formatting, with headers, and use these templates throughout the project-factory for adding data to these templates for different types of data i.e.(user, target, and facility)

The template workbook will have ReadMeSheet (frozen) for all types, the main sheet (i.e. Create List Of Users, List of Available Facilities, and the target sheet with the boundary type on which we split configured. It will also have an empty boundary data sheet with just a formatted header (colour formatting minus any data).

The unique identifier for each template which will be hidden -

1. User - UserServiceUuid

2. Facility- Facility Code

3. Target Sheet - Boundary Code Column will be hidden

Generate Data API

Endpoint

• Endpoint: /data/_generate

• Method: POST

Request Structure

• RequestInfo: Object containing request information.

• Query Parameters:

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

  • tenantId: Tenant identifier.

  • hierarchyType: Type of hierarchy.

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

Response Structure

• ResponseInfo: Object containing response information.

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

Flow

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

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

3. Generate Data Process:

   • Validation: The server validates the generated request.

   • Data Processing:

     • Fetch Data: Fetches existing data from the database.

     • Modify Data: Modify the retrieved data as necessary.

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

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

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

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

   • Force Update Logic:

     • If the forceUpdate parameter is set to true:

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

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

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

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

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

6. Error Handling: If errors occur, generate and send an error response.

Flow Diagram

Overview

This service is used to create a Project (Campaign), create required resource data, and create a mapping relation between them based on the boundary data.

Dependencies

1. Project

2. Facility

3. Product

4. HRMS

5. MDMS

6. Boundary

7. Localisation

8. Access Control

9. IdGen

10. Individual

11. User

API Specification

Base Path: /project-factory/

API Contract Link

Data Model

DB Schema Diagram

Table Details

```dbml
Table eg_cm_campaign_details {
  id varchar(128) [primary key ,not null, unique]
  tenantid varchar(64) [not null ,note: 'Tenant identifier']
  campaignname varchar(250) [not null ,note: 'Name of the campaign']
  projecttype varchar(128) [not null ,note: 'Type of project']
  startdate bigint [note: 'Start date in epoch']
  enddate bigint [note: 'End date in epoch']
  campaigndetails jsonb [note: 'Campaign specific details']
  status varchar(128) [not null ,note: 'Status of the campaign']
  parentid varchar(128) [note: 'refering to the previous campaign id']
  action varchar(64) [not null ,note: 'Action type']
  campaignnumber varchar(128) [not null ,note: 'Campaign number']
  hierarchytype varchar(128) [not null ,note: 'Hierarchy type']
  boundarycode varchar(64) [note: 'Boundary code']
  projectid varchar(128) [note: 'Project identifier']
  createdby varchar(128) [not null ,note: 'Created by user ID']
  lastmodifiedby varchar(128) [note: 'Last modified by user ID']
  createdtime bigint [note: 'Creation timestamp']
  lastmodifiedtime bigint [note: 'Last modification timestamp']
  additionaldetails jsonb [note: 'Additional details']
}
```

```dbml
Table eg_cm_campaign_process {
  id varchar(128) [primary key, not null, unique]
  campaignid varchar(128) [not null,note: 'Foreign key to eg_cm_campaign_details.id']
  type varchar(128) [not null,note: 'Type of campaign process']
  status varchar(128) [not null,note: 'Status of the campaign process']
  details jsonb [note: 'Detailed information of the process']
  createdtime bigint [note: 'Creation timestamp']
  lastmodifiedtime bigint [note: 'Last modification timestamp']
  additionaldetails jsonb [note: 'Additional details']
}
Ref: eg_cm_campaign_process.campaignid > eg_cm_campaign_details.id // many-to-one

```

```dbml
Table eg_cm_generated_resource_details {
  id varchar(128) [primary key,not null, unique]
  filestoreid varchar(128) [note: 'File store ID']
  status varchar(128) [not null,note: 'Status of the resource']
  type varchar(128) [not null,note: 'Type of resource']
  tenantid varchar(128) [not null,note: 'Tenant identifier']
  count bigint [note: 'Count of resources']
  createdby varchar(128) [note: 'Created by user ID']
  createdtime bigint [note: 'Creation timestamp']
  lastmodifiedby varchar(128) [note: 'Last modified by user ID']
  lastmodifiedtime bigint [note: 'Last modification timestamp']
  additionaldetails jsonb [note: 'Additional details']
  hierarchytype varchar(128) [not null,note: 'Hierarchy type']
  campaignid varchar(128) [note: 'Foreign key to eg_cm_campaign_details.id']
}
Ref: eg_cm_generated_resource_details.campaignid > eg_cm_campaign_details.id // many-to-one

```

```dbml
Table eg_cm_resource_activity {
  id varchar(128) [primary key,not null, unique]
  retrycount int [note: 'Number of retry attempts']
  type varchar(64) [not null,note: 'Type of activity']
  url varchar(128) [not null,note: 'URL for the activity']
  requestpayload jsonb [note: 'Request payload']
  tenantid varchar(128) [not null,note: 'Tenant identifier']
  responsepayload jsonb [note: 'Response payload']
  status bigint [note: 'Status code']
  createdby varchar(128) [note: 'Created by user ID']
  createdtime bigint [note: 'Creation timestamp']
  lastmodifiedby varchar(128) [note: 'Last modified by user ID']
  lastmodifiedtime bigint [note: 'Last modification timestamp']
  additionaldetails jsonb [note: 'Additional details']
  resourcedetailsid varchar(128) [not null,note: 'Foreign key to eg_cm_resource_details.id']
}
Ref: eg_cm_resource_activity.resourcedetailsid > eg_cm_resource_details.id // many-to-one

```

```dbml


Table eg_cm_resource_details {
  id varchar(128) [primary key,not null, unique]
  status varchar(128) [note: 'Status of the resource']
  tenantid varchar(128) [not null,note: 'Tenant identifier']
  filestoreid varchar(128) [note: 'File store ID']
  processedfilestoreid varchar(128) [note: 'Processed file store ID']
  action varchar(128) [not null,note: 'Action type']
  type varchar(64) [not null,note: 'Type of resource']
  createdby varchar(128) [note: 'Created by user ID']
  createdtime bigint [note: 'Creation timestamp']
  lastmodifiedby varchar(128) [note: 'Last modified by user ID']
  lastmodifiedtime bigint [note: 'Last modification timestamp']
  additionaldetails jsonb [note: 'Additional details']
  campaignid varchar(128) [note: 'Foreign key to eg_cm_campaign_details.id']
}

Ref: eg_cm_resource_details.campaignid > eg_cm_campaign_details.id // many-to-one


```

Web Sequence Diagrams

Data Create API

Generate Data API

Process Create Campaign API

Process Track api

This document outlines the UI design and configuration of screens and components for the application. It includes schema requirements, support for dynamic sections, and the necessary master data to facilitate data flow.

Key Points to Consider:

1. Schema Integration Based on Project Type

   • The UI design should incorporate schemas that vary depending on the selected project type.

   • Dynamic rendering of components and fields based on schema definitions.

2. Enable AddSection Functionality

   • Provide an option to dynamically add sections to the screen configuration.

   • Ensure sections can be personalized and managed efficiently.

3. Master Data Requirements The following master data sets are required to support the UI design and component configurations:

   • AppScreenConfigTemplate Predefined templates for application screen configurations based on project type.

   • AppScreenConfigPersonalized Personalized configurations for screens, tailored to specific user roles or preferences.

   • ComponentMetaDataMaster Metadata defining the components, such as type, properties, and behavior.

   • FieldTypeMaster Master data for supported field types, including their attributes (e.g., input, dropdown, date picker).

Master Data: AppScreenConfigTemplate

Schema Overview

The AppScreenConfigTemplate defines the configuration and structure of application screens. It supports dynamic field addition, sections, comments, and card-based layouts.

{
  // Array of screens for the application
  "screens": [
    {
      // Unique name for the screen
      "name": "screen1",
      // Parent category of the screen
      "parent": "Registration",
      // Screen headers and descriptions
      "headers": [
        {
          // Header label
          "label": "KJHSJKDHKJH",
          // Type of the header (e.g., header, info, description)
          "type": "header"
        },
        {
          "label": "KJHSJKDHKJH",
          "type": "info"
        },
        {
          "label": "KJHSJKDHKJH",
          "type": "description"
        }
      ],
      // Screen configuration settings
      "config": {
        // Allows adding fields dynamically to the screen
        "enableFieldAddition": true,
        // Allows adding sections dynamically to the screen
        "enableSectionAddition": true,
        // Enables commenting functionality on the screen
        "enableComment": true,
        // Specifies where fields can be added (e.g., body, header, footer)
        "allowFieldsAdditionAt": [
          "body"
        ],
        // Specifies where comments can be added
        "allowCommentsAdditionAt": [
          "body"
        ]
      },
      // Cards within the screen (UI components grouped into cards)
      "cards": [
        {
          // Card header text
          "header": "Header",
          // Card description text
          "description": "Desc",
          // Fields inside the card
          "fields": [
            {
              // Path for binding data in the field
              "jsonPath": "Screen heading",
              // Type of the field (e.g., text, dropdown)
              "type": "text",
              // Label for the field
              "label": "dzdzddadadad",
              // Specifies if the field is mandatory
              "required": true,
              // Indicates if the field is active
              "active": true,
              // Additional metadata for the field
              "metaData": {
                // Field is read-only
                "readOnly": true,
                // Field supports comments
                "isComment": true
              }
            },
            {
              "jsonPath": "Description",
              "type": "text",
              "label": "dzdzddadadad",
              "required": true,
              "active": true,
              "metaData": {
                "isComment": true
              }
            },
            {
              "jsonPath": "Description",
              "type": "text",
              "label": "Address Line 1",
              "required": true,
              "active": true,
              "metaData": {}
            },
            {
              // Unique ID for the field
              "id": "field2",
              // Field type is dropdown
              "type": "dropdown",
              // Label for the dropdown field
              "label": "Beneficiary Status",
              // Additional metadata for dropdown field
              "metaData": {
                // Field is mandatory
                "required": true,
                // Options available for the dropdown
                "options": [
                  {
                    // Label for the dropdown option
                    "label": "Beneficiary Absent",
                    // Value associated with the dropdown option
                    "value": "absent"
                  },
                  {
                    "label": "Delivery Successful",
                    "value": "successful"
                  }
                ]
              }
            }
          ]
        }
      ]
    },
    {
      // Placeholder for additional screen configurations
    }
  ]
}

UPDATE

```json
{
  "screens": [
    {
      "name": "HOUSEHOLD_LOCATION",
      "parent": "REGISTRATION",
      "headers": [
        {
          "jsonPath": "SCREEN_HEADING",
          "type": "header",
          "label": "SCREEN_HEADING_LABEL",
          "required": true,
          "active": true,
          "metaData": {
            "fieldType": "text"
          }
        },
        {
          "jsonPath": "DESCRIPTION",
          "type": "description",
          "label": "DESCRIPTION_LABEL",
          "required": true,
          "active": true,
          "metaData": {
            "fieldType": "text"
          }
        }
      ],
      "config": {
        "enableFieldAddition": true,
        "enableSectionAddition": true,
        "enableComment": true,
        "allowFieldsAdditionAt": [
          "body"
        ],
        "allowCommentsAdditionAt": [
          "body"
        ]
      },
      "cards": [
        {
          "header": "HEADER_CODE",
          "description": "DESCRIPTION_CODE",
          "fields": [
            {
              "jsonPath": "ADDRESS_LINE_1",
              "type": "text",
              "label": "ADDRESS_LINE_1_LABEL",
              "required": true,
              "active": true,
              "metaData": {}
            },
            {
              "jsonPath": "ADDRESS_LINE_2",
              "type": "text",
              "label": "ADDRESS_LINE_2_LABEL",
              "required": true,
              "active": true,
              "metaData": {}
            }
          ]
        }
      ]
    }
  ]
}
```

Output Data structure for App config

[
  {
    "name": "HouseholdLocation",
    "type": "page",
    "components": [
      {
        "title": "Household Location",
        "description": "Make sure the village name matches the one where you are today.",
        "order": 1,
        "attributes": [
          {
            "name": "administrationArea",
            "type": "field",
            "isEnabled": true,
            "attribute": "textField",
            "readOnly": true,
            "isRequired": false,
            "order": 1,
            "source": "DEFAULT"
          },
          {
            "name": "accuracy",
            "isEnabled": true,
            "readOnly": true,
            "attribute": "textField",
            "isRequired": true,
            "order": 2
          },
          {
            "name": "addressLine1",
            "isEnabled": true,
            "readOnly": false,
            "attribute": "textField",
            "isRequired": false,
            "validation": [
              {
                "pattern": "^\\d+$",
                "key": "onlyDigits",
                "errorMessage": "Digits only"
              }
            ],
            "order": 1
          },
          {
            "name": "postalCode",
            "isEnabled": true,
            "readOnly": false,
            "attribute": "textField",
            "isRequired": false,
            "order": 1
          },
          {
            "name": "TextField",
            "type": "additionalField",
            "label": "TextField",
            "attribute": "textField",
            "formDataType": "String",
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "keyboardType": "number",
            "validation": [
              {
                "pattern": "^\\d+$",
                "key": "onlyDigits",
                "errorMessage": "Digits only"
              }
            ],
            "order": 1
          },
          {
            "name": "SelectionBox",
            "type": "additionalField",
            "label": "SelectionBox",
            "attribute": "selectionbox",
            "formDataType": "List<String>",
            "menuItems": [
              "a",
              "b",
              "c",
              "d"
            ],
            "allowMultipleSelection": true,
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "order": 2
          },
          {
            "name": "dateForm",
            "type": "additionalField",
            "label": "dateForm",
            "attribute": "dateFormPicker",
            "formDataType": "DateTime",
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "order": 5
          },
          {
            "name": "DropDown",
            "type": "additionalField",
            "label": "DropDown",
            "attribute": "dropdown",
            "formDataType": "String",
            "menuItems": [
              "a",
              "b"
            ],
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "order": 3
          },
          {
            "name": "dobPicker",
            "type": "additionalField",
            "label": "dobPicker",
            "attribute": "dobPicker",
            "formDataType": "DateTime",
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "order": 4
          },
          {
            "name": "integerFormPicker",
            "type": "additionalField",
            "label": "integerFormPicker",
            "attribute": "integerFormPicker",
            "formDataType": "int",
            "initialValue": 0,
            "minimum": 0,
            "maximum": 10,
            "isEnabled": true,
            "readOnly": false,
            "isRequired": false,
            "order": 6
          }
        ]
      }
    ]
  }
]

Field Type Master Data

This provides the configuration and metadata for various input field types used in the application. Each field type is mapped to a specific appType and includes metadata such as data types, validation rules, and other properties.

{
  "fieldType": [
    {
      "type": "textInput",
      "appType": "textField",
      "metadata": {
        "formDataType": "String",
        "validation": [
          {
            "pattern": "^\\d+$",
            "key": "onlyDigits",
            "errorMessage": "Digits only"
          }
        ]
      }
    },
    {
      "type": "number",
      "appType": "textField",
      "metadata": {
        "formDataType": "String",
        "keyboardType": "number",
        "validation": [
          {
            "pattern": "^\\d+$",
            "key": "onlyDigits",
            "errorMessage": "Digits only"
          }
        ]
      }
    },
    {
      "type": "dropDown",
      "appType": "dropdown",
      "metadata": {
        "formDataType": "String",
      },
     "attributeToRename": {
        "from": "options", 
        "to": "menuItems" // Rename "options" to "menuItems" when restructuring
        "optionalFunction": null
      }
      "attributeToDelete": [],
      }
    {
      "type": "checkbox",
      "appType": "selectionbox",
      "metadata": {
        "formDataType": "List<String>",
        "allowMultipleSelection": true,
      },
      "fieldRenameMap": {
        "options": "menuItems" // Rename "options" to "menuItems" when restructuring
      }
    },
    {
      "type": "counter",
      "appType": "integerFormPicker",
      "metadata": {
        "formDataType": "int",
        "initialValue": 0,
        "minimum": 0,
        "maximum": 10
      }
    },
    {
      "type": "datePicker",
      "appType": "dobPicker",
      "metadata": {
        "formDataType": "DateTime"
      }
    },
    {
      "type": "dobPicker",
      "appType": "dateFormPicker",
      "metadata": {
        "formDataType": "DateTime"
      }
    }
  ]
}

Drawer Master Data

The Drawer Master Data defines the configuration for the list of fields to be displayed in the drawer. Each field includes a label for identification and a fieldType that determines the type of input control to be rendered in the UI.

{
  "drawerData": [
    {
      "label": "componentType",
      "fieldType": "dropdown",
      "defaultValue": false,
      "visibilityEnabledFor": []
    },
    {
      "label": "Mandatory",
      "fieldType": "toggle",
      "defaultValue": false,
      "visibilityEnabledFor": ["textField", "dropDown"]
    },
    {
      "label": "label",
      "fieldType": "toggle",
      "defaultValue": false,
      "visibilityEnabledFor": ["textField", "dropDown"]
    },
    {
      "label": "helpText",
      "fieldType": "toggle",
      "defaultValue": false,
      "visibilityEnabledFor":[]
    },
    {
      "label": "innerLabel",
      "fieldType": "toggle",
      "defaultValue": false,
      "visibilityEnabledFor": []
    }
  ]
}

Localisation Master data

{
  "LocalisationData": {
    "screen": "appScreenConfig"
    "LocalisationModule":"configure-app",
    "moduleVersion": "3",
    "minModuleVersion": "1",
    "fields": [
      {
        "fieldType": "dropdown",
        "localisableProperties": ["label", "options", "placeholder"]
      },
      {
        "fieldType": "toggle",
        "applicableFieldTypes": ["textField", "dropDown"]
      },
      {
        "fieldType": "toggle",
        "applicableFieldTypes": ["textField", "dropDown"]
      },
      {
        "fieldType": "toggle",
        "applicableFieldTypes": []
      }
    ]
  }
}

Overview of the Flow:

1. Fetching the App Configuration from MDMSv2:

   • Step Description: The app configuration master data is fetched from the MDMSv2 (Master Data Management System version 2). This data includes the settings, components, field types, and other configurations that dictate the structure and behavior of the app’s screens and components.

   • Flow Detail:

     • The data is fetched asynchronously via an API call to the MDMSv2.

     • Once the data is fetched, it is stored in the application’s global state using React’s useContext. This ensures the data is accessible across various components throughout the app.

     • The data might look like:

       • Screen configurations (e.g., component layout, form field types).

       • Master data for field types, component metadata, drawer configurations, etc.

   • Considerations:

     • Ensure that proper error handling is in place if the API call fails (e.g., retry logic or fallback UI).

     • The context should be memoized or optimized for performance if the app grows large.

2. User Interactions (Editing, Adding, Deleting Components):

• Step Description: Once the data is loaded and the UI is rendered based on the fetched configuration, users can interact with the UI by editing, adding, or deleting fields and components.

• Flow Detail:

  • Editing: Users can modify the existing field values or configurations. For example, changing field labels, modifying validation rules, or adjusting layout properties.

  • Adding: Users can add new components, fields, or sections to the form. The UI should dynamically update to accommodate new fields or components.

  • Deleting: Users can delete specific components, fields, or entire sections, and the UI should reflect these changes instantly.

  • The updates made by the user are stored in the local state (managed by React’s useState or within the useContext).

• Considerations:

  • The system must handle edge cases such as removing fields that are required or have dependencies.

  • Ensure that updates are validated locally before sending them back to MDMSv2, to prevent inconsistencies.

1. Restructuring Data for Web or Mobile Outputs:

   • Step Description: After the user makes changes, the data must be restructured based on the target platform (e.g., web or mobile). This restructuring ensures that the configuration is correctly formatted to match the specifications required by the platform.

   • Flow Detail:

     • Once the data is updated, it is transformed according to the specific platform’s output format. For example:

       • For web applications, the configuration might need to be structured in a way that fits the web component framework (e.g., React).

       • For mobile applications, it may need to follow mobile-specific guidelines (e.g., using mobile UI components or formats).

     • The restructuring process may involve:

       • Converting configuration fields to fit the layout constraints of mobile screens (e.g., adjusting padding, margins).

       • Changing input types or validations for mobile responsiveness.

       • Adapting field types and labels based on the platform (e.g., dropdowns might be replaced with modals on mobile).

   • Considerations:

     • This step may require conditional logic to determine which platform the configuration is being prepared for.

     • It’s crucial that no data is lost during the restructuring process, so careful testing is needed.

2. Updating MDMSv2 (Client Master Data Structure):

   • Step Description: After the changes are made and the data has been restructured for the appropriate platform, the final updated configuration needs to be sent back to MDMSv2. This update is stored as the ClientMasterData structure.

   • Flow Detail:

     • The modified data is packaged into a ClientMasterData structure, which conforms to the MDMSv2 schema.

     • An API call is made to send the updated data back to MDMSv2, where it is stored.

     • The ClientMasterData structure typically includes:

       • Updated configuration for screens, components, fields, and other UI elements.

       • Any changes to validation rules, field types, or component properties.

     • The system should notify the user once the update has been successfully pushed to MDMSv2, ideally with a confirmation message or toast notification.

   • Considerations:

     • Ensure data integrity is maintained during the update process.

     • The system should handle error scenarios (e.g., failed updates, validation errors) and provide appropriate feedback to users.

     • Implementing a versioning system for the configuration data could help manage updates and rollback scenarios, ensuring consistency over time.

Sequence Diagram

Flow Diagram

App Integration

Once the config is created, if it is directly for MDMS v2, we will enrich it with additional metadata and send it directly to MDMS v2.

If code generation is required based on the alternative approach, we will convert the config into code changes and push it to GitHub for app generation.