Loading...
Loading...
Loading...
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.
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.
Initiate Campaign Creation
The Client sends a request to the CampaignManager to create a campaign with all required and valid resources.
Fetch Boundary Relationship
The CampaignManager requests the BoundaryService to fetch the boundary relationship based on the hierarchy type.
The BoundaryService responds with the relevant boundary relationship data.
Fetch Project Type Master
The CampaignManager requests the MDMSService to fetch the project type master data.
The MDMSService responds with the project type master.
Validate Resource Files
The CampaignManager checks the Database to see if the input resource files have already been validated.
The Database responds with the validation status of the files.
Validation Check
The CampaignManager checks if all file templates and data are validated:
If validation is successful, the CampaignManager informs the Client that the campaign creation process has started, and the user needs to track the status using an ID.
If validation fails, the CampaignManager returns an error message, indicating which validation failed, and the user must resubmit the request.
Resource File Retrieval
The CampaignManager interacts with the FileStoreService to search for the resource based on the filestoreid.
The FileStoreService responds with the valid resource files.
Process Resource Data
The CampaignManager processes the retrieved sheets and identifies any resource data that needs to be created.
Facility Data Creation
The CampaignManager sends a request to the FacilityService to create facility data.
The FacilityService responds that the facilities have been created successfully.
Employee Data Creation
The CampaignManager sends a request to the HRMSService to create employee data.
The HRMSService responds that the employees have been created successfully.
Project Data Creation
The CampaignManager sends a request to the ProjectService to create project data with a parent-child relationship based on the project type and delivery configuration.
The ProjectService responds that the projects have been created successfully.
Project-Facility Mapping Creation
The CampaignManager sends a request to the ProjectService to create mappings between projects and facilities.
The ProjectService responds that the project-facility mappings have been created successfully.
Project-Staff Mapping Creation
The CampaignManager sends a request to the ProjectService to create mappings between projects and staff.
The ProjectService responds that the project-staff mappings have been created successfully.
Update Campaign Creation Status
The CampaignManager updates the Database with the status of the campaign creation process.
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.
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.
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.
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.
Initiate Campaign Update
The Client sends an update request to the CampaignManager with all required and valid resources.
Fetch Boundary Relationship
The CampaignManager requests the BoundaryService to fetch the boundary relationship based on the hierarchy type.
The BoundaryService responds with the relevant boundary relationship data.
Fetch Project Type Master
The CampaignManager requests the MDMSService to fetch the project type master data.
The MDMSService responds with the project type master.
Validate Resource Files
The CampaignManager queries the Database to check if the input resource files have already been validated.
The Database responds with the validation status of the files.
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.
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.
Deactivate Parent Campaign
The CampaignManager updates the Database to mark the parent campaign object as inactive.
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.
Process Resource Data
The CampaignManager processes the retrieved sheets to identify any resource data that needs to be created.
Facility Data Creation
The CampaignManager sends a request to the FacilityService to create facility data.
The FacilityService responds that the facilities have been created successfully.
Employee Data Creation
The CampaignManager sends a request to the HRMSService to create employee data.
The HRMSService responds that the employees have been created successfully.
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.
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.
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.
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.
Update Campaign Status
The CampaignManager updates the Database with the campaign update status.
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.
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.
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.
Hard Configuration (Process Flow Configuration)
Campaign Creation and Retry Mechanism Design
Full Mechanism Workflow
Main Campaign Creation Function
Retry Logic identifiers
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.
{
"Project Creation": "Facility Creation",
"Facility Creation": "User Creation",
"User Creation": "Facility Mapping",
"Facility Mapping": "User Mapping",
"User Mapping": "Product Mapping",
"Product Mapping": "End"
}
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.
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:
CampaignId
ProcessName
Status
2a7c9d91-e88b-4f54-8d88-4e70c08f85c1
Project Creation
Started
2a7c9d91-e88b-4f54-8d88-4e70c08f85c1
Facility Creation
Completed
2a7c9d91-e88b-4f54-8d88-4e70c08f85c1
Update Project Dates
Failed
2a7c9d91-e88b-4f54-8d88-4e70c08f85c1
Facility Mapping
Started
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).
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.
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 .
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:
The system queries the Status Tracking Table to identify the failed process.
The previously persisted CampaignObject state is retrieved.
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.
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.
createCampaignFunction 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.
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.
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.
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.
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.
id: A unique identifier for each record (Primary Key).
projectId: The ID of the project linked to the campaign.
campaignNumber: The campaign number associated with the project.
boundaryCode: A code representing the geographical boundary for the project.
isActive: A flag indicating whether the project is active (true) or inactive (false).
Steps
1. Delete Projects
Fetch all active projects (isActive = true) associated with the parentCampaignId(if present) from the campaignProject table.
Compare the boundaryCode of each project in the database with the boundaries listed in the target sheet.
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:
Compare the target data in the target sheet with the targets JSON stored in the database for that project.
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:
Use the Project Create API to create a new project with the data from the target sheet.
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.
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:
Search for active facilities in the campaignFacility table that match the facilityId and parentCampaignNumber.
If matching records are found, set isActive = false to deactivate those facilities.
2. Update Facility:
Logic:
Check for Boundary Change:
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.
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.
No other updates are needed beyond the boundary code change.
3. Create Facility:
Logic:
Check for New Facility in Sheet (Active Facility):
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.
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.
1. Delete User:
Logic:
For each user marked as inactive in the sheet:
Search for active users in the campaignUser table that match the userserviceid and parentCampaignNumber.
If matching records are found, set isActive = false to deactivate those users.
2. Update User:
Logic:
Check for Boundary Code Change:
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.
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):
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.
Steps:
Retrieve Data:
Fetch all projects from the campaignProject table for the current campaignNumber.
Fetch all facilities, both active and inactive, from the campaignFacility table.
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.
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.
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.
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.
Steps:
Retrieve Data:
Fetch all users from the campaignUser table for the current campaignNumber.
Fetch all active and inactive users from the system.
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.
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.
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.
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.
Steps:
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.
Generate Product-Project Combinations:
Create a list of combinations with each pvarId paired with the corresponding projectId.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
