Configuration Guide
Mifos 2 Configuration Guide
Mifos Configuration
The following topics are for system administrators and Mifos specialists configuring Mifos who are deploying Mifos.
Table of Contents
Mifos Configuration
Overview
Before you run Mifos...
About the One-Time Settings
Using a Custom Chart of Accounts
Creating your own Financial Action Mappings
Customizing the Application Configuration File
Locale
Accounting
Calendar
Clients
Process
Reporting
Adjusting Session Timeout
Scheduling Batch Jobs
Customizing your Database Connection
Mifos version 1.2 and older
Mifos versions greater than 1.2 and upgrades
Database-Configured Settings
Before your users access Mifos...
Starting Mifos
Customizing the User Interface
User Interface Labels
List Box Items (Look-Up Options)
Required and Hidden Fields
Create Additional Fields
Defining Office Hierarchy
Creating Roles
Creating Users
Configuring Payment Types
Configuring Payment Order
Setting Lateness and Dormancy Definitions
Defining Holidays
Information on Reporting and PPI Surveys
Configuring Mifos to work with Cloud Foundry
Overview
The topics assume that you have installed Mifos and configured its third-party applications as described in Installing Mifos, and that you are ready to configure the administrative settings in Mifos. After you configure these settings, your Mifos deployment will be ready for you or someone else to create loan and savings products, add new clients and groups, open accounts for clients and groups, and configure reporting.
The administrative configuration process involves two groups of settings, which should be configured at two different times:
Before you run Mifos: Certain administrative settings can only be configured when Mifos is not running. Among them are settings whose default values you have only one opportunity to change-before you run Mifos for the first time.
Before your users access Mifos: There are also administrative settings you should configure before your users access Mifos. You configure these settings via the Mifos user interface, on the Admin tab.
Note for version 1.0 users: Changes since Mifos version 1.0 include moving install-time settings out of the database and into plain-text files. If you are using Mifos version 1.0, see Configuring Mifos version 1.0.
Before you run Mifos...
This section describes the install-time settings in Mifos, or those that can only be configured when Mifos is not running. It also describes install-time settings whose values can only be changed to non-default values once, before you run Mifos for the first time.
About the One-Time Settings
When Mifos runs for the first time, it writes values to its database. Although many of these values can be changed later, some cannot. Specifically, the values from the Chart of Accounts can only be written to the database once. Similarly, TRAPDOOR properties in the application configuration file can only be assigned non-default values once, before you run Mifos for the first time. After that point, a TRAPDOOR property value can only be changed to its default setting.
Using a Custom Chart of Accounts
The Chart of Accounts used by Mifos can be customized to exclude certain General Ledger (GL) accounts or use a different hierarchy of accounts. Note that you have only one opportunity to make these customizations, before you run Mifos for the first time.
To customize the Chart of Accounts:
Create a copy of the default Chart of Accounts configuration file that ships with Mifos and name itmifosChartOfAccounts.custom.xml.
Customize mifosChartofAccounts.custom.xml as described in Chart of Accounts.
Mifos 1.6.x and earlier: Place your customized file on the app server classpath before you run your first instance of Mifos in your final, production environment.
Mifos versions greater than 1.6.x and trunk development:: Place your customized file in one of the MifosConfigurationLocations before you run your first instance of Mifos in your final, production environment.
Note: Once Mifos is deployed, you won't be able to delete GL accounts or change the account hierarchy. See the bulleted lists below for more information.
After Mifos is deployed, you can only make the following changes to your GL accounts:
Add new GL accounts (excluding top-level accounts)
Change account names (excluding top-level accounts)
You cannot make the following GL account changes after Mifos is deployed:
Delete GL accounts
Create new top-level accounts
Modify top-level account names
Modify the account hierarchy (moving parents/children)
Modify GL codes
Creating your own Financial Action Mappings
Unlike the Chart of Accounts, financial action mappings can be customized any time Mifos is not running.
GL accounts are used in conjunction with particular actions. For example, when principal is added to a new loan account (a credit), Mifos choses a GL account based on a mapping. The default mappings that Mifos uses are stored in applicationContext.xml, a file that ships with Mifos. For Mifos to function correctly, all actions must be mapped to an existing GL account.
To customize the financial action mappings:
Create a file named mifosBeanConfig.custom.xml.
Customize mifosBeanConfig.custom.xml (see the example below).
Mifos 1.6.x and earlier: Place your customized file on the app server classpath before you run your first instance of Mifos in your final, production environment.
Mifos versions greater than 1.6.x and trunk development:: Place your customized file in one of the MifosConfigurationLocations before you run your first instance of Mifos in your final, production environment.
The mappings will take effect once Mifos is restarted.
Example
Use the following as a starting point for creating your own mifosBeanConfig.custom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<beans
xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
" title="http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">">http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
<bean id = "financialRules"
class="org.mifos.accounts.financial.util.helpers.FinancialRules"
abstract="false" factory-method="getInstance">
<property name="actionToDebitAccount">
<map>
<entry key="PRINCIPALPOSTING" value="11201"/>
<entry key="INTERESTPOSTING" value="11201"/>
<entry key="FEEPOSTING" value="11201"/>
<entry key="PENALTYPOSTING" value="11200"/>
<entry key="ROUNDING" value="31401"/>
<entry key="MANDATORYDEPOSIT" value="11201"/>
<entry key="VOLUNTARYDEPOSIT" value="11201"/>
<entry key="MANDATORYWITHDRAWAL" value="24000"/>
<entry key="VOLUNTARYWITHDRAWAL" value="23000"/>
<entry key="SAVINGS_INTERESTPOSTING" value="41000"/>
<entry key="DISBURSAL" value="13101"/>
<entry key="MISCFEEPOSTING" value="11201"/>
<entry key="MISCPENALTYPOSTING" value="11201"/>
<entry key="CUSTOMERACCOUNTMISCFEESPOSTING" value="11201"/>
<entry key="MANDATORYDEPOSIT_ADJUSTMENT" value="24000"/>
<entry key="VOLUNTARYDEPOSIT_ADJUSTMENT" value="23000"/>
<entry key="MANDATORYWITHDRAWAL_ADJUSTMENT" value="11201"/>
<entry key="VOLUNTARYWITHDRAWAL_ADJUSTMENT" value="11201"/>
<entry key="WRITEOFF" value="13201"/>
<entry key="RESCHEDULE" value="11201"/>
</map>
</property>
<property name="actionToCreditAccount">
<map>
<entry key="PRINCIPALPOSTING" value="13100"/>
<entry key="INTERESTPOSTING" value="31100"/>
<entry key="FEEPOSTING" value="31300"/>
<entry key="PENALTYPOSTING" value="31102"/>
<entry key="ROUNDING" value="31401"/>
<entry key="MANDATORYDEPOSIT" value="24000"/>
<entry key="VOLUNTARYDEPOSIT" value="23000"/>
<entry key="MANDATORYWITHDRAWAL" value="11201"/>
<entry key="VOLUNTARYWITHDRAWAL" value="11201"/>
<entry key="SAVINGS_INTERESTPOSTING" value="24100"/>
<entry key="DISBURSAL" value="11201"/>
<entry key="MISCFEEPOSTING" value="31301"/>
<entry key="MISCPENALTYPOSTING" value="31102"/>
<entry key="CUSTOMERACCOUNTMISCFEESPOSTING" value="31301"/>
<entry key="MANDATORYDEPOSIT_ADJUSTMENT" value="11201"/>
<entry key="VOLUNTARYDEPOSIT_ADJUSTMENT" value="11201"/>
<entry key="MANDATORYWITHDRAWAL_ADJUSTMENT" value="24000"/>
<entry key="VOLUNTARYWITHDRAWAL_ADJUSTMENT" value="23000"/>
<entry key="WRITEOFF" value="13101"/>
<entry key="RESCHEDULE" value="13101"/>
</map>
</property>
</bean>
</beans>
You may notice that other unrelated sections from applicationContext.xml have been omitted. This is intentional. The code that parses this XML configuration file allows for partial changes, and only those settings specific to financial action mappings inmifosBeanConfig.custom.xml can be customized.
Action names are actually constants in the FinancialActionConstants enum class. All actions must be mapped (except, currently, PENALTYPOSTING and REVERSAL_ADJUSTMENT) because Mifos assumes they are. For example, Mifos expects the mapping to contain a ROUNDING account. If the mapping doesn't exist, the application may crash or corrupt data because it cannot find an account with which to resolve rounded amounts.
Values may be changed, but they must point to GL account codes as specified in the Chart of Accounts.
Customizing the Application Configuration File
Mifos ships with a default application configuration file (applicationConfiguration.default.properties) that controls many aspects of how Mifos is set up, including which currency and locale it uses, its accounting rules, and many other important settings. You should never edit this default configuration file directly. Instead, use the file applicationConfiguration.custom.properties to override the values you want to change:
To use the custom application configuration file:
Open the file applicationConfiguration.custom.properties in the conf folder of the Mifos install package. This file contains all the same properties and values as the default version.
Uncomment the properties whose values you want to change and edit the values. Pay special attention to TRAPDOOR properties.
Mifos 1.2.x and earlier: create a file named applicationConfiguration.custom.properties and place it on the app server classpath .
Mifos versions greater than 1.2.x and trunk development: create a file named applicationConfiguration.custom.properties in one of the MifosConfigurationLocations.
Locale
The following settings in your applicationConfiguration.custom.properties file control locale in Mifos.
Language
In Mifos, settings for country and language work together to create a locale-specific user interface. Choose the language you want first, then use the CountryCode value that must be paired with that language.
Property name: Localization.LanguageCode
Mutability: Always
Options: EN (English), ES (Spanish), FR (French)
Default: EN
Use the following table to determine which LanguageCodes and CountryCodes must be paired with one another:
For locales using this language... | use this CountryCode | and this LanguageCode |
|---|---|---|
Spanish | ES | ES |
French | FR | FR |
English | GB | EN |
Example: Setting Localization.LanguageCode to FR and Localization.CountryCode to FR cause Mifos to display a French user interface.
Country
In Mifos, settings for country and language work together to create a locale-specific user interface. To get the language you want, it's possible that you will have to use a country code that doesn't reflect where Mifos will be installed.
Property name: Localization.CountryCode
Mutability: Always
Options: ES (Spain), FR (France), GB (Great Britain)
Default: GB
Use the following table to determine which LanguageCodes and CountryCodes must be paired with one another:
For locales using this language... | use this CountryCode | and this LanguageCode |
|---|---|---|
Spanish | ES | ES |
French | FR | FR |
English | GB | EN |
Example: Setting Localization.LanguageCode to FR and Localization.CountryCode to FR cause Mifos to display a French user interface.
Direction
If you are using a language that requires right-to-left, this setting can be used to set the direction of the text. By default, this should be set to auto. If your locale is set up correctly, the direction should be automatically set and this direction does not need to be changed.
Property name: Localization.Direction
Mutability: Always
Options: auto, ltr, rtl
Default: auto
Accounting
The accounting settings in applicationConfiguration.custom.properties tell Mifos which currency you want to use and provide information it needs to calculate repayment schedules, including how many decimal places of precision should be used, and how repayments should be rounded and adjusted.
Currency
The currency that Mifos uses.
This setting causes Mifos to use currency set internally, in its calculations and database. Externally, you will see no effect. The user interface does not display currency symbols ($, £, etc.). This is a known issue. This sets the default currency in Mifos. All accounting rules without a currency code on the property applies to the default currency.
Property name: AccountingRules.CurrencyCode
Mutability: TRAPDOOR
Options: 3 letter Alphabetical codes from this list - `ISO 4217 currency codes <http://www.iso.org/iso/support/currency_codes_list-1.htm>`_
Default: INR
Example: AccountingRules.CurrencyCode=INR causes Mifos to use the Indian rupee as the currency.
If you want to use an additional currency for loan products, the setting is used to set an additional currency code. Use the currency code to set specific rounding rules below for that currency.
Property name: AccountingRules.AdditionalCurrencyCodes
Mutability: TRAPDOOR
Options: any currency code
Default: none
Number of interest-bearing days
The number of days per year that should be used by Mifos in its interest calculations.
This setting does not apply to meeting scheduling. The meeting calendar always has 365 days. This setting also doesn't apply to fees and penalties calculation and repayment schedule generation. Because of its dependencies, once you configure this setting, you should not change it. For example, in the case of a moratorium, the loan schedule is recalculated, and changing the number of interest-bearing days in a year could change the calculation results.
Property name: AccountingRules.NumberOfInterestDays
Mutability: Always
Options: 360 or 365
Default: 365
Example: AccountingRules.NumberOfInterestDays=365 causes Mifos to use 365 days in its interest calculations.
Number of digits after decimal
The number of digits after the decimal that Mifos will carry for the currency.
This setting interacts with the rounding mode settings: Rounding mode for currency, Rounding mode for repayments, and Rounding mode for final payment.
While most MFIs use a value that represents the currency's finest level of precision, some do not. For example, the Tunisian dinar's smallest denomination is the milem, which is 1/1000 of a dinar. Instead of setting AccountingRules.DigitsAfterDecimal to 3, which would represent the dinar's finest level of precision, a Tunisian MFI might set AccountingRules.DigitsAfterDecimal to 2 (1/100 of a dinar).
Property name: AccountingRules.DigitsAfterDecimal
Mutability: Always
Options: 0 - 5
Default: 1
Example: If AccountingRules.CurrencyCode=USD and AccountingRules.DigitsAfterDecimal=2, the number of digits Mifos will carry represents the currency's finest level of precision (1/100 of a dollar, or a penny).
If you want to set a different digits after decimal that Mifos will carry for an additional currency, set another property with the currency code in the property name. For example, if Mifos has been configured with an additional currency LBP, to set a different digits after decimal that Mifos will cary for LBP, use the property name AccountingRules.DigitsAfterDecimal.LBP.
Number of digits after decimal for interest
The number of digits after the decimal that Mifos will carry for interest.
Property name: AccountingRules.DigitsAfterDecimalForInterest
Mutability: Always
Options: 0 - 5
Default: 5
If you want to set a different digits after decimal that Mifos will carry for interest in an additional currency, set another property with the currency code in the property name. For example, if Mifos has been configured with an additional currency LBP, to set a different digits after decimal for interest that Mifos will cary for LBP, use the property name AccountingRules.DigitsAfterDecimalForInterest.LBP.
Number of digits after decimal for cash flow validations
The number of digits after the decimal that Mifos will carry for cash flow warning threshold.
Property name: AccountingRules.DigitsAfterDecimalForCashFlowValidations
Mutability: Always
Options: 0 - 2
Default: 2
Maximum interest rate
The maximum allowable interest rate.
Unless you're advised otherwise by a Mifos specialist, use the default value for this setting (999).
Property name: AccountingRules.MaxInterest
Mutability: Always
Options: 0 - 999
Default: 999 (recommended)
Example: AccountingRules.MaxInterest=999 means that the interest rate Mifos uses for its calculations can be as high as 999%.
Minimum interest rate
The minimum allowable interest rate.
Unless you're advised otherwise by a Mifos specialist, use the default value for this setting (0).
Property name: AccountingRules.MinInterest
Mutability: Always
Options: 0 - 999
Default: 0 (recommended)
Example: AccountingRules.MinInterest=0 means that the interest rate Mifos uses for its calculations can be as low as 0%.
Minimum Cash Flow Threshold
The minimum allowable cash flow threshold
Property name: AccountingRules.MinCashFlowThreshold
Mutability: Always
Options: 0 - 99
Default: 0
Example: AccountingRules.MinCashFlowThreshold=0 means that the minimum allowed cash flow threshold for a loan product is 0.
Minimum Cash Flow Threshold
The maximum allowable cash flow threshold
Property name: AccountingRules.MaxCashFlowThreshold
Mutability: Always
Options: 0 - 99
Default: 99
Example: AccountingRules.MaxCashFlowThreshold=99 means that the maximum allowed cash flow threshold for a loan product is 99.
Minimum Repayment Capacity
The minimum allowable Repayment Capacity.
Property name: AccountingRules.MinRepaymentCapacity
Mutability: always
Options: 150 - 1000
Default:: 150
Example: AccountingRules.MinRepaymentCapacity=150 means that the minimum allowed repayment capacity for a loan product is 150.
Maximum Repayment Capacity
The maximum allowable Repayment Capacity.
Property name: AccountingRules.MaxRepaymentCapacity
Mutability: always
Options: 150 - 1000
Default:: 1000
Example: AccountingRules.MaxRepaymentCapacity=1000 means that the maximum allowed repayment capacity for a loan product is 1000.
Minimum Indebtedness Ratio
The minimum allowable Indebtedness Ratio.
Property name: AccountingRules.MinIndebtednessRatio
Mutability: always
Options: 0 - 50
Default:: 0
Example: AccountingRules.MinIndebtednessRatio=0 means that the mimimum indebtedness ratio for a loan product is 0.
Maximum Indebtedness Ratio
The maximum allowable Indebtedness Ratio.
Property name: AccountingRules.MaxIndebtednessRatio
Mutability: always
Options: 0 - 50
Default:: 50
Example:AccountingRules.MaxIndebtednessRatio=50 means that the maximum indebtedness ratio for a loan product is 50.
Rounding mode for currency
How Mifos rounds currency amounts.
This setting interacts with Number of digits after decimal.
Property name: AccountingRules.CurrencyRoundingMode
Mutability: Always
Options: HALF_UP, FLOOR, CEILING
Default: HALF_UP
Example: Assuming that Number of digits after decimal is set to 1, a value of...
HALF_UP means that if the discarded digit is 5 or greater, the next digit is rounded up. 42.45 rounds to 42.5. 42.44 rounds to 42.4.
FLOOR rounds the amount down to the nearest digit even if the discarded digit is 5 or greater. 42.45 rounds to 42.4.
CEILING means that if the discarded digit is anything but zero, the next digit is rounded up. 42.41 rounds to 42.5.
Rounding mode for repayments
How Mifos rounds repayment amounts when it calculates repayment schedules except for the last scheduled repayment.
This setting interacts with Number of digits after decimal.
Property name: AccountingRules.InitialRoundingMode
Mutability: Always
Options: HALF_UP, FLOOR, CEILING
Default: HALF_UP
Example: Assuming that Number of digits after decimal is set to 2, a value of...
HALF_UP means that if the discarded digit is 5 or greater, the next digit is rounded up. 42.485 rounds to 42.49. 42.481 rounds to 42.48.
FLOOR rounds the amount down to the nearest digit even if the discarded digit is 5 or greater. 42.486 rounds to 42.48.
CEILING means that if the discarded digit is anything but zero, the next digit is rounded up. 42.481 rounds to 42.49.
Rounding precision for repayments
The decimal place repayments are rounded to when Mifos calculates the loan repayment schedule.
The precision you use must be equal to or less precise than what you specify for Number of digits after decimal. This setting does not affect the last repayment use Rounding precision for final payment instead.
Property name: AccountingRules.InitialRoundOffMultiple
Mutability: Always
Options: 1, 0.5, 0.1, 0.01, 0.001
Default: 1
Example: If the currency is...
INR, a value of 1 rounds to the closest whole rupee.
GBP, a value of 0.5 rounds to the closest 50 pence.
USD, a value of 0.1 rounds to the closest dime. If Number of digits after decimal is set to 1, this is the limit of precision, even though this currency has a smaller denomination (the penny).
How rounding interacts with Number of digits after decimal: The value you use for Rounding precision for repayments cannot be more precise than what you use for Number of digits after decimal. For example, you cannot specify 2 for Number of digits after decimal and 0.001 (which requires three digits after the decimal) for Rounding precision for repayments. You can specify 3 forNumber of digits after decimal and 0.01 for Rounding precision for repayments. Note that in this latter situation, the amounts stored in the database will use three decimal places but the amounts that you view in the Mifos user interface will use two.