Currency-Denominated Loan Products
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)
Priority | User Story | Section in FR |
---|---|---|
1 | As 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
Term | Definitions |
---|---|
- 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
- Administrator edits the configuration file and sets the default currency to USD and additional currency to LBP.
- 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.
- 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
- Administrator logs onto Mifos and navigates to creating loan products.
- Administrator creates new Loan Product A and specifies LBP as the currency for the loan product.
- 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
- Administrator logs onto Mifos and navigates to creating fees.
- 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.
- Mifos saves Fee A.
- 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.
- Administrator goes to edit Loan Product A. Administrator adds Fee B of a different currency to Loan Product A. Administrator hits Preview.
- 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
- LO logs onto Mifos and navigates to create a new loan account.
- 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
- 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.
- Mifos saves the loan. The loan has a fee in the same currency attached.
Loan Officer applies charges to an existing loan account
- LO navigates to an existing loan account and clicks on Apply Charges.
- 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
- LO logs onto Mifos and navigates to an existing loan that hasn't been disbursed.
- 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
- At step 2 of Basic Flow, LO tries to enter a value for loan disbursal that has more digits after decimal than 0.
- 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
- Accountant logs onto Mifos and navigates to Import Bank Transactions.
- Accountaint imports a file with all loan transactions for loans in LBP.
- 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
Priority | Size | User Stories | Mingle card # |
---|---|---|---|
1 | Small | As a User, I configure Mifos to have multiple currencies | |
1 | Small | As a User, I can select a currency when defining a loan product | |
1 | Small | As a User, I can select a currency when defining a loan fee. | |
1 | Small | As a User, I can attach a loan fee of the same currency to a loan product. | |
1 | Small | As a User, I can attach a loan fee of the same currency to a loan account. | |
1 | Small | As a User, I can disburse and repay loans of that currency |
Currency Denominated Loan Products Functional Requirements
Update configuration settings
FR# | Pri | Description | Comments / Mockups |
---|---|---|---|
1.1 | P1 | Add new setting for setting additional currencies in custom properties file. See properties file for examples => | applicationConfiguration_accounting.custom.properties |
1.2 | P1 | Additional currencies should only be applicable to loan repayments and loan fees | |
1.3 | P1 | Update View Organizational Settings in Admin section of Mifos to show the new and updated configuration settings. | http://img526.imageshack.us/i/orgsettings.png/ |
1.4 | P1 | By default there should be no additional currencies set | |
1.5 | P1 | Certain 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.7 | P1 | Currencies 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
2.1 | P1 | In 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.2 | P1 | The options are the 2 currency codes the Administrator set in the custom properties file. | |
2.3 | P1 | The Default currency code is first in the list of options for Currency and should be defaulted to it in the dropdown | |
2.4 | P1 | When editing a loan product, the Currency option should be displayed but uneditable. | |
2.5 | P1 | When 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
3.1 | P1 | In 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.2 | P1 | A 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.3 | P1 | The Default currency code is first in the list of options for Currency and should be defaulted to it in the dropdown | |
3.4 | P1 | This option should only be added for defining new fees and cannot be changed when editing the fee. | |
3.5 | P2 | When 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
4.1 | P1 | When 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.2 | P1 | Should work with GLIM on or off | |
4.3 | P1 | Should work with LSIM on or off | |
4.4 | P1 | All 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
5.1 | P1 | When 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.2 | P1 | The 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
6.1 | P1 | Collection 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.2 | P1 | Certain 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.3 | P1 | For a client's performance history, Amount of last loan and Delinquent Portfolio will not be displayed. | |
6.4 | P1 | For 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.5 | P1 | For a center's performance history, Total Loan portfolio will not be displayed |
Reports
FR# | Pri | Description | Comments / Mockups |
---|---|---|---|
7.1 | P1 | Existing 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# | Pri | Description | Comments / Mockups |
---|---|---|---|
8.1 | P1 | All 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? |