Control File: Structure

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.

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.

Layout

The control file consists of project settings and individual survey settings. The project settings should be at the top of the file followed by the survey settings. Each survey should commence with the keyword "%SURVEY" on a separate line. You can have multiple surveys in one file.

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

  • Each command is placed on a new line.
  • Keywords are case sensitive. Make sure you use the same upper and lower cases as in these instructions.
  • 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 4.

For simplicity, this example only contains one survey.

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".

#This section contains the project information.

project-name|PIEL Sample Project

author|PIEL Administration

author-email|contact@contact.com

subject-id|0001

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

can-test|1

#

#The next section contains the surveys.

#

%SURVEY

name|PIEL Sample Survey

max-duration|600

max-delay|180

run|7|1915,1920,1925

run|1|0900-1200,1500,1700-1900

run|2,3,4|1300-1600

run-for|7

can-run-once|1

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

alert-sound|005

#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.

Further Information

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