Welcome! With the release of the Community Health Toolkit (CHT) reference app, we thought it was appropriate to write a collection of tutorials explaining what goes into a CHT configuration, and guide you step by step on how to build your own. Later, we’ll talk about the more complex situations. These tutorials are aimed at software developers who are looking to build applications inside the CHT. As such, there will be programming! It’s all very simple though, and so not to worry.
If you want to look at one we’ve prepared earlier, you can also take a look at our fully formed reference application (brief instructions are at the bottom of the page). It may be helpful to periodically refer to this as the tutorial continues if you’d like to self-learn and dig into more complicated scenarios.
Firstly, you should be interested in building or maintaining an application built using the CHT Core Framework. For more information about the CHT, take a look at our CHT overview. If you’re unsure if you’re interested in building an application with the CHT, this is where you should start.
We’re not going to delve into too much detail here—that’s more for Core Framework development. However, it’s probably worth going through and clarifying a few terms and technologies.
The Core Framework is an offline-first web application that works on mobile phones as well as larger devices like tablets and laptops. On Android phones it can also be loaded directly as an Android app. It uses CouchDB and PouchDB to store data on the user’s device, and synchronize that data to the server when internet is available.
Its primary use case is as a health-care tool for Community Health Workers (CHWs): CHWs create families and patients and create reports about them, directed by a tasks system and incentivised by a targets system, with the ultimate goal being improving a CHW’s ability to provide healthcare in under-served, disconnected communities.
The Core Framework is highly configurable: by default (since 3.7.0) we ship with the reference application configuration, a fully featured implementation of an ANC workflow.
Configurations typically contain:
- XForms, using an extension of the ODK XForms spec, written using XLSForms (spreadsheet-based form definitions). There are a few different types of forms:
- Forms for creating Contacts, such as Places (physical places like Facilities, or conceptual places like Families or Areas) or People (patients, but also CHWs, Nurses and other humans)
- Forms for creating Reports, which are the primary form of data entry available to users
- Rules that create Tasks for users to complete (e.g., if a CHW create a report stating a patient is ill, a task may be created to check up on that patient the next day)
- Rules that track Targets for users to aspire to (e.g. to follow up with sick patients in under 24 hours 90% of the time)
- Customisable information panels that will appear on a Contact’s (e.g. patient) profile page. These can show any information contained in reports for that Contact, e.g., how many times they have been pregnant, what immunisations they’ve had and so on
- Translations, white labelling, and much much more
There are also some other uses (stock monitoring, or as a hub for primarily SMS-based workflows, which in turn have their own complex configurations), and there is nothing inherently health-care related in its technology and feature-set, but the description above is what we’re going to focus on.
In this tutorial we’re going to set up a blank CHT configuration. By the end you will have an environment capable of building and deploying CHT configurations, with the Core Framework running on your local machine. We’ll be using this as a basis for later tutorials.
First, we’re going to install medic-conf, the tool used to compile and deploy CHT applications. Then, we’ll create a default project and walk through what each part is for. Finally, we’ll install the CHT core and deploy our (still very blank) configuration to it.
Note: this tutorial was written by someone using Linux. There may be differences for MacOS and Windows users. We’ll try to keep this guide up to date for all operating systems!
Once you’ve done this, in your terminal install medic-conf:
npm install -g medic-conf
You can confirm the installation went successfully by typing
medic-conf at your terminal:
Medic-conf can create a blank template project, so let’s do that!
mkdir cht-app-tutorials cd cht-app-tutorials medic-conf initialise-project-layout
This will create a new, blank project. Your directory structure should look this:
➜ cht-app-tutorials tree . ├── app_settings.json ├── contact-summary.js ├── forms │ ├── app │ ├── collect │ └── contact ├── resources ├── resources.json ├── targets.js ├── tasks.js └── translations
Let’s talk briefly about what each of these is for:
app_settings.jsonis a JSON file containing lots of different small pieces of configuration: everything from supported locales to roles and permissions.
forms/appsis where forms that generate “reports” (new pregnancy, visits etc) are stored
forms/collectis where forms that are specific to an application called Medic Collect are stored, don’t worry about this one!
forms/contactcontains forms that are used to create contacts: CHWs, facilities, patients etc
resources.jsonallows you to specify custom icons: the directory is where they are stored, and the JSON file is where you define a mapping between the name of the resource (such as
icon-person) and it’s filename in the
targets.jsoncontains configuration for targets
tasks.jsoncontains our declarative tasks config
translationsis the directory where you’d put custom translations, to either make changes to a language already supported in the CHT core, or to upload your own
We’ll go over these in far more detail in later tutorials. For now, let’s go through deploying your project, first by getting the Core Framework up and running.
There are a few different ways of getting the Core Framework running.
If you are just interested in Core Framework configurations, follow the easy installation guide.
If you followed the easy installation guide the framework should be available at https://localhost.
If you followed the developer setup guide the framework should be available at http://localhost:5988.
To login to the Core Framework, you’ll need a username and password. You would have come up with one by following either guide (traditionally: easy installation would give you
password, while the developer guide would give you
As you’re logging in as an administrative user you’re logged into the application settings page. In later tutorials we’ll go into more detail, but just understand that this is where some settings can be viewed / changed, and to access the main application click ‘Application’ in the top right.
Now that the framework is working we can use
medic-conf to deploy your blank project. In your configuration folder enter the following:
medic-conf --url=https://medic:password@localhost --accept-self-signed-certs # or, if you setup the Core Framework development environment medic-conf --local
Here we’re passing two parameters
--urlis the fully authenticated (note the username and password) location of the framework server. If you are running the framework via the developer instructions you can instead pass
--localwhich uses credentials from your environment variables
accept-self-signed-certstells medic-conf that it’s OK that the server’s certificate isn’t signed properly, which will be the case when using docker locally
We’re then not passing anything else. This is where you could pass in a collection of actions for
medic-conf to perform. As we’re not passing in any, this tells
medic-conf to perform the default collection of actions, which will compile and upload everything in your project each time.
Once you’ve run the above command it should complete quite quickly, with the message:
INFO All actions completed..
How can you tell from inside your http://localhost application? Well, since we don’t have any configuration yet, there is nothing to see!
If you want to get a bit of a head start and poke around with what’s possible, you can use the same
medic-conf command you used to deploy your own config to deploy the reference config:
- First, check out https://github.com/medic/cht-core using git.
- Navigate to
- Run your
medic-confcommand as you did above
This will do a lot more, and your framework will now contain configuration, forms, tasks and more.
To get back to your own empty configuration, just run
medic-conf in your new project directory again.
That’s all we’re going to cover this time. I know that feels like a lot of effort to make nothing much, but it’s laid a good foundation to start on. Stay tuned, as next time we’re going to get stuck into building some actual configuration.
We haven’t done too much yet, but I’ve also uploaded our current progress to a git repository, and will continue this for each subsequent tutorial. If you’re having trouble at any point you can refer to this repository and see where you should be ending up.
To ask questions, get clarifications or share your experiences, the community health forums are open for discussions.