31.3 J2ME GPRS/3G Client

The DHIS2 GPRS/3G mobile module provides a mechanism for remote clients using mobile phones to enter data directly into the DHIS2 system. There are two functions of the client, namely:

The solution relies on the mobile phone having a data connection available (i.e. GPRS, Edge, 3G), over which it communicates with a DHIS2 instance which must be publicly available on the internet, as any other web server. The client application on the phone downloads the data entry forms to the phone from the server, and the forms can therefore be updated without installing a new application. This is also a crucial feature for community reporting, which relies on regularly downloading activity plans from the server.

31.3.1 Data connection availability

Data connection availability can be a problem in many of the contexts where DHIS2 mobile reporting would otherwise be a good solution for getting data directly into DHIS2. If that is the case for you, you might want to consider trying the SMS based solution described in a separate document. Keep in mind that even though a data connection is currently required for communication between the server and the mobile phone, it is only required when initializing or updating the mobile application and when sending reports to the server. The phone stores all entered data locally, so it can work fine with only temporary access to a data connection on a regular basis.

31.3.2 J2ME GPRS 3G facility reporting client

The server side component of the web based solution is included in the general build of DHIS2.

In order to configure the DHIS2 web-based mobile reporting, you should follow the following steps.

  • Set the “Available for Mobile Reporting” flag for the data sets you want reported: Under Maintenance->DataSet -> Edit mark the “Available for Mobile Reporting” check box and save.

  • Create a user role for the mobile user. Select Maintenance->Users->User Role->Add new . Add a user role name and description. Add the desired data sets for the role. The mobile user role will need to have at least privileges for DHIS2 Web API. Save the user role by clicking “Save”.

  • Create a user which will be used by the client to login from Maintenance->Users->User ->Add new . Fill in all of the required details, keeping in mind that the password must be at least 8 digits long, contain one capital letter,and one digit. Assign the desired user role to the user which was created in the previous step.


    Assign the user to exactly one organisation unit. Each mobile reporting client will need their own user name and password.

31.3.3 Detailed configuration of data sets and reporting forms

Though the previous steps is all that should be needed for testing the solution more detail configuration of the datasets may be required and are described in the following sections. The mapping of data sets to form layout on the phone

By default, a data set is mapped to a single form on the phone. If the data set is divided into sections, each section is displayed as a separate page on the phone. If a data element has more than one category option combo it will be displayed as a heading with the category combination options following.

Form design element DHIS2 Metadata Metadata element
Form title Data set Short Name if it exists, otherwise Name
Page tile Section Section name (or form name if no sections)
Question Data element Alternative name if it exists, otherwise Name
Question name if combos Category option combo name Sorting of forms

By default, data elements will be sorted according to the global sorting assigned in DHIS2. If sections are used, their section specific sorting order will be used. In some cases, when sections are not used, a data element might be used in multiple data sets, and conflict in the way it should be sorted in individual data sets. A work around for this situation is to wrap the whole dataset in one section (note that this will only work if the data elements have the same category option combo) Versioning of data sets

To make it possible to compare and update the data sets on the mobile phone with the version on the server, data sets are automatically versioned when you edit the data set structure. Some changes which occur on the DHIS2 server, will cause the mobile client to update its forms with a new version.

  • Create DataSet

  • Edit DataSet

  • Create/edit/delete Section in DataSet

  • Sort Section Order

  • Update DataElement (affect many related DataSets)

  • Delete DataElement (affect many related DataSets)

  • Edit DataElement Category

  • Edit DataElement Category Combo Language support

Multi-language support is available.

DataSet and DataElement are translated through web-based function. Default language on server is used on mobile in cases requested language from mobile is not available.

31.3.4 Mobile application setup Installation and initialization Installation

Download the jar packages from the DHIS2 homepage: www.dhis2.org/downloads Initialization

Initialization should be performed before the phones are delivered end-users. Given the large variation in possible phone configurations, it is impossible to describe the exact steps which are required in order to enable the client on the phone. However, for most phones, simply copying the DHIS2 Web Mobile client “JAR” file to the phone with a USB cable or via Bluetooth is sufficient. Of course, GPRS/3G connectivity must be enabled. Contact your mobile service provider for exact details on the configuration of the phones and networks.

Once the client has been installed on the phone, an initialization process must occur by providing a user name, password and server URL.

  1. Logging into the server for the first time.

    The first time the client logins to the server, or if the client is reinitialized, the username, password and server URL must be entered.

    If the client is unable to login, there could be several possible error messages which you see.

    • Connection Not Found: The specified server URL is not correct. Check the server address, ensure that the server is actually reachable, and try again.

    • Invalid User Name Or Password: the username or password is incorrect

    • Application not authorized to access restricted APIs : The server can be contacted, but the user does not have the necessary permissions to access the mobile reporting module

  2. Setting the PIN number: After the initial login process, a PIN number can be entered by the user. This will make the login process much easier, as the user only has to remember the four digit pin number, as opposed to typing in the user name and password each time. The PIN number can be preset if the phone is initialized prior to delivery, or it can be set by the users themselves if they have been provided with usernames and passwords.

    After entering the PIN, press (Menu)->Next.

  3. Download all forms: After the PIN has been specified, all forms will be downloaded from the server and stored locally on the phone..

    If the user has been configured to report on aggregate datasets, a list of appropriate datasets will be displayed. If the user is responsible for community based reporting, the list of assigned activities is displayed.

    Notes : If the Health Worker is responsible for both Facility Reporting and Community Reporting, DHIS2 server will send all forms of both Facility Reporting and Community Reporting to mobile and on mobile, there will be a screen to choose whether displaying Facility Reporting or Community Reporting.

    Errors : Logging in (for regular use)

After starting the application, the PIN form is displayed.

  • PIN: Enter the four digit number PIN.

  • Reinitialize Command: this function will clear all data on mobile and we start from the login screen with username and password.

  • Errors: Invalid PIN: If the user has entered an invalid PIN, they will need to enter the correct PIN, or reinitialize the application with the correct username and password. Facility Reporting Module Entering data

After selecting an aggregate dataset from the “Select report form” window, the user will need to select an appropriate time period. A list of available time periods is automatically generated.

  1. After the user has entered their PIN, they can select from a list of available datasets. Select the appropriate dataset and press “Next”.

  2. Choosing periods: A list of available periods will be automatically displayed to the user. They can select the appropriate period from the list.

  3. Fill in values: After choosing the period, the form can be displayed in two modes, depending on the

    • Form with sections

      Each form section is displayed in a single screen with the name of the section in the title window.

      To navigate from screen to screen, push “Next”.

    • Forms without section (Datasets without sections)

      All fields are displayed on one screen with the title that is the name of DataSet

    The user simply fills in each data element with the appropriate value.

  4. Save and Complete:

    After finishing data entry, the user can choose to save the data locally on the phone or to upload the data directly to the DHIS2 server.

    If the user saves the data form, they can edit the form at a later point in time if they need to. When selecting a period once again, the period will be marked as "Saved’ as seen in the next screen shot.

    If the user selects “Complete”, and the data entry form is not complete, the user will be asked if they are certain they wish to submit the form as incomplete. Once the form has been submitted, a message should be displayed informing the user that the transmission was successful. Notes
  1. Period list:

    Periods marked with an asterisk (*) is the period that is completed or saved, depending on the status of the data entry.

    All periods that are not in period list are considered old and will be deleted automatically.

  2. Storing values duration

    The number of saved forms on mobile are limited only by the effective amount of storage of the mobile device.

    Forms are saved for limited period only, depending on the frequency of collection of the particular dataset.

    • Daily Forms: 2 months (current and previous month)

    • Weekly Forms: 4 weeks (current and 3 previous week)

    • Monthly Forms: 2 months (current and previous month)

    • Quarterly Forms: 2 quarters (current and previous quarter)

    • Yearly Forms: 2 years (current and previous year)

  3. Completed forms - Uneditable forms

    If the form has been completed, the user can view the form on their phone, but they cannot make any subsequent edits to the form. Each field is greyed out and inactive for editing.

  4. Re-Edit completed forms

    If the user wishes to edit data which has already been submitted to the server, they can do so by pressing the “Edit” button. They are allowed to do this assuming that the dataset has not been locked for the period in question. If they attempt to upload the data, the user will be informed that the dataset has been locked, and it is not possible to upload the data.

  5. Update Forms:

    This function is used to synchronize the forms on mobile and on server. The process is automatically triggered after entering PIN number.

    Note: Checking and downloading updated forms process run in background. After finished, prompt is displayed to ask user whether refresh form list or stay where they are.

  6. Multi-Language Support:

    This function help user to choose language of mobile’s GUI (graphical user interface) and content’s language (Forms).

    The forms must be translated on server, otherwise, default language is used.

    Default language of first login is English. Change language in Setting menu will affect both interface and content.

    Multi-Language Interface: In Setting menu, there are list of supported language (downloaded from server). Language of GUI is only changed after restart application.

    Multi-Language Content (forms): Form’s language is change after click “Save”. In case there are many forms, it take several minutes to save setting. Troubleshooting
  • Data has been entered on the phone but does not appear on the server

    This usually occurs when users enter data on the phone, but cannot send it to the server. This may be because of the configuration of the phone, lack of credit on the phone, or lack of coverage. Usually an error message is displayed as shown below.

    Users should be informed that if they see this error, then it means that their data has not been transmitted.