Control File: Structure

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 July 2022.

Creating the Control File

The Control File is a text file which prescribes the content and scheduling of a survey. When imported into the PIEL Survey app, it creates a survey that can be seen on the app's home screen.

Save the file created in Notepad (Windows) or TextEdit (Mac) by creating a ".survey" extension. In the “Save as type” box, select “All Files”. In the Encoding box, select “UTF-8”.

Some software may try and add a different suffix (e.g. TextEdit will ask about this when saving). Make sure it is saved correctly. If there is a problem, you may need to edit the name in File Explorer or Finder by enabling the display of file suffixes.


There are some simple syntax rules which must be followed when creating a control file.

  • Each command is placed on a new line.
  • Many commands are optional, often having default values. This will be described in the following text.
  • A vertical bar "|" (usually located above the enter key) is used in the Control File to separate its different components. Do not use "|" at the beginning or end of a line. You do not need any spaces before or after this separator.
  • Do not use the symbol “%” followed immediately by a letter in the text of questions.
  • You can put comment lines in a Control File by inserting # in front of each line. # stops these lines from being read as a command.
  • Delete a Control File line by simply removing it or alternately by inserting # in front it. This second option is useful if there are lines that might be needed later. Rather than repeatedly deleting and reinserting lines, simply add or remove # at the front of the line.

Sample File

Below is a sample Control File. Use this sample as an easy way to develop your own Control File. You should edit it to insert your own email address on line 3.

Please note that because it has the line "can-run-once|1", it will not run as a scheduled survey (even though a schedule has been put in the file as an example). To allow the schedule to work, change this line to "can-run-once|0".

name|PIEL Sample Survey

author|PIEL Administration











exit-message|3|Thank you for testing the PIEL Survey.

placeholder-message|No questions for now, thank you for checking!


#Below are the questions. Integers indicate the question number

1|How did you hear about the PIEL Survey?|From a colleague %NEXT 3|Internet Search %NEXT 3|Advertisement %NEXT 3|Reading a review/blog %NEXT 3|In the Apple Store|Other

2|Please provide details of where you heard about the PIEL Survey. %TYPE text

3|Did you find the PIEL App easy to use? %TYPE slider|Difficult|Very easy

4|What features do you most like about the PIEL Survey? (you can choose more than one). %TYPE checkbox|Ease of use|Accessibility|It's quick|It's intuitive|It's on my iDevice|Other

5|How many times have you used the PIEL Survey. %TYPE list|First time|2-5 times|6-10 times|More than 10 times

6|Did you use our website before using this PIEL Survey? %TYPE list|Yes|No %NEXT 8

7|Please tell us what you found useful on the website and what you would change. %TYPE text

8|Will you use the PIEL Survey again? %TYPE list|Yes|No %NEXT END|Maybe

9|What type of questions will you use in your next survey? %TYPE checkbox|Button|Checkbox|Slider|Text

10|Do you have any more comments? %TYPE text

You might also find it useful to look at these examples of actual surveys.