PPI Functional Spec

Owned by Kay Chau
Last updated: Dec 21, 2010Version comment
17 min read

Release

Leila E

Current Owners

Kay Chau

Status (Draft, In Review, Approved)

In Review

Contents:

Introduction

PPI as it is in Mifos is difficult to use and does not meet all the needs of an MFI who using PPI.  We need to implement the feature in Mifos so that it is more flexible, and provides the reporting capabilities to do analysis.  For Leila E, we must meet our Cisco commitments.

User Stories

Priority

User Stories

Section in FR

P1

As a PPI Administrator at my MFI, I want to be able to access PPI surveys for my country when I am using Mifos.

3.1

P1

As a PPI Administrator at my MFI, I want to be able to activate one or more PPI's for my organization.

3.2

P1

As a PPI Administrator, I want to be able to apply Mifos PPI Surveys to more than one flow, and to be able to apply to multiple flows and modify the flows it applies to\

3.2

P1

As a Loan Officer, I want to be able to enter my clients' answers to PPI questions, and have them saved.

3.3

P1

As a Loan Officer, I want to be able to enter answers for PPI questions again (possibly in a different workflow), and have it saved as a separate survey.  I want to be able to track PPI score from survey to survey of the same client.

3.3

P1

As a Loan Officer, I want to be able to edit an answer that was entered (because of a mistake), and have reports take the latest version of that PPI Survey data since the old answer was incorrect

3.3

P1

As a PPI Administrator, I want to be able to select which version of PPI survey I want the Loan Officers at my MFI to fill out.

3.7

P1

As a PPI Administrator, I want to be able to inactivate one or more PPI's for my organization, but ensure that data saved against that survey is retained.

3.2

P1

As a PPI Administrator, when a PPI survey gets updated questions/answers, I want to ensure that the correct questions/answers are available.

3.6

P1

As a PPI Administrator, when a PPI survey gets updated points, I want to ensure existing surveys already taken get the right scores calculated.

3.6

P1

As a PPI Administrator, when a PPI survey gets an updated lookup table, I want to ensure new reports run display accurate data on likelihoods.

3.6

P2

As a PPI Administrator, I want to be able to run a "data dump" report to verify my clients' PPI scores

3.8

P2

As a PPI Administrator, I want to be able to run a "data dump" report to verify my clients' PPI likelihoods

3.8

Goals

  • Provide a way for MFI's to collect PPI survey data from clients entered into Mifos
    • When data is entered into Mifos, it is part of a workflow to collect information from clients
  • Ability to do analysis on scores and likelihoods of clients
    • 1 data dump will be available
  • Ability to select which PPI surveys are available for the MFI

Non-Goals

The following items will not be addressed in this release:

  • View clients' scores and likelihoods directly in Mifos (can be run in report)
  • Ability for anyone other than the Mifos product team to provide the PPI surveys in Mifos.

Definitions and Terminology

Term

Definitions

User

User of system


  • Mandatory fields will be preceded by "*" (an asterisk)
  • Links are italicized
  • Buttons are Button

Related Documents

Use Cases

Access PPI's

Actors

  • Administrator

Preconditions

  • Mifos is shipped with several PPI's
  • Mifos has been upgraded to version with this PPI.

Basic Flow

  • Administrator is able to view a directory of all shipped PPI's here - Past Releases. Administrator selects the one(s) relevant to their MFI, and copies it into the QG directory to be picked up.

Post-conditions

  • Under Activate QG, the dropdown includes the PPI's the Administrator has copied over.

Activate India PPI

Actors

  • Administrator

Preconditions

  • Mifos is shipped with India PPI 2005.
  • Mifos has been upgraded to version with this PPI.
  • Mifos Administrator has copied the PPI India 2005 manually to the correct directory (part of Upgrade notes)

Basic Flow

  • Administrator navigates to Activate Question Groups in Admin section of Mifos.
  • Administrator is able to select "India PPI Survey 2005" from a list of available QG's and chooses to activate.
  • Mifos activates "India PPI Survey 2005".

Post-conditions

  • Under "View Question Groups" will be a QG called "India PPI Survey 2005" with the questions and answer choices.  The survey is automatically assigned to the Create Client workflow.
  • When a Loan Officer enters in clients' answers to a PPI, he is able to select India PPI 2005 as the version he wants to enter.

Change where the PPI questions are asked

PPI Administrator wants the PPI questions to be asked during Close Client, not Create Client

  • Administrator navigates to View Question Groups, and selects PPI India 2005.
  • Administrator edits the QG, and edits the Applies To: to be Close Client, and removes Create Client.  Administrator saves the new QG.

OR

  • Mifos Administrator changes the PPI India 2005 XML file directly to have Close Client instead of Create Client as the <applies to> tag.  Administrator restarts Mifos.
  • Mifos Administrator logs onto Mifos, and follows the Activate PPI Survey and activates the new survey.  They also inactivate the old one.

Post-conditions

  • The PPI Survey is now available only when a client's status is being changed to Closed.  It is not displayed during Client Creation.

Have PPI questions asked in more than one flow

PPI Administrator wants the PPI questions to be asked during both Create Client, and when opening a new Loan account for the client.

  • Administrator navigates to View Question Groups, and selects PPI India 2005.
  • Administrator edits the QG, and edits the Applies To: to be Create Client and Create Loan.  Administrator saves the QG.

Post-conditions

  • The PPI Survey is now available during Client Creation and Loan Creation.

Inactivate PPI

A new survey has come out, and the Administrator needs to inactivate the old one

  • Administrator navigates to View Question Groups, and selects the old Survey.
  • Administrator edits the QG, and chooses to make it Inactive.  Administrator saves the QG.

Post-conditions

  • The old survey is now inactive.  It does not appear anywhere in Mifos.
  • For clients who had used the old survey, it is still possible to run reports based on the old survey.

Validations

Save PPI Answers

Actors

  • Loan Officer

Preconditions

  • PPI India 2005 has been activated and applied to the Create Client workflow.

Basic Flow

  • Loan Officer navigates to create a new client, and under Additional Information, the PPI Survey questions are displayed. Loan Officer selects the right answer choices and saves the client information.

Post-conditions

  • Client has PPI Survey data saved, and the data is ready for reporting.

Save another set of PPI Answers

Actors

  • Loan Officer

Preconditions

  • PPI India 2005 has been applied to both Create Client and Close Client workflows. Client's PPI data was collected during client creation.

Basic Flow

  • Client is leaving the MFI. Loan Officer would like to conduct an exit survey. Loan Officer navigates to Close the Client, and PPI Questions are displayed. Loan Officer saves the latest answers.

Post-conditions

  • Report can be run to take both PPI scores from Client creation and Close Client. The scores are separate and accurate.

Update Incorrect Answers Captured with a PPI Survey

Actors

  • Loan Officer

Preconditions

  • PPI India 2005 has been filled out for a client. One of the answers captured was incorrect.

Basic Flow

  • Loan Officer navigates to where the wrong answer was captured for the client. Loan Officer is able to view the answers already captured, and clicks on Edit to edit the answers.
  • Loan Officer saves the correct answers.

Post-conditions

  • Reports only take the latest version of this data saved. Old data is retained but is not used for reporting the score.

Update Incorrect Questions/Answer Choices with a specific PPI Survey Version

Example:  PPI India Survey 2005 was published, and is shipped with Mifos.  However, a couple of months later, it turns out one of the questions and/or answer choices was incorrect and needs to be updated.

Actors

  • PPI Administrator

Basic Flow

  • Mifos Team updates the PPI India Survey 2005 QG that was shipped with Mifos with a new version with new question/answers.
  • Mifos is upgraded at the MFI.
  • Mifos Administrator locates the new XML file with the updated Survey questions and answer choices, and copies to the QG directory for activation.
  • Administrator navigates to View Question Groups, and inactivates the old QG with the incorrect questions and/or answers.
  • Administrator then navigates to Activate QG and activates the new India PPI 2005. (Is there an indicator that this is different?)
  • Administrator navigates to View Question Groups again, and edits the new PPI Survey to have all the properties he wants (workflows to apply to, editable answers, etc)

Post-conditions

  • Loan Officer can now see updated survey questions and/or answers for entering PPI surveys.
  • Old surveys need to be invalidated?

Update Incorrect Answers' Point Values with a specific PPI Survey Version

Example:  PPI India Survey 2005 was published, and is shipped with Mifos.  However, a couple of months later, it turns out one of the points associated with an answer choice was incorrect.  The Scoring associated with the survey needs to be updated to reflect this.

Actors

  • PPI Administrator

Basic Flow

  • Mifos Team updates the Mifos PPI Scoring and Likelihood Lookup Tool with the NEW scoring.  Mifos BI is updated and released.
  • Mifos BI is upgraded at the MFI.
  • PPI continues to be collected.

Post-conditions

  • All reports run on surveys taken with this particular version, should now use the new Scoring to calculate score.
  • No changes to UI

Update Incorrect Lookup Table(s) with a specific PPI Survey Version

Example:  PPI India Survey 2005 was published, and is shipped with Mifos.  However, a couple of months later, it turns out the lookup table was INCORRECT for the NPL.  The values need to be updated.

Actors

  • PPI Administrator

Basic Flow

  • Mifos Team updates the Mifos PPI Scoring and Likelihood Lookup Tool with the NEW Lookup tables.  Mifos BI is updated and released.
  • Mifos BI is upgraded at the MFI.
  • PPI continues to be collected.

Post-conditions

  • All reports run on surveys taken with this particular version, should now have the updated likelihood data.
  • No changes to UI

Update NEW PPI Survey version

Example:  PPI India Survey 2005 was published, and is shipped with Mifos.  In 2007, a new PPI India Survey comes out.  It can have different questions, answers, scoring, and/or lookup tables.  These all need to be updated.  However, all surveys taken before 2007 should still use old Scoring and Lookup Tables.

Actors

  • PPI Administrator

Basic Flow

  • Mifos Team delivers new PPI India Survey 2007 with updated Survey questions and answers, Scoring, and/or Lookup Tables.
  • Mifos and Mifos BI is upgraded at the MFI.
  • PPI Administrator follows the Access PPI's and then Activate PPI use case and activates PPI India Survey 2007.  They also inactivate PPI India Survey 2005.

Post-conditions

  • Reports run should map to correct survey version date.  If a report is run from 2005 to 2009, for likelihoods under $1/day, and that band is not available in 2005, then the report should throw an error.
  • No changes to UI

View PPI Score and Likelihoods

Actors

  • PPI Administrator

Basic Flow

  • PPI Administrator logs onto Pentaho, and selects to run PPI Data Dump Report.
  • PPI Administrator selects the dates to run the data dump for, and runs the Report.
  • Data Dump Report in Excel is displayed.  

Post-conditions

Functional Requirements

Pre-shipped PPI Surveys

FR #

Pri

Description

Comments/Mockups

1.1

P1

Mifos will ship with a set of XML files that are the latest PPI surveys for each country available.  These are in the Mifos Question Group format.

Mifos will ship with all countries available.


1.2

P1

See XML template here -

 

1.3

P1

Each file will have survey questions and answer choices associated with the PPI Survey.

Bug fixed to allow longer question titles

1.4

P1

In addition, there will also be a field to enter the Date of Survey Taken.

 

1.5

P1

Each survey is also by default applied to the "Create Client" workflow.

 

Activate PPI

FR #

Pri

Description

Comments/Mockups

2.1

P1

PPI Surveys are not active by default.  Mifos Administrator must copy the relevant PPI survey files and place them in the QG directory in Mifos in order for them to be available for activation.


2.2

P1

Administrator can navigate to Activate Question Group link and view a dropdown of Question Groups available.  PPI Surveys will be prefixed with "PPI".  All PPI surveys available will be listed. 

 

2.3

P1

Administrator can choose a PPI Survey they want to activate, and click Submit. 

 

2.4

P1

Afterward, Administrator can view the QG is available in "View Question Groups".  Once it is activated, the PPI Survey is active and automatically in the Create Client workflow.

 

2.5

P1

Administrator can edit a PPI Survey QG to change and update multiple workflows the PPI Survey applies to. 

The only workflows that will generate a PPI Score are the following:

Create Client
View Client
Close Client
Create Loan
View Loan
Approve Loan
Create Savings
View Savings

 

2.6

P1

Administrator can change the order of questions asked in a PPI Survey.  This has no effect on the score.

 

2.7

P1

Administrator can inactivate a PPI Survey by changing Status to Inactive when editing the PPI Survey.

We will encourage MFI's to inactivate old/wrong surveys first before activating a new/updated PPI survey to avoid confusion on which version to use.  See FR Section 7 for more details

2.8

P1

By default, all questions in the PPI QG are mandatory.  This can be changed by the MFI but it is not recommended.  If any question is not answered, then we do not expect the survey to be scored

 

2.9

P1

The PPI questions themselves are locked - IE, an Administrator has no way through the Mifos UI to edit the question or answer text.  This should only be handled outside of Mifos and through updates to Mifos.

 

 

 

Issue MIFOS-4078 :  It is possible to re-activate the same PPI QG.  A new QG is created with the same title but the questions are re-used.

 

Save PPI Answers

FR #

Pri

Description

Comments/Mockups

3.1

P1

PPI QG's are displayed in the workflow(s) it is applied to.  Mifos User can enter in answers to questions and they are saved.


3.2

P1

IF the PPI QG has been marked as "Can be edited" then this means a Mifos user can return to the survey already taken, and edit the answers.  This scenario should only be used for correcting wrong answers. 

 

3.3

P1

If a new survey has been taken for the client, then the Mifos user should open a new unanswered survey for the client - this can be done using the View Entity workflows (similar to surveys today)

 

3.4

P1

If a PPI survey is applied to more than one flow, then each new survey taken should yield a distinct PPI score.  These can be seen in reports.

 

3.5

P1

One behavior to note is - if the PPI QG is applied to the Create Client workflow for example, and the Loan officer does not know all answers to mandatory questions in QG's applied to that workflow, they cannot save any answers.  They must return to the Create Client workflow only when they know all answers to mandatory questions.  This is the same as previous behavior for Additional Fields in entities.

 

Mifos PPI Scoring and Lookup Tool

FR #

Pri

Description

Comments/Mockups

4.1

P1

Mifos BI will ship with a PPI Scoring and Lookup Tool (ETL) that maps PPI Surveys to Scoring and Likelihood Tables associated with them.  PPI Surveys are identified by name and version (i.e. PPI India 2005.1). 

 

4.2

P1

The versions of scores and lookup tables will be mapped to the Survey version in Mifos. 

 

4.3

P1

Each question is identified by an internal short name that will be able to be mapped to the PPI Scoring and Lookup Tool for point values.

 

4.4

P1

Versioning for each survey and scoring and lookups are by year then by minor version.  For example, A Survey might be PPI India 2009.01

 

4.5

P1

MFI must have both Mifos Leila E Release, and Mifos BI 1.0 Beta installed to have the Mifos PPI Scoring and Lookup Tool work correctly.

 

How to Score and Look up Likelihoods

FR #

Pri

Description

Comments/Mockups

5.1

P1

Each survey has 10 questions. Each question has some answer choices. Each answer choice has a point value. For any single survey taken, sum up points associated with each answer choice chosen. Total is the PPI Score for that particular score.

 

5.2

P1

If a survey is not completely filled out (this should be not be possible in Mifos, all questions should be marked mandatory), then there should be no score returned, and the survey is invalid.

 

5.3

P1

With the PPI Score, the client's likelihood under or above several poverty lines can be looked up using the associated Lookup Tables.  There will be a different set of lookup tables associated with each PPI Survey.  These tables can also change from version to version.

 

Correction of PPI Surveys (Questions, Answer Choices, Point Values, and Lookup Tables)

FR #

Pri

Description

Comments/Mockups

6.1

P1

If a question or answer choice was incorrect in a survey recently released, Mifos will bundle with a new QG with the correct questions and answer choices.  Upon upgrade to this version of Mifos. the Mifos administrator can inactivate the old incorrect survey, and activate the new one.

 

6.2

P1

All surveys taken previously with the wrong questions and answer choices should be invalidated

 

6.3

P1

If a point value associated with an answer choice for a PPI Survey needs to be corrected, the Mifos PPI Scoring Tool must be updated so that the new point value is taken when calculating the PPI Score.  All reports run for the PPI Survey taken with this version must now use the updated point value(s) to calculate the PPI Score.

 

6.4

P1

If a lookup table associated with a PPI Survey was incorrect, the Mifos PPI Scoring and Lookup Tool will be updated with the correct lookup tables.  All reports run will use the correct lookups.

 

New Versions

FR #

Pri

Description

Comments/Mockups

 

7.1

P1

When a new version of PPI comes out, Mifos must have the new QG and Mifos BI must be upgraded with the new ETL's.  It might be only necessary to upgrade the Mifos BI solution, depending on if there were any fundamental changes in Mifos for PPI.

If the MFI has a roll-out phase of PPI's, they can have both old and new PPI's activated.  The old PPI remains active, and they can activate the new PPI.  However, both PPI's are set mandatory by default.  If both surveys need to be available in the same workflow (ie Create Client), and then it is up to the LO to fill out the correct one.  The different PPI versions will have different headings at the top of each survey - IE, PPI India 2005 or PPI India 2008. 

In the case where both versions of PPI's can be in the same workflow, they have to go into each PPI QG manually and make none of the questions mandatory.  Otherwise, a LO might be required to fill out both versions, and then the scores will be incorrect.

 

7.2

P2

In a future release, we should implement this so that the roll-out is easier for the MFI.

 

Reports

FR #

Pri

Description

Comments/Mockups

8.1

P1

A simple data dump will be provided in Mifos BI 1.0 with scores and likelihoods of all clients.

See attachment - Example PPI reporting - Data Dump tab

8.2

P1

For reporting, the ETL updates the D/W daily at a certain time.  That means updated scores are only available after the job runs.  The timing of the job can be configured.

 

Deprecate Old Functionality

Options

Pros

Cons

Cloud Customer Experience

Existing Customer Experience

Work TBD

 

 

 

 

 

 

2) Remove old PPI settings completely, but keep data saved.

Old PPI is not there anymore.

Existing customers have to migrate old PPI data over to QG's first

Just look at new spec for how to use

They must migrate old PPI over and train staff on new PPI

If they use new PPI too, need to migrate over - and they need to update their reports in Pentaho to use both

Remove old settings.

Standard Considerations

Security

Security (Permissions, Roles, and Data Scope)

Yes/No

Comments

Does the user need to be in a particular user hierarchy to use this feature?

Yes

Permission for PPI needed to activate PPI, permission with QG needed to edit the QG the Survey questions are in, and LO need to have rights to edit information for their clients or loan accounts depending on where in the Mifos workflow the PPI Surveys are active.

Does the office hierarchy affect use of this feature?

Yes

LO's can only enter data from PPI Surveys for clients in their hierachy

Are you using any existing permissions to control this feature?

Yes

We should be using existing permissions to control this

Are you adding any new permissions or changing existing permission to control this feature?

Yes

We added a new Activate Question Group permission.

Are you using any existing activities to control this feature?

Yes

Question Groups have been implemented

Are you adding any new activities or changing existing activities to control this feature?

No

 

Are there any special considerations for upgrade scenarios? What will be the default value for new permissions?

No

 

What will be the default values for default roles in a new installation?

--

Admin will have all permissions

Impacts to System

Impacts to System

Yes/No

Comments

Does this feature affect Bulk Loan Creation? How?

No

There are no QG's in this workflow

Does this feature affect Collection Sheet Entry? How?

No

 

Does this feature affect Redo Loans?

No

 

Does this feature affect Undo Loans?

No

 

Globalization/Localization

Globalization/Localization

Yes/No

Comments

Will this feature support users localizing data that they enter?

Yes

 

Does this feature involve any date/time related data, and if so how should conversions be handled?

Yes

 

Is there currency or other numeric data ? If so does it require any special handling or validation?

No

 

Logging

Change Log

Change Log

Yes/No

Comments

Do changes to the data that is collected or stored by the new feature have to be fully logged by the system?

Yes

This should already been done by the QG implementation

Does the administrator configuring the system need the ability to turn on or off logging for this feature?

No

 

Is the feature currently logged but the structure of the logged records changing?

No

 

Reporting

Provide any relevant information about reporting requirements for the new features and answer the questions below, providing detail to explain any particular area when necessary.

Reporting

Yes/No

Comments

Does the feature affect any existing reports?

No

 

Does the feature require adding any new reports?

Yes

See Reports FR above

Performance

Performance

Yes/No

Comments

Will the feature be a high use-case scenario?

Yes

 

Will the feature have potential for high concurrency?

No

 

Does the feature include complex UI or data gathering logic that will be used by a significant portion of the user base?

Yes

 

Does the feature contain risks of database connection timeout or JSP page timeout?

No

 

Will the feature contain any bulk insert/update/delete transactions?

?

 

Will the feature contain any caching mechanisms or cache refreshing mechanisms?

No

 

Could the feature result in a large amount of data being sent to the client or between the database and web server?

No

 

Would users on a low bandwidth connection likely face issues with a part of this feature?

?

 

Does the feature affect existing batch jobs or require adding any new batch jobs?

?

 

Setup and Installation

New Installations

New Installations

Yes/No

Comments

Will the feature include demo data?

No

 

Does the feature require any data to be gathered at setup runtime?

Yes

Surveys must be pre-shipped

Backward Compatibility and Upgrades

Backward Compatibility and Upgrades

Yes/No

Comments

Is there any data conversion that needs to be done as part of an upgrade?

Yes?

GK

Will customers lose data or will the way existing data is stored change significantly?

Yes

Migration for GK

Will another feature, workflow or portion of the data model be deprecated as a result of this new feature?

Yes

 

Will existing role permissions be changed or impacted by this feature? If so provide details in the security section.

No

 

Will existing customers need to learn a new UI process or change the way they use the system as a result of this new feature?

Yes

 

Hosting Support

Hosting Support

Yes/No

Comments

If different user groups are using the same database, are there concerns over the sharing of data related to the feature?

No

 

Are there expected to be performance related issues with having many customers sharing the same hardware in support of this feature?

No

 

Does this feature require Sys Admin work to set up for clients?

Yes

Pentaho and Mifos must be set up

Configuration

Configuration

Yes/No

Comments

Does this feature require changes to configuration files?

?

 

If so, is this feature enabled or disabled by default?

?

 

Open Issues

Reviews and Approvals