A Survey is a type of Activity you can add to your study in Avicenna and is arguably the most common Activity participants do in a research study. Surveys share all features of Avicenna Activities, as we described previously, such as Triggering Logics, Notification Templates, and Criteria. If you have not reviewed these features already, we suggest you read about them first. In this section, we focus on features that are specific to the Surveys.
Each Survey consists of one or more sections, and each section also contains one or more questions. Sections are used to group different questions, either because they are conceptually relevant or to apply branching or loop iterations to them. Questions are the main building blocks of a Survey that is presented to the participant to enter their responses. The Avicenna app shows questions one by one to the participant. Participants will not see any notion of sections within your Survey while responding to it.
Surveys in Avicenna are defined using a Survey Definition File which is basically a plain-text JSON document. The file describes when the Survey should be prompted (the Triggering Logics), how the participant should be notified (the Notification Templates), what enables or disables a Survey (the Criteria), what sections exist in the Survey, what questions each section contains, what is the branching and skip patterns, and any other settings Avicenna supports for Surveys. All these settings are defined in a schema file called Avicenna Survey Schema. When you create a Survey Activity, you can either use Avicenna Research's Survey Editor or Survey Definition File and upload it as your Survey. If you create and upload a Survey Definition File, Avicenna first validates it against the Survey Schema to make sure all settings are entered correctly.
Versions, Import and Export
To create a Survey from your Survey Definition File, you can upload the file to the Avicenna website. To import your Survey:
Open Avicenna Researcher Dashboard and navigate to the Activities page.
Create New Activity.
Import a definition file.
Drop your Survey Definition File into the drop zone or choose your Survey Definition File from a directory on your computer. This will start validating the Survey Definition File.
Importto create your Survey using this file.
If the file is not valid, you will see an error. You can refer to JSON Content Validation for details on how to validate your Survey Definition File.
You can also import a Survey Definition File into your existing Survey. To do so:
Open the Survey Activity Editor for your desired Survey.
Preview & Publish, then
There you will see the list of versions for your current Survey.
On top of the versions, click on
Upload Survey Definition File.
You will see a similar Import dialog as above. You can upload a valid Survey Definition File there.
When completed, the content of the file will be loaded into your Survey as a draft. You can preview and then publish this Survey.
Every time you publish your Survey, a new version is created in Avicenna. You can
see the list of all versions in the
Versions tab, along with other information
such as when the Survey was published, who published it, and what was noted left
on that published version. For each version, you can click on
Download Survey Definition File to download the content of that version as a
Survey Definition File.
You also can click on
Load this version to load the selected version of the
Survey. This will create a new version of your Survey with the content of the
version you selected and set it in draft mode. For the last published version,
you'll find a
Revert to this version button instead. You can use that button
to discard your draft changes.
Survey Definition File Validation
Avicenna does not offer an advanced Survey Definition File validation. So if you try to upload a Survey Definition File that is invalid, you will just see an error saying the file is not valid, but no more details on what the issue is in the file.
To get more information on exactly what the problem is with the file, you can use external JSON schema validators such as this option. On this website, you can upload the content of the Avicenna Survey Schema on the left side and the content of your Survey Definition File on the right side. This will validate the content of the Survey and shows you any problems or errors:
Before publishing your Survey, it's important to check it thoroughly to make sure there are no issues. The Preview tab on the Preview & Publish page can help you with this. The following image shows what this tab looks like:
There are two sections on this page. The right side of the page shows a preview of the Survey. This preview can simulate exactly how the Survey flow will be in the Avicenna mobile or web app. From the top of the simulator, you can choose to preview a Desktop or Mobile view. This way, you can see how your Survey will look on different screen sizes.
The left side of the page shows the list of Criteria from other Surveys that impact the flow of this Survey. As we explained in the Criteria section, in Avicenna, you can define a Criteria for a section or a question based on the responses to questions from other Surveys in your study. The Preview tab detects such dependencies and loads those questions here on the left side. This allows you to try out the flow of the Survey using different assumptions.
For example, consider the previous image. Assume the Survey asks about the weight and height of the participant, and if they are females between 18 to 40 years old, it also asks if they are pregnant. So the flow of the Survey depends on the gender and the age of the participant, which is asked in another Survey. That is why on the left side, you can see Avicenna lists two questions, one is asking the participant's gender, and the next one asks the participant's age:
By default, these two questions have no answers. So the flow of the Survey
behaves as if the participant skipped responding to these questions. If you
answer these questions, Avicenna asks you to reload the Survey to see the changes
in the Survey flow. You can click on the dialog or click on the
in the top right corner to apply this change:
Any changes you make to the Survey will be saved in the Draft mode. This means while the changes are saved, they are not accessible to the participants (both test participants and real participants), and you may revert them if they are not satisfactory. To make them available to the participants, you need to publish your changes.
You can publish your Survey using the Publish tab of the Survey Editor's Preview & Publish page:
This section first runs validation on your Survey to ensure all settings are done correctly. If there are any errors or warnings, you can see them under the Activity Validation part. You must resolve all errors before you can proceed with publishing your Survey.
When all issues in your Survey are resolved, or if there are no warnings or
errors, you can press the
Publish button to publish your Survey. You can also
leave a note on this to document what changes were made as part of this
published version. This note will be available later on in the Versions tab.
Export Your Survey as a PDF
Avicenna allows you to export your Surveys in PDF format. Here is how you can do this:
- In your Survey Editor, go to the Preview & Publish page.
- If you have already published your Survey, go to the Versions tab. If not, you need to publish your Survey first.
- On this page, you can see the list of your Survey versions. They are sorted based on the Version number. To export a copy of your Survey in PDF, select the Download as PDF button from the version that you want.
Each Survey offers a set of additional settings. You can access these settings
by opening the Survey Editor, navigating to the Content page, and opening
Settings tab in the lower right corner. Below we describe each of these
This specifies the criteria for the Survey Activity. This acts as the main Criteria for the Activity and supersedes the Criteria set on the Triggering Logics. You can learn more about Activity and Triggering Logics Criteria in the Criteria Section.
You can randomize the selection of the sections within your Survey using the
options available in
Section Randomization. This feature allows you to choose
a subset of sections within your Survey using the
Included Section ID(s)
option and also choose a
Selection Count. Using this, besides the sections
that are not part of the
Included Section ID(s), only a subset of the
specified sections will be used to construct the Survey, where the size of the
subset is the same as the
For example, assume the Survey has seven sections, and the
Included Section ID(s) option is set to sections 3, 4, and 5, with a
Selection Count of 2. With these settings, sections 1, 2, 6, and 7 will always
be in the Survey, and from sections 3, 4, and 5, only two randomly selected
sections will be used to construct the Survey. For example, the sections shown
to the participant can be any of the following:
- 1, 2, 3, 5, 6, 7
- 1, 2, 4, 5, 6, 7
- 1, 2, 3, 4, 6, 7
Similarly, you can enable the
Random Section Order option. Doing so will
randomize the order of all sections of the Survey.
Please note that these randomizations happen only once for each Survey Session whenever the corresponding Survey is opened.
This option instructs Avicenna to capture the participant's location while answering a given Survey. When enabled, each response will be geo-tagged before storage.
Note that this option is different from using the Location Data Sources in your study. When you add a Location Data Source to your study, the Avicenna app will continuously capture participants' location, whether they are answering a Survey or not. Such data is stored separately from the Survey responses. While it is possible to join the data at a later stage to infer the participant's location at the time of answering a Survey, this is not done automatically by Avicenna.
On the other hand, the
Capture Location option makes sure all Survey responses
are geo-tagged, whether the Location Data Sources is enabled or not, assuming
the participant grants GPS permission to the Avicenna app and the GPS
functionality is available and enabled on their phone.
By default, this option is turned off.
This option instructs Avicenna to show the participants how many questions are
left to answer in the current Survey session. The following picture shows the
same Survey, with and without the
Show Progress option enabled:
|Show Progress Enabled||Show Progress Disabled|
Note that the progress shown here is approximate and does not present the exact number of questions left to complete. Certain sections or questions might not be presented due to the defined branching, skip patterns, or randomized section selection. In this case, the participant will notice a jump in progress.
By default, this option is turned on.