Configuring the CHT User Management tool

How to configure a web-based user management tool for your CHT project.

The user management tool is a user-friendly web application used within CHT projects to manage users.

Required Resources

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

    domainsArrayControls the list of instances which the user can login to
    domains.friendlystringFriendly name for the instance (eg. “Migori”)
    domains.domainstringHostname for the instance (eg. “”)
    domains.useHttpbooleanWhether to make an insecure connection (http) to the hostname (defaults to false)
    contact_typesArrayOne element for each type of user which can be created by the system
    contact_types.namestringThe name of the contact_type as it appears in the app’s base_settings.json
    contact_types.friendlystringFriendly name of the contact type
    contact_types.contact_typestringThe contact_type of the primary contact. As defined in base_settings.json
    contact_types.contact_friendlystringFriendly name of the primary contact type
    contact_types.user_rolestring[]A list of allowed user roles. If only one is provided, it will be used by default.
    contact_types.username_from_placebooleanWhen 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.hierarchyArrayDefines 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.levelintegerThe hierarchy element with level:1 is the parent, level:3 is the great grandparent.
    contact_types.replacement_propertyPropertyDefines how this contact_type is described when being replaced. The property_name is always replacement. See ConfigProperty.
    contact_types.place_propertiesArrayDefines the attributes which are collected and set on the user’s created place. See ConfigProperty.
    contact_types.contact_propertiesArrayDefines the attributes which are collected and set on the user’s primary contact doc. See ConfigProperty.
    contact_types.deactivate_users_on_replacebooleanControls 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.
    logoBase64Image in base64Logo 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.


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

friendly_namestringDefines how this data will be labeled in CSV files and throughout the user experience.
property_namestringDefines how the value will be stored on the object.
typeConfigPropertyTypeDefines the validation rules, and auto-formatting rules. See ConfigPropertyType.
parameteranySee ConfigPropertyType.
requiredbooleanTrue if the object should not exist without this information.


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

TypeValidation RulesAuto Formatting RulesValidatorParameter
stringMust be definedRemoves double whitespaces, leading or trailing whitespaces, and any character which is not alphanumeric or ()\-'None
nameMust be definedSame as string + title case + parameter behaviorOne or more regexes which are removed from the value when matched (eg. "parameter": ["\\sCHU"] will format this CHU into This)
regexMust match the regex captured by parameterSame as stringA regex which must be matched to pass validation (eg. "parameter": "^\\d{6}$" will accept only 6 digit numbers)
phoneA valid phone number for the specified localityAuto formatting provided by libphonenumberTwo letter country code specifying the locality of phone number (eg. "parameter": "KE")
generatedNone. No user inputs.Uses LiquidJS templates to generate dataNoneDetails
select_oneSingle choice from a list of optionsSame as stringNoneDictionary where the keys are the option values and the values are the corresponding labels
select_multipleMultiple choice from a list of optionsSame as stringNoneSame as select_one

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": "{{ }}'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.

placeHas the attributes from place_properties.property_name
contactHas the attributes from contact_properties.property_name
lineageHas the attributes from hierarchy.property_name


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


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

Then run:

npm run dev


npm run build
npm start

Environment Variables

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

CONFIG_NAMEName of the configuration to usechis-ke
EXTERNAL_PORTPort to use in docker compose when starting the web server3000
PORTFor localhost development environment3000
COOKIE_PRIVATE_KEYA string used to two-way encryption of cookies. Production values need to be a secret. Suggest uuidgen to generate589a7f23-5bb2-4b77-ac78-f202b9b6d5e3
INTERFACEInterface to bind to. Leave as ‘’ for prod, suggest ‘’ for development127.0.0.1
CHT_DEV_URL_PORTCHT instance when in NODE_ENV===dev. Needs URL and
CHT_DEV_HTTP‘false’ for http ’true’ for httpsfalse

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.

CHT Applications > Tutorials > Contacts + Users 1

Creating and editing contacts and users in the CHT UI

CHT Applications > Quick Guides > Data > Bulk Load Users

How to create users in bulk