In the Campaign Details section, there are 4 screens:

• Campaign Type

• Campaign Name

• Campaign Dates

• Campaign Details Summary

1. Campaign Type

This is the first screen when the user clicks on "set-up campaign". In this screen, the user can select the campaign type, and the beneficiary will be prepopulated from the MDMS. This field is mandatory to set up a campaign.

Here, the dropdown will show the list of campaign types in the MDMS. We will fetch the MDMS data from, for more information you can check on configurations from the link here

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

2. Campaign Name

This screen comes after the campaign type. This step is crucial for saving your campaign as a draft, as the name serves as a unique identifier. After clicking on 'Next', the name will be saved and the user can check from the draft.

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

3. Campaign Dates

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

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

4. Summary

This screen will show the summary of the campaign details screen

Api Details

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

Click on the following links to learn more:

• Campaign Details

• Delivery Details

• Boundary Details

• Resource Upload Details

• Setup and Implementation of Campaign

• Summary

In this step, the user will encounter 2 screens:

• Boundary Details

• Boundary Details Summary

Boundary Details

This screen allows users to select the boundaries according to their requirements.

The working of this screen is as follows:

We will fetch the boundary data according to the hierarchy saved in the MDMS.

The file where data is fetched - https://github.com/egovernments/DIGIT-Frontend/blob/console/health/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/Module.js

The hierarchy structure and the lowest boundary will be fetched from the MDMS

HCM-ADMIN-CONSOLE.HierarchySchema

For more information on the master data can be referred here

This screen will be shown using the component

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

Which internally calls the - Selecting boundary component

Validation: The user must select boundaries till the lowest level. If the parent boundary is selected, then the user should select at least one of its child.

Boundary Details Summary

This screen displays all the boundaries selected in the previous step.

Localisation Details

Boundary localisation for this screen happens by using the combination of hierarchy type and boundary type

 {t((hierarchyType + "_" +boundaryType).toUpperCase())}

It should be in this format.

API Details

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

• Cycles & Deliveries

• Delivery Screen

• Summary

1. Cycle Configuration Screen

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

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

Link:

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

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

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

2. Delivery Screen

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

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

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

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

Reference files:

Select or Create a Product

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

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

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

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

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

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

3. Summary

This screen will show the values the user has added in the cycle configuration screen and delivery screen.

Guide on Setting Up Delivery Configuration for the screen.

This MDMS schema is used to fetch the details for every product type, to convert the data to the required format used by the screen, we are writing the util.

The following is the structure for the delivery configuration:

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

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

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

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

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

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

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

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

for name: product/v1/_search

for variant: product/variant/v1/_search

FilePath:

Reference links:

MDMS:

HOOKS:

New changes

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

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

deliveryConfig: It will contain the default data of all deliveries.

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

deliveryType: Default value of delivery type.

API Details

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

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

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

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

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

API Details:

For draft status only:

The logic for the step-by-step screens, stepper functionality, storing data in localStorage, creating/updating campaigns, and restructuring API data back into localStorage is all managed within SetupCampaign.js.

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

All screens are present in the given configuration. Link: https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/configs/CampaignConfig.js

In the configuration:

• stepCount represents the step number. Multiple configuration objects can share the same stepCount.

• skipAPICall: If this is set to true, the API call for the screen is skipped.

• sessionData: Local storage data is passed in custom props, allowing for custom logic to be added to the screens as needed.

export const CampaignConfig = (totalFormData, dataParams) => {
  return [
    {
      form: [
        {
          stepCount: "1",
          key: "1",
          name: "HCM_CAMPAIGN_TYPE",
          body: [
            {
              isMandatory: false,
              key: "projectType",
              type: "component",
              skipAPICall: true,
              component: "CampaignSelection",
              withoutLabel: true,
              disable: false,
              customProps: {
                module: "HCM",
                sessionData: totalFormData,
              },
              populators: {
                name: "projectType",
              },
            },
          ],
        },
        ``````

In setup campaign, we have functions to perform specific logic:

• loopAndReturn: This function takes the delivery rule conditions coming from API response and restructure the data in local storage format.

• cycleDataRemap: This function takes the delivery rules data coming from API response and return array of object of start date and end date based on cycles.

• reverseDeliveryRemap: This function takes the deliveryConditions from the API response and return the structure of delivery data.

• groupByTypeRemap: This function creates the local structure of boundaries.

• updateUrlParams: This function is used to update the URL.

New Campaign & Implementing Local Storage

• In a new campaign, we update the total form when a user clicks on next after entering the data.

• After updating the total form data, we store the data in localStorage.

• We also call the API to draft the data in case a user wants to come back and resume the campaign.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L545

Draft Campaign & Data Fetching

• When a user clicks on the draft campaign, he/she can fetch campaign data from the response.

• After getting a response, one can restructure the data in screen format and store it in the local storage.

• After updating, the user is redirected to the last screen where additional details are stored in response.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L327

Stepper

• Based on screens, a user can filter the configuration and show the stepper based on the configuration.

• Refer to the following link:

https://github.com/egovernments/DIGIT-Frontend/blob/campaign/micro-ui/web/micro-ui-internals/packages/modules/campaign-manager/src/pages/employee/SetupCampaign.js#L1159

New Changes:

As part of v0.3, we have introduced a new vertical stepper and summary screens for all the steps.

The vertical steppers are clickable and the user can navigate between the screens using the steppers.

Summary screens will show all the details entered by the user in that step.

Overview

The "Setup Campaign" feature facilitates the creation of a campaign using an approved microplan. It ensures that only authorized users can initiate the setup process, generates required campaign data, and integrates with external APIs to fetch user, facility, and target data.

. User Role Validation

• Role Required: MICROPLAN_CAMPAIGN_INTEGRATOR

• Validation Logic:

  • Only users with the above role can select an approved microplan to initiate the campaign setup.

  • If the user lacks the role, access to the feature is denied with a proper error message.

Campaign Object Creation

• Input: Approved microplan object.

• Steps:

  1. Extract the base campaign object from the selected microplan.

  2. Create a new campaign object by cloning the base campaign object with the following updates:

     • Add unique identifiers (campaignId, createdBy).

     • Set the campaign status to draft.

  3. Save the new campaign object to the backend.

Generate Empty Templates

• Trigger: After updating the campaign object with selected boundaries, it gets auto-generated from Backend

• Steps:

  1. Automatically generate empty templates for the campaign, including:

     • User assignments.

     • Facility data placeholders.

     • Target data placeholders.

Fetch Data from Microplan API

• API Endpoint: project-factory/v1/project-type/fetch-from-microplan

• Steps:

  1. Call the Microplan API to fetch:

     • User data.

     • Facility data.

     • Target data.

  2. Populate the empty templates with the fetched data.

  3. Save the updated templates back to the backend.

Campaign Search Polling

• Purpose: Monitor the progress of data population and transition to the next step once completed.

• Steps:

  1. The UI triggers a periodic call to the campaignSearch endpoint:

     • API Endpoint: /campaign-search

     • Parameters: campaignId.

  2. Check the status of the campaign:

     • If Completed:

       • Navigate the user to the Setup Campaign page.

     • If In Progress:

       • Re-trigger the data fetch from Microplan API to ensure completion.

       • Continue polling.

Navigation to "Setup Campaign" Page.

• Steps:

  1. Transition the user to the Setup Campaign page.

  2. Pass the necessary campaign data as route parameters or via state management.

API Details:

The resource upload details consists of 3 types of uploads:

• Upload Target Data

• Facility Upload

• User Upload

• Upload Summary

1. Upload Target Data

This screen will come after a user selects the boundaries.

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

2. Upload Facility Data

This screen will come after the target upload screen.

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

3. Upload User Data

This screen will appear after the facility details screen.

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

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

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

HCM_CAMPAIGN_MANAGER_UPLOAD_ID

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

4. Summary

This screen displays all the files which were uploaded in the previous screens, Validation in this screen -

All the 3 files are mandatory to upload in this step otherwise the user is not allowed to move to the next step.

Schema Validation

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

Schema Module = adminSchema Below is the admin schema-

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

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

• Facility Type can only be Warehouse/Health Facility

• Facility Name can only be string

• Facility Status can only be Temporary or Permanent etc.

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

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

targetValue <= 0 || targetValue >= 100000000

Validation API Call:

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

For more information on this schema, you can refer to:

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

Reference Links:

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

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

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

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

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

API Details

New Features:

A new pop-up has been added which displays the option to download the template in all three upload screens.

Use Case:

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

For IRS to be displayed as the campaign type , initially it needs to added in the MDMS. Master name: projectTypes Module name: "HCM-PROJECT-TYPES" https://github.com/egovernments/egov-mdms-data/blob/UNIFIED-DEV/data/mz/health/project-types.json

Changes in delivery details:

The delivery configuration in the MDMS needs to be updated. The desired properties will show the attributes, operator, and value.

For the IRS campaign type, the number of cycles and the number of deliveries will not be editable.

To make the cycle and deliveries not editable, we need to pass one flag in the delivery configuration.

 "IsDisable": true

The delivery conditions page will be shown like this in which values will come from the MDMS.

Master name: HOUSE_STRUCTURE_TYPES

Module name: HCM

For the target templates to be generated dynamically, data needs to be added in the adminSchema.

 "schemaCode": "HCM-ADMIN-CONSOLE.adminSchema"

{
                "title": "boundary",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "numberProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_IRS_1",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at the Selected Boundary Level",
                            "orderNumber": 2
                        },
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_IRS_2",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at the Selected Boundary Level",
                            "orderNumber": 3
                        }
                    ],
                    "stringProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_BOUNDARY_CODE",
                            "type": "string",
                            "isRequired": true,
                            "description": "Boundary Code",
                            "orderNumber": 1,
                            "freezeColumn": true
                        }
                    ]
                },
                "campaignType": "IRS-mz"
            },
            "isActive": true,
            "auditDetails": {
                "createdBy": "bfab6822-ec28-40f0-aef1-efd1cda8fcd5",
                "lastModifiedBy": "bfab6822-ec28-40f0-aef1-efd1cda8fcd5",
                "createdTime": 1722846607391,
                "lastModifiedTime": 1722846607391
            }
        },
        {
            "id": "87d17bf5-b0dd-4796-a36f-32e466c47569",
            "tenantId": "mz",
            "schemaCode": "HCM-ADMIN-CONSOLE.adminSchema",
            "uniqueIdentifier": "boundaryWithTarget.IRS-mz",
            "data": {
                "title": "boundaryWithTarget",
                "$schema": "http://json-schema.org/draft-07/schema#",
                "properties": {
                    "numberProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_IRS_1",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at the Selected Boundary Level",
                            "orderNumber": 2
                        },
                        {
                            "name": "HCM_ADMIN_CONSOLE_TARGET_IRS_2",
                            "type": "number",
                            "isRequired": true,
                            "description": "Target at the Selected Boundary Level",
                            "orderNumber": 3
                        }
                    ],
                    "stringProperties": [
                        {
                            "name": "HCM_ADMIN_CONSOLE_BOUNDARY_CODE",
                            "type": "string",
                            "isRequired": true,
                            "description": "Boundary Code",
                            "orderNumber": 1,
                            "freezeColumn": true
                        }
                    ]
                },
                "campaignType": "IRS-mz"
            },
            "isActive": true,
            "auditDetails": {
                "createdBy": "bfab6822-ec28-40f0-aef1-efd1cda8fcd5",
                "lastModifiedBy": "bfab6822-ec28-40f0-aef1-efd1cda8fcd5",
                "createdTime": 1722846554092,
                "lastModifiedTime": 1722846554092
            }
        }