CHT User Management Tool

Goal

A simple user-facing web application using CHT's API that supports user management needs for CHT projects at scale.

eCHIS Kenya Training Videos

• Creating a New User in CHIS User Management Tool
• Replacing an Existing Community Health Promoter using the User Management Tool
• How to Replace a CHA Using the User Management Tool
• Bulk Uploading Users with the User Management Tool
• Moving an Existing Place with the User Management Tool
• CHIS Kenya - CHA Changing a Phone Number for a CHP
• How to Bulk Replace CHPs with CHIS User Management Tool
• How to Resolve eCHIS-KE Logic Error

For Developers:

• Running CHT User Management Tool with a Local CHT Instance

Using this tool with your CHT Project

To use the User Management Tool with your CHT project, you'll need to create a new project configuration folder and follow some deployment steps.

Configuration

1. Create a new folder in src/config.
2. Create a config.json file and specify the values as defined below.

3. Add reference to your configuration folder in src/config/config-factory.ts.

   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.
   contact_types.hint	string	Provide a brief hint or description to clarify the expected input for the property.
   logoBase64	Image in base64	Logo image for your project

ConfigProperty

The ConfigProperty is a data structure used several times each config.json file. At a high level, a ConfigProperty defines a property on an object.

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

NodeJs with reloading code

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

If you don't have redis running locally, you can start it with:

docker compose -f docker-compose.redis.yml up -d

Then run:

npm run dev

or

npm run build
npm start

Docker with static code

To build the Docker images and run Docker Compose locally, run:

./docker-local-setup.sh build

If you just need to run the development environment without rebuilding the images run:

./docker-local-setup.sh

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.