Currency-Denominated Loan Products

Owned by Ed Cable
Jun 19, 2014
10 min read

Introduction

An MFI could currently have loan products in 2 currencies.  They need a way to track both in their own currencies.  This feature implements basic multicurrency support and also sets the basis for full multicurrency support in the future.

User Stories (Epics)

PriorityUser StorySection in FR
1As an Administrator at an MFI, I want to be able to disburse loans of different currencies to my clients. 

Goals

  • Ability to configure Mifos to have a default currency and additional currency
  • Ability to select a currency when creating loan products.
  • Ability to set appropriate rounding rules per currency
  • Loans will inherit currency definition from the loan product it's created from.
  • Ability to select a currency for fees created for loans only.

Non-Goals

The following items will not be addressed in this release:

  • Support for 2 currencies with performance history - if Performance History involves rolling up values in 2 different currencies, then that item will not be displayed
  • Support multiple currencies for client, group, or centers  - they will all use default currency (fees)
  • Support multiple currencies for savings
  • Support multiple currencies in Collection Sheet Entry
  • Displaying additional currency labels anywhere in Mifos
  • Support for multiple currencies in fees other than loan fees

Definitions and Terminology

TermDefinitions
  
  • Mandatory fields will be preceded by *
  • Links are italicized
  • Buttons are Button

 

Currency Denominated Loan Products

This feature will allow minimal multiple currency support in Mifos.

Use Cases

Administrator configures Mifos for multiple currencies

Actors

  •  Administrator

Preconditions

  •  None

Basic Flow

  1. Administrator edits the configuration file and sets the default currency to USD and additional currency to LBP.
  2. Administrator updates relevant accounting settings such as rounding amount for each currency accordingly.  Administrator updates settings for the additional currency that differ from the settings for the default currency.

Post-conditions

  • Mifos can have 2 currencies now.

Alternative Flows

Administrator does not configure Mifos for multiple currencies.

  1. Administrator does not have additional currency set in configuration file.

Post-conditions

  • There are no options for currencies in Mifos.  The user has no knowledge that Mifos can have 2 currencies.

Validations

  • None

Administrator creates a loan product in a currency other than the Default

Actors

  • Administrator

Preconditions

  • Mifos has been configured to have a default currency of USD and an additional currency of LBP.

Basic Flow

  1. Administrator logs onto Mifos and navigates to creating loan products.
  2. Administrator creates new Loan Product A and specifies LBP as the currency for the loan product.
  3. Mifos saves Loan Product A.

Post-conditions

  • All loans created from Loan Product A use LBP.

Alternative Flows

  • None

Administrator creates a loan fee in the secondary currency and attaches to Loan Product A.

Actors

  •  Administrator

Preconditions

  • Mifos has been configured to have a default currency of USD and an additional currency of LBP.
  • Loan Product A has LBP as its currency defined.

Basic Flow

  1. Administrator logs onto Mifos and navigates to creating fees.
  2. Administrator creates new loan fee Fee A and specifies LBP as the currency for the loan fee if the loan fee is a specific amount, not a % of calculation.
  3. Mifos saves Fee A.
  4. Administrator navigates to edit Loan Product A and is able to attach Fee A to the loan product.

Post-conditions

  • None

Alternative Flows

Administrator tries to attach a loan fee in different currency than Loan Product A.

  1. Administrator goes to edit Loan Product A.  Administrator adds Fee B of a different currency to Loan Product A.  Administrator hits Preview.
  2. Mifos displays error message - A fee of a different currency cannot be attached to this loan product.

Loan Officer creates a loan account in secondary currency

Actors

  •  Loan Officer

Preconditions

  •  Mifos has been configured to have a default currency of USD and an additional currency of LBP.

Basic Flow

  1. LO logs onto Mifos and navigates to create a new loan account.
  2. LO selects a loan product of the secondary currency.  LO saves the new loan.

Post-conditions

  • New loan account is in secondary currency.

Alternative Flows

Loan Officer attaches a loan fee of secondary currency to a loan account

  1. At step 2 of workflow, LO attaches new loan fee also of the same currency to the loan account.  Options under Fees available only include fees of the same currency as the loan account.
  2. Mifos saves the loan.  The loan has a fee in the same currency attached.

Loan Officer applies charges to an existing loan account

  1. LO navigates to an existing loan account and clicks on Apply Charges.
  2. LO chooses a fee to attach.  The only options available are those of the same currency.

Loan Officer disburses and repays loan in secondary currency

Actors

  •  Loan Officer

Preconditions

  • Mifos has been configured to have a default currency of USD and an additional currency of LBP.
  • Loan accounts in secondary currency have been created.

Basic Flow

  1. LO logs onto Mifos and navigates to an existing loan that hasn't been disbursed.
  2. LO disburses loan.

Post-conditions

  • Loan disbursal is in secondary currency
  • Repayment schedule is all in secondary currency

Alternative Flows

LO enters in values for amounts that do not correspond to the settings in Configuration

Preconditions

  • Mifos has been configured to have a default currency of USD and an additional currency of LBP.
  • Loan accounts in secondary currency have been created.
  • Mifos has been configured to have digits after decimal for LBP to be 0.

Alternate Flow

  1. At step 2 of Basic Flow, LO tries to enter a value for loan disbursal that has more digits after decimal than 0.
  2. Mifos throws an error message that this is invalid.

Accountant imports file of transactions in secondary currency

Actors

  •  Accountant

Preconditions

  • Mifos has been configured to have a default currency of USD and an additional currency of LBP.
  • Loan products and accounts in secondary currency have been created.

Basic Flow

  1. Accountant logs onto Mifos and navigates to Import Bank Transactions.
  2. Accountaint imports a file with all loan transactions for loans in LBP.
  3. Mifos imports the file of transactions.

Post-conditions

  • All loan accounts in that file have been updated accordingly with the transactions in that currency.

Alternative Flows

User Stories

PrioritySizeUser StoriesMingle card #
1SmallAs a User, I configure Mifos to have multiple currencies 
1SmallAs a User, I can select a currency when defining a loan product 
1SmallAs a User, I can select a currency when defining a loan fee. 
1SmallAs a User, I can attach a loan fee of the same currency to a loan product. 
1SmallAs a User, I can attach a loan fee of the same currency to a loan account. 
1SmallAs a User, I can disburse and repay loans of that currency 

Currency Denominated Loan Products Functional Requirements

Update configuration settings

FR#PriDescriptionComments / Mockups
1.1P1Add new setting for setting additional currencies in custom properties file.  See properties file for examples =>applicationConfiguration_accounting.custom.properties 
1.2P1Additional currencies should only be applicable to loan repayments and loan fees 
1.3P1Update View Organizational Settings in Admin section of Mifos to show the new and updated configuration settings.http://img526.imageshack.us/i/orgsettings.png/ 
1.4P1By default there should be no additional currencies set 
1.5P1Certain rounding rules can be set different than the default for additional currenices. If those settings are not set for the additional currency, the default setting is used. If it is set, it overrides the default.

These settings are:

FinalRoundOffMultiple 

InitialRoundOffMultiple 

AmountToBeRoundedTo 

DigitsAfterDecimal 

DigitsAfterDecimalforInterest 		Rounding Modes are P2
    
1.7P1Currencies can be added at any time during Mifos deployment, but once a currency has been set, it cannot be removed.Document in Configuration Guide

Add ability to define a new loan product of secondary currency

FR#PriDescriptionComments / Mockups
2.1P1In Define New loan product pipeline, User now has a new Currency dropdown to choose the currency from default and additional currencies set in configuration file. 
2.2P1The options are the 2 currency codes the Administrator set in the custom properties file. 
2.3P1The Default currency code is first in the list of options for Currency and should be defaulted to it in the dropdown 
2.4P1When editing a loan product, the Currency option should be displayed but uneditable. 
2.5P1When defining a new loan product, if the User tries to attach a loan fee of a different currency, the following error message is displayed upon the User trying to Preview

A fee of a different currency cannot be attached to this loan product 		 

Add ability to define a loan fee of secondary currency

FR#PriDescriptionComments / Mockups
3.1P1In Define New Fee pipeline, when User selects "Loan" under Fee Applies To:, the option to select a currency should be dynamically displayed next to Amount calculation. 
3.2P1A new Currency dropdown should be displayed after the Amount field in Calculation - which should be the 2 currency codes the Administrator set in the custom properties file.  The Currency is only set for loan fees with specific amount, not % of calculation.  A loan fee with % of calculation can be of any currency. 
3.3P1The Default currency code is first in the list of options for Currency and should be defaulted to it in the dropdown 
3.4P1This option should only be added for defining new fees and cannot be changed when editing the fee. 
3.5P2When viewing a loan fee, currency should be displayed if the User has set additional currencies in the custom properties file 

Create new Loan account with Loan Product with a different Currency

FR#PriDescriptionComments / Mockups
4.1P1When creating a new loan account, the User should be able to select a loan product that has a secondary currency set as its currency 
4.2P1Should work with GLIM on or off 
4.3P1Should work with LSIM on or off 
4.4P1All loans under that Loan Product should take currency and rounding rules from the custom properties file set for that currency. 

Attach loan fee of secondary currency to loan account

FR#PriDescriptionComments / Mockups
5.1P1When creating a new loan account, the list of fees available under Apply Additional Fees should only be loan fees of the same currency set as the loan product of the loan account. 
5.2P1The User can also apply charges for an existing loan account. The available fees listed under "Select charge type" should only be fees of the same currency 

Disabled Functionality

FR#PriDescriptionComments / Mockups
6.1P1Collection Sheet Entry will not work if there are loans of multiple currencies under the center. There will be no changes to accommodate this, the feature will remain but advise to use with caution (or not use at all). (P2) When a user does use CSE and selects a center with more than 1 currency, warning text is displayed at the top. 
6.2P1Certain parts of Performance History will not be shown for a Center, Group, or Client that has loans of more than one currency under it. Instead of a value, the following string will be displayed in the field <Multiple Currencies> 
6.3P1For a client's performance history, Amount of last loan and Delinquent Portfolio will not be displayed. 
6.4P1For a group's performance history, the following will not be displayed

Amount of last Group Loan: xx

Avg individual Loan size: xx

Total Loan portfolio. xx

Portfolio at risk: xx		 
6.5P1For a center's performance history, Total Loan portfolio will not be displayed 

Reports

FR#PriDescriptionComments / Mockups
7.1P1Existing reports will NOT be rewritten to accommodate this feature. They will just not work if there is a problem with the query due to multiple currencies. 

Validations around accounting settings for new currencies

FR#PriDescriptionComments / Mockups
8.1P1All existing validations in Mifos for numbers entered for currency should be updated to validate according to the new settings set in the configuration file, if one is set.  For example, if USD is set to digits after decimal is 3, and LBP is set to 0, then if a User is entering in values for the loan account from the LBP Loan Product, Mifos should throw an error if the User enters in any digits after decimal.  

Other Assumptions

LSIM

  • LSIM will be on - but should work on or off

GLIM

  • GLIM will be on for Al M's configuration

QA Considerations

  • Performance History - for fields where there needs to be rollup of 2 currencies, will display a msg instead.
  • Create multiple loan accounts - should still work regardless of currency of loan products
  • Import Bank Transactions - make sure this works

Standard Considerations

Security (Permissions, Roles, and Data Scope)

Does the user need to be in a particular user hierarchy to use this feature?No
Does the office hierarchy affect use of this feature?No
Are you using any existing permissions to control this feature?No
Are you adding any new permissions or changing existing permission to control this feature?No
Are you using any existing activities to control this feature?No
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?Upgrade needs to work for existing configurations with only 1 currency
What will be the default values for default roles in a new installation?No

Impacts to System

Does this feature affect Bulk Loan Creation?  How?No
Does this feature affect Collection Sheet Entry?  How?Yes - if center has more than 1 currency, CSE will not work
Does this feature affect Redo Loans?Yes
Does this feature affect Undo Loans?Yes

Globalization/Localization

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?No
Is there currency or other numeric data ? If so does it require any special handling or validation?Yes - handled by configuration files

Logging

Change Log

Do changes to the data that is collected or stored by the new feature have to be fully logged by the system?Yes
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.

Does the feature affect any existing reports?Yes - but those will not be changed
Does the feature require adding any new reports?No

Performance

Will the feature be a high use-case scenario?No
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?No
Does the feature contain risks of database connection timeout?No
Will the feature contain any bulk insert/update/delete transactions?No
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?No
Does the feature affect existing batch jobs or require adding any new batch jobs?No

Setup and Installation

New Installations

Will the feature include demo data?No
Does the feature require any data to be gathered at setup runtime?No

Backward Compatibility and Upgrades

Is there any data conversion that needs to be done as part of an upgrade?No?
Will customers lose data or will the way existing data is stored change significantly?No
Will another feature, workflow or portion of the data model be deprecated as a result of this new feature?No
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?New options added in UI for currency if they choose to have one

Hosting Support

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

Configuration

Does this feature require changes to configuration files?Yes
If so, is this feature enabled or disabled by default?Disabled

Customers

Which MFI's do we expect to use this feature? 
How will this impact them?Â