Differences

This shows you the differences between two versions of the page.

Link to this comparison view

foundation:surveytool_spec [2010/12/18 17:35] (current)
Line 1: Line 1:
 +Functional Specifications for the [[http://eden.sahanafounration.org|Sahana Eden]] [[http://wiki.sahanafoundation.org/doku.php/foundation:gsoc_oconnor|Survey Tool]] for [[http://wiki.sahotanafoundation.org/doku.php/foundation:sahana_gsoc10|Google Summer of Code 2010]]
 +\\ \\
 +^Revision History^^^^
 +^Version^Author^Date^Comments^
 +|0.1|Robby O'Connor|2010-05-17|First Draft.|
 +|0.2|Michael Howden|2010-05-22|First Review.|
 +|0.3|Robby O'Connor|2010-05-24|Second Draft -- Response to Reviews|
 +|0.4|Robby O'Connor|2010-05-26|Added Question Data Types and mockups for each type|
 +|0.5|Robby O'Connor|2010-05-28|Changed the "author" column's FK on Survey Template to go to pr_person vs pr_pentity.|
 +|0.6|Robby O'Connor|2010-05-29|Added mock-ups for the create template and create series screen; as well as the "Home" screen.|
 +|0.7|Robby O'Connor|2010-05-31|Moved around the mock-ups for the "Add Question" and "Analysis" screen to the "Screens" Section of the spec. |
 +|0.8|Robby O'Connor|2010-05-31|Removed a few question types; added a "Nice To have" of localization on sections/questions and a suggested approach with a recommended data model.Also added "allow_comments" to survey question; tacked on an alternative data model|
 +|0.9|Robby O'Connor|2010-06-19|Updates to the data model|
 +|1.0|Robby O'Connor|2010-06-19|Added some UI mockups; detailed the wizard steps for the wizard UIs that will exist in the system.|
 +|1.1|Robby O'Connor|2010-06-24|Updated to reflect or->org||
 +|1.2|Robby O'Connor|2010-06-19|Added Wizard Flowchart.|
 +\\
 +
 +
 +====== Overview ======
 +In the aftermath of a natural disaster, it is imperative that the extent of the damages be evaluated in a timely manner. Enter stage right, Survey Tool: A tool to create, manage, and enter surveys to assess the needs of the peoples affected by the natural disaster to deliver the much needed aid in an efficient manner. 
 +
 +\\
 +
 +====== Background Scenarios and User Stories ======
 +Lucy has to conduct a survey on 100,000 people living in a conflict affected part of Africa. She wants to be able generate this survey, and then have it filled in by hand. These paper survey will then be collated by a number of data entry operators. [seperate instances in a series with 100,000 instances]
 +
 +Karl has to conducting a survey of schools in Iraq. This survey will be carried out initially, to collect baseline data (to better design an assistance program), and then repeated to track the performance of the program over it's duration.  [set up template; initial series; results from series; follow-up series]
 +
 +Tom, Dick and Harry work for different organisations all in Haiti responding to the earthquake. Each of their organisations have a different assessment for, but they would like to be able to share informations, and produce summaries of all their data. This will enable them to see what gaps they have in their data collection and avoid repeating the same infomration as others. Dick may want to print out the results of Harry's Survey onto a NEW survey, which also contains the questions that his survey contains which were missing from Dick's, so that he can repeat the survey, but only focus on the missing data.
 +
 +Different surveys will be aggregated differently.
 +In Lucy's case, we will be looking at averages over the entire population
 +In Tom Dick and Harry's case, each survey will (ideally) be for a different location - so we will not be "averaging", but looking at all the results together.
 +
 +An instance of a survey template may only contain one answer eg, an assessment of a village.
 +Or it might contain 100,000
 +\\ \\ 
 +====== Non-Goals ======
 +(to be completed)
 +\\ \\
 +====== Definitions ======
 +**Super Users** - have access to do EVERYTHING
 +
 +
 +**Data Entry Clerks** - People who enter the data. 
 +\\ \\
 +====== Users ======
 +  * People setting up surveys -> super users
 +  * people filling out surveys -> data entry clerks, super users
 +  * viewing results -> data entry clerks, super users
 +\\ \\
 +====== Data Model ======
 +
 +** Survey Template**\\
 +Holds information on a survey template. Question,section and series data will reside in a link table because of their many to many nature.
 +
 +^Field Name^Purpose^Data type^Required^
 +|name|Acts as the display name -- the title of the survey|string|Yes|
 +|description|Description of this template|text|No||
 +|locked|Prevent modifying a survey which is being edited|boolean|No|
 +|author|Who created this template|FK to pr_person.id|No -- defaults to logged in user|
 +|organisation|The organisation that this template is used for|FK to org_organisation.id|Yes||
 +
 +\\
 +** Survey Question**\\
 +Holds information about Survey Questions.
 +
 +^Field Name^Purpose^Data type^Required^
 +|name|acts as the display name for the question|string|Yes|
 +|description|Description of this question|text|No|
 +|question_type|denotes the question type (see section on question types).|FK to survey_question_type|Yes|
 +
 +\\
 +** Survey Section **\\
 +Holds information about survey sections.
 +^Field Name^Purpose^Data type^Required^
 +|name|acts as the display name for the section|string|Yes|
 +|description|Description of this section|text|No|
 +
 +\\
 +** Survey Series**\\
 +Associate a survey (or set of surveys with a series)
 +^Field Name^Purpose^Data type^Required^
 +|name|the name of the series|string|Yes|
 +|description|Description of the series|text|No|
 +|survey_template_id|Associated Survey Template|FK to survey_template.id|Yes||
 +|from_date|Start of period|datetime|Yes||
 +|to_date|End of period|datetime|Yes|
 +|location|Location Survey Conducted.|FK to gis_location.id|Yes|
 +
 +\\
 +** Survey Instance**\\
 +Holds the records for each survey answered in a survey series
 +^Field Name^Purpose^Data type^Required^
 +|survey_series_id|The series to which this instance refers to|FK to survey_series.id|Yes|
 +\\
 +** Survey Answer **\\
 +Holds answers to surveys to be displayed if survey is answered.
 +^Field Name^Purpose^Data type^Required^
 +|survey_instance_id|The instance this answers refers to|FK to survey_instance.id|Yes||
 +|question_id|Question to which this being answered for|FK reference to the survey_question.id|Yes|
 +|answer_value|the answer|string|Yes|
 +|comments|the comments (if any)|text|No|
 +
 +\\
 +** Survey Template Link Table **\\
 +Link table to solve the many-to-many relation between: Surveys<->Questions and Sections<->Questions 
 +^Field Name^Purpose^Data type^Required^
 +|question_id|Survey Question|FK to survey_question.id|No|
 +|section_id|Survey Section|FK to survey_section.id|No|
 +|survey_template_id|Survey Template|FK to survey_template.id|No|
 +|order|The order which the question appears in the survey|int|No|
 +
 +\\
 +                                                             
 +** Question Metadata **\\
 +Used to store configuration data
 +^Field Name^Purpose^Data type^Required^
 +|question_id|Question these options are related to.|FK to survey_question.id|Yes|
 +|row_choice|row choice for rating|text|No|
 +|column choice|column choice for rating (can customize)|text|No|
 +|ta_rows|how many rows for the text-area|int|No|
 +|tf_ta_columns|The number of rows for either Text Field or Text Area|int|No|
 +|allow_comments|Whether or not to render a comment field|boolean|No|
 +|comment_display_label|The comment to text display before the text field for comments|string|No|
 +|required|Whether or not the question should be required to be filled out|boolean|No|
 +|validate|Whether or not to enable validation for the question|boolean|No||
 +|aggregation_type|How the question should be aggregated (non-editable by the user|string|No|\\ \\
 +
 +\\ 
 +
 +** Survey Widgets (Custom Data Types) **\\
 +Used to store configuration data
 +^Field Name^Purpose^Data type^Required^
 +|question_id|Question this widget is related to.|FK to survey_question.id|Yes||
 +|widget|The render-able markup used to render the question|text|Yes|\\ \\
 +
 +\\
 +
 +** Survey Answer Options** \\
 +Used to store the answer options (e.g., Yes, No, Not Applicable)
 +^Field Name^Purpose^Data type^Required^
 +|question_id|Question these answer options are related to.|FK to survey_question.id|Yes||
 +|option_value|The value to display e.g., "Yes"|text|Yes|\\ \\
 +
 +\\ \\
 +
 +
 +====== Question Data Types======
 +
 +Internally question types are stored *NUMERICALLY*.
 +
 +  - Multiple Choice (Only One Answer): {{:foundation:mc_one_answer.png|}} -- **Option exists to display in one,two, or three columns** 
 +  - Multiple Choice (Multiple Answers): {{:foundation:mc_several_answers.png?648x135|}} -- **Options in layout: one,two, or three columns or horizontal layout.**
 +  - Rating Scale: {{:foundation:rating_scale.png?651x182|}}
 +  - Single Textbox 
 +  - Multiple Textboxes
 +  - Comment/Essay Box
 +    - Large text-area to take in an essay or comment.
 +  - Numerical textboxes
 +    - This has validation that ensures that a numeric answer is given.
 +  - Date and/or Time
 +    - Datepicker will be used here.
 +  - Image
 +    - Simple way of having a logo or branding on the survey.
 +  - Descriptive Text
 +    - A way to have some prose in whatever form necessary
 +  - Location
 +  - Organisation
 +  - Person
 +  - Custom Database Resource (any resource defined in eden is possible here). 
 +\\ \\
 +====== Flowcharts======
 +
 +{{{:foundation:survey_tool_flowchart.jpg?900px×653px}} \\ \\
 +
 +\\ \\
 +====== Screens ====== 
 +{{:foundation:step1_2.png?1044x433|}}\\ \\
 +Now the add question form\\
 +{{:section6.png?678px×658px}}\\
 +\\
 +
 +The pop-up generated when "Add Question is clicked will be a wizard-style ui with two steps as shown in the following (**NB: this is only for ONE data type and there are other variants of the configuration page, this gives an idea of what it will look like.)**:\\
 +{{:foundation:survey_question2.png?1359x597}}
 +
 +\\
 +
 +The pop-up generated when "Add Section" is clicked will look like the following:\\
 +{{:section_add.png}}
 +
 +\\
 +
 +**The home screen looks like follows:**\\
 +{{:foundation:home.png?1074x476|}}
 +\\
 +**Finally, the analysis page will look like this:**\\
 +{{:foundation:analysis_.jpg?650x715|}}
 +\\ \\
 +
 +====== Wizard Steps=====
 +
 +^Survey Creation^^                 
 +^Step Number^Page^
 +|1|Survey Template|
 +|2|Add Questions/Sections|
 +|3|Add Series/Create Survey Instance|
 +\\ \\
 +**Questions have a sort of "Mini" Wizard UI that isn't coupled to the survey wizard UI in any way.**
 +^Question Creation^^
 +^Step Number^Page^
 +|1|Survey Question|
 +|2|Survey Question Options Configuration|
 +
 +====== UI Design ======
 +-> implies going to a  new screen
 +
 +**Menu**:
 +
 +    * Create 
 +    * Fill Out
 +    * Results
 +    * Analysis
 +    * Advanced
 +
 +
 +**Screens**:
 +
 +**__Home__**:
 +
 +    * Big Button for create
 +    * List of recently created surveys
 +    * List of recently added surveys to fill out
 +    * List of recently completed surveys
 +
 +
 +**__Create__**:
 +
 +    * Option to re-use an existing survey -> who take you straight to "Create Survey"
 +    * Option to edit an existing survey -> who take you straight to "Survey Wizard", if this is the user's survey AND it has not been "Created", then they will edit it, otherwise a edittable copy will be made.
 +    * Option to retake a completed survey using a different survey template, which has overlap with the past survey, but also contains new questions. The overlapping questions could be prefilled with the results from the previous survey.
 +    * Option to go through the survey create wizard:
 +
 +   - Enter Survey Name, other details
 +   - Enter survey sections.
 +   - Add questions. This will be One of the major pages:
 +
 +
 +    * Create Survey -> Who, When, where, Why. The same "instance" of a survey could be created multiple times.
 +
 +**__Fill Out__**:
 +
 +    * List of all surveys which can be filled out -> Data entry screen for that survey / Print out survey question sheet
 +
 +
 +**__Results__**:
 +
 +    * List of all surveys there are results for (Which the user has permission to view) option to "Complete" (and thus lock) the survey -> display that result (read/edit depending on permissions, or perhaps the survey is "locked")
 +
 +
 +**__Analysis__**:
 +
 +    * List of Surveys (grouped so that instances of the same survey are together) -> analysis page for that survey. Allow user to add notes to the results for each question
 +    * Export the data to excel
 +    * We will need to be able to analyse different surveys together: eg NGO A did survey A, NGO B did survey B, OR NGO A did survey A in Jan 2010 then NGO A did survey A in Dec 2010
 +
 +   - compare the actual surveys (not the questions) - how similar are they? 
 +   - Add the answers together
 +   - what is the difference between the results (eg change from Jan-Dec)
 +\\ \\
 +====== API ======
 +
 +(to be completed later)
 +\\ \\
 +====== Technologies ======
 +(to be completed later)
 +\\ \\ 
 +======References======
 +[[http://www.surveymonkey.com|Survey Monkey]]
 +\\ \\
 +======Open Issues======
 +**None to date.**
 +\\ \\
 +======Comments======
 +**None**
 +\\ \\
 +======Nice to have======
 +
 +    * Ability to "Merge" two surveys together.
 +    * PDF export
 +    * Localization of sections and questions (see section following this one for two approaches)
 +
 +======Localization======
 +One approach (Robby O'Connor's preference):
 +
 +Two tables (section_localization, question_localization) and the following fields:
 +
 +   - section_id (FK to survey_section.id) and question_id (FK to survey_question.id) respectively.
 +   - locale (i18n locale, e.g., en_UK, en_AU, en_US,fr_fr)
 +   - name (localized name)
 +   - description (localized description)
 +
 +
 +Alternative approach, the appeal to this approach is as opposed to splitting sections and question localization into two tables, we combine them into one. Either approach is sound:
 +
 +One table, survey_localization and the following fields:
 +
 +   - section_id (FK to survey_section.id)
 +   - question_id (FK to survey_question.id)
 +   - locale (i18n locale, e.g., en_UK, en_AU, en_US,fr_fr)
 +   - name (localized name)
 +   - description (localized description)
  

QR Code
QR Code foundation:surveytool_spec (generated for current page)