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:

1. Create a copy of the default Chart of Accounts configuration file that ships with Mifos and name it mifosChartOfAccounts.custom.xml.
2. Customize mifosChartofAccounts.custom.xml as described in Accounting in Mifos.
3. Place your customized file on the app server classpath 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:

1. Create a file named mifosBeanConfig.custom.xml.
2. Customize mifosBeanConfig.custom.xml (see the example below).
3. Place your customized file on the app server classpath while Mifos is not running. 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
         http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">
    <bean id = "financialRules"
       class="org.mifos.application.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="VOLUNTORYDEPOSIT" value="11201"/>
               <entry key="MANDATORYWITHDRAWAL" value="24000"/>
               <entry key="VOLUNTORYWITHDRAWAL" 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="VOLUNTORYDEPOSIT_ADJUSTMENT" value="23000"/>
               <entry key="MANDATORYWITHDRAWAL_ADJUSTMENT" value="11201"/>
               <entry key="VOLUNTORYWITHDRAWAL_ADJUSTMENT" value="11201"/>
               <entry key="WRITEOFF" value="13201"/>
           </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="VOLUNTORYDEPOSIT" value="23000"/>
               <entry key="MANDATORYWITHDRAWAL" value="11201"/>
               <entry key="VOLUNTORYWITHDRAWAL" 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="VOLUNTORYDEPOSIT_ADJUSTMENT" value="11201"/>
               <entry key="MANDATORYWITHDRAWAL_ADJUSTMENT" value="24000"/>
               <entry key="VOLUNTORYWITHDRAWAL_ADJUSTMENT" value="23000"/>
               <entry key="WRITEOFF" 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 in mifosBeanConfig.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:

1. 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.
2. Uncomment the properties whose values you want to change and edit the values. Pay special attention to TRAPDOOR properties.
3. Save applicationConfiguration.custom.properties and place it on the app server classpath .

Adjusting Session Timeout

By default, Mifos gives users up to 30 minutes of inactivity before it times out their sessions and requires them to log in again. To change this value, edit the following section in the deployment descriptor file, web.xml, which ships in the Mifos WAR at WEB-INF:

<session-config>
  <session-timeout>30</session-timeout>
</session-config>

Scheduling Batch Jobs

The data that you and other Mifos users work with is maintained by batch jobs, which are a series of scripts that are executed on the computer where Mifos is installed. These scripts perform calculations, act on the Mifos database, and ensure, for example, that the repayment information entered in Mifos today is reflected in the reports that are generated tomorrow. Keep the following tips in mind with regard to batch jobs:

• By default, the Mifos batch jobs are scheduled to run every day at midnight.
• For the batch jobs to run, the computer where Mifos is installed must be running.
• If a user is logged in when the batch jobs start to run, they will be automatically logged out. No logins are permitted until the batch jobs complete.
• Reports that are generated before the batch jobs are complete will not reflect the results of the batch jobs.

Batch jobs are scheduled in task.xml in the Mifos WAR (WEB-INF/classes/org/mifos/framework/util/resources/batchjobs).

You can confirm whether a batch job ran by looking in the scheduled_tasks table in the Mifos database. A status value of 1 means the batch job ran; 0 means it didn't run. In most cases, the default settings should be adequate, but if you need to force a batch job to run, use the following procedure.

To force a batch job to run:

1. If Mifos is running, log out.
2. Execute the Tomcat shutdown script (shutdown.sh/.bat) in CATALINA_HOME/bin (for example, C:\Program Files\Apache Software Foundation\Tomcat 6.0\bin), or if Tomcat was installed as a service on Windows, navigate to Control Panel > Administrative Tools > Services and change the status of the Mifos service to Stopped.
3. Open task.xml in the Mifos WAR at WEB-INF/classes/org/mifos/framework/util/resources/batchjobs.
4. Edit <initial-time> for the batch job(s) you want to force. Change it from 24:00:00, which will occur at midnight today, to a time today that has already passed, such as 01:00:00 (1 am). For example: <initial-time>01:00:00</initial-time>
5. Save your changes.
6. Execute the Tomcat startup script (startup.sh/.bat) in CATALINA_HOME/bin or start the Mifos service. The batch jobs will start to run. You won't be able to log into Mifos until they complete.

Customizing your Database Connection

You can customize various aspects of your database connection, such as which host to connect to, the database name, your user name and password, as well as the connection pool settings, by placing a file called deploymifosDB.properties on the app server classpath while Mifos is not running. A sample of this file is in the Mifos install package, in the conf folder.

Note: The file deploymifosDB.properties is based on hibernate.properties. If the latter changes in a future release of Mifos, your copy of deploymifosDB.properties may also require changes.

Database-Configured Settings

Some Mifos features are configured directly in the database. The settings described below are located in the config_key_value_integer table in the Mifos schema:

• Loan Set Independent of Meeting allows loan payments to be scheduled independent of the meeting schedule. This feature is disabled by default. Note that this feature has some known issues (see issues 1994 and 2005). To enable this feature, set the flag for repaymentSchedulesIndependentOfMeetingIsEnabled to 1 and apply your change.

• The value for Minimum Days Between Disbursal and First Repayment is used when Loan Set Independent of Meeting is enabled. This setting determines how tight the interval can be between disbursing a loan and requiring the first repayment for same. The default value is 1, which ensures that a loan disbursal and the first repayment can never be less than one day apart.
• The value for Maximum Days Between Disbursal and First Repayment Day is used when Loan Set Independent of Meeting is enabled. This setting limits the number of days that can pass between disbursing a loan and requiring the first repayment for same. The default value is 365.

• Loan with Individual Monitoring can be used when a group opens a loan account. It lets you specify, at disbursal time, how much of the total loan amount each group member will receive. This feature is disabled by default. To enable it, set the flag for loanIndividualMonitoringIsEnabled to 1.

Starting Mifos

To access the settings on the Admin tab, you need to start the Mifos application.

To start Mifos:

1. Execute the Tomcat script named startup.sh/.bat in CATALINA_HOME/bin (for example, C:\Program Files\Apache Software Foundation\Tomcat 6.0\bin), or if Tomcat was installed as a service on Windows, navigate to Control Panel > Administrative Tools > Services to verify that the status of the Mifos service is Started.
2. Next, visit http:///localhost:8080//mifos in a web browser.
3. Enter mifos as your Username and testmifos as your Password.

Customizing the User Interface

The options in the Data Display and Rules group allow you to customize certain labels and list-box items, hide or require certain fields, and define new fields for additional information you want to collect.

Defining Office Hierarchy

Office hierarchy is Mifos' view of how your MFI is organized. Mifos uses the office hierarchy information you provide for a wide variety of essential actions, including creating users defining new clients and groups, managing transactions, and reporting. At minimum, Mifos requires two levels of hierarchy: a Head Office, provided by default (Mifos HO), and at least one Branch Office. At maximum, there can be five levels: Head Office, Regional Office, Sub-Regional Office, Area Office, and Branch Office.

Defining office hierarchy in Mifos involves first removing office types that aren't represented in your organization and then adding those offices that are.

To remove office types:

1. On the Admin tab in Mifos, click the View office hierarchy link under Offices.
2. Clear the check box(es) for office types that don't represent your MFI's organization. For example, if one or more Division offices aren't in your oganization's structure, clear the Division check box. You cannot remove Head Office and Branch Office as office types. They are required.
3. Click Preview > Submit.

To add offices:

1. On the Admin tab, click the Define a new office link under Offices.
2. Provide information for the new office. Any office types you removed in the above procedure are absent from the Office type list. You can only have one Head Office.
3. Click Preview > Submit.

Creating Roles

After you define your MFI's office hierarchy in Mifos, it's time to create roles, which are collections of actions that a user can perform in Mifos.

To create a role:

1. On the Admin tab, click Manage roles and permissions under System users.
2. Note that the Admin role is the only pre-defined role. Click the new Role link to create a new role.
3. Provide a Role Name and select actions or groups of actions that a person can perform in this role.
4. Click Preview > Submit.

Creating Users

Once you define roles in Mifos you can create the users who will be assigned those roles. There are two types of users in Mifos: Loan Officers or Non-Loan Officers. A Loan Officer can only belong to a Branch Office.

To create a user:

1. On the Admin tab, click Define new system user under System users.
2. Click the office to which the user will belong.
3. Provide information for the user, including their User Hierarchy (Non-Loan Officer or Loan Officer).
4. Add Role(s) that the user will perform.
5. Click Preview > Submit.

Configuring Payment Types

Mifos uses Cash as the default value for accepted payments.

To specify a different or additional payment type: On the Admin tab under Organization Preferences, click Define accepted payment types.

Setting Lateness and Dormancy Definitions

Before loan and savings products can be defined, the default loan lateness and savings dormancy definitions should be reviewed and changed, if necessary. Both of these settings are configured on the Admin tab via the View lateness/dormancy definition link.

• The loan lateness definition is the number of days of non-payment that can pass before Mifos changes a loan account's status from Active in good standing to In arrears. The default value is 10 days.
• The savings dormancy definition is the number of days of inactivity after which Mifos changes the status of a savings account from Active to On Hold. The default value is 30 days.

Defining Holidays

So that it can correctly calculate repayment schedules, Mifos needs to know what your MFI's holidays are and how you would like repayments handled if a repayment happens to fall on a holiday. Mifos can either schedule the repayment for the same day (regardless of it being a holiday), the next workday, or the next scheduled meeting or repayment. Note that in Mifos, holidays are different from non-workdays.

To define a holiday:

1. On the Admin tab, click Define new holidays under Organization Preferences.
2. Provide information about the holiday and select a Repayment Rule.
3. Click Preview > Submit.

Information on Reporting and PPI Surveys

As a system administrator you may also be reponsible for setting up reports for your users and adding a PPI survey to your deployment. Use the following links for more information:

• Reporting in Mifos: Describes how to use BIRT (Business Intelligence Reporting Tools) to build and upload non-standard reports.
• PPI Survey Conventions: Adding a PPI survey must be done at the source code level and requires assistance from a Mifos specialist. Use this link to learn about some of the requirements.