Control File: Project Information

project-name

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.

author

This field is optional but is highly desirable to use. The author field is displayed below the survey name on the home screen.

author-email

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.

subject-id

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.

can-test

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.

placeholder-message

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

compliance-display

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.