Overview

The objective of this service is to listen to the Kafka topics, validate the data based on the configuration, make the voucher API call to create the voucher in finance ERP and update the backend data. It also creates vouchers and instruments for the receipts collected through the collection service.

Pre-requisites

• Prior Knowledge of Java/J2EE

• Prior Knowledge of SpringBoot

• Prior Knowledge of REST APIs and related concepts like path parameters, headers, JSON, etc

• Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic, etc.

Key functionalities

• Create vouchers and instruments for the receipts collected.

• Listen to Kafka topics and validate the data.

• Update the data in finance ERP.

Setup Details

Step 1: Start the service finance-collections-voucher-consumer present in the following repo:

Step 2: Start the egov-mdms service present in the following repo:

MDMS Configurations

The business service and tax headmaster which are active in mdms json needs to be mapped with Finance related data.

The business service-related data is mapped with the finance-related data in git repo.

1. AccountheadMapping.json : This is used to map the taxhead data to glcodes. This holds one more property InstrumentGLcodeMapping, which is used to hold the mapping for transaction type i.e Cash/Cheque/DD to glcodes.

2. BusinessServiceMapping.json : This is used to map the business service to finance specific master data like Department, Fund and Function, etc. even it can manage to enable and disable the voucher creation for specific service by setting the property voucherCreationEnabled=true/false.

3. EgfInstrumentStatusMapping: This holds the status of Instruments.

Configuration Details

Following are the properties in the application.properties file in the egov-user-events service that is configurable.

Working

This service is implemented to listen to the specific Kafka topic, fetch the data and perform activities like creating vouchers, cancelling vouchers or reversing vouchers on dishonouring.

Create Voucher:

Once the collection-service will generate collection/payment,it will push the data to egov.collection.receipt-create/egov.collection.payment-create topic.

Listener will be listening to the topic egov.collection.receipt-create/egov.collection.payment-create.

Making MDMS calls based on the services to get the configuration data and validate i.e whether voucher creation is enabled for the service or not. If voucher creation is enabled then perform the following

1. Prepare the voucher contract like master data i.e Dept, Fund, Function etc.

2. Prepare the account-specific data i.e glocode, amount etc.

3. Then making a rest call to create a voucher to finance ERP.

4. Once the voucher is created successfully then it will prepare the instrument contract by adding the voucher reference, instrument type, status etc and will make a call to create the instrument.

5. Once the instrument is created later it will make the call to collection receipt update API to back update the receipt by adding the voucher reference in the contract.

6. And finally, it will store the logs i.e fetched data, status, message to log table egf_voucher_integration_log.

7. If anywhere any exception occurs then errors are handled by the Exception Handler. Exception Handler will store the fetched data and the error cause to log table egf_voucher_integration_log.

Cancel Voucher:

Once collection service cancels the payment/collections, it pushes the data to egov.collection.payment-cancel/egov.collection.receipt-cancel

Listeners are listening to the topicegov.collection.payment-cancel/egov.collection.receipt-cancel.

Making MDMS calls based on the services to get the configuration data and validate i.e whether voucher creation is enabled for the service or not. If voucher creation is enabled then perform the following.

1. Try to fetch the voucher based on the voucher number(which might be present inside the receipt contract) and the business service reference document.

2. If Voucher is present inside the finance ERP then it makes a call to cancel the voucher.

3. Later it cancels the corresponding instrument.

4. And keep the log inside the table egf_voucher_integration_log.

Interaction Diagram

Deployment details

1. Add MDMS configs required for Finance Collection Voucher Consumer service and restart MDMS service.

2. Deploy the latest version of the Finance Collection Voucher Consumer service.

3. Add Finance Collection Voucher Consumer service persister yaml path in persister configuration and restart persister service

4. Add Role-Action mapping for APIs.

Integration

• Can perform service-specific business logic without impacting the other modules.

• In the future, if we want to expose the application to citizens then it can be done easily.

• The workflows or service-specific workflows can be enabled at the service level at any time without changing the design.

Overview

This document describes the steps to be followed to set up a new instance of Finance. When a new state or city is to be set up, there are some activities to be executed in a defined order. Setting up an instance of an application server and configuration changes etc are a few of the key activities.

Technical Prerequisites

• Prior knowledge of Java/J2EE.

• Prior knowledge of Spring and Hibernate

• Prior knowledge of Maven

• Prior knowledge of Git

Hardware/Software Prerequisites

• Maven v3.2.x

• PostgreSQL v9.6

• Customized Wildfly Image

• Git 2.8.3

• JDK 8 update 112 or higher

• Create subdomains under the main domain for each of the cities that are to be set up

• Create a schema per city in the database

Configurations and Setup

The Co-existence repository is the base repository for the finance product and the client-specific data needs to be defined in the client repository defined within the base repository.

How to set up a client implementation repository

1. Fork and create a client implementation repository from the base repository to keep client-specific data and configurations.

2. Any configurations and data specific to the client should be added to the client repository.

Application Configuration

• The default application configurations of the finance service are present in the application configuration file. To enable or disable any feature, either update the values in the application configuration file or the override configuration file.

• The override configuration is the template and the values for the template are present either in the finance service values yaml file or in the environment named yaml file. The finance service values yaml is the common file to override the default values and the changes made to this file are applicable for all environments (dev, qa, uat, prod etc).

• Any specific configuration change is required for any specific environment then update the environment named yaml file.

Sample environment named yaml files for your reference

https://github.com/egovernments/Train-InfraOps/blob/master/helm/environments/qa.yaml
https://github.com/egovernments/Train-InfraOps/blob/master/helm/environments/uat.yaml

Database configuration

Add or update the db url in the environment specific file using the below property

erp-db-url: "jdbc:postgresql://egov-dev-db.ctm6jbmr5mnj.ap-south-1.rds.amazonaws.com:5432/finance_qa_db"

Update the db username and password, which are configured in the environment named secrets yaml file.

For example, for the qa environment, update the qa-secrets.yaml

secrets:
        db:
            username: <username value> 
            password:  <password value>

Set up a schema-based multi-tenant database

Finance co-existence service uses schema-based multi-tenancy, which means there will be one schema present for a city. The following are the configuration changes to set up this kind of database.

• Enable multi-tenancy by enabling the following property

multitenancy: true  

• Each ULB is enabled by adding a schema name and domain name. Schema names should follow a naming standard, It should be the same as that of the city name.

• Each ULB can be configured by adding an entry like tenant.<domain_name>=schema_name (city_name)

• The default tenants are configured in the finance service yaml file using the below configuration.

tenants: |
 tenant.citya.egovernments.org=citya
 tenant.cityb.egovernments.org=cityb

• To override and have separate tenants for a specific environment then update the environment-specific file like below.

FinanceTenants: |
 tenant.citya.egovernments.org=citya
 tenant.cityb.egovernments.org=cityb

• Here citya.egovernments.org, cityb.egovernments.org are the domains and citya, cityb are the schemas/tenants.

Example environment specific configuration file for your reference.

• Update the domainurl in the eg_city table.

• Domain URL value should be the same as configured tenant domain_name Ex:

For citya, domain url should be citya.egovernments.org
For cityb, domain url should be cityb.egovernments.org 

Database migration settings

The default database migration configurations are present in the application configuration file.

#Enable/Disable flyway migration
db.migration.enabled=true

#Enable/Disable flyway migration validation
db.flyway.validateon.migrate=false

#Enable/Disable repairing of flyway migration checksum
db.flyway.migration.repair=false

#Various flyway migration sql script file paths
db.flyway.main.migration.file.path=classpath:/db/migration/main/
db.flyway.sample.migration.file.path=classpath:/db/migration/sample/
db.flyway.tenant.migration.file.path=classpath:/db/migration/%s/
db.flyway.statewide.migration.file.path=classpath:/db/migration/statewide/

#Enable/Disable to run migration sql's inside "statewide" migration folder (resources/db/migration/statewide)
statewide.migration.required=false

#Schema name where statewide migration to be executed, value must be your default schema name (see default.schema.name)
statewide.schema.name=generic

#Enable/Disable dev mode, this must be set to false in all non dev environments
dev.mode=false

Override the default values by updating the properties either in the finance service values yaml file or the environment-specific yaml file. The following are different properties.

# Enable/Disable to execute the sample sql scripts.
dev_mode: false
# Enable/Disable flyway migration validation
db_flyway: true
#Enable/Disable to run migration sql's inside "statewide" migration folder (resources/db/migration/statewide)
statewide_migration: true
#Enable or Disable Multitenancy
multitenancy: true

System Integration User Details Configuration

Configure the following property either in the finance service values yaml file or the environment-specific yaml file.

Systemintegration: |
 si.microservice.user=${si-microservice-user}
 si.microservice.password=${si-microservice-password}
 si.microservice.usertype=SYSTEM
 si.microservice.scope=read
 si.microservice.granttype=password
 
 env: |
  - name: si-microservice-password
    valueFrom:
      secretKeyRef:  
        name: egov-si-microservice
        key: si-microservice-password
  - name: si-microservice-user
    valueFrom:
      secretKeyRef:  
        name: egov-si-microservice
        key: si-microservice-user

• Add one user in the system for system integration - SIFINANCE mapped with role SYS_INTEGRATOR_FINANCE by using the user service createnovalidate API.

• Find the createnovalidate API details below

{
	"info": {
		"_postman_id": "81469f7c-793c-43b2-8e05-9ce6c8174cd4",
		"name": "SIUSER_Creation",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "createnovalidate",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "Content-Type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n \"RequestInfo\": {\n   \"api_id\": \"1\",\n   \"ver\": \"1\",\n   \"ts\": null,\n   \"action\": \"create\",\n   \"did\": \"\",\n   \"key\": \"\",\n   \"msg_id\": \"\",\n   \"requester_id\": \"\",\n   \"auth_token\": \"12e8753e-099f-42cb-b2ec-402b10215610\"\n },\n \"User\": {\n  \"userName\": \"SIFINANCE\",\n  \"name\": \"SYS INTG FINANCE\",\n  \"gender\": \"Male\",\n  \"mobileNumber\": \"\",\n  \"active\": true,\n  \"type\": \"SYSTEM\",\n  \"password\": \"sifinance123@\",\n  \"tenantId\":\"pg.citya\",\n  \"roles\": [\n       {\n                   \"tenantId\": \"pg.citya\",\n                   \"code\": \"SYS_INTEGRATOR_FINANCE\",\n                   \"name\": \"System Integrator Finance\"\n               }\n   ]\n }\n}\n"
				},
				"url": {
					"raw": "https://egov-micro-qa.egovernments.org/user/users/_createnovalidate",
					"protocol": "https",
					"host": [
						"egov-micro-qa",
						"egovernments",
						"org"
					],
					"path": [
						"user",
						"users",
						"_createnovalidate"
					]
				},
				"description": "user create with no OTP validation"
			},
			"response": []
		}
	]
}

Elastic Dashboard Configuration

To enable or disable an event to push the bills and vouchers to the elastic search indexer the below need to be configured either in the finance service values yaml file or the environment-specific yaml file.

finance: true

File store Configuration

Configure the following property either in the finance service values yaml file or the environment-specific yaml file.

filestore: /tmp/egovfilestore

Quartz Scheduler Configuration

Configure the following property either in the finance service values yaml file or the environment-specific yaml file.

scheduler: true

DIGIT integration configuration

The finance service reads data from multiple other DIGIT services. The following are the different services the finance system reads data from. Update the domain URL of the respective service based on the service where it is running.

microservice: |
  egov.default.services.endpoint=https://egov-micro-dev.egovernments.org/
  egov.hrms.service.endpoint=http://egov-hrms.egov:8080/
  egov.accesscontrol.service.endpoint=http://egov-accesscontrol.egov:8080/
  egov.hr.masters.service.endpoint=http://hr-masters.egov:8080/
  egov.user.service.endpoint=http://egov-user.egov:8080/
  egov.common.masters.endpoint=http://egov-common-masters.egov:8080/
  egov.billing.service.endpoint=http://billing-service.egov:8080/
  egov.collection.service.endpoint=http://collection-services.egov:8080/
  egov.egf.master.service.endpoint=http://egf-master.egov:8080/
  egov.egf.instrument.service.endpoint=http://egf-instrument.egov:8080/
  egov.mdms.service.endpoint=http://egov-mdms-service.egov:8080/
  egov.indexer.service.endpoint=http://egov-indexer.egov:8080/
  egov.services.billing.service.bill.generate=billing-service/bill/v2/_fetchbill
  egov.filestore.service.endpoint=http://egov-filestore.egov:8080/

MDMS Configuration

• The following master data is present in the MDMS repository.

  • Department

  • Designation

  • BusinessServiceMapping

  • TaxHeadMasterGlCodeMapping

  • InstrumentGLcodeMapping

  • AccountCodeTemplate

  • FinanceInstrumentStatusMapping

  • tenants

  • OnlineGLCodeMapping

• Define all the departments in the Departments json

• Define all the designations in the Designations json

• Configure finance tenants in the Citymodule json to enable the finance module in the ULB.

{
      "module": "Finance",
      "code": "Finance",
      "tenants": [
        {
          "code": "pb.jalandhar"
        },
        {
          "code": "pb.nawanshahr"
        }
      ]
    },

• Define business services mapping in the Business Service Mapping json to integrate different business services like Property Tax, Trade License and FireNOC etc with Finance and to post vouchers like demand and receipt vouchers. Enabling and disabling voucher posting for any service can be configured here.

• Define the Tax head and instrument glcode mappings in the Account Head Mapping json. This file contains each tax head-wise glcode mapping and each instrument-wise glcode mapping.

• Different instrument statuses can be defined in the Instrument Status Mapping json file.

• Different types of contractor bill templates are defined in the AccountCode Template file. These templates will be used in the contractor bill creation screen to auto-populate the account codes.

• Service-wise glcode mapping for the online instrument type for the particular city is defined in the Online Instrument Type json.

• Define the business service-wise bank account mappings in the BankAccount Service Mapping json file. These details are to be configured city-wise as the bank details are specific to a city.

MDMS search URL is configured in the Application Configuration file.

Changes required to setup workspace in the local machine

1. Set up the Finance service workspace by following the instructions provided in README.

2. After set-up is done, make the changes to the host file in the local machine, by mapping the domain URLs with a local IP address and saving the changes. Restart your local machine to make the host mapping effective.

$ vim /etc/hosts

127.0.0.1 egov-micro-dev.egovernments.org

Reference Docs