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.
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.
name|PIEL Sample Survey
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.
The default survey type for the PIEL Survey is a scheduled survey. However, this can be changed.
The "can-run-once" 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 code creates a scheduled survey.
can-run-once|0
Please note that if "can-run-once" is disabled, or is not set, the survey will be run as a scheduled survey and a schedule must be included in the file.
The following code creates a contingent survey.
can-run-once|1
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.
The "start-day" line specifies the day of the week when the survey schedule will commence and is optional. Once a participant taps the "Start" button, the placeholder screen will be shown until the first scheduled survey is due (on the specified start day).
If a start day or start-date is not specified, the schedule will start the same day the start button is tapped if there are no scheduled surveys for that day prior to the time the button was tapped. If the first survey for that day is in the past, the schedule will start the next day there are surveys scheduled.
Ensure that the survey has a "run-for" specification that is long enough to reach the days required no matter when the participant taps the "Start" button. Usually a "run-for" of at least 7 is used.
If you require the schedule to run on a specific day of the year, you should use "start-date" rather than "start-day". You cannot set both a "start-day" and a "start-date".
The "start-day" is a number from 1-7. The week starts on Monday, specified as 1. Sunday is specified as 7. The following specification will start the survey on a Monday.
start-day|1
The "start-date" line specifies the date 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" or "start-day" is not specified, the schedule will start the same day the start button is tapped if there are no scheduled surveys for that day prior to the time the button was tapped. If the first survey for that day is in the past, the schedule will start the next day there are surveys scheduled.
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.
Also ensure that the survey has a "run-for" specification that is long enough to reach the days required. Usually a "run-for" of at least 7 is used.
Before using "start-date", check to see if "start-day" is more suitable for your needs as it is easier to test and use. You cannot set both a "start-day" and a "start-date".
Note that the format of the "start-date" is "dd/mm/yyyy".
start-date|16/09/2019
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
This line specifies 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 that day, 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.
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
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
This section explains how to control the behaviour of the survey.
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.
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 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.
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
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.
The following sounds are available.
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
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 on the control file can be found at the following links.