EpiHandyMobile
From EpiHandy
EpiHandy Mobile is a project developed by Makerere University as an extention of EpiHandy, by targeting low-end regular phones that are J2ME enabled.
- EpiHandy Mobile has been extended to work as a mobile solution for OpenMRS.
- Consists of both serverside and client side solution (end-to-end)
- Uses xForms to interface with i.e. OpenMRS and directly connects to EpiHandy Server.
- Can use SMS, File, Bluetooth and TCP/IP (GPRS, Wifi, Land) for data synchronization
- Targeted at lowest spec’ed devices, but runs on any device with J2ME.
The original source codes and distributions are available at: code.google.com/p/epihandymobile
Epihandy Mobile is a survey data management application for mobile devices (phones) developed at the Faculty of Computing and IT, Makerere University (CIT.
The application development project draws on support from a variety of sources, including the EpiHandy PocketPC-based data collection tool and the OpenMRS medical records system. Epihandy Mobile addresses challenges related to data collection in low resource settings. A special emphasis was placed on the ICT in Health arena. IT improves the quality of data collected and efficiency of surveys (timeliness of data).
Handheld computers, particularly those based on the Microsoft PocketPC platform are expensive . Similarly, components of the data collection application tool chain (e.g. Microsoft SQL Server) can add significant costs to any project. This has construed the adoption of handheld technology in data collection. However, current Java-enabled mobile phones provide sufficient computing power to support data collection applications, and as such offer a real alternative to the PocketPC platform. They are also significantly, and more widely available. In addition, the wide adoption of Open Standards data storage formats and software (e.g. XML, MySQL) mitigates the high cost of proprietary solutions .
Epihandy Mobile was developed to exploit these opportunities.
The application consists of:
a) A Java 2 Micro Edition (J2ME) phone-based application: for data collection, and. The phone- based application communicates with the server application using any one of several protocols/transports, including Bluetooth, GPRS, Wi-Fi or SMS.
b) A Java 2 Standard Edition (J2SE) server application: for form and data management Form/Questionnaire definitions may be prepared using either EpiHandy Study Manager or OpenMRS, and data collected may also be transferred back to either application.
1 Epihandy Mobile uses XForms for form definition and data representation . The application may be downloaded at http://code.google.com/p/epihandymobile/
This document describes the application components, setup and use.
User Manual
Installation Guide
The installation guide is split into two categories:
a) Mobile device application installation (see 1.1.1) and
b) Server side components installation (see 1.1.2).
Mobile Device Installation
Epihandy Mobile can be installed by sending the epihandy- midlet.jar file to a compliant phone using Bluetooth, Data Cable, Infrared or any available protocol that will get the file onto the phone. OTA (Over The Air) installation is currently being developed.
For most Java phones, installation begins automatically once the file has been transferred to the phone. A few phone models will require you to open the file manually to start the installations. Some other phones (e.g. Nokia 6020) will require you to send the installation file to the phone using special tools like the Nokia PC Suite, which then do the installation.
The guideline to use when installing is to start by just sending the file to the phone.
If installation does not start automatically, then, for Nokia phones send the file using Nokia PC Suite’s “Install applications icon. This will silently do the installation. CIT is part of the OpenROSA initiative, which has defined aspects of the XForms definition used by Epihandy 1 Mobile
For phones that will not automatically start the installation process, you will need to confirm where the phone stores the installation file. The destination varies from phone to phone. (E.g. Nokia E61 stores downloaded files in the message inbox). Open the file to start the installation.
Server Application Installation
Download the zip file containing the server application and unzip it into a folder. The folder should contain the following eight files
- Epihandy-service-manager.jar, application jar file
- EpihandySettings.Properties with application are specified;
- EpihandyFormMap.sql, scripts for updating EpiHandy SQL Server database;
- EpihandyOptionMap.sql, scripts for updating EpiHandy SQL Server database;
- EpihandyPageMap.sql, scripts for updating EpiHandy SQL Server database;
- EpihandyQuestionMap.sql, scripts for updating EpiHandy SQL Server database;
- EpihandyStudyMap.sql, scripts for updating EpiHandy SQL Server database and
- Start.bat, a batch file to start the application
The files with the .sql extension are used to update the Epihandy database in order to support Epihandy Mobile.
Open the SQL Server database scripts in SQL Server Query analyzer and execute them against the Epihandy SQL Server database.
NB. Using SQL Server query analyzer is outside the scope of this document
User Guide
The guide is divided into two categories described below.
Mobile Application
Introduction
Run the EpiHandy Mobile by opening it in the same way you would for a phone application (e.g. a game). The installation location varies from phone to phone but normally it is the same as the rest of the phone applications that came preinstalled on your phone.
For some phones this will be under games. For others follow:"Applications" -> "Collection" -> "Select application" -> “EpiHandy"
EpiHandy Mobile allows you access the different functions/items displayed in the menu below:
Menu Items
Figure 1. Menu Items
The various items are discussed below.
Select Study:
- Selects a study from a list. A study is a collection of related forms. The selected study is the one used when downloading forms, or selecting forms for data entry. Examples could be Malaria Study, Tuberculosis Study, etc.
Select Form:
- To display a list of forms, for the selected study. You will be able to select a particular from for data entry.
Download Study List:
- Downloads a list of studies from the server. (Note: This option will not download the actual forms for the study). This function will download information about available studies on the server. A user will then be able to select a study of interest and subsequently download only those forms that relate to a study of interest.
Download Forms:
- Downloads from the server a list of forms, for a selected study.
Upload Data:
- Sends data to the server using the selected connection type. This uploads data entered for all studies loaded on the device.
Settings:
- To set the connection type and other applications properties.
Logout:
- To end a user session. Logout can be used to switch users without quitting the application.
When the main menu is displayed, you can select "Exit" to close the application.
Usage
When running the application for the first time, you will be required to enter a username and password. If no users are downloaded from the server, you will be able to log in with username user and blank password. These are used when connecting to the server for downloading form definitions. (Access to the device does not mean access to the server as this requires a valid username and password).
When downloading form definitions, a list of valid users will also be downloaded. When connecting to the server for the first time, you will be required to choose a connection type (HTTP, Data Cable, SMS, Bluetooth, or File). This will be saved as the default connection type. This connection type can be changed by selecting the Settings menu and then choosing the appropriate Connection item.
Using EpiHandy Mobile requires a user to:
- Download a list of studies. (Download Study List) menu item.
- Select a study from the menu items.
- Download forms for the Study. (Use Download Forms menu item).
- Enter data to Forms. Only one form can be used for data entry at a time
- Upload captured data to the server. (Use Upload Data menu item). EpiHandy? Mobile was created with off line mode capabilities with data being stored on the phone until when a connection to a server is available for upload.
Data Entry
When you chose the "Select Form" menu item, a list of available forms, in the selected study, will be displayed as shown below:
Figure 2. (a) Select Form
Select the form you wish to capture data for. A list of previously collected data, if any, for the selected form will displayed see example below:
Figure 2. (b) List of Collected Data
Name display for the data items is specified on a template on the server for each form definition.
Figure 2. (c) Entering New or Amending ExistingData
If you want to enter new data, select the "New" menu item. This will open up a blank form for data entry.
If you want to delete a data item, select the item and then chose the "Delete" menu item.
Confirm if your action to delete this data record.
When you select existing data items the data form will be displayed. This record/item can now be edited see example below:
Figure 2. (d) Display Existing Data
When a form is opened, the form questions will appear, with data, if any, at the end of each question text.
You can edit an answer to the question by just selecting it, which opens up an editor appropriate for the question. E.g. editor for date questions will be different from that of numeric ones, single select or multiple select questions, as shown below:
Figure 3. Date Editor
'
Figure 4. Single Select Editor
'
Figure 5. Multiple Select Editor
After making changes to the question,in a “Single Question Edit mode" select "Cancel" to close without saving or "OK" to save the updated answer. This action will take you back to the list of questions on the form.
While in "Single Question Edit" mode, the "Next" option will take you to the next question as shown below:
Figure 6. Next Question in Single Question Mode
The "Previous" option under “Options" takes you to the previous question. In this mode, if you want to go back to the list of questions on the form, click the "Back to list" item as shown below:
Figure 7. Selecting Previous or Back to List of Questions
If a form has more than one page, scroll between the pages by using the "Next Page" or "Previous Page" menu items. You can select "Cancel" to close the form without saving as shown below.
Figure 8. Navigating to Next Page
Select the "Save" menu item to save changes made to the form and close it.
Epihandy Mobile allows you to customize General and Connection settings by using the Settings main menu item as shown below:
Figure 9. Settings
General Settings
There are two options under General settings as shown below:
Figure 10. General Settings
Single Question Edit
- Tick this to display one question at a time on the phone screen during data entry. If unchecked, Epihandy will display more than one question during data entry.
Background Save
- Tick this to automatically save data, in the background, as you fill forms. This guards against data loss in the event of sudden application failure e.g. due to the phone battery running out.
Connection Types
This specifies the method of connection to the server as shown below:
Figure 11. Connection Type Settings
Available connection settings are:
- HTTP: To connect to the server over GPRS or Wi-Fi. To use this setting a valid URL of the server will need to be specified. e.g. http://localhost:8080/openmrs/moduleServlet/xforms/xformDownload
- Bluetooth: To connect to server using Bluetooth. You will need to specify the Bluetooth address on which the server is listening.
When using a data cable to connect to the server . Data Cable:
To send data to server as SMS. You will need to supply the number of the modem that the SMS: server is connected to.
File: To save data as files on say the phone's memory card and then transferring them manually to the server.
External Interfaces
The EpiHandy Mobile engine is used by an OpenMRS midlet to collect patient data. This midlet can send data to OpenMRS using HTTP, Bluetooth, and SMS using the respective services on the OpenMRS server as part of the OpenMRS XForms module.
Figure 12. OpenMRS external interface
As from the screenshot above, the OpenMRS user can search for patients, or register new ones. Then select forms to fill for each patient. The form definitions and existing patients are downloaded from the server and stored on the device for use when not connected to the server. The collected form data and new registered patients can later on be sent back to the
OpenMRS server.
Details on how to configure and use the OpenMRS server side can be found under the OpenMRS XForms module documentation at http://openmrs.org/wiki/XForms_Module
Form Design
The Epihandy Study Manager is used to design the forms that will be downloaded by the phone. The form designer of Epihandy Study Manager has been extended to generate XForms which can be stored either on the file system or in a database of the user’s choice. The user can therefore design a form of their choice and then save it as XForms to the file system or to a database.
Please not that the design of forms is outside the scope of this document.
The screenshot below shows a form designed in the Epihandy Study Manager being saved as XForms to the file system
Figure 13. Study Manager Designer
With this form designer a user can
- Add form fields as questions
- Specify the data types for input that each field expects
- Add options for questions that can take on multiple answers
- Add options for questions that take on single answers and whose answers must be selected from a predefined list
- Save the form design and edit it as needed later on.
However, the details of the design of forms is outside the scope of this document
Server Application
After setting up the server application as explained in the installation section above, the user can launch the application by double clicking on the start.bat.
Below is a snap shot of the launched server application
Figure 14. Epihandy Mobile Server Application
A dropdown list provides available services that a user can choose to start or stop. In the current version of the se rver application, only two services have been provided i.e. Bluetooth and SMS services. However other services will be added to the application later on.
A user can select a service from the dropdown list and click the “Start Selected Service" button to start the service. To stop the service, the user selects the service they want to stop and then click the “Stop Selected Service" button.
The user can choose to start all the available services without having to choose one at a time.
All they have to do is click the “Start All Services" button. To stop all the Services the user clicks the “Stop All Services" button.
For one to use the Bluetooth service, the machine running the server application has to have Bluetooth hardware installed and turned on. No special configurations are required in the Properties file (application settings file) to run this service.
However to use the SMS service, one has to have a modem installed on the machine running the server application. Special configurations have to be made in the application settings file in the section labeled SMS Service Configurations .
The current version of the Server application supports two data sources i.e. Epihandy Study Manager SQL Server database and the file system to use XForms.
To use the Epihandy Study Manager SQL Server database as the data source, one has to set the value of the property in the application settings file to _DAL_IMPLEMENTATION_CLASS_NAME “org.fcitmuk.epihandy.dal.sqlserver.SQLServerDAL ".
A side from the above property extra configuration is required to use the Epihandy Study Manager SQL Server database. i.e. property holds the jdbc connection string for _DAL_IMPLEMENTATION _CONNECTION_STRING the Epihandy Study Manager SQL Server database.
Set the value of this property to the jdbc connection string of the Study Manager Database. e.g. _DAL_IMPLEMENTATION_CONNECTION_STRING=jdbc: microsoft: sqlserver: //DEVELOPER-TCK:4639;databaseName=epihandy0906;user=sa;password=djo8haccEPI
If one wants to use the file system as the data source with XForms change the value of the property to _DAL_IMPLEMENTATION_CLASS_NAME “org.fcitmuk.epihandy.dal.xforms.XFormsDAL ".
However extra configurations are required to use the file system. i.e. property holds the value of the location of the _EPIHANDY_FILE_SYSTEM_STUDY_LOCATION XForms study definition location on the file system. Set the value of this property to the file system location that has the study definition. E.g. _EPIHANDY_FILE_SYSTEM_STUDY_LOCATION=c: \\epihandy data\\form definitions
The other property that has to be set is the . This property holds the file system _EPIHANDY_COLLECTED_STUDY_DATA_FILE_LOCATION location that contains the collected data or where the collected data will be stored when pushed back to the server. Set the value of this property to the file system location where the data will be stored. E.g. “_ EPIHANDY_COLLECTED_STUDY_DATA_FILE_LOCATION=c: \\epihandy data\\collected data\\"
Technical Guide
The technical guide is split into two categories: Mobile device application installation and Server side components installation. We start with the mobile device application guide.
Mobile Device Application
EpiHandy Mobile is a forms support engine which can be used as an API by different kinds of data collection applications. The essence is to deal with scenarios that could be shared in more than one application.
The EpiHandy and OpenMRS midlets are example applications using this engine to build data collection applications. Basically, the applications using the API are responsible for building the main user interface and provide hooks into the API to handle user commands. These applications could also extend the API in areas where the default implementations are not satisfactory or to handle missing features.
The EpiHandy Mobile engine consumes forms definitions designed as XForms on the server. The engine differs from other Mobile XForms implementations by not loading the XForms XML onto the mobile device, but instead parsing the XML right on the server and sending a compact binary format of data structures to the device.
This is because of three major reasons: XML is bulky and hence not very suitable for low end devices that have memory constraints. * Although Epihandy uses free cost data transfer connections like Bluetooth and Data Cables, * real data transfer would normally use costly connections like SMS or GPRS. As a result there is a significant benefit in compacting of the data as this reduces transportations costs.
Applications that transfer XForms XML onto the mobile device also parse it and convert into * in-memory object model or data structures. This parsing and conversion requires processing from these devices which normally have limited processing capabilities. With Epihandy Mobile all this processing is done at the server providing efficient processing capabilities. This improves the performance of the application on the mobile device.
This is not deviation from the standard (XForms) by replacing it with a proprietary format, because:
The engine always consumes a standard (XForms) from the server side by having a layer * which transforms to the custom compact format.
The custom compact format is always converted back to the standard (XML) on reaching * the server, by the same layer as above.
This is what other applications do, but the difference is where it is done. They parse the XForms and build in memory data structures at runtime, on the device whereas this is done on the server for EpiHandy?.
The engine is split into three layers:
User Interface Layer:
The user interface handles display of various forms to the user as a way of displaying data or getting input. It is based on an implementation very close to the Model View Controller (MVC) Design Pattern. The following form concerns are separated:
- form definitions and data model; how it is presented to the user in various views, and
- Controller management of the storage and retrieval of the model and passing it to and from the views.
The views can vary depending on the type of data to be viewed or edited. For instance pictures could use a different viewer from text. The framework exposes an API to register custom views or editors for any data types that you want. The "MVCFactory" factory, based on the Factory
Design Pattern, is responsible for instantiating the various views which are either the default ones implemented by the engine, or those registered by the API user.
Business Logic Layer:
This layer handles data validation. Data validation is mainly built into the forms definitions during the form design stage at the server and is converted into the runtime form object model.
It has two categories:
Validation Rules: To ensure that data is always in a valid state before it can be saved. A * simple example of this could be not saving data before certain questions are answered.
Skip Rules: Determines sequencing of relevant questions. These rules will manage * branching or skip logic. Questions could be disabled/enabled, hidden/shown, or made mandatory/optional basing on users settings as per the form definitions. An example could be disabling the pregnancy question for males.
Data Access:
This is responsible for storage of data. It is not tied to any particular storage format. The default is Record Management System (RMS) for all data storage, but can be overridden to use any other storage facilities like device The default implementation temporarily stores data on the device as a way of enabling off line mode usages but can be overridden to enable direct storage to server, where constant connection to the server is available. All this is achieved by basing data persistence on the "Storage" interface which has methods to allow deleting, updating, adding and reading of data. The "StorageFactory", also based on the Factory Design Pattern, is responsible for determining which concrete implementation of the "Storage" interface is to be used to persist application data.
Transport Layer:
This deals with moving data between the mobile device and server e.g. uploading collected data to the server and downloading users and forms definitions from the server to the mobile device. It is based on an interface which allows extension for any other transportation means that we may not have thought of. The "TransportLayerFactory", also based on the Factory Design Pattern, is responsible for instantiating the concrete implementation of the
"TransportLayer" interface.
Server Application
Introduction
The server module is the application that sits on the server machine. It is the application that a user interacts with when sending and/or retrieving data.
It is made up of a number of services that can be used for different transport mechanisms like;
- Bluetooth service
- Http service
- SMS service
- Serial service
Not all the services mentioned above have been implemented in the server module. However the architecture has been built with these and more services in mind. The module has a server engine that handles the processing of the calls from the service layer. The data abstraction layer provides abstraction from the various data sources that could be used. The data abstraction layer is made up of a number of modules, which include;
- StudyManager module : To connect to the EpiHandy StudyManager Microsoft SQL Server database for data retrieval and forwarding
- XForm module which connects to the file system and retrieves XForms and stores data back to the file system into the XForm model.
Architectural Design
Figure 15. Server Application Architectural Diagram
Service Manager
This is the user interface element for managing the various services i.e. starting and stopping services It provides a dropdown list of services. The services are not inbuilt into the element but they are specified in a properties file where they are picked and are displayed.
A user can start one service at a time or start all services at once.
Below is a screenshot of the service manager.
Figure 16. Server Application User Interface Element.
Services (Service layer)
This is the layer where the various service components provided by the server module sit. The services that sit at this layer currently include:
- Bluetooth service
- Http service
- SMS service
- Serial service
Not all the services mentioned above have been implemented in the server module but have been taken into consideration in the application. Therefore one can create a service and add it to the system without having to recompile the system.
To add a service to the system, inherit from the base class and implement the operations specified. Then specify the fully qualified class name of the service implementation in the properties file. The services that are currently available in this layer include;
Bluetooth service : This service provides transport services over Bluetooth that is; for mobile devices that support Bluetooth, they would transfer and/or retrieve data over a Bluetooth channel.
SMS service : This service provides transport services over SMS . Data transfer and/or retrieval is made using concatenated SMS messages.
Server Engine
This is the core of the server module. It sits between the service layer and the data abstraction layer. Therefore every service interacts with or through the server engine. It receives calls from the service layer for processing. It abstracts the services from interacting with the data abstraction layer.
Data Abstraction Layer
This layer provides abstraction of the various data sources used. One may chose to use a database or the file system for storage and/or retrieval of data and the services, server engine and the Mobile phone clients will never know the difference.
The data abstraction layer has an open ended design to enable different data sources to be plugged in without having to recompile the system.
Some of the implemented modules in this layer include;
StudyManager Module
This module connects to the EpiHandy StudyManager Microsoft SQL Server database to pick the study and forwards them to the above definitions, converts them into the EpihandyMobile object model layer. It also receives data, converts it from the EpihandyMobile object model to the EpiHandy StudyManager format and pushes it to the database.
XForm module
This module uses the file system for storage. It read XForms from the file system and converts them into the EpihandyMobile object model and forwards them to the above layer. It also receives data, converts it from the EpihandyMobile object model to the XForm model and saves it to the file system.
Glossary
Application Programming Interface (API)
A set of calling conventions that allow application programs to access computing services.
Bluetooth
Bluetooth is an industrial specification for wireless personal area networks (PANs). Bluetooth provides a way to connect and exchange information between devices such as mobile phones, laptops, personal computers, printers, GPS receivers, digital cameras, and video game consoles over a secure, globally unlicensed short-range radio frequency.
Extensible Markup Language (XML)
XML is a general-purpose specification for creating custom markup languages. It is classified as an extensible language because it allows its users to define their own elements.
General Packet Radio Service (GPRS)
GPRS is a packet oriented Mobile Data Service available to users of Global System for Mobile Communications (GSM) and IS-136 mobile phones.
Hyper Text Transfer Protocol (HTTP)
HTTP is a communications protocol for the transfer of information on intranets and the World Wide Web.
Midlet
Midlet is a Java program for embedded devices, more specifically the Java ME virtual machine
Short Message Service (SMS)
SMS is a communications protocol allowing the interchange of short text messages between mobile telephone devices.