Control File: Structure

Creating the Control File

The Control File is a text file which prescribes the content and scheduling of a survey or multiple surveys. This file can also include contingent surveys which can be triggered by the research participant during the survey schedule. When imported into the PIEL Survey app, the control file creates a project 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".

Further Information

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