How to create surveys in MyOSCAR

[This blog is an adaptation of the original document written by Pavel Antiperovitch in September 2009. The more technical document is now contained in the official OSCAR User's Manual site.]

The MyOSCAR Survey Module was built to read a survey script file written according to the following instructions (which was derived from the programming standards of a MUMPS configuration file). The script file defines the survey questions and flow. The purpose of this document is to describe the format of the script file.

(I) The Header
The header of the script file contains several global parameters.  For example:

.title=Diabetes Risk Survey
.instances=1
.hidden=false

The following Table contains a list of global parameters.

Property	Values	Default	Explanation
.title	text		Title of the survey as it will show up in the drop-down list menu.
.instances	number (integer)	65000	A number of surveys each user can fill out.  If one-time survey, enter "1".  Once the survey # has been reached by the user, it will no longer appear in the drop-down menu.
.menuhidden	true/false	false	Indicates whether the survey will appear in the menu.  If "false" is selected, it will not appear in the menu and the users must have the link to the survey to fill it out.  This is useful if a research investigator wishes to e-mail out links to surveys at specific time points in the study.
.progressbar	true/false	true	Indicates whether the question progress bar is displayed in the survey.
.geomapping	true/false	false	Turns the geomapping module for the survey on/off (to map responses geographically).  This was used in the pandemic surveillance survey.
.booleanResultStatement	statement that evaluates to true or false		This allows the result for each survey to be rendered as true or false.  For example:  (A1.size()>=3) means that question A1 must have at least 3 items checked off.  This was used in the pandemic surveillance survey to indicate that the user must check off at least 3 symptoms to be classified as "true" for having the infectious disease.

(II) The Body
The body of the script file consists of a series of questions, where the beginning of each question is marked by a line starting with '.qu='. The following is an example of the question block:

.qu=E3a,type=select
Do you have any difficulty walking up 10 steps?
 
.an=1
1 = No
2 = Yes
3 = No longer do this due to the difficulty of doing it
4 = No longer do this, but reasons are not related to my health
5 = Never did it
6 = Don't know / refused
.lo=1
.hi=6
.if (E3a = 1) E3c
.if (E3a = 2) E3b
.if (E3a = 3) E3e
.if (E3a = 5) E4a
.if (E3a = 6) E3c

.next=E3b

The following are explanations of each of the above script line:
.qu=E3a,type=select 
*Required*
".qu=" indicates the start of the question; "E3a" is the question identifier (only alphanumeric characters are allowed - keep this short and simple, no spaces!)
"," separates the properties
"type=select" defines the answer to this question type as "select" (see below for possible question types).

Do you have any difficulty walking up 10 steps?
*Required* 
This block defines the actual question text.  You can use HTML to add various font properties or images.  The question block is always terminated by the ".an" line.  When the text is displayed the rendering survey engine puts <br> (enterspaces) in the html, so if you put multi-line html and javascript, you must escape it with <%--   your stuff here      --%> otherwise your code/html will be interspersed with <br> tags.

.an=1

*Required*

".an" stands for "answer", and indicates the start of the answer block. If the question shows the participant a list of choices, they would be listed underneath

1 = No
2 = Yes
3 = No longer do this due to the difficulty of doing it
4 = No longer do this, but reasons are not related to my health
5 = Never did it
6 = Don't know / refused

This block defines the answer choices, and is only applicable for question types "check" and "select". This is ignored for all other question types. Each choice consists of two parts: the identifier and text, separated by ' = '. The identifier is an integer that will be used to reference the answer choice in 'if' statements (see below), and the text is the part seen by the survey participant. Note that the identifier is optional, and defaults to incrementing numbers starting with 1. However, including the identifier is considered good form.

.lo=1
.hi=6

This defines integer answer validation, where .lo and .hi indicate the lowest and highest allowed integers respectively. To avoid problems, it is advisable that this is included ONLY for questions of type "number" (otherwise using these properties makes no sense).

.if (E3a = 1) E3c
.if (E3a = 2) E3b
.if (E3a = 3) E3e
.if (E3a = 5) E4a
.if (E3a = 6) E3c

This is the 'if' statement block that defines the survey question flow. In this example, E3a is a question identifier. The answer to each of these questions is mathematically compared to the value using operators such as =, >=, <=, <, >, @. 
If the condition is true, the survey jumps to the next question specified at the end of the line. For instance:
- The first statement is interpreted as "if answer to question E3a is '1', go to question E3c".
These 'if' statements are executed in order as defined. If one evaluates to "true", all the other ones are ignored.
- If the question is of type "check", it holds multiple answers. In this case the operator '@' must be used to symbolize "contains". For example, 

.if ((E3a @ 3) and (E3a @ 4)) E4a
.if ((E3a = 1 or E3a = 6) and (E3a = 1 or E3a = 3 or E3a = 4)) E4a

if the 1st statement reads "if the answer to question E3a contains 3 and 4, then go to question E4a"

.next=E3b

*Required* This defines the next question if the 'if' statements are missing, or all evaluate to 'false'. In this case, ".next" indicates that the next question in the configuration file is displayed. Optionally, the question identifier can be specified to direct the survey to go to a different question (i.e. ".next=E3c")

CAUTION: Make sure that the questions in the condition of the 'if' statement have been asked before. If the question appears in an 'if' condition that has not yet been asked, the survey module shows an error at runtime.

The following question types are curently supported:

• void - the question does not require a response. This is useful for displaing information such as introduction and conclusion instructions

• number - the user enters an integer answer.

• string - the user is given a textbox to type words or sentences.

• select - the user is given a series of options to select from (can select only ONE answer)

• check - the user is given a series of checkbox options to select from (multiple selection allowed)

• decimal - the user is given a small text box and value is stored as a decimal

DO's and DON'T's: If you must ask the user the same question more than once, copy + paste it under a different ID (don't make this more confusing that it has to)

Examples:

.title=Risk Profile Recording Form
instances=1

.qu=intro,type=void
This form will ask you a series of questions about your cardiovascular
health.  For each question, please select or type the appropriate response
and press "next".  You may exit the survey by clicking "Save and Close", and
return to it later by signing into myOSCAR and clicking the 'Surveys' link on
the left hand-menu.  The survey will save by default every 3 questions.
.an
.next

.qu=E1,type=select
Is this a repeat visit?
.an
1 = Yes
2 = No
.if (E1 = 1) finish
.next

.qu=E2,type=select
In general, would you say your health is:
.an
1 = Poor
2 = Fair
3 = Good
4 = Very Good
5 = Excellent
.next

.qu=E3,type=number
What is your height in cm?
.an
.lo=0
.hi=500
.next

.qu=E4,type=number
What is your weight in kg?
.an
.lo=0
.hi=1000
.next

.qu=E5,type=select
Have you ever had a transient ischemic attack (TIA or mini-stroke)?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E6,type=select
Have you ever had a stroke?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E7,type=select
Have you ever had a heart attack?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E8,type=select
Has your doctor told you that your cholesterol is high?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E9,type=select
Has your doctor told you that you have diabetes?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E10,type=select
Have you ever been diagnosed with high blood pressure by a doctor?
.an
1 = Yes
2 = No
3 = Not Sure
.next

.qu=E11,type=select
Are you currently taking prescription pills for high blood pressure?
.an
1 = Yes
2 = No
3 = Not Sure
.if (E11 = 1) E12
.next=E13

.qu=E12,type=select
Do you take pills for high blood pressure each day?
.an
1 = Yes
2 = No
.next

.qu=E13,type=select
Do you currently smoke?
.an
1 = Yes
2 = No
.next

.qu=E14,type=select
In a typical week, how many times do you eat high fat or fast foods?
.an
0 = Zero
1 = 1-2
3 = 3 or more
.next

.qu=E15,type=select
Typically, do you drink 2 or more alcoholic drinks a day?
.an
1 = Yes
2 = No
.next

.qu=E16,type=select
Do you eat 5 servings or more of fruits and vegetables a day?
.an
1 = Yes
2 = No
.next

.qu=E17,type=select
How frequently do you add salt to foods during cooking or at the table?
.an
1 = Rarely
2 = Sometimes
3 = Often
.next

.qu=E18,type=select
In a typical week, how frequently do you feel overwhelmed or stressed?
.an
1 = Rarely
2 = Sometimes
3 = Often
.next

.qu=E19,type=select
Are you moderately physically active for 30 to 60 minutes, most days of
the week? (e.g. brisk walking, active gardening, swimming, dancing or biking)
.an
1 = Yes
2 = No
.next

.qu=E20,type=select
Do you live alone?
.an
1 = Yes
2 = No
.next

.qu=finish,type=void
Thank you for completing this questionnaire.
Click "Next" to save your answers and exit.
.an
.next