Control File: Project Information

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 survey information.


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.

author|PIEL Administration


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

Further information on the control file can be found at the following links.