A Control File can contain multiple surveys. These surveys should be listed below the project information.
Each survey must start with the following line.
%SURVEY
Each survey should provide information relating to identification and behaviour of the survey. These are detailed below.
This information is then followed by the survey questions.
If using multiple surveys, the settings for each survey schedule are independent of the other surveys.
Identification
name
This field is optional but is highly desirable to use. The name field is the
name that will be used as part of the data file name and will be inserted into the data file so the data can be related to the correct survey.
If there are multiple surveys, each survey name should be unique.
The PIEL Survey app will alter the name slightly if they are not unique but for ease of identification by the researcher,
we recommend that a unique name be given in the Control File.
name|PIEL Sample Survey
Schedule
This section explains how to schedule multiple runs of the survey. If you are using multiple surveys, the schedule of each survey is independent.
You can run surveys on different days and even start surveys on different days.
If you are using multiple scheduled surveys, care should be taken to ensure the schedules of different surveys do not conflict
or are too close together.
start-date
This line specifies when the survey schedule will commence and is optional. The date must be in the future and
the participant must initiate the scheduled survey ahead of the start date.
The placeholder screen will then be shown until the first scheduled survey is due (after the specified start date).
If a start date is not specified, the schedule will start the same day the start button is tapped
if there are no scheduled surveys for today prior to the time the button was tapped. If the first survey for today is in the past,
the schedule will start the next day.
Take care to ensure that participants know to start the survey before the start date.
If they try to start the survey late, they will get an error
and be prompted to contact the researcher for instructions. This is designed to ensure data consistency.
While testing, it is often best to not set a start date as it would otherwise need continual updating as tests are carried out
on different days.
Note that the format of the start-date is "dd/mm/yyyy".
start-date|16/09/2019
can-run-once
The default survey type for the PIEL Survey is a scheduled survey. However, this can be changed.
This option allows the survey to be run on demand. This feature is sometimes called event contingent sampling.
A value of "1" enables the "can-run-once" feature and a value of "0" disables it. The following screenshot shows a survey
that has "can-run-once" selected. The green "Start" button shows this in the text "Start Run-once Survey".
If "can-run-once" is disabled, the text displayed will be "Start Scheduled Survey".
Please note that if "can-run-once" is enabled, the survey can be manually started as many times as you want, but once each time.
Even if a schedule is specified, a scheduled survey will not run unless this option is disabled.
If "can-run-once" is disabled, the survey will be run as a scheduled survey and a schedule must be included in the file.
If no value is set, "can-run-once" is enabled by default.
can-run-once|0
can-run-once|1
max-delay
This line specifies how long the participant has to commence a survey once they receive the notification that a survey is due.
It is in seconds (300 is equivalent to 5 minutes).
If the survey is terminated by the expiration of the max duration, any data will be saved and the survey will finish.
If more surveys are due, the PIEL Survey will show the placeholder and wait for the next survey.
If you use this setting, we advise that you explain to participants that the survey will only run if it is opened before the max delay time.
This setting is optional.
max-delay|300
run
This line specifies explicitly on which days of the week and at what times notifications are sent to prompt the completion of the
survey. There may be multiple times per day and multiple run lines per survey, allowing each day of week to be configured differently.
Surveys can be set to run at fixed or random times during a set time interval or can be set to use a combination of both fixed and
random sampling.
The week starts on Monday, specified as 1. Sunday is specified as 7. An asterisk (*) is used to denote “on all days",
indicating that the survey should be identically scheduled on all 7 days of the week.
Use a 24 hour clock (no punctuation e.g. 1230, not 12:30).
For example, to run a survey every day at 3:11pm (1511)
run|*|1511
If the same schedule is used on multiple days, separate the days with a comma. For example,
to run on Monday and Tuesday at 7pm, 7:30pm and 8pm.
run|1,2|1900,1930,2000
You can have multiple "run" lines if you want the survey to run a different times on different days,
The following lines in the control file will create a schedule to run for 7 days.
It will run at 9:00am on Monday and 10:00am on Tuesday. It will also run every day at 5:00pm.
can-run-once|0
run-for|7
run|1|0900
run|2|1000
run|*|1700
It is important to note if a participant starts the schedule after the first scheduled time for today,
the first survey notification will be on the next day for which there is a schedule.
For example, if the above survey schedule is started after 9:00am on Monday, the survey will not start until Tuesday.
If this occurs, the first Monday on which a notification will arrive will be next week.
If you want a survey to be run on a Monday, you must either allow at least 7 days to reach Monday next week or start the schedule before 9:00am on Monday.
If you want it to run on a specific Monday, ensure that participants start the survey before the first schedule or else have a "start-date" in the future.
Note that a scheduled survey will not start if the "run-for" period is not long enough for the app to reach a scheduled time in the future.
Schedules can also be set for random times. If multiple randomly timed surveys are desired within a specific time period,
it is best to break up the time period into shorter chunks and schedule an alert for each of these shorter periods.
This saves alerts falling on top of each other or running into each other. E.g., schedule 3 random runs on Monday between 9am and 2pm.
The following example ensures the minimum time between runs is one hour. Some researchers only allocate 5 or 10 minutes between chunks of time.
run|1|0900-1000,1100-1200,1300-1400
You can also combine fixed and random schedule times.
The following lines from the sample survey indicate both fixed and random sampling.
run|7|1915,1920,1925 #(fixed)
run|1|0900-1200,1500,1700-1900 #(fixed & random)
run|2,3,4|1300-1600 #(random only)
Researchers should pay close attention to the timing of schedules, particularly when using random times and multiple surveys.
If schedules are too close together, it may annoy participants and affect compliance.
run-for
This line specifies how many days the surveys run, starting from the date the survey starts.
In the example below, the schedule will run for 7 days. The start day will be the same day the schedule is started by the participant
if no schedules for that day have been missed. Otherwise, the start day will be the next day (this ensures no missed schedules).
There is effectively no limit to the number of days a survey can be programmed to run.
In most cases, the "run-for" setting should be at least 7 days to ensure all schedules can be run at least once,
no matter what day the schedule was started by the participant.
run-for|7
reminders
This feature will send a local notification using the same sound as the normal notification.
The text of the notification will identify it as a reminder. Once the survey is answered,
any other reminders for that scheduled time will be deleted to avoid annoying the participant.
Although there is no specific limit, we recommend that you do not add too many reminders.
Typically, 1-3 reminders will be effective. This setting is optional.
Please note that reminders cannot be set later than the max-delay (if it is set).
Reminders are set using seconds. For example, the following line in
the control file will set reminders for 5 and 10 minutes.
reminders|300,600
Behaviour
This section explains how to control the behaviour of the survey.
position: first/last
The position line determines if the survey should run before the scheduled surveys begin or after all scheduled surveys are finished.
This setting can only be applied to run-once surveys.
The following line set the survey to run at the beginning of the project. This survey will run immediately on starting the project and before the
placeholder screen is displayed. This is often useful to remind the participant of instructions for the survey project or to get baseline data.
position|1
The following line set the survey to run at the end of the project. This survey will run immediately after the last scheduled survey.
This is often useful to get feedback or comments about the survey project.
position|2
Please note the following.
This feature assumes that there is at least one scheduled survey in the project.
The survey which runs first or last should be a separate run-once survey to avoid confusion with the resulting data.
position: contingent survey
A run-once survey can also be initiated by the participant during a survey schedule (a contingent survey).
One or more surveys can be contingent surveys and they will be shown on the placeholder screen to allow participants to
initiate the survey when certain events occur, as instructed by the researcher.
For instance, there could be a survey to answer when the participant wakes.
This can be enabled using the following lines in the survey control file.
can-run-once|1
position|4
It is recommended that the survey be named in a way that makes the purpose clear to participants
random-ranges
Random ranges are preset sections of the survey that will be in random order.
Multiple sections of the survey can be randomised. The example below will randomise the order of questions 3 to 8
and 10 to 15. The ranges are inclusive of the beginning question and ending question.
random-ranges|3-8,10-15
Please note the following.
The order of these questions will be randomised by the app each time the survey is run.
The order of the questions in the data file will be the same as in the control file. That is, in order of the
question numbers.
To avoid unpredictable behaviour, no branching into or out of a random range is allowed.
exit-message
This is an optional line in the survey. This line specifies the text displayed on the screen following the last question
(see following image). Its length is specified in seconds. For instance, to show the message "Thank you for trying the PIEL Survey."
for 5 seconds use the following line.
exit-message|5|Thank you for trying the PIEL Survey.
Multiple exit messages can be scheduled to show throughout the duration of a project.
There will be one exit message per survey run which will be chosen randomly from the selection provided.
Specify each message and its duration on a new exit-message line.
exit-message|5|Thank you for trying the PIEL Survey.
exit-message|5|Thank you for your participation
alert-sound
There is a small library of alert sounds that can be used with the PIEL Survey App.
If the alert-sound line is omitted, the default sound is the notification sound on the user's device.
Update Required
To play the media you will need to either update your browser to a recent version.
Specify the alert sound via: alert-sound|x where x is the number of the sound in the library. The following example shows how to specify the robot alert sound.
alert-sound|5
max-duration
This line specifies how long the participant has to complete the survey run once they have opened it.
It is marked in seconds (600 is equivalent to 10 minutes).
If you use this setting, we advise that you explain to participants that the survey may be cut short if they take too long to finish it.
This setting is optional.
max-duration|600
Further Information
Further information on the control file can be found at the following links.