Users – Disable (Delete)

Users cannot be deleted from openXdata once they are added – this allows audit trails to be kept. However, users can be Disabled.

To disable a user, click Edit and set their status to Disabled

Resetting Admin password

An admin user can login to openXdata and reset all other user’s passwords. However, if you forget your admin password you may be stuck.

In this case, you will need to access your openXdata database directly and reset the default admin. This should really be a last resort measure and you should take care to safeguard your passwords appropriately.

You will need to know the MySQL username and password for your openXdata database or your MySQL root username and password.

To change the password of any user to admin, reset:
* password: 7357bec928a1af86415f7b8c11245296ec1779d
* salt: e2597cf74095403889c6b07b46d8af5d94b8e6

Start, End time and today’s date

Using ‘now()’ for start time and today’s date

media_1344532069638.jpg

If we use the special syntax ‘now()’ in the default value we can get a date and timestamp of the date and time “now”

Note the single quotes around ‘now()’, these are necessary.

‘now()’ is used in two common ways:

  1. Start time – sometimes we want to capture the time that a user started to enter data into a form. This can be hidden from the user by making the question Enabled but not visible. Used with endtime this can be very helpful for monitoring field workers. To just capture the time, set the question type to time. Note that this is better than submission time, because it is perfectly legitimate for a user to only upload all their forms at once in the evening – perhaps because they are now back in cell phone range. It is less likely, for example, that it is appropriate for them to be collecting all their data in quick succession in the evening.
  2. Default date – to reduce errors and reduce data entry time, we may want fill in today’s date for a user. ‘now()’ can also be used for this. If you only want the date, set the question type to Date

Endtime

media_1344532371353.jpg

Endtime is used to capture when a form is saved.

To capture endtime, you must specify the question binding as endtime – no quotes

Skip Logic, Validation and Calculation

Visible, Enabled, Locked

wpid1515-media_1344533153244.jpg

The Visible and Enabled settings that you check when you design a form are the initial defaults when a form is opened. They can then be modified through skip logic.

Disabled is the opposite of Enabled, if you un-check the Enabled box, we will refer to that as Disabled.

Disabled and Locked are similar but distinct properties:

  • Locked means that the user can not edit the value, but any default or calculated values will be shown (if the question is visible) stored on save.
  • Disabled, means that no data for that question will be stored, it is regarded as skipped. A disabled question also can’t be edited.

Say the following:
Question1 Locked with default ‘now()’ would store the value generated
Question2 Disabled with default ‘now()’ would not store the value generated.

To the data capture user, the effect would be similar: They can’t edit the question. But the data that is uploaded is different.

Note the implementation of Locked is not always perfect – check you forms to see they perform as you expect.

Skip Logic – new thinking

wpid1520-IMG_0138.jpg

When you look at a paper form, it will usually say things like "If you answered No to Question 4, skip to Question 8. If you answered Yes, continue at Question 5" e.g.

  • Smoker? – Yes / No (if No, skip to Question "History of Cancer?")
  • How many? – Conditional on "Smoker?"
  • How often? – Conditional on "Smoker?"
  • Want to quit? – Conditional on "Smoker?"
  • History of Cancer?- Always required

One way we could do this in openXdata is the following:

  • For questions 5, 6 and 7 hide/disable them if the answer to question 4 is No – this may feel natural if translating from a paper form

However, it is often cleaner to do the reverse, which is not really possible with paper.

  • Start out with questions 5,6 and 7 hidden so your form looks like this
  • - Smoker?
  • - History of Cancer?
  • Then add logic so that if the answer to "Smoker?" is Yes the relevant questions appear
  • - How many?
  • - How often?
  • - Want to quit?
  • - History of Cancer?

Obviously, how you structure your form depends on your data, your users, and feedback from form testing

Adding Skip Logic

wpid1522-media_1344534847657.jpg

Once you have worked out how you want your form to look at the start and after the skip logic, adding the skip logic will be relatively simple.

Before you start adding skip logic:

  1. Add all your questions,
  2. Save your form and
  3. Refresh the page

This ensures that all possible values are available to the logic builder

Select how conditions will apply

wpid1518-media_1344534959307.jpg

Click on the all to edit

Conditions can apply

  • all – all the conditions must be met for the skip logic to occur
  • any – if any one of the following conditions occurs, the skip logic will happen
  • none – if none of the following conditions are true then the skip logic will happen
  • not all – if any of the following conditions does not occur, the skip logic will happen

 

Add conditions

wpid1514-media_1344535475731.jpg

Once you click < Click here to add new condition > a question will be automatically filled in for you, in the above diagram it was Options, my first question.

When you click Options (or whatever your question Text is) it will open up a box where you can get the question you’re looking for. To find the question you want, delete the text that’s in the box and type the first few letters of the question you’re looking for – a drop down will appear with the possible questions in.

When you click is equal to you will get a dropdown that will give you different options depending on the question type. For a list:

  • is equal to
  • is not equal to
  • is in list
  • is not in list
  • is null
  • is not null

For a number or date value

  • is equal to
  • is not equal to
  • is greater than
  • is greater than or equal to
  • is less than
  • is less than or equal to
  • is null
  • is not null

For a text value

  • is equal to
  • is not equal to
  • is null
  • is not null
  • starts with
  • does not start with
  • contains
  • does not contain

Skip logic can’t evaluate certain question types like Picture, Audio, Video.

When you click ______ you will either be shown a list of options in the case of a Select box (as pictured above) or a blank box with a checkbox Question value, as shown below

wpid1516-media_1344536200795.jpg

From this point, you can enter a number which will be a constant in your form. Or you can compare one number to another number from another question. To do the latter, check Question value and then ciick in the box and start typing to enter the name of the question

wpid1513-media_1344536304028.jpg

Repeat this process until you have all your conditions. Then save your form.

It is a good idea to back-up frequently when adding skip logic to a form

Delete a condition

wpid1517-media_1344536702849.jpg

Click on <> to delete a condition

Adding skip logic to multiple questions at once

wpid1519-media_1344536589876.jpg

If, as in our earlier smoking example, you have a set of questions for which the same logic applies. Click on < Click here for other questions >
to get a dialog that allows you to select multiple questions to apply the skip logic too.

Validation logic

wpid1521-media_1344536862094.jpg

The interface for validation logic is similar to that for Skip Logic.

Validtaion compares this questions Value or Length with another value. e.g. maybe you don’t want a name longer than 10 characters – use a text question and validate with Length -> is than or equalt to -> 10

Note that the conditions that you enter are the conditions that describe a valid value, and the error message is the message that appears when a user has done something wrong and the conditions are not met.

Check out the sample form to see how to prevent a future date from being added.

Calculations

media_1344537273867.jpg

The calculat ions field allows you to enter calculations using the questions bindings as a substitiute for the value. Calculations only work on the mobile client at the moment. To run calculations on the web form use the Javascript tab.

To help with the question bindings. click on Add Field and find questions these will then be added to the calculation field for you. You do not need = at the beginning of the row, like you do in excel. You can use mathematical operators like + * – to manipulate your values.

Javascript in Web Forms

Javascript Tab

media_1344524499712.jpg

The Web Form does not, as of 1.16.3, automatically handle calculations or complex skip logic. However, it is possible to add this functionality by using the Javascript tab.

It is beyond the scope of this book to give a tutorial on Javascript or traversing a DOM, please see other internet references such as http://www.w3schools.com for this.

Add HTML Ids for your form elements

media_1344526505995.jpg

The javascript tab, relies on identifying the elements of your form by Id. However, if does not use the bindings to do this, instead these must be set manually in the Design Surface.

  1. Select the Design Surface
  2. Select the element you are interested in
  3. Scroll down to the bottom of the Widget Properties window to find the Field Id
media_1344526645858.jpg

Once all the necessary id’s have been set, save your form, edit and save your javascript.

Test in the Preview Tab

media_1344526848283.jpg
  1. Right click in the Preview tab and hit Refresh if necessary

You can then test your javascript including using standard browser debugging tools like Firebug and console.log() if necessary.

Editing / Importing XML

XForms Source tab

media_1344521669452.jpg

This box is generally for more advanced users, or programmers comfortable with xforms. Be careful, you can break your form.

  1. Click on the XForms source to view the raw xform that you are creating
  2. You can edit the text in this box including copying in an entire new XForm
  3. Once you have made manual edits to your XForm, if you wish to save them, press the “Folder” or “Open” button – this saves your new XML to your database, you cannot undo this, there is no option to preview before you save.

Once you are more comfortable desgining forms, this can be a convenient way to make an extra backup of your xform while you are busy designing that does not involve exiting the form designer and using openXdata’s Export functionality

In addition, if skip logic and validation are doing unexpected things, you can learn to read the xform and check for any errors in this text box.

Designing Web Forms

Autogenerate layout

media_1344519714298.jpg

The first time you click on Design Surface, a form layout will be auto-generated for you.

If you have made some changes but want a new autogenerated layout:

  1. Right click in your form and press Select All
  2. Press Delete to Delete all widgets
  3. Press refresh button

Note, hand designing web forms can be tedious and time consuming. Where possible use the autogenerated layout to save yourself time when your form gets a new question later down the line

Use Palette to add items manually

media_1344519906196.jpg

Select the Palette for the left window to see the available graphical widgets that can be added to your design surface.

 

Use Widget Properties to edit widgets

media_1344520038694.jpg

Select the Widget Properties for the left window to edit all the parameters for the widget you have selected including tooltips, fonts, height and width

Select multiple items at once for a group edit

media_1344520208565.jpg
  1. While holding left mouse click down, drag an imaginary rectangle around a group of items – a dotted rectangle will appear
  2. You can then edit items in the left window and it will apply to all items

Use tool bar tools for tidying

media_1344520498522.jpg

The toolbar icons are explained in Introduction to the Form Designer

Use these to tidy your form

Guiding users through skip logic – options

If you have lots of skip logic in your form and want to hide questions from your users in a helpful way, there are a number of possible methods.

  • 1 – Hidden overlay
  • 2 – Fake Pages
  • 3 – Real pages

1/3 – Hidden overlay

This only works if your question sets are genuinely exclusive – that is there’s no chance that the will appear on top of one another.

To do this:
1) Set your questions to visible and have openXdata autogenerate a layout for you.
2) Set your questions to not visible and make sure your skip logic is set – to show and make required depending on a previous answer
3) Go to form layout, select the questions in the second batch and drag them over the questions in the first batch. Then repeat for the questions in the third batch so that all the questions are on top of each other.

Pros – this method makes it easy for users to enter data & works nicely on phone
Cons – this method is time consuming to change the form

2/3 – Fake Pages

In this method we keep the questions as one long list, but we add fake pages on the web capture.

To do this:
1) Set your questions to visible and have openXdata autogenerate a layout for you.
2) Set your questions to not visible and make sure your skip logic is set – to show and make required depending on a previous answer
3) Return to form designer and with cursor highlighted at the top, right click and “Add Tab” – add as many tabs as you need
4) On the first page, select the questions for one tab, right click and “Cut”, go to the new tab and “Paste”
5) Save when complete.

You’ll notice that when you try and press submit on the first page you get thrown to the tab with required questions.

Pros – this will still work nicely on the phone
Cons – using the form designer like this can sometimes be a little buggy, I’ve had the occasional ugly error with manually adding tabs

3/3 – Real Pages

We use openXdata’s built-in page function to generate pages for us.

To do this:
1) Add your questions to individual pages – you make a new page by selecting Page 1 and clicking Add New
2) Leave the questions as visible
3) Go to Design Surface and openXdata will autogenerate a layout with tabs and with the questions on
4) Return to properties and set the questions as hidden and add skip logic.

Pros – uses openXdata’s functionality to build a tabbed layour
Cons – does not translate well on a phone – a user will have to go through a series of blank pages to find the ones with questions

Adding Single Select Dynamic

Create Single Select Dynamic question

wpid1456-media_1344518349718.jpg
  1. Create a single select question with two or more options
  2. With your Single select question selected, press Add New as normal to add a new question
  3. Question 3 appears, select it
  4. Change the Question type to Single Select Dynamic
  5. The Dynamic Lists tab will automatically pop-up
  6. If you only have one Single Select question in your list it will be pre-populated here
  7. The first option of the selected Single Select question is automatically displayed

(Note Single Select Dynamic questions cannot be used inside a repeat question)

Changing the Question that is being referred too

wpid1457-media_1344518782420.jpg

A Single Select Dynamic Question can refer to another Single Select Dynamic question or to a Single Select question to get the value on which to filter its own list.

To edit the question that is being referred to, click the question title that is written in link style between "…the answer for:" and "is equal to…"

On doing this a text box appears, delete the text in the text box and start typing the Question Text of the question you wish to refer to. the Form Designer will present a list of all valid choices.

Add your new options under each old option

wpid1455-media_1344519130114.jpg
  1. Ensure you are on the correct option
  2. Click Add New
  3. Enter the Option values – Text (the binding will be automatically generated, but you can change to any valid binding)

You can also use delete and up, down to move the options around

Repeat this for each of the options in your original question

Sample Form Example

Look at the standard sample form example that comes with openXdata. That has Single Select Dynamics that

  • select Country (from Single Select question Continent)
  • then select District (from Single Select Dynamic question Country)

Question Types Explained

The best way to understand the different question types is to open up the Sample Form which has a question of each type

Text

A text field. Allows you to enter free text as the data input.

The mobile and web client will allow you to enter as much text as you want, and it will get saved to the database. However, you will not be able to process responses greater than 255 characters (i.e. you will see the red warning for unprocessed data and you will not be able to see your responses in the Dashboard). See Known Issues for further information.

Number

Accepts integers or whole numbers – so 1235 is valid but 12.23 is not. Negative numbers are accepted. Only ne

There is a limit to the size of integer accepted that is documented here as with Text a number longer than 10 digits will be accepted and saved, it just can’t be exported by default.

Decimal

Accepts numbers including numbers with decimals like 123.345

Date

Accepts a date.

On the mobile client, a prompt with a Select Day option will be available that takes the user to a calendar, the exact format depends on your phones settings
On the web form, a pop-up calendar will appear

The display and submit Date Format can be changed through the Admin Console -> Settings

Time

Accepts a time.

On the mobile client the format is HH:MM or HH:MM AA (where AA = am or pm) – depending on your phone settings
On the web form the format is HH:MM:SS AA

The display and submit Time Format can be changed through the Admin Console -> Settings

Date and Time

Both Date and Time must be recorded for one question answer

Boolean

Yes / No – user must select one or the other. Using this is the same as creating a Single Select question with two options "Yes" and "No." It is a useful shortcut for english forms, but as the Yes and No are not editable it is not useful for non-English forms.

Single Select

Add a series of options to this question type and the user can only pick one.

On the mobile phone it is presented as a list with a "radio" button
On the web form it is presented as a dropdown box

Multiple Select

Add a series of options to this question type and the user can pick as many as they want

Repeat

A repeat question contains a group of questions that can be repeated multiple times. Clicking Add Child will add a new question. In a web form, repeats are shown by default as rows of a table where new rows can be added
On the mobile client, the option New is available which takes the user into a new list of questions, this can be repeated as many times as necessary

Tip: it is possible to validate the "length" of a repeat question to see how many rows or sets of answers you have – see the sample form for an example.

Picture

Image question

On the mobile phone this accesses the phones camera funcitonality
On the web capture, this allows the upload of a picture

Video

Video question – video format must be 3gp

On the mobile phone this accesses the phones camera in movie mode
On the web capture, this allows upload of a file – it does not check on upload whether the file is the correct format or not.

Audio

Audio question – audio format must be 3gp

On the mobile phone this accesses the phones microphone
On the web capture, this allows upload of a file – it does not check on upload whether the file is the correct format or not.

Single Select Dynamic

Single Select Dynamic questions present a shortlist of a longer list of options, based on answers to previous questions. Single select dynamic questions require a Single Select Question to be present before they can be used.

A simple example is to narrow down a list of countries by first selecting a continent. The continent question would be a standard single select question. The country question would be a Single Select Dynamic question. You add all the countries of the world, but you map them to a continent. Once the user has selected a continent, only countries in that continent are displayed.

Single Select Dynamic questions appear like Single Select Questions

There is no limit to the nesting of Single Select Dynamic questions
e.g. to narrow down all the pupils in school in the entire world:
Continent -> Country -> District -> Village -> School -> Teacher -> Pupil

GPS

Get or enter the GPS co-ordinates (longitude, latitude, altitude) for a place

On the mobile phone, if GPS functionality is available it will launch the GPS to get the current location. If GPS functionality is not available it will present three windows to enter the data

On the web form, a single text box is presented which doesn’t validate that the input is a valid GPS co-ordinate.

Barcode

Not implemented in 1.16, but available in ~1.18 onwards

On the web form it just presents a free text box.

On the mobile client, if you have the -barcode midlet which includes a barcode reader, the barcode reader is launched which then uses mobile phone’s camera to take an image and process the barcode.

Adding Questions

REMEMBER – In the Form Designer, if you didn’t press Save it isn’t Saved

Blank Form

wpid1438-media_1344493456450.jpg

When you first design a form the form designer will open like the above picture.

Note the extra fields Description Template and Form Key that appear when you select a Form in the left window as opposed to a question.

The Description Template is used to display more meaningful list of forms to a user on the mobile phone. For example, if they are collecting data in the Sample Form and there is nothing in the Description Template then, on the phone, each form will be given a default name "Data1", "Data2" and so on.

However, you can use the description template to display a field from the form such as "Last name" or "Patient ID" so the list of saved data could read: "Smith ID 123", "Jones ID 345" etc.

Add First Page and Question with Add New Child

wpid1434-media_1344493841487.jpg
  1. With the Form selected, press the Add New Child Button
  2. The Form Designer will automatically add your first page and first question

Add Another Question

wpid1436-media_1344493978071.jpg
  1. Click on Question 1 so it is highlighted
  2. Click Add New
  3. Another Question will appear

Add question options

wpid1435-media_1344494245762.jpg
  1. Change your question to a question type that accepts options – Single Select, Multiple Select
  2. Ensure the Question is Selected
  3. Press Add New Child to add an option.

If you press Add New when the question is selected, then if will add another Question not an option.

You can keep pressing Add New Child to add as many options you like. Or you can select the option and then press Add New to add more options (because now you are at the Option level not the Question level)

Add another page

wpid1437-media_1344494671603.jpg

Pages are useful to group sets of questions. Pages are like tabs on the web view and are seperate lists of questions on the mobile client.

  1. Select the Page you wish to add a new page after
  2. Click Add New
  3. Your new page will appear

Save and Refresh often

wpid1439-media_1344494746668.jpg

If you have not pressed (1) Save, your changes have not been Saved.

If you press (2) Refresh before you press Save your form will be restored to what is currently saved on the server. This can be useful for undoing some changes if sometihng went wrong.

Video from older version

This video from an older version of openXdata still applies covering all the principles of adding questions to a form:

(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.