Troubleshooting EMIT

EMIT 1.0 is an easy to use online data capture application based on the OpenXData server. It is used to capture, view and edit form data. To design forms and perform administrative functions such as create users and manage roles the “Admin Console” (OpenXDataServerAdmin) must be used.

EMIT uses the same database as the OpenXData application, uses the same server code, and runs alongside OpenXData in the web application server. EMIT 1.0 runs with the OpenXData release 1.1.

As of v1.3 of openXdata, EMIT was combined into openXdata to make the new Dashboard View and this page does not apply to new versions of openXdata

Common problems/Troubleshooting/FAQ

I have x responses, but when I open the “browse responses” window I see nothing.

The browse responses window reads the form data from the exported tables. This means that if the rdms data export does not run successfully and export the form data you will see this problem. Look in the log files to see the error.

I see duplicate responses in the “browse respones” window.

The ‘Data export’ task cannot be running on a schedule and continuously. For Emit, it must be set on “run at startup” and “continuous=true”.

When I login I see “Access Denied”.

The Emit application requires the permission “Perm_Emit”. Please add this permission to the user’s role (using the admin console)

The user can see all the studies even though I have set the study permissions using the Admin console.

If the user has the Role_Administrator then they will always see all the studies/forms

I don’t see my questions on the form.

You need to do a preview of the form in the OpenXData Admin Console before they will appear in Emit.

Creating MySQL database and user (All Platforms)

A run through of the command line steps required to add a new database and user for openXdata on your MySQL. A variety of graphical interfaces for MySQL exist for various platforms including MySQL Administrator and phpMyAdmin, there are a wide number of resources online to cover these programs.

Enter MySQL command line

Add a new user

mysql> CREATE USER ‘myoxduser’@'localhost’ IDENTIFIED BY ‘securepassword’;

Don’t forget the ; at the end of the line. If successful, you will see:

  • Query OK, 0 rows affected (x sec)

Add a new database

mysql> CREATE DATABASE myopenxdatadb;

Don’t forget the ; at the end of the line. If successful, you will see:

  • Query OK, 1 row affected (x sec)

Grant new user access to new database

mysql> GRANT ALL ON myopenxdatadb.* to ‘myoxduser’@'localhost’;
mysql> FLUSH PRIVILEGES;

Don’t forget the ; at the end of the line. If successful, after each command you will see:

  • Query OK, 0 rows affected (x sec)

Exit MySQL

mysql> quit

To confirm your setup worked re-enter MySQL as your new user

From the command line / command prompt:
~$ mysql -u myoxduser -p
(then enter the password created in step 2)

mysql> USE myopenxdatadb;

If you get the response "Database changed" then your setup has worked

Adding and designing forms

The following, was taken from http://www-old.openxdata.org/Main/DataManagerGuide#Data_Manager

Login

  • Go to the link for your openXdata server (e.g http://localhost:8080/openxdata)
  • Enter the given username and password and click Login
  • For demo.openxdata.org you may use:
    • Username: admin
    • Password = openxdata

User Interface Details

The sections below this one provide brief descriptions of how to perform common data management tasks. For more detailed guides to user interace features and their capabilities see the two links below as required:

Create a new study

  • First click in the leftmost column to activate the list of studies
  • Click on the New button, or got to -> File -> New
  • A new study will be created. You may change the name in the left column.
  • Temporary steps required:
    • Right click on the study and select Add New Child, that will create a new form.
    • Give it a name of your choice
    • Right click on the form and select Add New Child, that will create a defined version of that form.
    • Click on Save Button or go to -> File -> Save

Add additional forms to a study

  • Right click a study and select Add New Child, that will create a new form
  • Give it a name of your choice
  • Temporary step required:
    • Right click on the form and select Add New Child, that will create a defined version of that form.
    • Click on Save Button or go to -> File -> Save

Add a new version of a form

  • Right click on the form and select Add New Child, that will create a defined version of that form.
  • Click on Save Button or go to -> File -> Save

Import a form (reuse an existing form)

  • Create a new form or a new version of form as described earlier.
    NOTE! You can only import into a study that has not previously had items (pages/question/options added to it. It must be completely new and empty!!!
  • Click on Save Button or go to -> File -> Save
  • Click on the version to be edited and the Design tab should be loaded.
  • If not loaded automatically, just click on the Design tab page.
  • Click on the form
  • Go to -> File -> Open
  • A small window will open. Select the saved file and click OK.
  • Click on Save Button or go to -> File -> Save

Edit a form or study

  • Start design of a form by clicking on the version you want to edit.
  • It will load the design tab. If not click on the design tab.
  • If the form does not open the the design tab, you can right click the version you wish to edit and select ‘Design form version’ from the pop-up menu

Form Binding

Forms and form elements have a property called binding; this property is important because it is used in the xform definition and by the RDMS data exporter (which exports the form data from XML into a table format). It is important that the form (and every version) have a unique binding and that questions and options within a form are unique. Bindings are automatically generated using the descriptions + text of form elements.

Opening a form in Read-only mode

If a form has captured data, it can only be opened in read-only mode. This means that the form structure cannot be modified.

It is possible to change:

  • form layout,
  • question properties such as text, required, locked, visible and enabled,
  • default values,
  • skip logic,
  • validation logic, and
  • dynamic lists.

If you wish to modify form structure, you can select the option to “create new version”. This will create a new form version with the same structure as the current version (you will need to layout the new version). The existing form data will remain in the old form version.

Add Pages to a form

  • First start design of form version (as described above)
  • Right click the form and select Add New Child
  • A page is now added, you may add any number of pages.

Add Questions to a page

  • First start design of form version (as described above)
  • Right click a page and select Add New Child
  • A question is now added, you may add any number of questions to a page.
  • For detailed description of question properties see here?

Single Select Dynamic

Single select dynamic questions allow you to change the question options depending on the selected value of an earlier single select question.

  • Create the first question with type ‘single select’ and some options (see below on how to do that)
  • Create the second question with type ‘single select dynamic’
  • On the second question, open the tab ‘Dynamic Lists’ – this is on the ‘Properties’ tab
  • Link the questions together by selecting the first question in ‘when the answer for:’ – click on the link and type in the first question.
  • Once the options of the linked first question are loaded in the drop down list after ‘is equal to’, select the first option
  • Click ‘Add New’ button to add options.
  • Enter the text and binding for the second questions options which should be linked to this first option.
  • Repeat for all the options which are linked to the first question’s first option.
  • Select the next value in the drop down ‘is equal to’.
  • Repeat for all the first question’s possible values.

Add Options to a question

  • First start design of form version (as described above)
  • Ensure the question type is a type that allows options to be added e.g. Single & Multi Select.
  • Right click a question and select Add New Child
  • An option is now added, you may add any number of options to a question.
  • For detailed description of option properties see here?

Changing the order of questions or options

  • Open the form in design mode
  • In the form structure tree view, right click the question or option you wish to change
  • Select “Move up” or “Move down” in the menu
  • Repeat until the question or option is in the correct position
  • Save

Insert a default Date or Time question

You can automatically fill in a date or time for any date/datetime/time question. There are two options:

  1. Current date/time which is the date/time currently recorded on the system (either the mobile phone or computer)
  2. End date/time which is the date/time when the form was closed

To configure a current date/time question:

  • Create a question (see above)
  • Set the type to either “Date”, “Date and Time”, or “Time”
  • Set the Default Value to ‘today()’
  • note:
    • the single quotation marks around today())
    • ‘now()’ is still supported, and has the same effect as ‘today()’

To configure an endtime date/time question:

  • Create a question (see above)
  • Set the type to either “Date”, “Date and Time”, or “Time”
  • Set the binding to “endtime”
  • Untick the “Visible” checkbox (if you wish to hide this question from the user – they will not be able to submit their own value)

Design of Form Layout

  • . NOTE! The following only relates to web forms.
    . NOTE! Forms displayed on the different mobile clients will be rendered based on the structure of the form and not the layout shown here.

First time

  • The first time you go to the Design surface it will be empty.
  • Right click anywhere on the white space
  • Select Refresh or ‘Load’(this should happen automatically)
  • All of the pages, pages, question of the currently selected form will be automatically put onto the pages.
  • Note! If the current page is to small to hold the different items it will create additional pages.
    • To have many items on a page ensure your browser is maximized before doing this operation.
    • An option to have scrolling pages will come.

Refresh Form Layout

If you have made a change to the form structure (including changing question related text), you will need to trigger the auto layout by deleting the widgets related to the modified questions.

  • Open the ‘Design Surface’ tab
  • Select the question’s widgets (this includes the label). To do this you either can “draw” a box around the widgets or press the control button while clicking on the widget. If you wish to select all the widgets, you can use the “Select All” option in the pop-up menu
  • Ensure the widgets you wish to select are all greyed out
  • Right click on the white space of the canvas and select “Cut” or “Delete selected”
  • Right click on the white space and select “Refresh” You should see a popup that indicates that that the layout is being regenerated

Group widgets

If you wish to layout certain questions within a box, you will need to group them.

  • Open the ‘Design surface’ tab
  • Select the question widgets (ensure you have included the question labels). To do this you either can “draw” a box around the widgets or press the control button while clicking on the widgets
  • Ensure the widgets you wish to select are all greyed out
  • Right click on the white space of the canvas and select “Group widgets”
  • A box should now appear with the selected widgets inside. If you move the box, the widgets inside will also move.
  • To change the box header, open “Widget properties” (underneath the form structure tree) and change the text “Header Label”

Radio buttons

If you wish your single select or boolean question to use a radio button instead of a drop down list, you will need to change it manually

  • Open the ‘Design surface’ tab
  • Right click the question widget
  • Select either “Change widget H” or “Change widget V”. If you select H it will lay out the radio buttons on the same line, and V will lay them out underneath each other.

Adding extra widgets to the form

If you would like to add extra text to a form, you will need to add a label widget.

  • Open the ‘Design surface’ tab
  • Right click in the white space of the canvas
  • Select ‘Add Widget’ and then ‘Label’ from the pop up menu
  • A label will now appear on the design surface.
  • You can change the text on the label, by opening ‘Widget properties’ (underneath the form structure tree) and then editing the Text value

Aligning widgets

On the design surface you can use the align buttons to help with your layout.

  • Open the ‘Design surface’ tab
  • Select the widgets you wish to align (e.g. all form labels). You can do this by drawing a box around the labels or using the control button while you click.
  • Press the align button you wish to use (on the toolbar)
    • Align left – all selected widgets will be aligned on their left edge with the left most widget
    • Align right – all the selected widgets will be aligned right with the right most widget
    • Align top – all the selected widgets will be in a horizontal line with the widget at the top
    • Align botton – all the selected widgets will be in a horizontal line with the widget at the bottom
  • Note: you could also do this manually by changing the widget properties: left and top. You will have to do this for each widget individually.

Auto sizing widgets

On the design surface you can use the auto size buttons to help with your layout.

  • Open the ‘Design surface’ tab
  • Select the widgets you wish to size (e.g. all form labels). You can do this by drawing a box around the labels or using the control button while you click.
  • Press the size button you wish to use (on the toolbar)
    • Make same width – all the select widgets will have the same width
    • Make same height – all the select widgets will have the same height
    • Make same size – all the select widgets will have the same size
  • Note: you could also do this manually by changing the widget properties: width and height. You will have to do this for each widget individually.

Viewing xForms source

  • To view the xForms source, first save the form and then click on the ‘xForms Source’ tab page under design
  • Note! This is not an xHtml version as required by JavaROSAJavaROSAclients. The required processing and xHtml wrapping is made on the server prior to download to clients.

Loading a new form using xForms source

This is another method of importing a form, which can be useful if the form does not originate from OpenXData .

  • Create a new form and version
  • Open the form in Design Mode (see above)
  • Open the ‘Xforms source’ tab
  • Copy and Paste your xform into the tab
  • Optional:
    • Open the ‘Layout Xml’ tab
    • Copy and Paste your layout xml into the tab
  • Click on the “open” button, or select “Open” from the “File” menu

Previewing

Before you can use your form online (for data capture) you will need to preview your form. Once you have designed your form structure and layout:

  • Open the ‘Preview’ tab
  • Fill in the form
  • Press submit
  • You will now see the data XML which will be submitted for the form you just filled in.
  • Note: it is only possible to test skip and validation logic on the preview tab, so this is an essential step in the process.
  • If you have changed the form structure or layout, right click on the white space and select “Refresh” from the pop-up menu

Managing users

openXdata server overview

1 minute introduction to the basic functions of openXdata server

Study management – overview

Form management – overview

Designing forms – the basics

Covers:

  • (00:00 – ~00:45) Adding your first question to a new form
  • (~00:45 – ~10:15) Question types: Text, Number, Decimal, Date, Time, Date and Time, Boolean, Single Select, Multiple Select, GPS, Picture, Audio, Video, Barcode (not yet enabled)
  • (~10:15 – ~11:15 ) Getting the Start Time and End Time of form entry.
  • (~11:15 – end) Moving questions, copy and pasting questions.

Managing Tasks and Settings

Includes instructions on how to configure Data Export task for use with EMIT (~1:08)  – only necessary with v1-2

Emit – installation & setup

To install emit:

  1. download emit.war
  2. no need to set-up a new database, it needs our openXdata database
  3. Follow the same instructions as for openXdata to deploy the war (emit.war)
    1. See ~00:30 to ~1:30 on the video here
    2. it won’t run until we give it the correct properties file
  4. copy the OPENXDATA_SETTINGS.properties file from your openxdata folder to your emit folder. On Ubuntu default installation of tomcat:
    • $ cd /var/lib/tomcat6/webapps
    • $ sudo cp openxdata/OPENXDATA_SETTINGS.properties emit/
  5. Start your web application from tomcat adminstrator homepage
    1. See ~5:40 on the same video as in step 3
  6. Log-in to emit using users set-up in openXdata server

To use emit you will need to have the Data Export task running, brief instructions on this are in the video here at ~1:08.

If you want to create a user that can use EMIT, you will need to create a role “Perm_Emit” to login and a few other permissions for capturing data. They will also need to be specifically allowed to view Studies. This is demonstrated in this video and this video.

The following permissions are required:

  • Perm_Add_Form_Data
  • Perm_Add_Users
  • Perm_Data_Edit
  • Perm_Data_Entry
  • Perm_Edit_Form_Data
  • Perm_Edit_Users
  • Perm_Emit
  • Perm_View_Forms
  • Perm_View_Form_Data
  • Perm_View_Form_Versions
  • Perm_View_Locales
  • Perm_View_Mapped_Studies
  • Perm_View_Permissions
  • Perm_View_Roles
  • Perm_View_Settings
  • Perm_View_Settings_Group
  • Perm_View_Studies
  • Perm_View_Tasks
  • Perm_View_Users