Skip to end of metadata
Go to start of metadata


mUzima is a mobile application running on Android that deploys and runs HTML forms. These HTML forms are currently 'created by hand' and do not support the inclusion of multimedia content such as images and videos.

This document proposes a model for using a designer to create these HTML forms (that include multimedia content), creating and packaging all files that is logically attached to an HTML form, deploying the form packages to a remote server,  loading these form packages from the remote server to the mobile devices and using these forms on the android devices to display the embedded images and collect images using the form. 

Step 1. Creating forms 

HTML forms (with or without multimedia content) intended for deployment in mUzima are proposed to be created using the following steps:

  1. A HTML form is created. This acts as the view component and contains all the input fields to be displayed and used for collecting data. This should be stored in a folder called 'html'.
  2. All logic is contained in separate javascript files. These javascript files are stored in a folder called 'js'. This logic may be 
    1. View Logic - where HTML input fields or divs are displayed, hidden or disabled based on a user selection or form state 
    2. Skip Logic - where based on a certain selection of a form field, the user is redirected to alternative sections of the forms fields 
  3. Additional styling is contained in separate css files and referenced in the HTML file. These css files should be stored in a folder titled 'css'
  4. An xml file called 'form.xml' stored in the xml folder. 
  5. All multimedia content should be stored in a folder called 'multimedia'. Two types of multimedia content should be stored i.e. images and videos. Within this folder, there should be the following folders 
    1. A folder entitled 'collected' for storing multimedia content collected using the form. 
    2. A folder entitled 'embedded' for storing multimedia content that has been packaged with the form.

Within each of these 2 folders there should be 2 folders entitled 'images' and 'videos' to store their respective types of media.


The form.xml

This xml file stores meta data about the form and must include the following information 

  1. logical name of the form (this is what is publicly displayed as the publicly referenced) 
  2. author (name of the creator of the form)
  3. created_date (date when the form was created)
  4. modification_date (latest timestamp when the form was modified)
  5. version (version of the source)
  6. formId (a randomly generated 32 char string uniquely identifying the form)
  7. description (this is a short description of the form)

The root element for this xml file will be form. For example:

<!--xml charset="utf-8">
<name>Registration form</name>
<author>dave loper</author>
<descriptio>This is the registration form used to capture patient data</description>

An editor/designer used for creating mUzima forms should be able to generate this file and populate it automatically based partially on fields entered by a user. 

Generating the formId

The form id uniquely identifies a form. While all information about a form may be altered, initial/alternative instances of the form may be identified using this id. The form id generated is a type 4 UUID (universally unique Identifier) as specified in IETF RFC 4122 (

This form id will have a structure similar to


Generation of a UUID that is compliant with RFC 4122 is supported in most programming languages.

Using Java 

Long uuid = UUID.randomUUID();

Using python

>>> import uuid 
>>> uuid.uuid1() 

or using the online GUID generator available at

An editor/designer used for creating mUzima forms should be able to generate the form id and append it to the form.xml file.

side note: Possible functionality for a mUzima forms designer 

In the long term, development of mUzima HTML forms is recommended to be done using a designer. In addition to automatically generating form.xml and the form Id, this designer may have the following functionality: 

  1. Development of forms using a pallete or menu that has the following functionalities
    1. Allow addition of UI components 
    2. Allow addition of skip or view logic to the form components
    3. Management of multimedia content to a form under design 
    4. Addition of minimal validation functionality to a form 
  2. Real-time preview of form under development 
  3. Ability to view generated HTML/js/css 
  4. Ability to view payload that will be generated from the forms 
  5. Packaging of forms 
  6. Deployment of forms to remote storage


A mUzima forms designer may also have other functionality such as being able to compress multimedia content (since this kind of content may be delivered using a wireless network with significant latency), and a minimal image management tools with functionality that allows a user to perform basic image manipulations such as cropping.

Step 2: Packaging the forms 

Once a mUzima has been developed and all relevant dependent files are stored in respective folders, these files should be packaged to a .zip file. The file name for the zip file might have a .muz extension to assist programs and Operating systems to correctly map the files with an editor installed on the client. 

This zip file with the HTML form and all dependencies may then be uploaded to a remote server waiting downloading to a mUzima client. 

Step 3: Deploying the mUzima form zip to a mUzima device 

A mUzima form zip deployed to a remote (but publicly accessible server) may be downloaded by a mUzima Android client. Once the mUzima client downloads the form, the following steps are processed to extract and store the form and its dependencies onto the mUzima device:

  1. mUzima checks to ensure that the zip file has a form.xml file in an xml folder and that the xml file has a root element <form>
  2. mUzima then checks the formId and version of the downloaded package and compares it to its internal storage with a list of all forms stored.
    1. If another form has been deployed on the mUzima client with the same formId and version, then this is a replacement form. mUzima then prompts the user to allow a form replacement to occur
    2. If another form has been deployed on the mUzima client with the same formId but with a lower version, then this is an update form. mUzima then prompts the user to allow a form update to occur
    3. If another form with the same form Id is not found, then mUzima prompts the user to allow it to add the form and its dependencies to mUzima.

Viewing the HTML file and referencing embedded and collected images 

Assets stored in the xml, html, css and js folders are referenced using the structure 

#{formId}/{resource}/{filename} e.g. 





  • No labels