Survey-Simple Module Requirements

I. Introduction

The following is a requirements document for the Survey-Simple ACS module. The "simple" designation derives from the fact that this module only handles basic survey functionality and is soon to be superseded by an enhanced, more feature-rich one.

II. Vision Statement

The Survey-Simple module adds basic survey handling capabilities to the ACS toolkit, by allowing users with no knowledge of HTML or programming to create online surveys, edit their properties, respond to them, analyze response statistics, export responses, and manage the surveys.

Each survey is presented as a form that contains a set of questions. Each individual question can accept one of several different types of responses.

Real-world examples of online surveys usage include:

surveys can be used to solicit and collect users' information or opinions (e.g., contact information gathering forms, satisfaction surveys);
surveys can be used as templates that are to be filled in either once (e.g., job application forms) or periodically (e.g., project reports).

III. System/Application Overview

The Survey-Simple module is structure along three levels of interaction that contain the following features:

User level:

Responding to a survey

Survey administration level:

Creating a survey
Editing a survey
Analyzing user responses to a survey
Exporting user responses for external analysis

Site-wide administration level:

Managing (enabling or disabling) a survey

IV. Use-cases and User-scenarios

The Survey-Simple module is intended for the following classes of users, which may or may not overlap:

Users respond to the surveys.
Survey administrators create and edit surveys and analyze the responses they have collected.
Site-wide administrators (administrator) enable or disable surveys.

Creating a Survey

Sophia Survey-Admin creates a survey by giving it a name, a short name and a longer description, which can be either preformatted text, plain text or HTML.

Sophia then proceeds on to creating the first question of the survey. To do this, she enters the text of the question, the type of presentation for the response - text field, text area, selection, radio buttons, checkboxes, date or file attachment - and whether the question is active or not, and required or not. The next step allows Sophia to enter more details about the presentation of the response, namely the layout of the response relative to the question - beside or below its text - as well as some response type dependant options.

The recently created survey is set by default to be disabled and only an administrator can enable it to become displayable to users.

Editing a Survey

Sophia is shown a list of all available surveys, in separate `enabled' and `disabled' sections. If her survey hasn't been enabled by an administrator, she can choose to delete it permanently.

She can also pick her survey from that list and see all the survey properties and a list of its questions, sorted by relative order. She can add more questions to the selected survey by inserting a new question after an existing one and following the procedure described above for creating the first question.

At this point Sophia can also make changes to some survey-level properties: edit the survey description, add question categories, limit responses per user to a single response (specifying whether the single response is editable or non-editable), or allow multiple responses per user.

Only after adding question categories to the survey does Sophia have the option of categorizing questions during the question creation process; questions will otherwise be labeled as `uncategorized'.

At the question level , Sophia can choose to edit a question's text, delete a question, change the order of the questions in the survey by swapping two adjacent questions, activate or inactivate a question, and set a question as required or non-required. If a question only allows a response from a predetermined set of options (as is the case with radio-buttons, checkboxes and selection lists), she is also allowed to edit the existing options or add new ones.

Enabling and Disabling a Survey

Arnold Administrator is shown a list of all available surveys on the system and he decides which surveys are shown to users and which are not, by enabling or disabling each individual survey.

Responding to a Survey

Ursula User is directed to a survey by following either a link on other page or an embedded link in an e-mail message. She is presented with the survey description and a form containing an ordered list of all active questions in that survey and their respective response fields.

Ursula goes on to filling in the survey form. She responds to each question by either entering text on text fields, selecting from lists of available options, clicking radio buttons or checking checkboxes, and she then submits her response.

If Ursula tries to respond to the same survey again, one of three scenarios can develop:

if Sophia had configured the survey to allow multiple responses per user, Ursula is shown a blank survey form (identical to the first time she took the survey) and allowed to submit a new response. She is also offered a link to a list of all of her previous responses to that same survey;
if the survey only allows a single, editable response per user, Ursula is shown a survey form with her previous response filled in and allowed to change that response;
finally, if the survey only allows a single, non-editable response per user, Ursula is shown a survey form with her previous response filled in and informed of the fact that she cannot change that response.

Analyzing Responses to Survey

Sophia can check user responses to her survey in two distinct ways:

responses by user: this view provides her with a list of all users who have responded to the survey. Each responding user is linked to a list of all their previous responses to this survey, sorted by date (most recent first);
summary of responses: in this view, Sophia has the option of either seeing all responses or only seeing responses from distinct users. In both cases, this view shows all survey questions and their responses, according to their type:

For questions that have a limited range of possible responses, Sophia is presented with the number of responses for each option; each number links to a list of the users who have provided that response. By selecting a user from this list, Sophia can see all of their previous responses in which they have chosen this option to answer this particular question.
For open-format responses, Sophia is provided with a link to a list of users who have responded to that question, along with their responses, the date of submission and the originating IP address.

If Sophia wants to further analyze the user responses, she can export them in CSV format. Here, as in the internal views, she has the option of either exporting all responses or only exporting responses from distinct users.

V. Related Links

VI.A Requirements: Data Model

10.10.0 Surveys - Surveys are the main entity in the Survey-Simple module.

10.10.10 A survey id (primary key) that is guaranteed to be unique to the system must be maintained.
10.10.20 A human readable survey key that is guaranteed to be unique to the system must be maintained.
10.10.30 Surveys must have a brief name.
10.10.40 Surveys must have a longer description.
10.10.50 The description referred to in 10.10.40 will be tagged to be in HTML or plain text.
10.10.60 Surveys will be linked to their creating user.
10.10.70 Surveys will have a creation date.
10.10.80 Surveys will be in one of `enabled' or `disabled' states.
10.10.90 Each survey can allow one or multiple responses.
10.10.100 For surveys that only allow a single response, editing of that single response can be allowed or denied.

10.20.0 Questions - a survey contains a set of questions.

10.20.10 A question id (primary key) that is guaranteed to be unique to the system must be maintained.
10.20.20 Each question will be linked to one survey.
10.20.30 A question will have a sort key that defines its relative order to other questions within the same survey.
10.20.40 A question will store text that formulates the question itself.
10.20.50 A question will have an abstract data type that defines the high-level type of the question. Allowable values for the abstract data type are: 'text', 'shorttext', 'boolean', 'number', 'integer' and 'choice'.
10.20.60 Each question will be marked required or non-required.
10.20.70 Each question will be marked active or non-active.
10.20.80 Questions have a presentation type, which can be one of the following values: 'textbox','textarea','select','radio', 'checkbox', 'date' and 'upload_file'.
10.20.90 Questions may have additional presentation options, that are specific to each abstract type. Possible values include: 'small', 'medium', 'large' for 'text' abstract data type, and 'rows=5 cols=40' for `textarea' abstract data type.
10.20.100 Questions store a presentation alignment option for the response field. Allowable values are `below' or `beside' the question text.
10.20.110 Questions will be linked to their creation user.
10.20.120 Questions will have a creation date.

10.30.0 Categories - questions can be categorized

10.30.10 Each question is linked to a site-wide category.

10.40.0 Question choices - set of options for a question that has a limited set of possible responses.

10.40.10 A question choice id (primary key) that is guaranteed to be unique to the system must be maintained.
10.40.20 Each question choice is linked to a question.
10.40.30 A question choice has a human-readable label.
10.40.40 A question choice may have a numeric value associated with it, to allow weighing or averaging.
10.40.50 A question choice will have a sort key that defines its relative order to other question choices for the same question.

10.50.0 Responses - response by one user to one survey

10.50.10 A response id (primary key) that is guaranteed to be unique to the system must be maintained.
10.50.20 Each response is linked to one survey.
10.50.30 Responses have a scope, which can be `user', `group' or `public'.
10.50.40 Each response may be linked to one user.
10.50.50 Each response may be linked to one user group.
10.50.60 A `user' scope response must be linked to a user and must not be linked to a user group.
10.50.70 A `group' scope response must be linked to a user group and must not be linked to a user.
10.50.80 A `public' scope response must not be linked to a user group and must not be linked to a user.
10.50.90 Responses have a title.
10.50.100 A submission date will be recorder for each response.
10.50.110 The originating user IP address will be recorded for each response.
10.50.120 Each response will be tagged to indicate whether or not the creating user will be notified when a comment is added to the response.
10.50.130 Responses will have a proposal state. Allowable values are `public', `private' and `deleted'.

10.60.0 Question responses - answers given by one user to each question in a survey

10.60.10 Each question response will be linked to a response.
10.60.20 Each question response will be linked to a question.
10.60.30 A question response may be linked to a question choice, if the user picked from a limited set of options.
10.60.40 Question responses may store a boolean answer value, which can be either true or false.
10.60.50 Question responses may store a numeric answer value.
10.60.60 Question responses may store a brief alphanumeric answer value.
10.60.70 Question responses may store a long alphanumeric answer value.
10.60.80 Question responses may store a date answer value.
10.60.90 Question responses may store a long binary answer value, such as a file attachment.
10.60.100 Question responses that store a long binary value such as described in 10.60.90 can also store the attached file name.
10.60.110 Question responses that store a long binary value such as described in 10.60.90 can also store the attached file MIME type.
10.60.120 Question responses that store a long binary value such as described in 10.60.90 can also store the attached file extension.

VI.B Requirements: User Interface

User Interface

20.10.0 Responding to a Survey (user must be logged in)

20.10.10.0 Survey presentation
20.10.10.10 The user shall be presented with a form containing all the active questions in a survey, sorted in ascending order by their numerical sort key, with the survey name and description at the top.
20.10.10.20 For each question, its sort key and text will be shown
20.10.10.30 For each question, the response field will be displayed according to the presentation alignment option for that question (beside or below the question text).
20.10.20.0 Number of allowed responses
20.10.20.10.0 Survey allows multiple responses
20.10.20.10.10 The user will be presented with a blank form, with empty fields.
20.10.20.10.20 The user must be able to respond to the survey by selecting one or more options from limited-response questions or providing a response to open-form questions.
20.10.20.10.30 If the user has previously responded to the survey, a link will be provided to check all previous responses to the survey.
20.10.20.20.0 Survey only allows a single, editable response
20.10.20.20.10 If a previous response to this survey by this user exists, the user will be presented with a form with fields filled in with the user's previous response values; otherwise the response fields will be left blank.
20.10.20.20.20 The user must be able to respond to the survey by either keeping or changing his previous response values (if they exist), or by selecting one or more options from limited-response questions or providing a response to open-form questions.
20.10.20.30.0 Survey only allows a single, non-editable response
20.10.20.30.10 If a previous response to this survey by this user exists, the user will be presented with a form with fields filled in with the user's previous response values; otherwise, the response fields will be left blank.
20.10.20.30.20 If the user had already submitted a response to this survey, the user will be informed that another response cannot be submitted. Otherwise, the user must be able to respond to the survey by selecting one or more options from limited-response questions or providing a response to open-form questions.

20.10.30 If the user fails to provide a response to a question marked as required, the response won't be accepted.

Survey-Administrator Interface

20.100.0 Creating a Survey

20.100.10 The survey-administrator must be able to create a survey by entering appropriate values for the survey name, short name, description and description format.
20.100.20 The survey-administrator must approve the formatting of the survey description before the survey is created.
20.100.30 If the survey-administrator fails to provide a valid value for any of the properties named in 20.100.10, the survey won't be created.
20.100.40 After the survey is created, the survey-administrator will be offered the option of immediately creating the first question.

20.110.0 Displaying a Survey

20.110.10 The survey-administrator will be presented with the following survey properties: survey name, creation user name, creation date, short name, survey state (`enable' or `disabled'), number of allowed responses per user (`single' or `multiple'), editable status of single response per user surveys (`editable' or `non-editable'), survey description and a list of question categories.
20.110.20 The user name mentioned in 20.110.10 will be linked to that user's community member page.
20.110.30 The survey-administrator will be presented with a list of all questions, sorted by their relative sort order.
20.110.40.0 Displaying a Question
20.110.40.10 For each question, the question sort order, question text and question category will be displayed.
20.110.40.20 For each question, a response field will be displayed, in an abstract data type-dependant manner.
20.110.40.30 If the question only allows a limited set of question choices as a response, all question choices will be displayed, in an abstract data type-dependant manner.

20.120.0 Editing a Survey

20.120.10.0 Changing the Survey Description
20.120.10.10The survey-administrator must be able to change the survey description, by editing the existing description.
20.120.10.20 The survey-administrator must approve the formatting of the survey description before the existing description is changed.
20.120.10.30 If the survey-administrator fails to provide an appropriate value for the survey description, the existing description won't be changed.

20.120.20.0 Changing the Allowed Number of Responses per User
20.120.20.10 The survey-administrator must be able to change the number of allowed responses per user, by toggling between allowing `multiple' responses and a `single' response.
20.120.20.20 For surveys that only allow a `single' response per user, the survey-administrator must be able to specify whether that single response is editable or not, by toggling between `editable' and `non-editable' single response states.
20.120.30.0 Creating a Category
20.120.30.10 The survey-administrator must be able to create a new category for later categorization of questions, by supplying an appropriate value for the category name.
20.120.30.20 If the survey-administrator fails to provide an appropriate value for the category name, the category won't be created.
20.120.30.30 After creating a new category, the category will be displayed in the survey properties.
20.120.30.40 After creating a new category, the category will be available in the question creation process to categorize each new question.
20.120.40.0 Creating a Question
20.120.40.10 The survey-administrator must be able to create a new question and have it inserted in a specific sort order within the survey.
20.120.40.20 The survey-administrator must be able to create a question in two distinct steps: by first entering appropriate values for the question title, response presentation, active status, required status and, if any categories have been created, question category; and then entering appropriate values for response type-specific properties and options, as well as for the response field alignment option.
20.120.40.30 If the survey-administrator fails to provide a valid value for any of the properties named in 20.110.10.20 for any of the question creation steps, the question won't be created.
20.120.40.40 After the question is created, the whole survey will be shown to the survey-administrator, including a list of survey properties and a list of all questions that includes the just created question in the appropriate sort order.
20.120.50.0 Deleting a Question
20.120.50.10 The survey-administrator must be able to delete a question from the survey.
20.120.60.0 Editing a Question
20.120.60.10 The survey-administrator must be able to change the question text.
20.120.60.20 The survey-administrator must be able to change the active status of a question, by toggling between `active' and `inactive' state.
20.120.60.30 The survey-administrator must be able to change the required status of a question response, but only for questions in the `active' state, by toggling between `required' and `non-required' state.
20.120.60.40.0 Creating and Editing Question Choices
20.120.60.40.10 For questions that force the user to pick from a limited set of question choices, the survey-administrator must be able to add new choices to the existing ones.
20.120.60.40.20 For questions that force the user to pick from a limited set of question choices, the survey-administrator must be able to edit existing choices.

20.120.70.0 Changing the Relative Order of Questions
20.120.70.10 The survey-administrator must be able to change the relative sort order of questions, by swapping the order of two adjacent questions.

20.130.0 Analyzing Responses to a Survey

20.130.10.0 Displaying Responses to a Survey by User
20.130.10.10 The survey-administrator must be able to view a list of all users who have responded to a survey.
20.130.10.20 Each item in the list mentioned in 20.130.10.10 contains the identification of one user and must be linked to a list of all the responses that user has entered for the survey, ordered by response date (most recent at the top).
20.130.20.0 Displaying a Summary of Responses to a Survey
20.130.20.10 The survey-administrator must be able select to be shown a summary of all responses or a summary of responses submitted by distinct users.
20.130.20.20 The number of responses that match the criterium defined in 20.130.20.10 will be displayed.
20.130.20.30 The survey-administrator will be presented with a list of all questions, sorted by their relative sort order.
20.130.20.40.0 Displaying a Summary of Responses to a Question
20.130.20.40.10 For each question, the question sort order and question text must be displayed.
20.130.20.40.20.0 Limited Response Questions
20.130.20.40.20.10 For each question that only allows a limited set of question choices as a response, a list of the labels of all question choices that have been chosen by at least one user will be displayed.
20.130.20.40.20.20 Each item of the list of question choice labels mentioned in 20.130.20.40.20.10 will also display a count of the number of users that match the criterium defined in 20.130.20.10 who have selected that question choice. This count will link to a list of all users who have selected that question choice for that question.
20.130.20.40.20.30 Each item of the list of users mentioned in 20.130.20.40.20.20 will link to a list of the responses that user has entered for the survey, in which that user has selected the correspondent question choice, ordered by response date (most recent at the top).
20.130.20.40.20.40 The list of responses mentioned in 20.130.20.40.20.30 will display the user that submitted them, linked to that user's community member page.
20.130.20.40.30.0 Free-form Response Questions
20.130.20.40.30.10 For each question that allows a free-form value as a response, a link to a list of responses, ordered by response date (most recent at the bottom), will be displayed.
20.130.20.40.30.20 Each item of the list mentioned in 20.130.20.40.30.20 will contain the value of the response submitted by the user, the user name, the response date and the originating IP address.
20.130.20.40.30.40 The user name mentioned in 20.130.20.40.30.20 will link to the user's community member page.

20.140.0 Exporting Responses to a Survey

20.140.10 The survey-administrator must be able to export all responses to a survey, in a standard CVS format, for further external analysis.
20.140.20 The survey-administrator must be able to export responses to a survey by distinct users, in a standard CVS format, for further external analysis.

Site-wide Administrator Interface

20.200.0 Enabling or Disabling a Survey (site-wide administrator must be logged in)

20.200.10 The site-wide administrator will be presented with a list of all surveys in the system and must be able to toggle each survey between the `enabled' and `disabled' states.

VI.C Requirements: API

Since Survey-Simple is primarily an end user application, there are no external APIs for this module.

VII. Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/28/2000	Nuno Santos

nuno@arsdigita.com

Last modified: $Date: 2001/01/19 21:36:46 $