Question Groups Functional Spec

DEPRECATED - see Question Groups Functional Spec for the latest version of this.

Introduction

This is the FS for new Question Groups feature. This feature is available in Mifos 2.0 and beyond.

Add question

Questions can be added from either Add Question in Admin, or during creation of a Question Group.

More than one question can be added at a time.
While adding a new question, a user can enter a question title and can set the corresponding answer type.
Answer types can be free text, date, number, single select, multi select, smart select. See below for more details on each.
Preview of added questions is visible on the same page upon clicking “Add Question”.
The preview of the question contains the following: question title, answer type, choices and the remove link.
Answer choices can be added for single select / multi select / smart select answer types
Each answer choice added can be removed
On submitting the question, the user is taken to the Mifos Admin page.
Adding a question without specifying the question title gives an error message in red on the top of the page asking the user to specify the question title.
The user is prompted with a validation message if any of the following mandatory fields are not filled before submission: Title, Applies To.
In the case of single select / multi select / smart select, if the user tries to add a question without entering more than one choice of answer, the user is prompted by a validation message.

Answer type: Free text

Any type of text can be entered as part of response for this type of question including special characters.

Answer type: Number

Maximum and minimum values of the number can be entered
A default value cannot be set.

Answer type: Multi Select / Single Select

This answer type should be used for questions where you want the user to choose one choice or multiple choices for answers.

Any number of answer choices can be added.
The answer choices added do not have to be unique
Each choice can be removed by using the associated remove link before adding the question
Tagging is not available for this answer type. See Smart Select Answer type for this.
Once a question has been added to the preview, clicking the remove button for this question will remove the question along with all its answer choices.

Answer type: Smart Select

This answer type can be used for questions where you might have categories, and you may want the user to have see answer choices and their tags when entering in answers. For example, you may want to ask a client what their business activity is, and have categories of business activity. Answer choices could be entered as Cow Purchase, Pig Purchase, etc. A tag can be added to these answer choices as "Animal Husbandry". Then, when the Loan Officer is entering the answer for this client's business activity, they can enter Animal Husbandry to see the detailed choices.

Any number of answer choices can be added
Maximum 5 tags can be added per answer choice to give responder an idea of what all the answer choice incorporates
Tags can be of max 50 characters
A tag can be removed by clicking the cross beside it
There is a remove link for each answer choice. Clicking on this removes the choice along with its tags.
Both answer choices and the associated tags get stored as responses.
Tags cannot contain special characters (Including white space), only alphanumeric characters allowed
Tags are not arranged in alphabetical order
User cannot view the tags associated with an answer choice on the Add Question screen, once a question has been added to preview.

View Question

List of all questions can be seen
The question title, answer type, the answer choices and the associated tags for each answer choice (if applicable) can be viewed.
Questions can be edited by clicking the Edit link.
No other information except the question title can be seen on the View Questions screen.
Once a question has been created, it can never be deleted. It can only be set as inactive.

Edit Question

Only one question can be edited at a time.
Only the Title and status can be edited.
The status of the question could be set to active or inactive by clicking on the corresponding radio buttons.
A note is displayed on the Edit Question page at all points of time which says : Significant modification of questions could affect reporting
By default, the status of the question is set to active
Answer type of the question is not editable
While editing a question for single select/ multi select / smart select / smart select
- Additional answer choices can be added
- Only newly added answer choices can be removed
- Existing answer choices are visible but cannot be edited or removed
For smart select, tags can be added to existing as well as new choices. Tags can be removed for existing answer choices as well
Both minimum and maximum values are editable for questions with numeric answer types.
On submitting the changes, user returns to the view question details page and the changes are reflected on that page.
The user is prompted with a validation message if mandatory fields are not filled before submitting.
On cancelling the changes, user returns to the view question details page and none of the changes made are saved

Add question Group

Question Group Title, Applies to and Select Questions are mandatory fields.
The admin can choose to make the response editable by checking in the ‘Is response editable’ option. If this is checked, and the response to the question group is edited, the old answer choices are overwritten in the UI. Historical data entered is still saved, but it is expected that reports may take the latest answers entered.
A question group can be created for any of the following workflows
- Create Client; View Client; Close Client; Create Group; View Group; Create Office; Create Personnel; Create Center; View Center; Create Savings; View Savings; Create Loan; View Loan; Disburse Loan; Approve Loan
- For the "Create" workflows, the Question Group is displayed during creation of that entity. For the "View" workflows, the QG can be attached to that entity.
- If "Create Loan" workflow is selected, you can choose to have the QG automatically apply to all Loan Products. If this is not checked, then the user must go edit each loan product individually for the QG to apply to that loan product.
There can be more than one section within a group.
More than one question can be selected from the list of questions at one time.
User can add any number of questions to the sections.
The questions added to the section can be marked mandatory.
If the user removes a particular section, all the questions within that section will also be removed.
Removing all the questions within a section removes the section itself.
The question list can be from the content typed in the text box corresponding to ‘Select Questions’, or new questions can be created on the fly. See Add Question for more details.
Simply adding the questions without mentioning the section title puts the questions within the default section Misc.
If a question has already been added to some section, that question is no more a part of the list of questions in the drop-down available.
A section should have at least one question within it.
Question group title and the section title can both contain special characters (including spaces).
When the user selects a question to be added to a particular section containing at least one question , but do not click ‘Add Questions’ and instead clicks submit, the user is taken to the admin page and the question does not get added.
Two sections cannot have the same questions within them.

View Question Group

View Question Groups lists all question groups created with the workflow it is applied to. Because a Question Group can be applied to multiple workflows, a QG may be listed multiple times.
A new question group can also be defined from the view question group page.
On the particular question group page, I can view the following information :
- The workflows it belongs to
- Is the response editable
- Questions within the question group, if the question is mandatory, and the status of the question (active or inactive).
- Status of the question : whether the question is active or inactive
Once a question group has been created, it cannot be deleted. It can only be set as inactive or it may be hidden if all the questions within that question group are inactive
On the particular question group page, for questions within that question group, tags cannot be seen if the chosen answer type for the questions is smart select.

Edit Question Group

Question group title can be edited
Additional sections can be added to the question group
Both new and existing questions can be added
Only one question can be edited at a time.
The status of the question group could be set to active or inactive by clicking on the corresponding radio buttons.
By default, the status of question group is set to active
On submitting the changes, the user is navigated to the view question group details page and the changes made to the question group are reflected on that page.
On cancelling the changes, user returns to the view question group details page and none of the changes made are saved
The ‘is response editable’ field can be checked or unchecked depending on whether the user wants the question group responses to be editable or not.
Each question within a question group can be set mandatory or otherwise. By default, the mandatory option is unchecked.
If a user leaves the section heading field blank and adds questions, these questions will be added to Misc section
The list of existing questions limits itself to the text typed in the attached textbox.
The section heading textbox populates itself with the last typed section heading. By default, the section heading is set to Misc.
The workflows the QG applies to can be edited as well. If a QG is removed from a workflow, the answers saved remain the DB, but the QG no longer appears as available in the workflow.
Section headings cannot be edited
Within a question group, a question cannot be a part of more than one section.

Associating question groups to "Create" workflows

A question group is created for this flow by selecting the ‘applies to’ field as ‘create' xxx depending on which entity.
When question group is created belonging to ‘create ’ flow, the sections and questions within it can be viewed on the second page of the workflow questions during that entity's creation. The user is expected to respond to the questions on this page. The user will not be allowed to proceed to the next page if the questions have been marked mandatory in the question group definition.
The question group name is not visible on the capture response page. The section headings and the associated questions are only visible.
The sections and questions belonging to that question group are also visible on the ‘Review and submit’ page during client creation. The responses to the questions are also visible here.
‘Edit additional information’ button on the ‘Review and submit’ page lets the user edit the response to the questions belonging to the question group.
The questions and the associated responses can be viewed by clicking on ‘View Additional Information’ link on client details page.
The responses can be edited if ‘is response editable’ field has been set to yes in the question group definition. The responses edited and saved are versioned.
For "Create Loan" workflow in particular, the loan product have this QG applied for it to be available.

Associating question groups to "View" workflows

A question group is created for this flow by selecting the ‘applies to’ field as "view" xxx depending on which entity.
Users can be made to respond to these question groups by clicking on ‘attach a survey’ on the right hand corner of entity details page.
A question group can be selected for responding from ‘select survey’ which contains the list of all question groups associated with this workflow.
After selecting a question group and clicking ‘continue’, the user is navigated to the capture response page for the selected question group.
The question groups responded to and the date of response can be seen under the ‘Surveys’ label on the entity details page.
The responses can be edited if ‘is response editable’ field has been set to yes in the question group definition. The responses edited and saved are versioned.
Clicking on the edit link on the ‘view and edit questionnaire’ page lets the user edit the responses to the questions within the question group.
The edited version is appended to the list of responded surveys along with the date of modification.
The previous (non-edited) version of the responded question group also remains as part of the list.

Associating question group to Approve loan workflow

A question group is created for this flow by selecting the ‘applies to’ field as ‘Approve Loan’
When question group is created belonging to ‘approve loan’ flow, the sections and questions within it can be viewed on the capture response page for loan approval. The user is expected to respond to the questions on this page. The user will not be allowed to proceed to the next page if the questions have been marked mandatory in the question group definition.
The question group name is not visible on the capture response page for loan approval. The section headings and the associated questions are only visible.
The responses are not editable (even if the ‘is response editable’ field is checked in the question group definition)

Activate question groups

Leila E allows MFIs with the feasibility of creating question groups using XMLs. As soon as the XMLs are saved in the folder in the format. The $MIFOS_CONF/uploads/questionGroups and $MIFOS_CONF points to the users’ Mifos configuration directory. The files are named as "PPISurvey<QuestionGroup_NAME>.xml" where [QuestionGroup_NAME] should be replaced with the question group name that the user wishes to activate.

Data migration for additional fields

Additional fields can be migrated by clicking on ‘Migrate Additional fields’ link on the ‘migrate data’ page. ‘Migrate data’ ‘page can be reached by clicking the ‘Migrate data’ link on the admin page. Clicking on ‘migrate additional fields’ triggers the additional field migration. The user is navigated to the admin page once the migration is complete.

Leila E deals with the migration of client, group and loan additional fields and their corresponding responses only.

CAN

The default values do not get migrated on additional fields’ migration.
When the server is restarted, all the responses will be migrated all over again.
Validation messages during the migration process are logged in the tomcat log automatically.
On migrating additional fields, if there is at least one additional field for a particular flow, then question groups are created with names (E.g. : Additional_Fields_Create Client, Additional_Fields_Create_Group, Additional_Fields_Create_Loan) and all additional fields belonging to the same flow are associated to the corresponding question groups.
The migrated additional fields are added under the 'Misc' section of the question group
Post migration, the corresponding question of the migrated additional field is in the active state
The additional field retains its mandatory/non-mandatory status post migration
Post additional field migration, the corresponding created questions and responses can be viewed in the corresponding capture response pages under label “Additional Information”

CANNOT

When the titles for an additional field and a question are same, but the answer types are different, then that additional field is not migrated. A validation message with reference id for additional field is logged in the tomcat log. Data migration process for other additional fields continues
When the string length of an additional field on the UI is greater than 50 characters, then the additional field is not migrated.
Post migration, additional field responses are not editable.

Data migration for surveys and additional fields

Surveys are migrated on upgrade to Leila E

Leila E deals with the migration of surveys and responses belong to all workflows

CAN

Surveys and responses for all workflows migration as part of Leila E
Validation messages during the migration process are logged in the tomcat log automatically.
The existing survey definition and responses are not lost post migration.
A new question group is created for each migrated survey for the same flow the survey belonged to.
The survey title becomes the question group title
The migrated survey questions are added under the 'Misc' section of the question group
Post migration, the question groups are in the active state
When the migrating survey and an existing question group have the same title and flow, then post migration, a duplicate QG is created with the same title as the existing QG.
The order of the questions within the survey remains the same post migration.
Question within a survey retains its mandatory/non-mandatory status after migration in the corresponding flow

CANNOT

‘Date of survey, surveyed by, entered into the system by’ fields and their corresponding responses are not visible on the UI after migration
When the server is restarted, all the responses get migrated all over again if the earlier migration failed.
When the string length of a survey title on the UI is greater than 50 characters, then the additional field is not migrated.
The existing survey definitions and responses are not lost post migration
The survey responses are not editable post migration.

If successful

NO additional fields should be listed under "View Additional Fields" in Admin
No more data exist in old Additional Fields tables in the DB
In the workflows where these additional fields existed, these additional fields shouldn't be displayed as Additional Fields - should now be under Question Groups
There should be no validation for mandatory additional fields - the validation should only be for QG's

If NOT successful

The additional fields that did not migrate should be listed under "View Additional Fields" in Admin
The additional fields that did not migrate and all data saved with them should still be in the DB
In the workflows where these additional fields existed, these additional fields shouldn't be displayed as Additional Fields - the MFI must re-create them manually under Question Groups
There should be no validation for mandatory additional fields - the validation should only be for QG's