Page Comparison

Overview

This document describes all the steps to be followed to set up a new instance of Finance. When a new State 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.

• Centralised Server hosting all the ULBs within a state

• All ULBs access the software over API calls.

• Uniform code base supporting all the ULBs for the state. City-specific changes are maintained using client-specific implementation repositories.

• A separate schema for each ULB in the database.

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

• JBoss Customized Wildfly v11.xImage

• 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 implementation repository

How to set up a client implementation repository

1. Branch out Fork and create a client implementation repository from Client implementation repository to keep client-specific data and configurations.

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

Application Configuration

Setup schema based multi tenant database

Finance co-existence service uses schema based multi tenancy i.e . multi-tenancy with a single multi-tenant database. The following are the configuration changes to setup schema based multi tenant database.

The configurations to be done either in the /egov-egi/src/main/resources/config/application-config.properties or in the ${HOME_DIR}/wildfly-11.0.0.Final/modules/system/layers/base/org/egov/settings/main/config/egov-erp-override.properties

• Enable multi tenancy by enabling the following property

multitenancy.enabled=true

• The state schema is configured by adding the following property

statewide.schema.name=generic

generic is the statewide schema name.

...

• 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 to 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/dev.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 dev environment, update the dev-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, this 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

default.schema.name=generic

...

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 below configuration.

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

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

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

• Insert data into eg_city, in the city table, domain 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:

  Code Block
  language java
  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

• The following are the SQL file locations to pick and execute according to the properties configured in the properties file.

• The SQL files present in the following locations will be executed on all the schemas present in the database.

#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/

• Sample scripts will be executed if dev.mode=true enabled.

db.flyway.sample.migration.file.path=classpath:/db/migration/sample/

• City wise scripts will be executed on the city’s schema

db.flyway.tenant.migration.file.path=classpath:/db/migration/%s/

• State wide scripts will be executed on the configured statewide schema if the state wide migration is enabled.

statewide.schema.name=generic
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=true
db.flyway.statewide.migration.file.path=classpath: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 the 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)
statewide_migration: true
#Enable or Disable Multitenancy
multitenancy: true

System Integration User Details Configuration

Add the following System integrator user details

...

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

Systemintegration: |
 si.microservice.user=SIFINANCE${si-microservice-user}
 si.microservice.password=sifinance123@${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

Elastic Dashboard Configuration

Enable/Disable event to push the created/updated bill/vouchers to ES indexer

finance.esk.dashboard.event.enabled=false

...

{
	"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

Finance service reads data from multiple other micro DIGIT services. The following are the different services 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=httpshttp://egov-micro-dev.egovernments.org/hrms.egov:8080/
  egov.accesscontrol.service.endpoint=httpshttp://egov-micro-dev.egovernments.org/accesscontrol.egov:8080/
  egov.hr.masters.service.endpoint=httpshttp://egovhr-micro-dev.egovernments.org/masters.egov:8080/
  egov.user.service.endpoint=httpshttp://egov-micro-dev.egovernments.org/user.egov:8080/
  egov.common.masters.endpoint=httpshttp://egov-microcommon-dev.egovernments.org/masters.egov:8080/
  egov.billing.service.endpoint=httpshttp://egovbilling-micro-dev.egovernments.org/service.egov:8080/
  egov.collection.service.endpoint=httpshttp://egovcollection-micro-dev.egovernments.org/services.egov:8080/
  egov.egf.master.service.endpoint=httpshttp://egovegf-micro-dev.egovernments.org/master.egov:8080/
  egov.egf.instrument.service.endpoint=httpshttp://egovegf-micro-dev.egovernments.org/instrument.egov:8080/
  egov.mdms.service.endpoint=httpshttp://egov-micromdms-dev.egovernments.org/service.egov:8080/
  egov.indexer.service.endpoint=httpshttp://egov-micro-dev.egovernments.org/
egov.filestore.service.endpoint=https://egov-micro-dev.egovernments.org/

Changes required to setup workspace in local machine

1. Setup 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 save the changes. Restart your local machine to make the host mapping effective.

$ vim /etc/hosts

127.0.0.1 egov-micro-dev.egovernments.orgindexer.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 masters master data is present in the mdms 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 finance module in the ULB

...

• 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 System and to post vouchers like demand and receipt vouchers. Enabling /and disabling voucher posting and different masters for voucher 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 mappings.

• 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 ulb 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 to be configured city wise as the bank details are specific to a city.

Add the property and update the MDMS search URL, egov.services.master.mdms.search.url=/egov-mdms-service/v1/_search in application-config.properties file or egov-erp-override.properties file

References

...

Title

...

Link

...

MDMS serach url is configured in the Application Configuration file.

Sub domain formation logic in front end employee app

Finance coexistence follows schema per ulb structure and each city requires one sub domain. Sub domain formation for the different environments is happening dynamically by reading the environment value from the FIN_ENV environment variable in the js file.

The following code snippet shows the sub domain formation logic

locale = localStorage.getItem("locale"),
    menuUrl = this.props.location.pathname,
    loc = window.location,
    subdomainurl,
    domainurl,
    finEnv,
    hostname = loc.hostname,
    winheight = window.innerHeight - 100,
    erp_url,
    tenantId = getTenantId();
    domainurl = hostname.substring(hostname.indexOf(".") + 1);
    finEnv = this.globalConfigExists() ? window.globalConfigs.getConfig("FIN_ENV") : process.env.REACT_APP_FIN_ENV;
    subdomainurl = !!(finEnv) ? "-" + finEnv + "." + domainurl : "." + domainurl;
    erp_url = loc.protocol + "//" + getTenantId().split(".")[1] + subdomainurl + menuUrl;
    console.log("ERP URL : " + erp_url);

The FIN_ENV variable is configurable and configured in the globalConfigs.js which is present (to be created if not present) in the S3 Bucket. The following code snippet shows the same.

var globalConfigs = (function() {
  var stateTenantId = 'pb'
  var finEnv = 'dev'
  var getConfig = function(key) {
      if(key === 'STATE_LEVEL_TENANT_ID'){
          return stateTenantId;
      } else if(key === 'FIN_ENV'){
        return finEnv;
      }
  };
  return {
      getConfig
  };
}());

The following are some examples

EX 1:
Domain url : citya.digit.org
Sub domain url: citya-uat.digit.org

Then configure the FIN_ENV variable as 'uat' like below
FIN_ENV='uat'

EX 2:
Domain url : staging.digit.org  
Sub domain url: citya.digit.org

Then configure the FIN_ENV variable as 'uat' like below
FIN_ENV=''

EX 3:
Domain url : dev.digit.org 
Sub domain url: amritsar-dev.digit.org

Then configure the FIN_ENV variable as 'uat' like below
FIN_ENV='dev'

The globalConfigs.js file is custom injected in the environment specific yaml files. The following code snippet shows the same.

employee:
  custom-js-injection: |
    sub_filter.conf: "
      sub_filter  '<head>' '<head>
      <script src=https://s3.ap-south-1.amazonaws.com/egov-telemetry-data/egov-telemetry-1557467338.js type=text/javascript></script>
      <script src=https://s3.ap-south-1.amazonaws.com/egov-dev-assets/globalConfigs.js type=text/javascript></script>
      <link rel=stylesheet href=https://egov-dev-assets.s3.ap-south-1.amazonaws.com/dashboard-iframe-fix.css>
      ';"

The sample environment yaml files for your reference

https://github.com/egovernments/

...

Train-

...

InfraOps/blob/master/helm/

...

environments/

...

dev.yaml

Changes required to setup workspace in local machine

1. Setup 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 save the changes. Restart your local machine to make the host mapping effective.

$ vim /etc/hosts

127.0.0.1 egov-micro-dev.egovernments.org

References