You can create and modify a survey using the Ethica Survey Editor. The following document describes how to use the Survey Editor for this purpose. You can also create a survey by defining a JSON document which includes the survey hierarchy, content, and attributes.
Creating a New Survey
Adding a new survey to a study or modifying a survey is part of a study design. Hence you can perform these tasks by selecting your study and navigating to the Design section as follow:
- In your dashboard, select the study you intend to modify from the left panel.
- Extend the Design section, and then select the Surveys option, as shown in the following image:
- From the Surveys section, click on the Add New Survey button.
This will create a new survey and navigates you to the Survey Editor to edit the survey.
Similarly, you can edit or delete a survey from the Design -> Surveys section. For any given survey, if you expand its row, you will see the options to Edit or Delete the survey. Pressing Edit will open the selected survey in the Survey Editor to modify, and pressing Delete will ask you for confirmation and subsequently deletes the survey.
Deleting a survey does not delete the responses provided for that survey so far. It only deletes the survey definition.
The following image shows the options for adding, editing, or deleting surveys in a given study:
Saving and Restoring Surveys
As you edit a survey and you have an unsaved work, the Survey Editor reminds you to save your work by showing a message on the top left corner:
The Survey Editor periodically saves your changes to make sure none of the changes are accidentally lost. You can also save your work at any time by pressing the Save button on the top left panel of the Survey Editor:
At this point, as the message indicates, all your changes are saved on the server, but they are still not available to the participants. The Survey Editor does not make the changes available to participants right away. Rather, it just stores them on the server. You can think of saving as an interim state which allows you to store your work-in-progress. When you are done with making all changes and you wish to send your changes to all participants (currently enrolled or prospective), you need to Publish your changes. You can publish your changes by pressing Publish button from the top left corner, which will ask for your confirmation:
If you confirm to Publish, the Survey Editor publishes all changes and also notifies all currently enrolled participants (if any) about the changes, so their app can update their survey content.
Saving and publishing the changes right away is acceptable as long as there is no participant enrolled in the study. If the study currently has enrolled participants, you might want to be more cautious with changing the surveys, as this affects all participants right away.
At any point, if you are unhappy with the changes you have made and you want to discard them and go back to the last published version, you can press the Discard button:
This will discard all non-published changes and loads the last published version of the survey into the Survey Editor.
Navigating the Survey
Each survey consists of one question set (or multiple question sets, for Advanced Triggers). The question set consists of multiple pages, where each page consists of one or more questions. If a question is of type Single Choice or Multiple Choice, they, in turn, can have one or more potential answers. This creates a hierarchy for the survey. The Survey Editor provides an easy way to view this hierarchy and navigate it, using the Survey Navigator panel on the top right corner:
When you create a new survey, the Survey Navigator has only one entry which is considered the root. Selecting the root will show the survey configuration page in the main section, which is described below. As you add the question set to your survey, or add new pages to your question set, or add new questions, each of these elements will appear in the Survey Navigator panel.
Selecting any element from the Survey Navigator loads and highlights that element in your workspace. It also shows the properties of the selected element in the Properties panel.
Each survey element has certain attributes which you need to set as part of creating your survey, for example, whether a question has to be enabled or disabled by default, or whether selecting a given answer should end the survey or not. The Survey Editor shows all properties for a given element in the Properties panel. As you select a given element from the Survey Navigator, whether it's a survey page, a question, or a potential answer, the properties available for that element is shown in the Properties panel. The following image shows the properties for a Calendar question as an example:
While Question Types article has explained in details what are the available properties for each element and what they each mean, it can be hard and time-consuming to either remember all these properties or refer to the document every time. To help you remember what each of these properties is, the Properties panel offers a Help mode, which can be enabled by selecting the light bulb icon on the top right corner of the panel:
Turing the Help mode on instructs the Survey Editor to show a small tool-tip next to each element, as you move your cursor close to the element:
When the Survey Editor is opened after creating a new survey, or to edit a survey, it first shows the survey configuration page. You can access this page also by selecting the survey name (the topmost element) from the Survey Navigator:
The first part of the survey configuration page allows you to assign a name to the survey, and also write a few lines of description for the survey. The survey name and description are not shown to the participants and are mostly for your own reference.
The second part, Survey Type asks you to select the type of the survey. You can set the survey to be either Eligibility Survey, Baseline Survey, Generic Survey, or Exit Survey. Each of these types is explained in details in Survey Type article.
The next section, Triggering Logic, is only available if you have set the survey type to Generic, and allows you to define the criteria under which the survey should be triggered during the study. You can decide whether the survey should be triggered by participants, be triggered based on a certain schedule, or have an advanced triggering logic. For more details about the triggering logic of generic surveys, you can refer to the Trigger Types article.
The next section, Question Sets, allows defining a question set for the survey. A question set defines the content of the survey, including the pages, questions, potential answers, and branching logic. Most surveys can only have one question set. Therefore the option for adding a new question set is disappeared after creating the first question set, as shown in the image below:
The only exceptions are generic surveys with advanced triggering logic, as described before. These surveys can have more than one question set. The Java code used in their triggering logic defines when each of these question sets should be triggered. The following image shows a survey with multiple question sets:
Downloading and Uploading Survey as JSON
Each survey in Ethica is described in plain text JSON format. The Survey Editor is a visual tool which allows creating these JSON files in the format expected by Ethica app and Ethica dashboard. When you create a survey using the Survey Editor, at any time you can ask for and download the JSON content representing your survey. To do so, simply click on Download button in the survey configuration page, as shown in the image below:
Similarly, you can define your survey in a JSON file (or edit the JSON file downloaded from the Survey Editor), and upload it to the Survey Editor for further modification, or content validation. As long as your JSON file follows the specified schema, the Survey Editor can load your survey and use it just as if it was created with the Survey Editor. To upload your JSON file to the Survey Editor, simply click on Upload button in the survey configuration page, as shown in the image above.
The survey's question set comprises of multiple survey pages, where each contains one or more questions. When a survey is triggered, Ethica presents the content of the first page to the participant. Each page should specify the next page, or indicate that it's the last page. If there is a next page, participants will be directed to it after finishing the current page, otherwise, they will finish the survey.
Answers to single choice or multiple choice questions can override the predefined flow of the pages. For example, selecting a given answer can mark the current page as the last page, or can move the survey flow to a different page. You can read more about overriding the page flow in Changing the Next Page section.
Additionally, each page can have a criterion which if specified, has to be met before it's shown to the participant. If the page criteria are evaluated to False, the survey moves to the next page or finishes if the current page is the last page.
Overriding the flow of the pages based on the participant responses, and defining criteria for each page which determines when the page should or should not be shown provides a powerful way to define skip patterns and branching logics for the survey.
The following image shows the action area at the bottom of a survey page. In order to add a new page, you can click on the Add Page option here. This will add a new page at the end of the currently defined pages, modifies the former last page to point to the new page as its next page, and marks the new page as the last page.
You can modify these for a given page by selecting the page from the Survey Navigator, and change the appropriate option from the Properties panel. Selecting the Is last page? option will mark this page as the last page, and the survey will finish after reaching this page, regardless of whether there are more pages defined after this page or not. Alternatively, you can choose a page as the next page from the list shown in front of the Next page attribute.
You can also delete a page by selecting the page from the Survey Navigator or from the bottom action area and subsequently click on the Delete This Page option, as shown in the image above. If the deleted page was the last page, the page prior to it will be marked as the last page. Otherwise, the page prior to this page will be modified to point to the page following this page.
After adding a new page to the survey, you can add one or more questions to the page. To add a question, simply drag the question from the Questions panel on the left side, and drop it at the location you prefer in the page. After placing the question on the page, you can re-order the questions by dragging them up and down.
When you add a new question to the page, it starts in the Edit mode. In this mode, you can type the content of the question and add, remove, or modify the potential answers. The following image shows a given single choice question in the Edit mode:
You can also delete a question by clicking on the trash bin icon on the top right corner of the question area.
Each question has a set of properties which are described in details in Question Types article. You can modify these properties by selecting the question (whether from the Survey Navigator or by clicking on the question). This will show the properties for the current question in the Properties panel, and allows you to modify any of them.