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 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. If you are using the old format, please refer to the
old format instructions.
Each control file must contain the project information at the top of the file.
This information provides the project identification and controls the behaviour of the project. This section is followed by the
This section contains information needed to identify the survey, the researcher and the survey data.
This field is optional but is highly desirable to use. The project 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 project a name that might be regarded as sensitive or private by participants.
project-name|PIEL Sample Survey
This field is optional but is highly desirable to use. The author field is displayed below the survey name on the home screen.
The author-email field is the address to which a project's surveys 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.
This line allows the allocation of a unique identifier to each participant’s surveys and is recorded as a field in the output files.
If you don't include a Subject ID, the PIEL Survey will ask for an ID when it runs the first 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.
random subject id
Rather than manually inserting a Subject Id in each control file, you can choose to insert a random number as the Subject Id by inserting the keyword "%RANDOM"
(see the example below). This will ensure that all surveys sent from a particular device will have the same random number as the Subject Id in the data file and
in the data file name itself. This number will remain the same unless the app is deleted and reinstalled.
Note that the participant cannot be identified using this random number. The only way to link the data to a particular participant is through direct contact with the participant,
such as by the email used to send the data.
This section explains how to control the behaviour of the project.
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.
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.
If the project has more than one scheduled survey, notifications will be sent for each survey in alphabetical order,
with 1 minute delays. This allows time to answer a survey and wait on the next notification.
We recommend that "can-test" be disabled for the actual research project.
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!
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.
A value of "1" will show how many surveys have been answered as a percentage of all scheduled surveys (past and future).
A value of "2" will show how many surveys have been answered as a percentage of all scheduled surveys in the past.
Note that the number of surveys used in this calculation does not include surveys that are
set to run at the beginning or the end of all the scheduled surveys. The excluded surveys have their
"position" attribute set as 1 or 2.
Further information on the control file can be found at the following links.