The document is a guide to the various configuration options available in the HCM Console. Proper configuration is crucial for optimising performance, ensuring security, and customising the user experience to meet specific needs. This document is designed to help system administrators, developers, and end-users understand and implement these configurations effectively. To learn more about HCM Service/App Configuration, Click here.
Scope
This guide covers all aspects of application configuration, including global settings, module-specific options, and environment-specific adjustments. It addresses configuration methods such as through files, environment variables, and command-line arguments. Additionally, it includes advanced configuration topics like custom scripting, API integrations, and feature flag management.
Audience
The primary audience for this document includes:
System Administrators: Responsible for setting up and maintaining the application in various environments.
Developers: Need to understand configuration options for development, testing, and deployment.
End-Users: They may require guidance on configuring user-specific settings via the user interface.
Structure
The document is organised into the following sections:
Configuration Types: Detailed descriptions of global, module-specific, and environment-specific settings.
Configuration Methods: Instructions on how to apply configurations using different methods.
Common Configuration Options: Examples of frequently used settings, including database connections, authentication, logging, and UI adjustments.
Advanced Configurations: Information on extending the application's functionality through custom scripts, plugins, and integrations.
Best Practices: Recommendations for managing configurations securely and efficiently.
Troubleshooting: Solutions to common configuration problems and tips for debugging issues.
Appendices: Additional resources, including a glossary and references for further reading.
By following the guidance provided in this document, users can ensure that the application is configured correctly to meet their operational needs, enhancing both performance and user satisfaction.
This overview section sets the stage for the rest of the document by clearly outlining its purpose, scope, intended audience, and overall structure.
Boundary Master Setup
The Boundary serves as the primary master data for a campaign and can be configured using the screen provided below. To upload a boundary into the database, a hierarchy is required. If the necessary hierarchy is not available in the existing list, it can be created using the designated screen. Hierarchies of any level can be established.
An example of a hierarchy structure is as follows, with the hierarchy type set to ADMIN:
HierarchyType22
Country -> Province -> District -> AdministrativePost -> Locality -> Village
First, navigate to the MDMS data configuration page with moduleName = HCM-ADMIN-CONSOLE and masterName = HierarchySchema and configure the console and campaign as the hierarchy you want to have (Ex. HierarchyTest22)
Keep hierarchy, lowest level, and split boundaries on column same for console and campaign and name should be same as defined while creating hierarchy. (Example: Here we have AdministrativePost and Locality)
Now navigate to the boundary management page and continue with boundary creation.
After creating the hierarchy we can download the template and add data to it.
In this screen, the user needs to download the template containing boundary levels in the headers according to the hierarchy. The user needs to fill that template in a specific format. A dummy template is attached for reference.
All the boundaries are localised to the below localisation module:
hcm-boundary-${BOUNDARY_HIERARCHY_TYPE} // hierarchy type should be according to the selected hierarchy and the module has everything in lowercase.
The system automatically generates a default localization for all boundary codes during the boundary data upload, using the same language/locale as specified at the time of upload.
The data provided above is based on the hierarchy created above. Any changes in the levels will change the headers respectively and data will have to be filled accordingly.
MDMS Data Setup
1. Hierarchy Configuration (Newly added in 0.3)
This schema contains different hierarchy types and their lowest hierarchy.
Based on isActive, choose which type of hierarchy the campaign will be created. This config defines the boundary hierarchy on which a campaign can be created. All the boundary levels are coming according to the hierarchy configured.
The lowestHierarchy will represent the lowest level hierarchy to be displayed in the boundary selection screen while creating a campaign.
The SplitBoundariesOn defines the hierarchy level for dividing the target sheet tabs.
The consolidateUsersAt the function is utilised during microplan integration, ensuring user sheets are populated
Users can change the lowest hierarchy but it is advised to keep till the mentioned level because a lot of boundaries will increase the validations and the load on the server to load all the boundaries
Based on this schema, validations happen in Excel from both the UI and the backend for the different uploads; there is one schema with the title according to the uploaded type.
If a user wants to change anything in the Excel validation, then the data of the schema needs to be updated.
Schema properties:
IsRequired: True for all those columns that are mandatory to be filled
orderNumber: Position where that column will be present
title: Set according to the type of upload
enum: Defines a set of allowed values for a specific property, ensuring that only predefined, valid options can be assigned to that property.
numberProperties: Numeric fields with specific characteristics such as uniqueness, required status, and value constraints like minimum and maximum limits.
string properties: Text fields with specific characteristics such as required status, uniqueness, and constraints on length and content.
Users can change the following validations from Excel using this schema such as:
User Validations -
Roles - Roles to be validated can be added or deleted in the schema.
Employment Type - This can be changed from the enum.
All the headers are mandatory they can be adjusted according to the requirement, just by changing isRequired to true/false.
Facility Validations -
Facility Type - More types can be added or deleted.
Facility Status - More requirements can be added or deleted.
Facility Usage - More requirements can be added or deleted.
Capacity - Minimum and maximum can be changed.
Facility Name - Maximum length and minimum length can be changed.
All the headers are mandatory they can be adjusted according to the requirement, just by changing isRequired to true/false.
Target Validation -
Target - Minimum and maximum validations can be changed.
Boundary code and target header are mandatory.
It also has a field called campaign type, so based on the campaign type boundary target updated, any new target column can be introduced.
while introducing a new campaign/project type this admin schema needs to be added for that type.
3. Attributes Configuration
It includes a list of attribute configurations, each identified by a unique key and specified by a code and an internationalisation key (i18nKey). The attributes listed are 'Age', 'Height', 'Weight', and 'Gender', which can be used in campaigns to capture relevant information.
The attribute dropdown is populated from this schema. If the user wants to add or delete attribute options, this schema is helpful.
This schema configures the base time interval after which the search API is called following a file upload. The search API checks the validation status of the uploaded file. The frequency of the API calls is determined by the data present, with the time interval calculated as the base time multiplied by the number of fields in the sheet, constrained by both the minimum base time and the maxTime stated in the schema. The search API will continue to be called repeatedly until a successful or failed response is received.
TimelineRefetch is also added to call the getProcessAPI of the timeline after a certain interval of time.
It has the by default mail ID to contact the L1 or implementation team if the hierarchy a user wants is not present. The mail ID can be configured from this schema
mailConfig Sample MDMS Data
[
{
"mailId": "L1team@email.com"
}
]
8. Operator Configuration
This schema contains all the operator options which are required for the attributes.
This schema displays the options to add the resource type if the resource a user wants is not present in the options. The resource added here will be present in the resources dropdown, so prevent adding any junk data.
This schema is used to display the info message in the UI and the read-me sheet in the downloaded template. It configures according to the upload type which shows the instructions to a user on how to fill the template. These codes are localised according to the message.
Below is an example of how data is entered into the read-me schema for the headers and their description:
When type is null, it indicates that the description is just plain text.
point:
When type is set to point, it likely means that the description should be displayed as a bullet point or list item.
step:
When type is set to step, it suggests that the description is part of a sequence of steps.
subdescriptions: to show the sub-descriptions in the point.
13. Date with boundary
This config is used when we want to update the dates with or without the selected boundaries.
If the flag is false, then by default it updates the dates at the country level. If the user wants to update the dates at the lower boundary levels, then make the flag true.
This configuration is now used in the place of delivery configuration.
This is used to store all the pre-required conditions for the delivery conditions screens.
Master Name: HCM-PROJECT-TYPES
ModuleName: projectTypes
ProjectTypes MDMS Data
{
"id": "ea1bb2e7-06d8-4fe4-ba1e-f4a6363a21be",
"name": "configuration for Multi Round Campaigns",
"code": "MR-DN",
"group": "MALARIA",
"type": "multiround",
"beneficiaryType": "INDIVIDUAL",
"eligibilityCriteria": [
"All households having members under the age of 18 are eligible.",
"Prison inmates are eligible."
],
"taskProcedure": [
"1 bednet is to be distributed per 2 household members.",
"If there are 4 household members, 2 bednets should be distributed.",
"If there are 5 household members, 3 bednets should be distributed."
],
"resources": [
{
"productVariantId": "PVAR-2024-05-09-000331",
"isBaseUnitVariant": false,
"name": "SP 500mg"
},
{
"productVariantId": "PVAR-2024-05-09-000332",
"isBaseUnitVariant": true,
"name": "SP 250mg"
}
],
"observationStrategy": "DOT1",
"validMinAge": 3,
"validMaxAge": 64,
"cycles": [
{
"mandatoryWaitSinceLastCycleInDays": null,
"startDate": 1714329000000,
"endDate": 1715279400000,
"id": 1,
"deliveries": [
{
"id": 1,
"deliveryStrategy": "DIRECT",
"mandatoryWaitSinceLastDeliveryInDays": null,
"doseCriteria": [
{
"condition": "3<=age<11",
"ProductVariants": [
{
"productVariantId": "PVAR-2024-05-09-000331", // should be set according to the environment
"quantity": 1,
"name": "SP 500mg"
},
]
},
]
},
]
},
]
},
This is the sample data for the project type - MR-DN
Explanation for the MDMS Data
Project Types: Three main project types (LLIN-mz, MR-DN, and IRS-mz) with unique configurations.
Cycles and Deliveries:
Each project type contains cycles, and each cycle contains multiple deliveries.
Deliveries include details such as deliveryStrategy, doseCriteria, and ProductVariants.
Resources: A list of resources specific to each project type.
Eligibility Criteria: Contains a list of conditions for each project type.
Other Configurations:
attrAddDisable, deliveryAddDisable, and similar attributes determine UI behavior.
Requirements
Mandatory to set product variant ID according to the environment.
"ProductVariants": [
{
"productVariantId": "PVAR-2024-05-09-000331", // should be set according to the environment
"quantity": 1,
"name": "SP 500mg"
},
]
2. Roles for Checklist
This Master data is used to show the dropdown of roles in the checklist screens
This Master is utilized for Microplan Data fetching. Here, "type" refers to the data template that needs to be filled. "To" and "from" pertain to Microplan data, and while populating campaign data, various filter conditions, such as "includes" or "equals," can be applied.
