CHT User Management tool

How to use and configure a user management tool for a CHT project

The Community Health Toolkit (CHT) is highly configurable and can be customized to support multiple hierarchies and users in the health care system. The CHT user management tool is a user friendly web application that works with the CHT to decentralize the user management process to the subnational levels, increasing efficiency and accuracy. This guide highlights steps for setting up and configuring the user management tool. The guide has been tailored for specific CHT-supported national community health information systems. Partners and ministries of health are advised to customize the tool to fit their specific needs. The tool provides templates that can be downloaded and populated.

The user management tool has various features and fuctionalities including:

• Creation of single or bulk (many) users.
• Replacing of existing users
• Moving of an existing place
  • Users can access bulk user templates that they can populate.
  • One can validate the entries before the upload.
  • Download the user credentials upon upload.
• Validation of input for completeness and accuracy. The tool identifies errors that the can be corrected.

Configuring the CHT User Management tool

Implementation Steps

1. Clone the cht-user-management repository.

2. Create a new folder under src/config with your required instance eg. chis-znz

3. Within that new folder create a config.json file with the following parameters

   Property	Type	Description
   domains	Array	Controls the list of instances which the user can login to
   domains.friendly	string	Friendly name for the instance (eg. “Migori”)
   domains.domain	string	Hostname for the instance (eg. “migori-echis.health.go.ke”)
   domains.useHttp	boolean	Whether to make an insecure connection (http) to the hostname (defaults to false)
   contact_types	Array	One element for each type of user which can be created by the system
   contact_types.name	string	The name of the contact_type as it appears in the app’s base_settings.json
   contact_types.friendly	string	Friendly name of the contact type
   contact_types.contact_type	string	The contact_type of the primary contact. As defined in base_settings.json
   contact_types.contact_friendly	string	Friendly name of the primary contact type
   contact_types.user_role	string[]	A list of allowed user roles. If only one is provided, it will be used by default.
   contact_types.username_from_place	boolean	When true, the username is generated from the place’s name. When false, the username is generated from the primary contact’s name. Default is false.
   contact_types.hierarchy	Array	Defines how this contact_type is connected into the hierarchy. An element with level:1 (parent) is required and additional elements can be provided to support disambiguation. See ConfigProperty.
   contact_types.hierarchy.level	integer	The hierarchy element with level:1 is the parent, level:3 is the great grandparent.
   contact_types.replacement_property	Property	Defines how this contact_type is described when being replaced. The property_name is always replacement. See ConfigProperty.
   contact_types.place_properties	Array	Defines the attributes which are collected and set on the user’s created place. See ConfigProperty.
   contact_types.contact_properties	Array	Defines the attributes which are collected and set on the user’s primary contact doc. See ConfigProperty.
   contact_types.deactivate_users_on_replace	boolean	Controls what should happen to the defunct contact and user documents when a user is replaced. When false, the contact and user account will be deleted. When true, the contact will be unaltered and the user account will be assigned the role deactivated. This allows for account restoration.
   logoBase64	Image in base64	Logo image for your project

4. Add reference to your configuration folder(that you have just added above) in src/config/config-factory.ts. For example import znzConfig from './chis-znz'

5. Configure the config.json file.

ConfigProperty

The ConfigProperty is a data structure used several times within the config.json file and defines a property on an object. The ConfigProperty include:

ConfigPropertyType

The ConfigPropertyType defines a property’s validation rules and auto-formatting rules. The optional parameter information alters the behavior of the ConfigPropertyType.

The Generated ConfigPropertyType

ContactProperties with type: "generated" use the LiquidJS template engine to populate a property with data. Here is an example of some configuration properties which use "type": "generated":

{
  "place_properties": [
    {
      "friendly_name": "CHP Area Name",
      "property_name": "name",
      "type": "generated",
      "parameter": "{{ contact.name }}'s Area",
      "required": true
    }
  ],
  "contact_properties": [
    {
      "friendly_name": "CHP Name",
      "property_name": "name",
      "type": "name",
      "required": true
    }
  ]
}

The user will be prompted to input the contact’s name (CHP Name). The user is not prompted to input the place’s name (CHP Area Name) because the place’s name will automatically be assigned a value. In this example, if the user puts john as the contact’s name, then the place will be named John's Area.

The data that is passed to the template is consistent with the properties defined in your configuration.

Deployment

This tool is available via Docker by running docker compose up. Set the Environment Variables.

Development

Create an environment file by cp env.example .env. Change INTERFACE to 127.0.0.1 and otherwise see Environment Variables for more info.

Then run:

npm run dev

or

npm run build
npm start

Environment Variables

The env.example file has example values. Here’s what they mean:

Publishing new docker images

Docker images are hosted on AWS’s Elastic Container Registry (ECR). To publish a new version:

1. Update the version string in the package.json.
2. Submit a PR and have it merged to main.
3. Existing CI will push an image to ECR.