mForms v2.4 Features

We keep adding new features to our mobile client, while stlil maintaining our support for low-end phones. In mForms 2.0 you will find:

All the existing features

  • User-based authentication
  • Off-line data collection
  • Support the following data types on all phones: Text, Integer, Decimal, Single Select (select only one option), Multiple Select (check all that apply), Boolean (Yes/No), Date, Time, Date & Time, Repeat (a group of questions which can be repeated), Picture, Video, Audio, Single Select Dynamic (see Glossary),
  • If your phone has, you can collect GPS location data
  • Support for validation and skip logic
  • Support for a wide-range of low-end java phones http://doc.openxdata.org/all-versions/977

Plus

  • A log of all uploaded data
  • The ability to download data you have submitted and re-edit it
  • Support for calculations
  • Support for complex expressions – complicated skip logic and validation (currently requires a little tinkering on the server side, but you mobile users don’t need to worry about this)

Compatible phones & compatible servers

To run openXdata, your phone, at the least must be able to run java applications. These phones are often called “feature phones.” They usually cost $20 and up.

Basic requirements

The current main mobile client for openXdata requires CDLC-1.1, supported by most recent phones.

However, the standard is not always implemented in the same way, so different phones have varying performance.

Phones that work

cMost current openXdata users are using Nokia phones as they’re widely available and often inexpensive.

We can’t test all phones, so we greatly appreciate other user experiences.

Phones that we know work:

Nokia Series 40 phones:

  • Nokia 2700c
  • Nokia 2710c aka 2710 Navigator Edition (has GPS)
  • Nokia 5130c aka 5130 Xpress Music
  • Nokia 2600c
  • Nokia 6700c (has GPS)
  • Nokia 3110c
  • Nokia 6131 NFC
  • Nokia 6220c (not great design for inputting data)
  • Nokia 1680 (price <$50)
  • Nokia 6020
  • Nokia 5230
  • Nokia C1

All the above have been used in the field, so as far as we can tell all Nokia S40 phones work fine (see the note in Troubleshooting about setting up your GPRS connection settings).

Other phones known to work:

  • E71
  • Sony Ericsson P1i

It has been reported that many Samsung models and some LG models also have suitable j2me support.

Partially working

  • Motorola RazR – application will install but runs v. slowly (based on one test – other feedback welcome)

Known not to work

  • Sony Ericson – w350i

Server compatibility

openXdata is generally released in recommended pairs e.g. server 1.16.X is paired with mForms 2.4.X

However, if you wish to use older versions of the mobile client you can, we maintain forward compatibility. So mForms 1.7 will work with openXdata server 1.16.X. However, we do not maintain backwards compatibility, so mForms 2.4.x will not work with openXdata 1.3.X

Error messages & Troubleshooting

Description of error messages a user may see and what the problem likely is

Problems occurred while processing request on server

media_1333328047891.jpg

Causes:
1) User does not have the role Role_Mobile_User – will affect only this user
2) The mobile application is looking for a protocol that is not available on the server – will affect all users
3) User has tried to upload data to a study they don’t have access to – will only affect this user

  • This can happen when a user has logged into a phone that was previously used by another person, has used the forms that were already downloaded by that user, and has tried to upload. (See working Offline for more information)

Can also check the tomcat logs to confirm:
1) protocol error while handling request from client – org.openxdata.proto.exception.ProtocolException: failed to serialize users
2) protocol error while handling request from client – org.openxdata.proto.exception.ProtocolNotFoundException: Could not load protocol jar ‘xxx’ (where xxx is the name of the protocol the mobile client is looking for)
3) protocol error while handling request from client – org.openxdata.proto.exception.ProtocolException: failed to deserialize uploaded form data

Access Denied

Username or Password is wrong

User sees a blank screen after trying to download studies

No studies / forms have been assigned to the user

Problems saving large videos

There is a known bug (https://trac.openxdata.org/ticket/842) when you try to save video larger than your phone can handle which may well cause mforms to crash.

Changing the application language

Changing the application language is about changing the menus and prompts in the mobile client. To do this, you will need to edit the language properties file. The process is very similar to changing the server URL.

To do this you will need java installed on your desktop machine where you are editing the .jar

Open a terminal / command prompt:

  • Windows: from the start menu, go to run a program and type cmd
  • Mac: Terminal is in the utilities
  • Linux: gnome-terminal / xterm / terminator etc.

From the command prompt type:
$ java -version
If you see something like
java version “1.6.0_32″
Java(TM) SE Runtime Environment (build 1.6.0_32-b05)
Java HotSpot(TM) 64-Bit Server VM (build 20.7-b02, mixed mode)
you should be able to update your jar.

Extract the language properties file from the jar

At the command prompt, navigate to the location of your mobile client – e.g. mforms-midlet-2.4.8-me.jar

$ jar -xf mforms-midlet-2.4.8-me.jar menu_text.properties

(Don’t forget to use your midlet name)

This extracts the menu_text.properties file from your jar and you should now see it in the folder you are in with your mforms-midlet-2.4.8-me.jar. If you omit menu_text.properties from the end of the command it will extract the entire contents of the jar. In this case you will also be able to see the menu_text_es.properties which is the spanish translation of the application that comes by default with the mforms client.

If you are running mforms on a spanish phone, the phone should detect the _es file and use the spanish version automatically

Edit the menu_text.properties file

Open menu_text.properties in your favorite text editor (not Word) e.g. notepad, gedit

It will contain many lines, this is a sample from menu_text_es.properties
SELECT=Seleccionar
MAIN_MENU=Menu Principal
SELECT_STUDY=Elija estudio
SELECT_FORM=Elija formulario
DOWNLOAD_STUDIES=Descargar estudios
DOWNLOAD_FORMS=Descargar formularios
UPLOAD_DATA=Cargar datos
DOWNLOAD_DATA=Descargar datos
SETTINGS=Configuraciónes
LOGOUT=Terminar sesión
LOGOUT_PROMPT=¿Desea salir de la aplicación?
GENERAL=General
DATE_FORMAT=Formato Fecha
MULTIMEDIA=Multimedia
LANGUAGE=Idioma
CONNECTION=Conexión

Edit this for your translations.

When you are finished, save this file back to where you opened it

Update your jar with your new menu_text.properties

At the command prompt, navigate to the location of your mobile client again

$ jar -uf mforms-midlet-2.4.8-me.jar menu_text.properties

This is the same as before but with -uf instead of -xf

(Don’t forget to use your midlet name)

Check it woks

Copy your jar onto your phone and you should now have a new default menu.

Settings

wpid1691-media_1351381804718.jpg

The settings menu can be accessed from most screens in the mForms application.

  • General – this contains settings about how mForms displays forms
  • Date Format – override the phone’s default date settings
  • Multimedia – Multimedia settings
  • Language – this menu is non-functional
  • Connection – change the connection settings
  • About – information about the mForms client you are running

General

wpid1692-media_1351382345699.jpg
  • Single Question Edit – in this view when you are entering data into a question, you can click Next and go straight to the next question instead of saving an answer and going back to the list of questions
  • Numbering – this automatically adds numbers to each question in the form for you
  • OK on Right – makes sure that the OK menu button is always on the right
  • Auto Save – when entering data into a form, from the list of questions there is a cancel option. With auto save selected this will just take you back to your list of forms and your data will be saved. Without it, you will be prompted to save or not before leaving the form.
  • Force No GPS – This setting will prevent a GPS question from accessing the phone’s GPS functionality (if it has it) and always show the screen to manually enter GPS data

Date Format

wpid1690-media_1351383117285.jpg

Multimedia

wpid1694-media_1351383196953.jpg

You can use the multimedia settings to enforce specific encoding formats.

In addition, if your phone’s camera has a high resolution and you want to limit the amount of data uploaded, you can edit the settings to capture only a smaller image size. To control the size of the photo taken, you can use the Multimedia settings on the mforms client.

You must set the encoding, width and height for this to work.

  • Picture Format eg jpeg = jpeg
  • Picture Width eg 320 = 320
  • Picture Height eg 240 = 240

Notes:

  • Picture format must be exactly “jpeg” and must be supported on your phone. Check the encodings for your phone model
  • Set Picture format to “jpeg&quality=25″ to reduce the size of the picture taken even further. You will see pixelization at this quality.
  • At these settings the xml should be around 17 kilobytes, and the picture itself (unencoded) around 11 kilobytes.

Language – non functional

wpid1695-media_1351383553136.jpg

The language menu is currently non-functional. It is being developed as part of https://trac.openxdata.org/ticket/732

To change the language of the application, see Changing the application language

Connection Settings

wpid1693-media_1351383663905.jpg

The connection settings menu will take you to the same connection settings screen that you saw on first login.

About

wpid1696-media_1351383717726.jpg

The About screen will give you information about the version of the midlet that you are running which may be of use to project administrators if they are trying to troubleshoot issues

Users: new logins, password resets

What happens when:
1) A new users wants to login to the mobile client when another user has previously been using it
2) you reset the password for a user

New user login

When a new user wants to login, the application needs to connect to the server to verify the username and password as well as the user’s permissions.

So make sure that the first time a new user logs onto the phone application, you have cellphone signal. After this initial login, the user will be able to access the application and collect data as normal.

IMPORTANT SECURITY CONSIDERATION: When a new user logs into the phone, any information stored on the phone will be available to the new user until the new user tries to download new studies or perform another action that connects them with the server.

Studies, forms, and data already entered will be available. However, users will not be able to upload data to a study they don’t have access too.

NOTE: mForms 2.13 and higher has enhanced security that corrects this issue

Workaround to ensure this isn’t a problem:
1) Have in place a system that means when a phone transfers between users that the previous owner confirms that they have uploaded all their data
2) On new user login, make sure the first activity is to Download Studies – this will reset everything.

Password reset

Because the application is designed to run offline, passwords are stored locally and so the user will continue to be able to login to their phone even when you’ve reset their password at the server level. However, as soon as a password has been reset at the server level, the phone user will not be able to upload or download data – they will get an access denied message.

To force the phone to re-check the server, the user must:

  1. Go to the login screen
  2. Enter their new password upto three times. They will get a message “Invalid username or password” until the phone reconnects to the server to get the new list of passwords.

The user will need to have mobile signal and a data connection to reset their password.

Working offline

mForms is offline by default, connecting only when it needs to

mForms is offline most of the time. It connects to the server :

  1. Confirm a username / password if it is the first time a user has logged in
  2. Download studies (on first time login, or by user request)
  3. Downlad forms (by user request)
  4. Upload / Download data
  5. Re-confirm a user after 3 failed attempts at login (see password resets)

To use mForms offline, you do not need to do anything. Before your phone users leave mobile coverage range, make sure they have logged in and downloaded the forms they will need to complete their work.

Once the forms are downloaded onto the phone, they will be able to collect data until their phone runs out of storage space (this is typically a lot of forms).

When they are back in mobile range they can upload the data they have collected.

mForms does not automatically upload data

Don’t forget, because mForms is offline by default, users must upload the forms they have completed.

Uploading & Downloading data

Data can be uploaded from two levels in the mforms client:

  • Study view – bulk upload
  • Data view – individual upload

You need a mobile signal and a data connection to upload and download data

Upload – data view

media_1351380106264.jpg

From the data view we can select individual forms to upload, which is useful if you have some forms currently incomplete

When uploading from the data view, you can upload one form at a time. To upload:

  1. Highlight the form you want to upload
  2. Click menu
  3. Select Upload Data

Upload – study view

media_1351380080842.jpg

Selecting upload from the study view will upload all saved data that is complete, but will leave any partially completed forms on the phone.

Upload Reference

media_1351380342205.jpg

When the data is uploaded, a confirmation message will appear on the phone. With this confirmation message will be an upload reference for each form that was successfully uploaded. This same ID can also be seen in the View Responses window on the server.

Deleting uploaded data

By default, successfully uploaded data is deleted from the phone. This can be changed in the phone’s settings menu

Upload Log

media_1351380480035.jpg

From the studies screen, you can select View Upload Log

media_1351380511574.jpg

The upload log gives a list of all data that a user has uploaded. For example, in the above screenshot:
3 – Sample Form_v1 Data: 2 – Sat Oct 27 16:25:19 PDT 2012

This means the following:

  • 3 – this is the upload reference
  • Sample Form_v1 – this is name of the form
  • Data: 2 – this is the name of the form that was on the phone
  • Sat Oct 27 16:25:19 PDT 2012 – this is the time and dat of upload

Downloading data

media_1351380894613.jpg

From the form view, you can download data that you have previously uploaded

Downloading data – enter session reference

media_1351380924900.jpg

The Download data screen asks you to enter the session reference for the data you want download. The session reference is the same as the upload reference.

You can only download data you uploaded yourself.

media_1351381037485.jpg

Once the data is downloaded, you will see the data indicator again and you can edit the data.

Audit / Edit Trail

The database for the server tracks all edits to forms. There is currently no front-end way to view this, but it is possible to retrieve all the changes that were made to data and when.

Saving forms (including partially completed forms)

Saving Data

media_1351373482345.jpg

Once you have entered all the data into your phone click Save

media_1351374050301.jpg

New list of data is started

media_1351374526323.jpg

A list of data saved for that form will now be started. If you press Back from this screen, you will taken back to the list of forms.

Saved data indicator

media_1351374721793.jpg

You will be returned to your list of forms but there will now be a small grey dot indicating that data is saved for that form.

media_1351374772285.jpg

This indicator is also present on the list of studies

Saving partially completed forms

media_1351375671872.jpg

If a form has required data that has not yet been entered, you will be able to save the form, but you will not be able to upload it.

media_1351375699476.jpg

Partially completed forms are then marked with a * to indicate that required data is still left to be completed.

View your saved data

To edit your data or complete your form, simply select the row you wish to edit and you will be returned to the form.

Multimedia questions (Audio, Video, Image)

Audio, Video and Image questions are available if the phone supports them.

User permission

media_1351381340640.jpg

When you enter a multimedia question the user will typically be asked for permission to access this feature of the phone.

Problems saving large videos

There is a known bug (https://trac.openxdata.org/ticket/842) when you try to save video larger than your phone can handle which may well cause mforms to crash.