Control File: Survey Information

This page describes the new Control File format, which allows the creation of multiple surveys in one project. Please note that projects currently underway may still use the older Control File format. The old format will still work until July 2022. Any surveys imported prior to that date will still continue to work but no new surveys which use the old format will be able to be imported from that future date. If you are using the old format, please refer to the old format instructions.

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 Sunday and Monday 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

The position line determines if the survey should run before the scheduled surveys begin or after all scheduled surveys are finished.

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 can be a scheduled survey or a run-once survey.
  • If the survey is a scheduled survey it will also run at the scheduled times.

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 3 seconds use the following line.

exit-message|3|

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|3|Thank you for trying the PIEL Survey.

exit-message|3|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.

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

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.