DIGIT Collections - Finance Integration

Owned by Elzan Mathew
Last updated: Oct 15, 2020 by Subhashchandra Bose
6 min read

Introduction

Receipts created in the platform will have information on the payee, tax heads and the amount collected. When there is no Finance Accounting System running for a State/Client, having a receipt will be sufficient enough to give the receipt output as a receipt format to the citizen or other stakeholders. When it comes to cases where these receipts need to be accounted, there is a need for financial integration. Basically, an equivalent receipt voucher will have to be created for every receipt. This can be achieved in the DIGIT platform with just having few configurations in place.

High-Level Design

DIGIT system has defined each business services and sub-services. Each of the business services may have one or more tax heads defined. Details of this are available in Billing-Collection-Integration.  All financial master related information will be stored against each of these business services/sub-services. Again these mapping can be given at a state-level or it can be at a city level. All these mappings are done using json mapping files.

There is a consumer listening to the receipts which will take care of the finance voucher creation. Consumer name is finance-collections-voucher-consumer.

Low-Level Design

There are mainly two json files where all the data mapping is done. You can find this under https://github.com/egovernments/egov-mdms-data/tree/master/data/pb/FinanceService. There can be different repo for client specific master data.

BusinessServiceMapping.json

All Finance related master data related to creating a receipt voucher will be defined in this mapping file. See below for the sample data.

"moduleName": "FinanceModule",
"BusinessServiceMapping": [
{
"code":"PT",
"voucherCreationEnabled":true,
"fund":"01",
"function":"909100",
"department":"TAX",
"functionary":"",
"scheme":"",
"subscheme":"",
"validFrom":1234567890,
"validTo":2345678901,
"serviceAttributeMappingEnabled":true,
"serviceAttributeUrl":"/property-services/property/_search?propertyIds=",
"serviceAttributeKey":"Properties.usageCategory",
"serviceAttributeTaxHead":"PT_TAX"
},
{
"code":"FIRENOC",
"voucherCreationEnabled":true,
"fund":"01",
"function":"101100",
"department":"FIRE",
"functionary":"",
"scheme":"",
"subscheme":"",
"validFrom":1234567890,
"validTo":2345678901
}


In the above sample, we can see there are two sets of mapping- one for PT (Property Tax) and another for FIRENOC (Fire No Objection Certificate). For each of these business services, the department, fund, a function can be different. Also, there is a provision to enable voucher creation.

There is a provision to enable/disable service attribute based accounting like in case of property tax, property usage wise financial accounting required. So it is done by using the serviceAttributeMappingEnabled, serviceAttributeUrl, serviceAttributeKey and serviceAttributeTaxHead  json parameters. If any business service requires service attribute based accounting then that business service should be configured using the above four parameters.

Here In case of Property Tax, service attribute is Property Usage. There might be other properties  for other business services. So the configuration of the service attribute should be done accordingly.

Details of each parameter
  1. code - This will be the same as that of the business service/sub-service code.
  2. voucherCreationEnabled - True means for this receipt voucher needs to be created and false means voucher need not be created.
  3. fund - This will be the fund code in the Finance system to which the receipt is applicable.
  4. function - This will be function code in the Finance system to which the receipt is applicable.
  5. department - This will be department code in the Finance system to which the receipt is applicable.
  6. functionary -  This will be functionary code in the Finance system to which the receipt is applicable.
  7. scheme - This will be the scheme code in the Finance system to which the receipt is applicable.
  8. subscheme - This will be sub-scheme code in the Finance system to which the receipt is applicable.
  9. validFrom - This is the date in epoch format from which this configuration is applicable.
  10. validTo - This is the date in epoch format until which this configuration is applicable.
  11. serviceAttributeMappingEnabled - This is to enable/disable service attribute based accounting.
  12. serviceAttributeUrl - This is the business service api to fetch the service attribute value.
  13. serviceAttributeKey - Configure the service attribute key here.  This key is used to read the service attribute value from the service attribute api response.
  14. serviceAttributeTaxHead - There might be multiple tax heads for a business service. So we need to configure the tax head for which tax head the service attribute accounting is to be done.

Note that code is the unique value here. Based on the finance system configured in a state/city, the mandatory parameters list will differ.

AccountHeadMapping.json

For each of the tax head defined for a service, there needs to be an equivalent finance account code mapping. This is being achieved using the accountheadmapping.json file. 

If service attribute based accounting is enabled in the business service mapping, then service attribute wise (Property usage wise in case of PT) tax head and glcode mapping should be configured. In case of Property Tax, there are different property usages, so different glcodes for the different usages should be configured for the tax head, which is configured in the business service mapping with the property serviceAttributeTaxHead.

Below is the sample data.

"moduleName": "FinanceModule",
"TaxHeadMasterGlCodeMapping": [
{
"billingservicecode": "PT",
"taxhead": "PT_ADHOC_REBATE",
"glcode": "2716003",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_ADVANCE_CARRYFORWARD",
"glcode": "1100101",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_OWNER_EXEMPTION",
"glcode": "2716003",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_TIME_REBATE",
"glcode": "2716003",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_UNIT_USAGE_EXEMPTION",
"glcode": "2716003",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_ADHOC_PENALTY",
"glcode": "1100107",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1100101",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "RESIDENTIAL",
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1404009",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "NONRESIDENTIAL",
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1100102",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "NONRESIDENTIAL.COMMERCIAL",
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1100103",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "NONRESIDENTIAL.INDUSTRIAL",
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1404009",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "NONRESIDENTIAL.INSTITUTIONAL",
},
{
"billingservicecode": "PT",
"taxhead": "PT_TAX",
"glcode": "1404009",
"validFrom": 1234567890,
"validTo": 2345678901,
"serviceAttribute": "MIXED",
},
{
"billingservicecode": "PT",
"taxhead": "PT_FIRE_CESS",
"glcode": "3502021",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "PT",
"taxhead": "PT_CANCER_CESS",
"glcode": "3502022",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "FIRENOC",
"taxhead": "FIRENOC_ADHOC_REBATE",
"glcode": "2716004",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"billingservicecode": "FIRENOC",
"taxhead": "FIRENOC_ADHOC_PENALTY",
"glcode": "1808003",
"validFrom": 1234567890,
"validTo": 2345678901
}

Details of each parameter
  1. billingservicecode - This will be the same as that of the business service/sub-service code.
  2. taxhead - This will be the tax head code defined for the selected business service
  3. glcode - This will be the account code (Chart of accounts) in the Finance system which is relevant for this tax head.
  4. validFrom - This is the date in epoch format from which this configuration is applicable.
  5. validTo - This is the date in epoch format until which this configuration is applicable.
  6. serviceAttribute - This is the service attribute value (Property usages in case of Property Tax). 

Note that each of the tax head defined for a business service needs to have a mapping account head for finance. If any tax head is not mapped, the voucher generation will fail.

Receipts can be created in the system using different modes of payment- cash, cheque, dd and card. For each of these modes, Finance accounting will be different. The account head to which the collected amount is be debited will be defined here.

"InstrumentGLcodeMapping": [
{
"instrumenttype": "DD",
"glcode": "4501003",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"instrumenttype": "Cash",
"glcode": "4501001",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"instrumenttype": "Cheque",
"glcode": "4501003",
"validFrom": 1234567890,
"validTo": 2345678901
},

Details of each parameter
  1. instrumenttype - This will be the instrument type code.
  2. glcode - This will be the account code (Chart of accounts) in the Finance system which is relevant for this instrument.
  3. validFrom - This is the date in epoch format from which this configuration is applicable.
  4. validTo - This is the date in epoch format until which this configuration is applicable.

All online receipts will be accounted into some pre-defined bank accounts. Most probably there will be a different bank account configured for a city or ULB and there can be separate bank account configured for various business services. Make sure this bank account is created in the Finance accounting system, which will be linked to a chartofaccount code. The account head to which the collected amount is be debited will be defined in the mapping json. If there is a different bank account configured per city, this mapping file will need to be kept at the city level and not state-level.

"OnlineGLcodeMapping": [
{
"servicecode": "PT",
"glcode": "4502001",
"validFrom": 1234567890,
"validTo": 2345678901
},
{
"servicecode": "TL",
"glcode": "4502003",
"validFrom": 1234567890,
"validTo": 2345678901
},

Details of each parameter
  1. servicecode - This will be the business service code.
  2. glcode - This will be the account code (Chart of accounts) in the Finance system that is associated with the bank account which is relevant for this particular business service.
  3. validFrom - This is the date in epoch format from which this configuration is applicable.
  4. validTo - This is the date in epoch format until which this configuration is applicable.


Now that you have gone through this document lets see what are the steps to be followed for configuring a new service with finance.

Steps to configure

  • Firstly make sure the finance-collections-voucher-consumer service is running.
  • Next, add an entry into BusinessServiceMapping.json file with appropriate mapping data. Be very sure the master data mapping given are valid ones.
  • Then add one entry per tax head in the TaxHeadMasterGlCodeMapping section in AccountHeadMapping.json. Make sure you don't miss any tax heads here.
  • If there are any new mode of payments add an entry for the same in the InstrumentGLcodeMapping section of AccountHeadMapping.json (this is not a frequent case)
  • Push the code to the GitHub repository.
  • Reload the egov-mdms-service pod.
  • Create the bank account in the finance system to which amount needs to be accounted in case of online payments by a citizen.

We are all set to go. Any receipt created for the newly created service will create a corresponding voucher in the finance system.