Accounting Integration with Mifos

1. Introduction

This document is created while working on Mifos Accounting Integration with Tally ERP. The terminology is kept generic so that it can be used for other Accounting Software.

1.1 Current State of Accounting Integration

• Mifos can generate XML output (Vouchers) on daily basis which can be exported to an Accounting Software.
• Mifos can show the Vouchers in Mifos UI for verification before generating XML output for a date range.
• Mifos Chart of Account has to be mapped using alias in an Accounting Software to be able to export XML output

1.2 Next State of Accounting Integration

• Mifos can export the Vouchers in Accounting Software automatically.
• Mifos can detect what data have been exported into the Accounting Software
• Mifos can provide more details of the Voucher at drill down from UI
• Avoid Duplicates and better error handling.

1.3 Purpose

Define "Accounting software interface for Mifos accounting Integration"(AMI) in order to achieve integration between accounting software and Mifos.

1.4 Terminology

Mifos Accounting Integration: Integration of an Accounting Software with Mifos.
Common Integration Layer (CIL): Mifos Accounting Integration interacts with AMI using XML messaging which is called CIL. Mifos only understand/expect the CIL messaging from AMI.
Accounting software interface for Mifos accounting Integration (AMI): Implementation specific to an Accounting Software deployed on the Accounting Software side(ex. Tally ERP, MS Dynamics e.t.c.). In other words, a module developed in Accounting Software to support the "Common Integration Layer". AMI provides a Common Integration Layer which is controlled by Mifos.
Vouchers ("Consolidated Transactions" or "Accounting Data") : Transactions in Mifos are grouped by Branch/Office, Date and combination of "Financial Action" to "Account Action" which are called Mifos Vouchers, i.e. an Accounting software understandable formate of Mifos transactions.
There are 3 types of Vouchers in Mifos

• PAYMENT
• RECEIPT
• JOURNAL

2. AMI requirements

2.1 Base requirements

• Running as a service on a known port at localhost which will take an XML request and provide XML response.
• Additional response header "Access-Control-Allow-Origin: http://*.mifos.org"   , Stored as KEY=VALUE pair
• Does mapping of Mifos "Chart of Account"(One Level GL) to Accounting software "Chart of Account" (Multi level GL)
• Read/Write access for KEY=VALUE pair at AMI storage.
• Maintains mapping of Mifos Voucher ID and Accounting Software specific ID to detect duplicates.
• Returns error code and message for voucher export failure, or return master id with success message
• Query status of export in case a process is taking more than 10 secs, return how much vouchers have been exported. (RUNNING, NUMBER OF VOUCHERS REMAINING)
• There will be two request parameters which AMI will understand.
  1. COMMAND - One word instruction send to the AMI, based on which AMI knows what to do with the DATA
  2. DATA - used by AMI to process some instruction

2.2 Request <-> Response protocol for CIL implemented by AMI

2.2.1 Mifos Vouchers export

Mifos (Request)

<COMMAND>export</COMMAND>
<DATA>
<FORCED>YES/NO<FORCED>
<VOUCHERS>{Mifos XML vouchers}</VOUCHERS> 
</DATA>

AMI (Response)

Case: When all vouchers are exported successfully.

<RESPONSE>
<TYPE>export</TYPE>
<RESULT>success<RESULT>
</RESPONSE>

Case: When zero vouchers found in DATA tag

<RESPONSE>
<TYPE>export</TYPE>
<RESULT>empty<RESULT>
</RESPONSE>

Case: When at least one voucher export failed : Correct vouchers get exported and the failed ones get error message. Mifos Voucher ID of both successful and failed will be returned.

<RESPONSE>
<TYPE>export</TYPE>
<RESULT>partial<RESULT>


<VOUCHER>
<ID>34535</ID>                     <!-- this voucher failed -->
<STATUS>failed</STATUS>
<MESSAGE>error message</MESSAGE>
</VOUCHER>


<VOUCHER>
<ID>34536</ID>                   <!-- this voucher was correct, it was exported correctly -->
<STATUS>exported</STATUS>
<MESSAGE></MESSAGE>
<VOUCHER>
...
</RESPONSE>

Case: When at least one voucher already exist (already exported) but others not : based on Mifos Voucher ID and mapping of accounting software ID.

<RESPONSE>
<TYPE>export</TYPE>
<RESULT>partial<RESULT>


<VOUCHER>
<ID>34535</ID>
<STATUS>duplicate</STATUS>
<MESSAGE></MESSAGE>
</VOUCHER>


<VOUCHER>
<ID>34536</ID>
<STATUS>exported<STATUS>
<MESSAGE></MESSAGE>
</VOUCHER>
...
</RESPONSE>

Case: When at least one voucher already exist (already exported) but some are not and FORCED tag is YES: based on Mifos Voucher ID and mapping of accounting software ID.

<RESPONSE>
<TYPE>export</TYPE>
<RESULT>forced<RESULT>

<VOUCHER>
<ID>34535</ID>                     <!-- this voucher already exist in accounting software -->
<STATUS>overwrite</STATUS>
<MESSAGE></MESSAGE>
</VOUCHER>


<VOUCHER>
<ID>34537<ID>
<STATUS>failed</STATUS>
<MESSAGE>error message</MESSAGE>
</VOUCHER>


<VOUCHER>
<ID>34537</ID>
<STATUS>exported<STATUS>          <!-- this voucher does not exist in accounting software -->
<MESSAGE></MESSAGE>
</VOUCHER>
...
</RESPONSE>

It is possible in extreme(worst) case an export can contain correct, duplicate, failure. The interface should be able to give correct response as mentioned in above cases.

FORCED tag is only used to overwrite vouchers and would be used only in the case of update or missed entry. 

2.2.2 Expendable storage capability:

Writing KEY=VALUE in storage

Mifos (Request) :

<COMMAND>write</COMMAND>
<DATA>
<KEY>{KEY}</KEY>
<VALUE>{VALUE}</VALUE>
</DATA>

AMI (Response) :

<RESPONSE>
<TYPE>write</TYPE>
<RESULT>success/failure</RESULT>
</RESPONSE>

Reading KEY=VALUE from storage

Mifos (Request) :

<COMMAND>read</COMMAND>
<DATA><KEY>{KEY}</KEY></DATA>

AMI (Response) :

<RESPONSE>
<TYPE>read</TYPE>
<RESULT>success/failure</RESULT>  <! -- success when the key exist, failure when key does not exist -->
<VALUE>{VALUE}<VALUE>
</RESPONSE>

2.2.3 Validation of Mifos Chart of Account by AMI

AMI should be able to validate the Chart of Account of Mifos against Accounting Software.

Mifos (Request) :

<COMMAND>chartoofaccount</COMMAND>
<DATA>{Mifos Chart of Account}</DATA>

AMI (Response) :

<RESPONSE>
<TYPE>chartofaccount</TYPE>
<RESULT>success/failure</RESULT>  <! -- success when the key exist, failure when key does not exist -->
<MESSAGE>{VALUE}<MESSAGE>
</RESPONSE>

Mifos XML Vouchers example

it's simillar to Tally XML but if there is any transformation of information required then AMI would have to take care of it.

<VOUCHERS>
<VOUCHER>
<DATE>20110104</DATE>
<VOUCHERTYPENAME>Receipt</VOUCHERTYPENAME>
<NARRATION>Mifos Accounting Export ID - 0394</NARRATION>
<ALLLEDGERENTRIES.LIST>
<LEDGERNAME>11201</LEDGERNAME>
<ISDEEMEDPOSITIVE>Yes</ISDEEMEDPOSITIVE>
<AMOUNT>-600.0</AMOUNT>
<CATEGORYALLOCATIONS.LIST>
<CATEGORY>Primary Cost Category</CATEGORY>
<COSTCENTREALLOCATIONS.LIST>
<NAME>chennai</NAME>
<AMOUNT>-600.0</AMOUNT>
</COSTCENTREALLOCATIONS.LIST>
</CATEGORYALLOCATIONS.LIST>
</ALLLEDGERENTRIES.LIST>
<ALLLEDGERENTRIES.LIST>
<LEDGERNAME>1505</LEDGERNAME>
<ISDEEMEDPOSITIVE>No</ISDEEMEDPOSITIVE>
<AMOUNT>567.2</AMOUNT>
<CATEGORYALLOCATIONS.LIST>
<CATEGORY>Primary Cost Category</CATEGORY>
<COSTCENTREALLOCATIONS.LIST>
<NAME>chennai</NAME>
<AMOUNT>567.2</AMOUNT>
</COSTCENTREALLOCATIONS.LIST>
</CATEGORYALLOCATIONS.LIST>
</ALLLEDGERENTRIES.LIST>
<ALLLEDGERENTRIES.LIST>
<LEDGERNAME>5001</LEDGERNAME>
<ISDEEMEDPOSITIVE>No</ISDEEMEDPOSITIVE>
<AMOUNT>32.8</AMOUNT>
<CATEGORYALLOCATIONS.LIST>
<CATEGORY>Primary Cost Category</CATEGORY>
<COSTCENTREALLOCATIONS.LIST>
<NAME>chennai</NAME>
<AMOUNT>32.8</AMOUNT>
</COSTCENTREALLOCATIONS.LIST>
</CATEGORYALLOCATIONS.LIST>
</ALLLEDGERENTRIES.LIST>
</VOUCHER>
<VOUCHERS>

Steps involved in installation

1. Install the AMI at Accounting Software side. (Dropping a file or an executable)
2. Configure the Mifos to be able to talk to AMI (Login to Mifos and configure the location of AMI)
3. Map Chart of Accounts of Mifos to Accounting Package using AMI

Mifos will be controlling the export of Vouchers to the Accounting Software. Mifos expect AMI to implement CIL, using which Mifos will be controlling the Mifos Vouchers exports.

Architecture Diagram

[1] https://developer.mozilla.org/En/HTTP_Access_Control