unicefuganda · madhavaramu · Dec 14, 2016 · Dec 21, 2016 · Mar 7, 2017 · Mar 7, 2017
diff --git a/.coveragerc b/.coveragerc
diff --git a/.gitignore b/.gitignore
@@ -52,3 +52,4 @@ tags
 submissions/*
 answerFiles/*
 survey/static/admin/*
+
diff --git a/.travis.yml b/.travis.yml
@@ -1,3 +1,8 @@
+branches:
+  only:
+  - master
+  - uSurvey
+
 language: python
 
 python:

diff --git a/config/database.yml b/config/database.yml
diff --git a/docs/Add_Groups.png b/docs/Add_Groups.png
diff --git a/docs/Add_Variable.png b/docs/Add_Variable.png
diff --git a/docs/Batch1.png b/docs/Batch1.png
diff --git a/docs/Batch10.png b/docs/Batch10.png
diff --git a/docs/Batch11.png b/docs/Batch11.png
diff --git a/docs/Batch12.png b/docs/Batch12.png
diff --git a/docs/Batch13.png b/docs/Batch13.png
diff --git a/docs/Batch14.png b/docs/Batch14.png
diff --git a/docs/Batch15.png b/docs/Batch15.png
diff --git a/docs/Batch16.png b/docs/Batch16.png
diff --git a/docs/Batch17.png b/docs/Batch17.png
diff --git a/docs/Batch18.png b/docs/Batch18.png
diff --git a/docs/Batch2.png b/docs/Batch2.png
diff --git a/docs/Batch3.png b/docs/Batch3.png
diff --git a/docs/Batch4.png b/docs/Batch4.png
diff --git a/docs/Batch5.png b/docs/Batch5.png
diff --git a/docs/Batch6.png b/docs/Batch6.png
diff --git a/docs/Batch7.png b/docs/Batch7.png
diff --git a/docs/Batch8.png b/docs/Batch8.png
diff --git a/docs/Batch9.png b/docs/Batch9.png
diff --git a/docs/Edit_group.png b/docs/Edit_group.png
diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
@@ -0,0 +1,69 @@
+
+###Getting Started
+
+**The General flow for the uSurvey is as follows**:
+
+* Admin creates uSurvey Users and assigns them Roles
+* User ‘Data Researcher’ defines Modules, Groups, Listing, Surveys, Batches and creates questionnaires for Listing & Batches in application
+* Data Researcher also defines ‘Interviewers’ and assigns them to an Enumeration area to conduct a Listing or Survey
+* In the field, Interviewer conducts the actual survey in the designated Enumeration area
+* Data collection is done using a hand-held mobile device like Android Smart Phone or Featured Phone via ODK and USSD channels respectively.
+* Captured data is sent to uSurvey portal
+* Data collected by Interviewers is then viewed on the uSurvey portal for reporting and analysis
+
+**A Quick step by step uSurvey process flow**
+
+**Step -1**
+
+Create [New Module](./Modules.md) or skip this step, if you want to use existing Modules
+
+**Step -2**
+
+Create [New Group](./Groups.md) or skip this step, if you want to use existing Groups
+
+**Step -3**
+
+Create [New Listing](./Listing.md) or skip this step, if you want to use existing Listing or you can Clone existing Listing and rename it. Here we have to observe two things;
+
+1. Use existing Listing: This option benefits by providing data collected earlier <br>
+2. Clone existing Listing: Duplicates Listing questions only <br>
+
+   3.0. Once Listing is created, next <br> 
+   3.1. Create Questions in Listing <br>
+   3.2. If necessary, <br>
+   3.3. Create Looping in questions and <br>
+   3.4. Add Logic to questions. <br>
+
+**Step -4**
+
+Create [New Survey](./Survey.md) or you can Clone existing Survey and rename it,<br>
+**Clone existing Survey**: This option duplicates the survey along with the Listing data, and ready to use.
+
+4.0. Once a new Survey is created, next <br>
+4.1. Create Batch or Batches <br>
+4.3. then Create Questions in Batch <br>
+     If necessary, <br>
+4.4. Create Looping in questions and <br> 
+4.5. Add Logic to questions. <br>
+4.6. Finally, don’t forget to change the status to Open, via Action Item ‘Open/Close’ for Batch
+
+**Step -5**
+
+Enroll [an Interviewer](./Interviewer.md) <br>
+To conduct a Survey in the field, define an Interviewer as follows: <br>
+5.0. Provide basic Interviewer details, <br>
+5.1. Assign a Survey, <br>
+5.2. Allocate Enumeration Areas, <br>
+5.3. Create ODK Access ID, <br>
+5.4. Provide Mobile Number to access via USSD channel <br>
+5.5. Finally, finish enrollment <br>
+
+**Step -6**
+
+**Conduct Survey**: 
+Data collection and submission is done in two ways:
+
+1. Android channel - [Using uSurvey App](./ODK_App.md)
+2. USSD channel - [Featured Phone](./ussd-integration.md)
+
+At any point on the uSurvey portal, use breadcrumbs on top of each page for easy navigation.
diff --git a/docs/Group1.png b/docs/Group1.png
diff --git a/docs/Group10.png b/docs/Group10.png
diff --git a/docs/Group2.png b/docs/Group2.png
diff --git a/docs/Group2_1.png b/docs/Group2_1.png
diff --git a/docs/Group2_2.png b/docs/Group2_2.png
diff --git a/docs/Group3.png b/docs/Group3.png
diff --git a/docs/Group4.png b/docs/Group4.png
diff --git a/docs/Group5.png b/docs/Group5.png
diff --git a/docs/Group6.png b/docs/Group6.png
diff --git a/docs/Group7.png b/docs/Group7.png
diff --git a/docs/Group8.png b/docs/Group8.png
diff --git a/docs/Group9.png b/docs/Group9.png
diff --git a/docs/Groups.md b/docs/Groups.md
@@ -0,0 +1,84 @@
+
+###Groups
+
+Groups are Survey dependent classification of people/respondents based on their Age, Gender and combination of both into one or more survey- respondents categories called Groups.
+Population has to be segment into Groups / multiple groups and our system allows us to create as many as needed.
+
+From this above Groups page, Groups are managed, i.e. to Create a New Group, Edit existing Group, Delete Groups and Manage Parameters
+
+###Create a New Group
+Groups are available from main menu under, <b>Design</b> >> <b>Groups</b>
+
+![Group](./Group1.png)
+
+To create a new Group, click on ‘Add Group’ button at top right of the Groups page, that opens a form to create a new Group.
+
+![Group](./Group2_1.png)
+
+###Elements of Group
+
+<b>Name</b>: Is Group Name, which is a unique identity to a Group and is a mandatory field.   
+
+<b>Description</b>: A short description about Group
+
+<b>Parameter</b>: Need to select a parameter, based on which Group is created. Like Age, Gender  
+
+<b>Operator</b>: Also need to select an Operator based on the Parameter value, like value starts with, equals to and between, etc.
+
+![Group](./Group3.png)
+
+A Group is created by providing above all field, such that a Group can be created using a single or combination of Parameters, finally click on ‘Save’ button to Create Group. 
+
+<b>Existing Criteria</b>
+This table shows list of parameters used in creating a Group and can be altered by Deleting the existing one and assigning a different parameter to the same Group Name, by changing the ‘Parameter’ and ‘Operator’ values, then click ‘Save’ button.
+
+<b>Edit and Delete Groups</b>
+From the Groups Table each of the Group has Action items to ‘Edit’ and ‘Delete’ Group.
+
+![Group](./Group4.png)
+
+![Group](./Group5.png)
+
+To Edit a Group – In the table under column name ‘Actions’ select ‘Edit’ to modify existing the criteria, name, description, then click ‘Save’ button.
+
+To Delete a Group – In the table under column name ‘Actions’ select ‘Delete’ to remove from list, before deleting you will be prompted with conformation to delete, click ‘Yes’ to Delete permanently.
+
+###Available Parameters
+
+Parameters plays a major portion in creating a Group, to check what are the Parameters available, Add, Edit and Delete Parameters are managed.
+
+![Group](./Group6.png)
+
+<b>Add Parameters</b>
+
+To Add Parameter, click on ‘Add Parameter’ button at top right of the Parameter page, that opens a form to create a new Parameter, which has following elements;
+
+![Group](./Group7.png)
+
+<b>Elements of Parameter</b>
+
+<b>Variables Name</b>: Is an identifier for Parameter, Enter the name of the Parameter 
+
+<b>Text</b>: A short description about Parameter
+
+<b>Answer Type</b>: Select an Answer Type for Parameter from dropdown list, such that Parameter is of type Text, Numeric and Multi choice.
+
+![Group](./Group8.png)
+
+A Parameter is created by providing above all field, finally click on ‘Save’ button to Create Parameter or click on ‘Save and Add More’ button to continue adding more Parameters to the list.
+
+<b>Edit and Delete Parameter</b>
+From the Parameter Table each of the Parameter has Action items to ‘Edit’ and ‘Delete’ Parameter.
+
+![Group](./Group9.png)
+
+![Group](./Group10.png)
+
+To Edit a Parameter – In the table under column name ‘Actions’ select ‘Edit’ to modify existing the Variable name, Text and Answer Type, then click ‘Save’ button.
+
+To Delete a Parameter – In the table under column name ‘Actions’ select ‘Delete’ to remove from list, before deleting you will be prompted with conformation to delete, click ‘Yes’ to Delete permanently.
+
+<b>View Options</b>: This Action item is visible only for the Questions that has Answer Type “Multi choice”, to view Answer Choices.
+
+<b>Export Parameter</b>
+Click on ‘Export Parameter’ to download available list of Parameter in ‘.CSV’ file format.
diff --git a/docs/Home.png b/docs/Home.png
diff --git a/docs/Ind1.png b/docs/Ind1.png
diff --git a/docs/Ind10.png b/docs/Ind10.png
diff --git a/docs/Ind11.png b/docs/Ind11.png
diff --git a/docs/Ind12.png b/docs/Ind12.png
diff --git a/docs/Ind13.png b/docs/Ind13.png
diff --git a/docs/Ind2.png b/docs/Ind2.png
diff --git a/docs/Ind3.png b/docs/Ind3.png
diff --git a/docs/Ind4.png b/docs/Ind4.png
diff --git a/docs/Ind5.png b/docs/Ind5.png
diff --git a/docs/Ind6.png b/docs/Ind6.png
diff --git a/docs/Ind7.png b/docs/Ind7.png
diff --git a/docs/Ind8.png b/docs/Ind8.png
diff --git a/docs/Ind9.png b/docs/Ind9.png
diff --git a/docs/Indicators.md b/docs/Indicators.md
@@ -0,0 +1,75 @@
+###Indicators
+
+A Data Researcher can choose one or more fields from their survey and create an arithmetic expression to generate metrics as per their requirement. Each such expression is called an Indicator. Any number of indicators can be created for a Survey. A limited number of these indicators can be selected to be shown on the dashboard.
+
+Our system facilitates creating customized Indicators for every survey and show an analysis report in tabular and bar chart form.
+
+**How to create an Indicator?**
+
+On the ‘Indicator’ page one can view list of all survey wise Indicators in the application and can view analysis report.
+
+To create an Indicator, click on ‘Add Indicator’ button at top right of the Indicator page, this will open a blank form with following elements;
+
+**Elements in the Indicator form**
+
+**Survey**: Select Survey from list, for which the Indicator need to be defined.
+
+**Listing**: Select respective Listing, for which the Indicator need to be defined.
+
+**Indicator**: Define a name to the Indicator   
+
+**Description**: A short description about Indicator
+
+**Variables**: To create an Indicator, certain metrics are needed for calculation, which are derived from survey/ listing questions   
+
+**Formulae**: compose a formula based up on available Variables, <br>
+Auto suggestion feature is available, which will prompt with the ‘Variables’ already defined above for composing. <br>
+i.e. just type, double curly brackets to automatically prompt with the ‘Variables’ already defined, <br>
+Ex: type {{ , system prompts with ‘Variables’ then select any one to insert Variable, <br>
+Like: {{hh_age}} <br>
+
+**Display on dashboard**: This option allows the indicator to be displayed on the dashboard. A user can select a maximum of 5 indicators to be shown on the dashboard.
+
+**Add Variable**: 
+
+To Add a Variable, click on respective ‘+’ icon adjacent to ‘Variables’ Text box, that opens form to define a Variable, following parameters are involved and expressed.
+
+**Name**: Define a name to the Variable
+
+**Description**: A short description about Variable
+
+**Test question**: Select respective Listing questions, for which the Variable need to be defined.
+
+**Operator**: Select respective operator based up on the value of the above ‘Test question’
+
+Once all the above fields are filled, then click on ‘Add’ button to add to below table ‘Settings for this Variable’, since you can add more Variables for combination, once all Variables are defined then, finally click on ‘Save’ button to add to Variables list.
+
+One can also ‘Edit’ and ‘Delete’ Variables using the respective icons adjacent to ‘Variables’ Text box.
+
+Once Variables are defined, now you can compose the formula in ‘Formulae’ Text box, the composed formula is validated automatically and a message is shown here as ‘Valid’ or ‘in valid’.
+
+Once Variables are defined, formula is composed and validated, finally click on ‘Save’ button to create an Indicator.
+
+On the ‘Indicator’ page one can view all the Indicator created in the application, in a tabular form with following column names:
+
+**Sts**: Represents Indicator display status on dashboard, that means status with color code indicates as:
+
+ <span style="color:Gray;font-weight:bold;">•</span> – Not Displayed<br>
+ <span style="color:Green;font-weight:bold;">•</span> – Displayed<br>
+
+**Indicator**: Is the title of Indicator, which is a unique identity to represent Indicator of a Survey.
+
+**Description**: A short description about Indicator
+
+**Survey**: Name of the Survey to which this Indicator belongs
+
+**Batch**: Name of the Survey Batch to which this Indicator belongs
+
+**Actions**: 
+
+* **Edit**: click on, Action Item ‘Edit’, User can Edit all fields in Indicator.
+* **Delete**: click on, Action Item ‘Delete’, the Indicator is removed, before deleting you will be prompted with conformation to delete, click ‘Yes’ to Delete permanently
+* **Formula**: click on, Action Item ‘Formula’, to edit the Indicator Formula directly
+* **Analysis**: click on, Action Item ‘Analysis’, navigates to ‘Indicator Analysis’ page, here one can view two forms of district wise reports based up on the Indicator Formula,
+  * A Bar chart report is generated and displayed
+  * A tabular report 
diff --git a/docs/Interviewer.md b/docs/Interviewer.md
@@ -0,0 +1,71 @@
+###Interviewer
+
+Interviewer is a role in the system, one who conducts a Survey in the field.   
+These Interviewers conducts the survey in the designated Enumeration areas and data collection is done using the hand-held mobile device like Android Smart Phone or Featured Phone via ODK and USSD channels respectively.
+
+Data researcher enrolls Interviewer, assigns Survey and defines the Enumeration areas.
+
+Enrolled Interviewer are available from main menu under <b>Administration</b> >> <b>Interviewers</b>
+
+![Interviewer](./Interviewer1.png)
+
+###Interviewer Registration
+On the ‘Interviewers’ page one can view list of enrolled Interviewers in the application, Add, Manage and Edit Interviewer can be done.
+
+To register a new Interviewer, click on ‘Add Interviewer’ button at top right of the Interviewers page, this will open a registration form with following elements;
+
+![Interviewer](./Interviewer2.png)
+
+<b>Elements in the registration form</b>
+
+![Interviewer](./Interviewer4_1.png)
+
+<b>Select Locations</b>: Initially get list of Enumeration Areas (EA) by selecting respective, District, County, Sub-county and Parish from locations filters at top of this page, to allocate Enumeration areas to the Interviewer where survey has to be conducted.
+
+<b>Name</b>: Name of the Interviewer
+
+<b>Date of Birth</b>: Date of birth of the Interviewer
+
+<b>Gender</b>: Gender of the Interviewer
+
+<b>Education</b>: Education qualification of the Interviewer
+
+<b>Preferred Language</b>: select, Interviewer’s preferred language to write and speak
+
+<b>Survey</b>: Assign a Survey to the Interviewer, select a Survey from the list
+
+<b>Enumeration Area</b>: The places or locations where assigned Survey is supposed to be conducted by the Interviewer. Select EAs from ‘All EAs’ list by clicking on the list item, that is on listed EA.
+
+<b>ODK Access</b>: The process of collecting data using Android channel is known as ODK Access, to provide permissions to access this channel, an Interviewer needs following ODK Access credentials;
+
+<b>ODK ID</b>: It is the User Id / User Name to access ODK channel, only alphabets are accepted
+
+<b>ODK Token</b>: It nothing but password to access ODK channel, only numeric values are accepted
+
+<b>Activated</b>: Allow access or prevent access to ODK channel
+
+<b>USSD Access</b>: The process of collecting data using Featured Phone is known as USSD Access, to access this channel, an Interviewer needs to provide Mobile Number. 
+
+Options in USSD Access:
+
+<b>Add Mobile Number</b>: System facilitates, accessing from multiple mobile numbers also. So one can add multiple mobile numbers or remove here using ‘Add’ and ‘Delete’ options.
+
+<b>Activated</b>: Allow access or prevent access to USSD channel
+
+Interviewer is enrolled by providing above all field, finally click on ‘Save’ button to complete the process. 
+
+From this above Interviewers page, Interviewers are managed, i.e. to Edit Interviewer Details and block/unblock Interviewer
+
+<b>Actions</b>:
+
+![Interviewer](./Interviewer3.png)
+
+<b>View Details</b>: View Interviewer profile and Edit details, all profile details, Survey Details, ODK Access and USSD Access details are editable by click on ‘Edit’ button at the bottom of the page.
+
+<b>Un Block/ Block</b>: Option to make Interviewer active or in active.
+
+<b>Search</b>: One can find Interviewers in system by two ways:
+<b>Sort</b> Interviewers location wise by selecting respective, District, County, Sub-county and Parish from locations filters at top of this page. Or
+<b>Search</b> using the search bar at top right side of this page, by providing Interviewer’s Name.
+
+<b>Export Interviewers</b>: On click, ‘Export Interviewers’ button, user can download the Interviewers list in “.csv” file format.
diff --git a/docs/Interviewer1.png b/docs/Interviewer1.png
diff --git a/docs/Interviewer2.png b/docs/Interviewer2.png
diff --git a/docs/Interviewer3.png b/docs/Interviewer3.png
diff --git a/docs/Interviewer4.png b/docs/Interviewer4.png
diff --git a/docs/Interviewer4_1.png b/docs/Interviewer4_1.png
diff --git a/docs/Library.md b/docs/Library.md
@@ -0,0 +1,32 @@
+###Library Questions
+
+List of Questions very common in Surveys are available here which are also categorized into Module wise.  This is a feature/ facility available to pick up questions from this library and add to Batch or Listing, by ‘Select Questions’ feature in respective pages.
+
+<b>Create Library Questions</b>
+
+To add new questions in Library can be done in 2 ways.
+
+1. Adding directly question to Library 
+2. Using feature ‘Update Library’ while creating Batch or Listing Questions
+
+<b>Adding Directly</b>:
+On the ‘Library’ page one can view all the list of Library Questions, 
+Now click on, ‘Add Question’ button at top right side of this page, this will open a form where one can create a Question, which has following elements; 
+
+<b>Elements in Library Question</b>:
+
+<b>Module</b>: All Modules in the application are listed here in this dropdown, one has to select, respective Module that is related to survey.
+
+<b>Variables Name</b>: This is an identifier for Question, type a code for Question
+
+<b>Text</b>: Is the actual Question, Write a Question.
+
+<b>Answer Type</b>: Select an Answer Type from dropdown list, such that Question has to be answered in any one of these formats only, that is ‘Answer type’ should be: “Audio, Auto Generate, Date, Geo Point, Image, Multi choice, Multi Select, Numeric, Text and Video”
+
+A Library Question is created by filling above all fields, finally click on ‘Save’ button to Add Question to Library or click on ‘Save and Add More’ button to continue adding another Question.
+
+<b>Search</b>: One can find Questions in Library by two ways:
+<b>Sort</b> questions using ‘Answer Type’ dropdown at top left side of this page. Or
+<b>Search</b> using the search bar at top right side of this page, by providing text or code.
+
+<b>Export Questions</b>: On click, ‘Export Questions’ button, user can download the Library Questions in “.csv” file format.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -52,3 +52,4 @@ tags
		submissions/*
		answerFiles/*
		survey/static/admin/*