Functional Specifications for the Sahana Eden Survey Tool for Google Summer of Code 2010

Revision History
0.1Robby O'Connor2010-05-17First Draft.
0.2Michael Howden2010-05-22First Review.
0.3Robby O'Connor2010-05-24Second Draft – Response to Reviews
0.4Robby O'Connor2010-05-26Added Question Data Types and mockups for each type
0.5Robby O'Connor2010-05-28Changed the “author” column's FK on Survey Template to go to pr_person vs pr_pentity.
0.6Robby O'Connor2010-05-29Added mock-ups for the create template and create series screen; as well as the “Home” screen.
0.7Robby O'Connor2010-05-31Moved around the mock-ups for the “Add Question” and “Analysis” screen to the “Screens” Section of the spec.
0.8Robby O'Connor2010-05-31Removed 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.9Robby O'Connor2010-06-19Updates to the data model
1.0Robby O'Connor2010-06-19Added some UI mockups; detailed the wizard steps for the wizard UIs that will exist in the system.
1.1Robby O'Connor2010-06-24Updated to reflect or→org
1.2Robby O'Connor2010-06-19Added Wizard Flowchart.


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


(to be completed)


Super Users - have access to do EVERYTHING

Data Entry Clerks - People who enter the data.


  • 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 NamePurposeData typeRequired
nameActs as the display name – the title of the surveystringYes
descriptionDescription of this templatetextNo
lockedPrevent modifying a survey which is being editedbooleanNo
authorWho created this templateFK to pr_person.idNo – defaults to logged in user
organisationThe organisation that this template is used forFK to org_organisation.idYes

Survey Question
Holds information about Survey Questions.

Field NamePurposeData typeRequired
nameacts as the display name for the questionstringYes
descriptionDescription of this questiontextNo
question_typedenotes the question type (see section on question types).FK to survey_question_typeYes

Survey Section
Holds information about survey sections.

Field NamePurposeData typeRequired
nameacts as the display name for the sectionstringYes
descriptionDescription of this sectiontextNo

Survey Series
Associate a survey (or set of surveys with a series)

Field NamePurposeData typeRequired
namethe name of the seriesstringYes
descriptionDescription of the seriestextNo
survey_template_idAssociated Survey TemplateFK to survey_template.idYes
from_dateStart of perioddatetimeYes
to_dateEnd of perioddatetimeYes
locationLocation Survey Conducted.FK to gis_location.idYes

Survey Instance
Holds the records for each survey answered in a survey series

Field NamePurposeData typeRequired
survey_series_idThe series to which this instance refers toFK to survey_series.idYes

Survey Answer
Holds answers to surveys to be displayed if survey is answered.

Field NamePurposeData typeRequired
survey_instance_idThe instance this answers refers toFK to survey_instance.idYes
question_idQuestion to which this being answered forFK reference to the survey_question.idYes
answer_valuethe answerstringYes
commentsthe comments (if any)textNo

Survey Template Link Table
Link table to solve the many-to-many relation between: Surveys↔Questions and Sections↔Questions

Field NamePurposeData typeRequired
question_idSurvey QuestionFK to survey_question.idNo
section_idSurvey SectionFK to survey_section.idNo
survey_template_idSurvey TemplateFK to survey_template.idNo
orderThe order which the question appears in the surveyintNo

Question Metadata
Used to store configuration data

Field NamePurposeData typeRequired
question_idQuestion these options are related to.FK to survey_question.idYes
row_choicerow choice for ratingtextNo
column choicecolumn choice for rating (can customize)textNo
ta_rowshow many rows for the text-areaintNo
tf_ta_columnsThe number of rows for either Text Field or Text AreaintNo
allow_commentsWhether or not to render a comment fieldbooleanNo
comment_display_labelThe comment to text display before the text field for commentsstringNo
requiredWhether or not the question should be required to be filled outbooleanNo
validateWhether or not to enable validation for the questionbooleanNo
aggregation_typeHow the question should be aggregated (non-editable by the userstringNo

Survey Widgets (Custom Data Types)
Used to store configuration data

Field NamePurposeData typeRequired
question_idQuestion this widget is related to.FK to survey_question.idYes
widgetThe render-able markup used to render the questiontextYes

Survey Answer Options
Used to store the answer options (e.g., Yes, No, Not Applicable)

Field NamePurposeData typeRequired
question_idQuestion these answer options are related to.FK to survey_question.idYes
option_valueThe value to display e.g., “Yes”textYes

Question Data Types

Internally question types are stored *NUMERICALLY*.

  1. Multiple Choice (Only One Answer): Option exists to display in one,two, or three columns
  2. Multiple Choice (Multiple Answers): Options in layout: one,two, or three columns or horizontal layout.
  3. Rating Scale:
  4. Single Textbox
  5. Multiple Textboxes
  6. Comment/Essay Box
    1. Large text-area to take in an essay or comment.
  7. Numerical textboxes
    1. This has validation that ensures that a numeric answer is given.
  8. Date and/or Time
    1. Datepicker will be used here.
  9. Image
    1. Simple way of having a logo or branding on the survey.
  10. Descriptive Text
    1. A way to have some prose in whatever form necessary
  11. Location
  12. Organisation
  13. Person
  14. Custom Database Resource (any resource defined in eden is possible here).




Now the add question form

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.):

The pop-up generated when “Add Section” is clicked will look like the following:

The home screen looks like follows:

Finally, the analysis page will look like this:

Wizard Steps

Survey Creation
Step NumberPage
1Survey Template
2Add Questions/Sections
3Add 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 NumberPage
1Survey Question
2Survey Question Options Configuration

UI Design

→ implies going to a new screen


  • Create
  • Fill Out
  • Results
  • Analysis
  • Advanced



  • Big Button for create
  • List of recently created surveys
  • List of recently added surveys to fill out
  • List of recently completed surveys


  • 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:
  1. Enter Survey Name, other details
  2. Enter survey sections.
  3. 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


  • 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”)


  • 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
  1. compare the actual surveys (not the questions) - how similar are they?
  2. Add the answers together
  3. what is the difference between the results (eg change from Jan-Dec)


(to be completed later)


(to be completed later)


Open Issues

None to date.



Nice to have

  • Ability to “Merge” two surveys together.
  • PDF export
  • Localization of sections and questions (see section following this one for two approaches)


One approach (Robby O'Connor's preference):

Two tables (section_localization, question_localization) and the following fields:

  1. section_id (FK to and question_id (FK to respectively.
  2. locale (i18n locale, e.g., en_UK, en_AU, en_US,fr_fr)
  3. name (localized name)
  4. 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:

  1. section_id (FK to
  2. question_id (FK to
  3. locale (i18n locale, e.g., en_UK, en_AU, en_US,fr_fr)
  4. name (localized name)
  5. description (localized description)

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