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.

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.

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.

Repeat questions

Using the Example Form, in the Example Study we look at how to use repeat questions on the mForms client.

Open the repeat question “Details of Children”

media_1333309500300.jpg

You are presented with a blank screen

media_1333309570268.jpg

This blank screen will contain a list of all of the groups of questions you have added, as you add them. For now, it is empty.

  1. Click New

You now have the questions that are in the repeating group

media_1333309654544.jpg

Note that as no information is added only “Cancel” is available as an option

Add information to each question

media_1333309683257.jpg

The list of questions now has OK option

media_1333309829711.jpg

After entering data for some or all of the questions, the OK option has appeared on the Right Option

Click OK

Now add more repeat question data (or return back to main form)

media_1333309919953.jpg

You now have a list of the data you entered. From here you can use the “Menu” button to add new data, delete a data set you’ve added or return to the main form.

Added some more data rows

media_1333310228253.jpg

In the above shot I have entered three seperate groups of answers to the repeat question.

Group 1
Name: NameOne
Age:
Sex:

Group 2
Name: NameTwo
Age: 23
Sex: Female

Group 3
Name: NameThree
Age:
Sex: Male

You can also go up and down this list and select a row, to return and edit it.

To return to the main form

media_1333310254075.jpg
  1. Click Menu
  2. Click OK

Repeat data is now displayed in main form

media_1333310326482.jpg

The different rows are seperated by |

Note there is currently a ticket, to change the display on the main form from this to simply a count of the number of groups of repeat data entered.

Entering Data

Entering data on the phone is very self explanatory. The best way to learn is to try entering data a few times on the sample form that comes with a default openXdata implementation.

Text question

media_1351288008140.jpg

Text questions will take all values using your phone’s standard input – whatever language your phone’s writing settings are set to is what will appear here.

Number

media_1351288136864.jpg

Number questions only accept integers, like 65, not decimals like 65.3. Your phone will be forced to enter numbers on number fields. Negative numbers are accepted

Decimal

media_1351288193013.jpg

Deciml accepts both integers and decimals. Your phone will be forced to enter numbers. Negative numbers are accepted.

Date

media_1351288390359.jpg

Date questions will allow you to enter a date manually. But there will also usually be a Select Day option presented in the bottom menu which will bring up a calendar as shown above.

Time

media_1351288512254.jpg

A time question will force the user to enter numerical values for hour and minute

Boolean / Single Select

media_1351288633141.jpg

On a single select, the default selection will be No Selection (unless you’ve specified a default in your form definition). Scroll up and down to select the value you want.

Multi Select

media_1351288700022.jpg

On a multi-select, use the middle key on your phone to select all the values that apply. In this screenshot, you can also see the help text that can be set in the form designer scrollign along the top of the mobile screen.

Repeat Question & Multimedia

Repeat and Multimedia questions are covered in seperate sections: Repeat questions

GPS

media_1351289459321.jpg

If your phone has GPS, and mForms can detect it, when you click the GPS question, you will be asked for permission to use the GPS. There is no way to circumvent this, the user must agree to use the GPS. Once GPS co-ordinates have been determined, they will be shown in the question.

If your phone does not have GPS, you will be given a screen to enter co-ordinates manually

Single Select Dynamic

Single select dnyamic questions look just like single select questions except that no options will be presented to the user until the preceding questions are entered. E.g. if you have a single select dynamic question Country, that presents a list of countries based on the Continent previously selected, until Continent is selected, no Countries will display in the question.

Required

media_1351372849362.jpg

Required questions are marked with a * (red asterisk)

Disabled

media_1351372933202.jpg

Disabled questions are marked with a grey stop sign.

Locked

If a locked question is enabled, you will be able to enter the question, but not enter data. Depending on the phone, the phone may show a lock symbol when you attempt to enter data.

Running the first time

The first time mForms runs on a phone, the user will see some additional screens by default,

First time login

wpid1618-media_1333318061240.jpg

The application is designed to be used offline, so user names and passwords are stored in the phone so that a user can login even when she doesn’t have a cell phone signal.

However, the first time you login, the phone has no knowledge of the users on the server. So the first time you login, only the first time, the login screen will accept any username and password – these are later checked once you have confirmed the server details on the next screen.

Confirm connection settings

wpid1615-media_1333318113090.jpg

This is only presented to the user on the first login, afterwards the Connection Settings are available through the Settings menu.

You can confirm or edit the server settings.

For more information, see the Settings section.

Project administrators may also want to change this default URL before loading the mobile client onto the phone – for more information see Configuring the server URL

Application confirms user password and downloads list of studies assigned to user

wpid1617-media_1333322548521.jpg

Every time the application needs to access the internet, the user will be asked to confirm whether to allow the connection. This is something the phone does, not the application and we cannot change. Experience may vary from phone to phone.

  1. You must click yes to continue

User is presented with the list of Studies

wpid1616-media_1333323044147.jpg

This is the screen that the user will now see each time they log in

What if I enter the wrong username / password?

wpid1614-media_1333323250209.jpg

If you enter the wrong username or password, you will see an Access denied message. Pressing ok will return you to the login page you will then have the opportunity to enter a correct username and password.

What if I enter the wrong server address?

wpid1619-media_1333323833640.jpg

If you enter the wrong server address, you will see an error message. You will then be returned to the login screen, and then once again to the connection settings screen.

Note: In the unlikely even that you enter a valid openXdata server address, but not the correct openXdata server address then the application will think that you have an incorrect username and password and you will be taken back to the username and password screen but will not be shown the Connection Settings screen again and you will not be able to login. In this case you will need to delete the app from your phone and reinstall.

Configuring the server URL

When you go live with a project, you may not want to manually edit the server URL on every phone. You can edit the .jar (the mobile client) file before putting it on the phone so that your server URL is the default URL in the mobile application.

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 default.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 defaults.properties

(Don’t forget to use your midlet name)

This extracts the defaults.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 defaults.properties from the end of the command it will extract the entire contents of the jar which is a lot of files but is fine and you can continue with the following instructions

Edit the default.properties file

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

It should contain one line:
httpUrl=http://localhost:8080/openxdata/mpsubmit

Edit this to be your server – do not forget the /mpsubmit at the end of the URL for example:
httpUrl=http://www.myopenxdataserver.net:8080/webapp-1.16.7/mpsubmit

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

Update your jar with your new defaults.properties

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

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

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

(Don’t forget to use your midlet name)

Done!

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

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