How to Create a Survey

Surveys in Codespec consist of the following parts:

• survey - the over-arching questionnaire respondents will complete

• survey page - a standalone page in a survey (surveys can have many pages)

• question - a single question on a given page (pages can have many questions)

• choice - an option respondents can select when replying to a single- or multiple-choice question

Relatedly, Codespec tracks respondents and their responses via the following concepts:

• respondent - a specific person who was invited to, started, or completed a survey

• response - a particular answer a respondent selected or entered

Now, let's go through the process of creating a survey.

Inside a particular course, visit the "surveys" page and click "Add Survey". The following fields are available:

• name - (required) the public-facing name of the survey (respondents will see this)

• short description - (optional) a brief summary of the survey that will show when users are looking at their list of open surveys in the course

• pre-start content - (optional) a place to summarize/introduce the survey. This appears before respondents start the survey.

• post-submit content - (optional) a place to thank the respondent for their answers after they've officially submitted the survey

• open at - (optional) the date and time at which the survey is open for respondents to completed. Entering future times will schedule the survey to automatically open at the specified date/time. Entering the current date/time will open the survey immediately.

• close at - (optional) the date and time at which the survey will close for respondents. Leaving the close at date empty will leave the survey open indefinitely once the open at date has passed.

• audience - the group of people eligible to view/complete the survey once it's open (options are "Active Course Members" and "Invited Users"). The former means any user who is an active member of the course for the survey will have access; the latter means that only users you invite (from the course from the survey) will have access.

• maximum responses per user - (optional) by default this field is blank, meaning respondents can complete the survey an infinite number of times. If specified, respondents will only be able to complete the survey that many times.

• show progress bar - (optional) if checked, this will show a progress bar to respondents as they progress through each page. Progress is calculated by taking the total number of pages and dividing that by their their current page .

• code - (optional) an internal facing identifier to be used during data exports when referencing this survey. If not specified, a default one is provided (e.g., survey_005).

After you create the survey you will arrive at a page for authoring survey pages and questions. Clicking the "Add page" button will bring up a form with the following fields:

• title - the name of the page

• show title - (optional) the will show the page title to respondents if checked

• description - (optional) a place to provide more context to the page before displaying any questions

• code - (optional) an internal facing identifier to be used during data exports when referencing this page. If not specified, a default one is provided (e.g., page_003).

• skip to - (optional) a page that respondents should be taken to after submitting their answers to all questions on this page. Note: question-level skip-to's will override this setting.

• exit on submit - (optional) check this box if you'd like respondents to be marked as 'complete' after submitting their answers to this page. They'll then be taken to an exit confirmation page.

Note, the last page must have the exit on submit box checked in order for respondents to be marked complete.

Once you've created a page, click the "Add question" button to create a question. You will be prompted to enter the text for the question. After that, a longer form will appear to further customize it.

Question Types

A question can be one of 5 different types:

• input field - allows respondents to enter a custom value (e.g., short or long text, a number, email address, etc)

• numeric scale - presents respondents with a list of numeric choices from which they can only choose one (e.g., a scale from 1 to 5)

• likert scale - presents respondents with a list of numeric choices describes by Likert scale phrases (e.g., "strongly disagree to strongly agree)

• multi-answer multiple choice - presents respondents with a list of options from which they can choose 1 or more

• single-answer multiple choice - presents respondents with a list of options from which they can only choose 1

Question Widgets

The type of question you're creating determines which widgets you may use. A "widget" is an HTML element such as a text input, select/dropdown input, checkbox, etc. Codespec offers the following widgets:

• Checkbox - a checkbox with a custom label (for multi-answer multiple choice questions only)

• Date - a text input for entering a date (for input field questions only)

• Date and Time - text input for entering a date and time (for input field questions only)

• Dropdown - a select element that displays a list of choices (for single- and multi-answer multiple choice questions only)

• Duration - a text input for entering a duration in hours, minutes and seconds (e.g., 01:30:00 for 1.5 hours, input field questions only)

• Email - a text input for entering email addresses (for input field questions only)

• Long Text - a textarea input for entering in paragraphs of text (for input field questions only)

• Number - a text input for entering in a number (for input field questions only)

• Radio - a radio input with a custom label (for single-answer multiple choice questions only)

• Short Text - a text input for entering brief text responses (for input field questions only)

• Telephone - a text input for entering phone numbers (for input field questions only)

• Time - a text input for entering times (for input field questions only)

• URL - a text input for entering in a URL address (for input field questions only)

Additional Question Controls

There are other ways to customize a question besides the type and widget:

• description - (optional) a place to elaborate on the original question. This text will appear between the question text and the list of options/input field.

• code - (optional) an internal facing identifier to be used during data exports when referencing this question. If not specified, a default one is provided (e.g., question_001).

• list style - (optional) for multiple choice questions, you may select a list style format to go along with the choices. Options include uppercase letters, lowercase letters, or roman numerals.

• maximum selections - (optional) place a limit on the number of selections a respondent can make for a multi-answer multiple choice question

• required - (optional) mark a question as required to force a response. Respondents will not be able to move forward until they provide an answer.

• randomize choice order - (optional) for single- and multi-answer multiple choice questions, if this is checked, each user will see the list of options in a different order.

If you are creating a single- or multi-answer multiple choice question, or a numeric/Likert scale question, you must next create choices for respondents to select. Click "Add choice" at the bottom of the question form to proceed. Each choices contains:

• label - the respondent-facing text for the choice

• value - the internal-facing text for the choice (defaults to the full label text)

• has text input - (optional) if this is checked, a text box will appear below the choice to collect custom respondent input (e.g., for elaborations on an "other" choice). This field is only available for single- and multi-answer multiple choice questions.

• skip to - (optional) specify a page the respondent should skip to after selecting this choice. Leave it blank if you'd like them to continue to the next page by default.

If you are creating an input question, you may add custom logic to validate user input. Validation rules contain the following fields:

• logic - the behavior/expectation for evaluating the input

• value - the content that completes the criteria for the rule

Example validation rules include:

• for questions expecting a number, a validation rule expecting the response be greater than 0. "Greater than" is the logic, and "0" is the value.

• for questions expecting a date, a validation rule expect the response be less than (before) today. "Less than" is the logic, and "today's date" is the value.

Currently, surveys are only visible to respondents if they are part of a workbook. To add them, follow these steps:

• Navigate to a workbook in the course console

• Click into a particular page from the list of chapters/pages

• Click "Add survey" and select the survey you wish to display

Assuming that the page is published and the survey is an in "open" state (based on the open/close-at dates), respondents will be able to take the survey.