Skip to end of metadata
Go to start of metadata

This is a WIP documentation.  If you find any part is not clear or not updated, please feel free to make changes. 


mUzima Developer Guide (version 0.01)

This document is a guide for mUzima developers. This document outlines the steps that need to be taken to set up the mUzima development environment.

mUzima is an android application that is used by health workers to enable them to collect patient information, medical data and submit forms to an OpenMRS server (as first use case).



Please ensure that you have the following installed:

  • Java 6. Ensure that the JAVA_HOME variable is configured.
  • Install apache-maven 3.0.5 and configure the M2_HOME variable.
  • Install Android 8,17, 18 and 21.(The project is developed using Android 21 but is tested out on four of these platforms.) Configure your ANDROID_HOME variable.
  • Install Android platform 14 through SDK manager. The actionbarsherlock is expecting this version to be present. Note that API 14 is obsolete, hence SDK manager will not show it in the download list. For it to be shown, click the checkbox named "Obsolete" in the SDK manager.
  • OpenMRS version 1.9.7.
  • Install Genymotion. It is an Android emulator for app testing and presentation.
  • You will need a GitHub ID and access to the mUzima repository at
    • Please request for this from your team.


Cloning repositories from GitHub

Clone the following repositories from GitHub

Building modules (omod)

Build the following maven projects in the same order as specified:

  1. search-api
  2. muzima-api
  3. openmrs-module-muzima
  4. openmrs-module-muzimaforms 
  5. openmrs-module-muzimaregistration
  6. muzima-android

Building the above maven projects will generate the build artifacts under :

  • muzima-android/target/muzima-android.apk
  • openmrs-module-muzima/omod/target/muzima-1.0.1-SNAPSHOT.omod
  • openmrs-module-muzimaforms/omod/target/muzimaforms-1.0.0.omod
  • openmrs-module-muzimaregistration/omod/target/muzimaregistration-1.0.1-SNAPSHOT.omod


Setup IntelliJ IDEA

To setup muzima-android using IntelliJ IDEA follow the steps below:

  1. Import the project into IDEA using File -> Open and selecting muzima-android/pom.xml.
  2. Once the project is imported, open Project Structure using File -> Project Structure. 
  3. Select muzima-android module and Dependencies tab
    1. Choose Module SDK as "Android API 21 Platform". If this option is not available then please click on New -> Android SDK, choose the Android SDK directory, click OK, select Build target as "Android 5.0.1" and Java SDK as "1.6"
    2. Change the Scope of module to "Provided"
  4. Select muzima-android module and Sources tab.
    1. Choose Language level as 6.
    2. Mark the following directories as "Sources"
      1. res
      2. src/main
    3. Mark the following directories as "Tests"
      1. src/test
  5. Select ~apklib-com.actionbarsherlock_actionbarsherlock_4.3.1 module and Dependencies tab.
    1. Choose Module SDK as Android API 14 Platform, it is not already chosen
    2. Mark the following directories as "Sources"
      1. res
      2. src/main

Setup in Android Device and OpenMRS Standalone

Setup in Android Device 

  • Install muzima-android.apk onto your emulator/device. This is the main mUzima app that will run on the device.

Setup in OpenMRS Standalone

Install modules in OpenMRS

  • Login to your OpenMRS instance.
  • Click on Administration link on the menu bar.
  • Navigate to modules
  • Click on Manage modules link
  • Click on Add or Upgrade module
  • Choose the browse button to locate the .omod from your machine or install the module from the openMRS hosted site by using the Install from Module Repository Section and type in the name of the module. Click on install.
  • mUzima also requires the latest Xforms module and latest Rest Web Services modules to be installed. These modules can be found in the OpenMRS module repository;Install from Module Repository (


User Account Creation on OpenMRS

  • Follow the instructions outlined in the Muzima User Guide to create a user account in OpenMRS. Assign the role of a System Developer to the user.


Cohort creation on OpenMRS

Create a few sample cohorts for testing purposes. To create a cohort on OpenMRS, follow the steps outlined below :

A cohort is a set of patients with specific characteristics. For example you could create a Cohort titled "Patients tested Positive for Malaria". A 

  • Step 1 : Locate Cohort Builder on the menu bar and click on it


  • Step 2 :Click on Patient Attributes Tab


  • Step 3 :Specify the parameters the cohort should take by filling the cohort builder form appropriately** Example: Gender=Any, Age between 20 and 40, And click on the save button icon as shown below:


  • Step 4 :A screen will pop up for you to enter the Name and Description of the cohort you created. Enter the fields with the appropriate name and description and click on save button


  • Step 4Check if the cohort was created by clicking on the Saved link next to the **Search **text

 Uploading forms onto OpenMRS.

The next step is to upload a few test forms onto OpenMRS.The muzima-form repository contains the forms that have to be uploaded onto OpenMRS.  To upload forms :

  • Step 1: Click on Administration link on the menu bar

  • Step 2: Navigate to Muzima Forms link.

  • Step 3: Click on Manage forms link.
  • Step 4: Use the Import feature to upload forms onto OpenMRS.

  • Step 5: Select the form that you would like to import. The form is located inside the muzima-form repository. Ensure that you import atleast one registration form uploaded in OpenMRS. Note: A form is recognised as a Registration form through tags. Hence after importing any registration form, click on the tag icon & enter "registration" & hit "Enter", so as to tag the form as registration form.
  • Step 6 : After selecting the form, validate and upload the form.
  • Step 7 :Fill in the fields as shown below. Make sure the Form Discriminator is set to “json-encounter".
  • Step 8 :The forms can then be tagged. Please see this video on “tagging muzima forms”.


Setting up Muzima on your device or emulator

Muzima an android platform application that renders html5 forms with build in logics and constrains the application has various prompts including text, number, location, and multimedia which can run in online and offline situations.


You will need an Android device to install mUzima. Or install an emulator if you don’t have one.

Using the Application

mUzima application will appear in your applications. Select it to launch the application.

First time login


For the first time you log in you will have three text prompts.

URL field: This the prompt for the URL to the server that the application will be communicating to.

Username: enter the valid username for the user to use the application. This user must be a valid provider on the server. 

Password: enter the password for the username given in the username prompt. 

After successful authentication you will be taken through a wizard to set up mUzima app.

Step 1: Download Cohort(s) Step1 requires you to select one or more cohorts from the list then click Next button


Step 2: Download Form(s) In this step, you are required to select one or more forms from the list and click Next button to start download. Upon clicking next a dialog notification box will pop up a message "Downloading Form Templates...." . You will need to select one registration form.


Step 3: Add Concept

For this step the user is allowed (not compulsory if user is unsure) add concepts which they would want observations to be downloaded and click on the next button.



Step 4: Check For BarCode Scanner This step is optional and you can skip if you do not want to use a barcode scanner.


After completing the above steps, you will be taken to the mUzima Clinic Dashboard page. The dashboard consists of:

Cohorts, Clients and Forms.

  • No labels

1 Comment

  1. Muzima_Developer_Guide.odt

    This is the first version of the guide that is intended to guide developers in setting up the development environment for Muzima.

    Note : This document is a work in progress. If you are a developer and find that you would like to add/modify the content of this document, please do so.