Control File: Survey Information

Please note that the Control File now has a new format. This new format is more flexible in allowing multiple surveys. Researchers should use this new Control File format for new research projects. The old format will still work until the end of June 2022. Any surveys imported prior to that date will still continue to work but no surveys using the old format will be able to be imported from that future date.

Identification

This section explains each of the lines in the first part of the Control File. Many of these field names are case-sensitive. Keep them in lower case.

name

This field is optional but is highly desirable to use. The name field is the name that will be displayed on the PIEL Survey App home screen. It will also be displayed prominently on the Placeholder Screen (the screen that appears in between scheduled surveys).

We suggest that you do not give the survey a name that might be regarded as sensitive or private by participants.

name|PIEL Sample Survey

author

This field is optional but is highly desirable to use. The author field is displayed below the survey name on the home screen.

author|PIEL Administration

author-email

The author-email field is the address to which a survey project will be emailed at its completion. If you do not specify an email address, the participant will need to add it manually before sending the data file. Please take care to ensure that the email address is correct to avoid errors in sending the data file. As mentioned previously, we highly recommend that you test the survey, including sending data files before using the survey with participants.

author-email|contact@contact.com

subject-id

This line allows the allocation of a unique identifier to each participant’s survey and is recorded as a field in the output file. If you don't include a Subject ID, the PIEL Survey will ask for an ID when it runs the survey. You should enter a subject-id if you don't want the participant to be asked to enter an ID.

Note that the subject-id can be 200 characters long and can include numbers and letters and other characters. The subject-id is used as part of the data file name so if necessary will be truncated to 20 characters and some characters replaced by a hyphen to make an acceptable file name. The subject-id in the data file will be the original unaltered subject-id.

subject-id|0001

Schedule

This section explains how to schedule multiple runs of the survey.

start-date

This line specifies when the survey 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 survey will start either the same day the schedule is started (if there are no scheduled for today prior to the start time) or the following 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.

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

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

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 a random time between 9:00am 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|0900-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)

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

Behaviour

This section explains how to control the behaviour of the survey.

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.

can-test

Enabling this feature will allow testing of some features such as the alert sounds, max-delay, exit messages and survey questions after the Control File is installed into the PIEL Survey. A value of "1" enables "can-test" and "0" disables it.

If no value is set, testing is enabled by default.

can-test|0

can-test|1

The screenshot above shows a survey with "can-test" enabled. This can be seen by the enabled "Test" button.

This setting is of most use for a scheduled survey. For a scheduled survey, tapping the test button will send a notification in 10 seconds. The 10 seconds allows time to put the app into the background and wait on the notification. The survey will start when the user taps the notification or the app icon. Please note that in versions older than iOS 10, notifications are not received when the app in the foreground.

We recommend that "can-test" be disabled for the actual research project.

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

placeholder-message

This is an optional line in the survey. This line specifies the message that appears on the screen when a scheduled survey commences or if participants peek at the App in between survey runs (see following screenshot).

placeholder-message|Nothing for now, thank you for checking!

compliance-display

This is an optional line in the survey. This line determines the display shown to the participant during a scheduled survey series while waiting for the next survey. We expect that other options will be added over time as users provide feedback.

A value of "1" will show how many surveys have been answered as a percentage of all scheduled surveys (past and future).

compliance-display|1

A value of "2" will show how many surveys have been answered as a percentage of all scheduled surveys in the past.

compliance-display|2

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