Overview

The Collection service is to serve as a revenue collection platform for all the billing systems through cash, cheque, dd, swipe machine. It enables payment for all services provided by the eGov platform at a single point for the Citizen and counter collection in municipal alike.

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.

• Following services should be up and running:

  • egov-localization

  • egov-mdms

  • egov-idgen

  • egov-url-shortening

  • billing-service

Key Functionalities

• Allows citizens to create a payment.

• Allows employees to create the payment for the citizen indirectly.

• provides facilities to capture partial and advanced payment based on configs.

• allows payment cancellation to help with scenarios of bad checks and other failed payment scenarios.

• Integrates with billing-service for demand back-update of payment.

Deployment Details

• deploy the latest version of the collection-services docker build.

Configuration Details

The MDMS data configuration uses the same data updated by Billing-Service

Billing Service | Configuration-Details: Refer MDMS data config from here.

Following are the properties in the application.properties

Integration

Integration Scope

Collection service can be integrated with any organization or system that wants a payment system to keep track of its payments. Organizations can customize part of the application or its functionality based on their requirements.

Integration Benefits

• Easy payments and tracking of payments.

• Configurable functionalities according to client requirement

Steps to Integration

1. Customer can create a payment using the /payments/_create

2. Actors on the system can keep track of payments using /payments/_searchendpoint

3. Once the payment is done but it encounters a technical issue outside of the system then it can be cancelled with /payments/_workflow

4. For employees to access the payments API the respective module name should be appended after the payment API path - /payments/PT/_workflow - here PT refers to property module.

IFSC Code Migration in Collection Service

1. Port foward the collection-service to current environment where the IFSCCODE bankdetails data to be migrated. Find the sample command below. 1kubectl port-forward collection-services-76b775f976-xcbt2 8055:8080 -n egov

2. Import postman collection from API list which refers as /preexistpayments/_update and run with the same localhost to where we port forwarded using above command.

3. Expected result. In EGCL_PAYMET table where IFSCODE data is present for those record, EGCL_PAYMET.ADDITIONALDETAILS bankdetails will be updated.

   Ex: For IFSCCODE : UCBA0003047 Response from API https://ifsc.razorpay.com/UCBA0003047 will be update in EGCL_PAYMET.ADDITIONALDETAILS as {"bankDetails": {"UPI": true, "BANK": "UCO Bank", "CITY": "BHIKHI", "IFSC": "UCBA0003047", "IMPS": true, "MICR": "151028452", "NEFT": true, "RTGS": true, "STATE": "PUNJAB", "SWIFT": "", "BRANCH": "BHIKHI", "CENTRE": "MANSA", "ADDRESS": "ADJOINING HP PETROL PUMP MANSA ROADDISTRICT MANSA","BANKCODE":"UCBA","DISTRICT":"MANSA","CONTACT":"+918288822548"}

Interaction Diagram

Billing-Collection-Integration Refer integration with details and explanation.

Reference Docs

Doc Links

API List

Introduction

DIGIT is India's largest open-source platform for Urban Governance. It provides API based access to government functions enabling the government to provide facilities via integration with relevant service players. This document is aimed at System Integrators looking to provide bill collection facilities to their government customers using DIGIT as their governance platform. It outlines the integration approach with Billing and Collections services to enable fetching bill dues to Citizens and recording their payments into the system.

High-Level Approach

DIGIT is completely API driven and allows for data exchange with disparate systems using REST API calls. Most functional API are protected resources that can be accessed after proper authentication with the platform. The platform also checks for the right level of access for the given credentials. A bill collection flow consists of the following steps -

1. Authentication with DIGIT

2. Get Bill for the citizen using a service-specific query

3. Record the payment details against the bill

4. Optional - Get Payment API to fetch the details of the receipt

As the in-field team of the system integrator would already be making these calls to the integrator's own system (or a standard system like BBPS), integration with DIGIT is a server to server integration where the backend system of the integrator will make these calls to the DIGIT platform as per the need. The following diagram depicts the high-level flow of calls between On Field devices like PoS (On Field Device) to Backend of the Integrator (Integrator System) and from Backend of the Integrator to DIGIT (DIGIT Platform).

Integration Details

DIGIT uses Swagger 2.0 as its API standard and all its APIs are documented in Swagger. Wherever needed this document will provide a link to our API documentation online. An example of typical request/response snippets necessary for integration is provided below in the respective sections. Please note that DIGIT being a multi-tenanted system, all APIs in DIGIT expect tenantid passed either in the query param or RequestBody (Please refer to detailed API documentation as indicated in sections below). The tenantid represents the modular operating unit for the operation of an API, e.g. in a municipal governance use case, a tenantid will represent one ULB. Your platform contact will help you access the configured list for your use case. Authentication API also expects tenantid (Your platform contact will help you with which one to use), however, based on the role as an integrator the OAUTH token in response can be used for unit/ULB level tenants in subsequent API calls (meaning you may not need one authentication per unit/ULB level tenant).

1. Authentication

To ensure data privacy and security, transactional APIs in DIGIT are protected under authentication. System integrators are requested to contact the respective state authority to get the necessary OAUTH tokens that can be used to access these APIs. Kindly note that apart from userid/password system may enforce IP based access control in which case integrator may be required to share IP or range of IPs from which the request will originate. To generate the access token based on the credentials provided, please use the following API - Given below is the example of the request and response, OAuth token to be used from the response is highlighted in Bold.

Request Snippet

Response Snippet

2. Fetching Bill

DIGIT allows the integrators to fetch the bills for citizens using the Consumer number of the respective service (e.g. Water charges, Property Service, Trade License). Please note that different services may have different notions of consumer number, e.g. for Water Charges consumer number will signify the "Connection number" while for Property it will be "Property Id". For some services, DIGIT also provides the facility to fetch bill by mobile number, please note that a bill search by mobile number may return multiple bills across services and may not return bills from services that do not support mobile-number based search. To support partial payment use case each bill in the response of the fetch bill API will indicate whether it is allowed to be partially paid and any minimum amount if partial payment is allowed. To fetch a bill from DIGIT, please ensure that OAuth token is generated as per the Authentication section above. Post that you can use the following API to fetch the bill -

• Choose Billing Service from the dropdown

• Go to the Bill section of BillingService

• Go to the Bill tab

3. Make Payment

Once the bill is fetched from the DIGIT system, the system integrator is expected to relay it back to the Field Device. Integrator is expected to Initiate and collect the payment based on government preference indicated in the bill (can it be partially paid and if so the minimum amount etc.) and Citizen's preference of payment instrument etc. Once the payment is successfully done in the integrator's system, the integrator is expected to register the payment in DIGIT using the Payment Create API. Please note that a bill is considered unpaid/partially paid by DIGIT till appropriate receipts are created using this API - which means that a subsequent fetch of the bill, till this API is called, will return the original bill. DIGIT expects a Receipt (The result of calling payment API) to be created against the bill number returned in the fetch bill API, please note that a receipt needs to be created for each bill. Therefore, if a total payment represents multiple bills - One receipt creation per bill is expected (DIGIT supports multiple receipt creation in a single call). To create a receipt in DIGIT, please ensure that OAuth token is generated as per the Authentication section above. Post that you can use the following API to create the receipt -

• Choose Collection Service from the dropdown

• Go to payment

• Go to the make payment

Overview

Apportion service is used to apportion the amount paid against a bill among the different tax heads based on the implemented algorithm. The default algorithm uses order of the tax head to apportion, the tax head with lowest order is apportioned off first while the highest order tax head is apportioned last.

Pre-requisites

Before you proceed with the documentation, make sure the following pre-requisites are met -

• Java 8

• Kafka server is up and running

• egov-persister service is running and has apportion persister config path added in it

• PSQL server is running and database is created to store apportion audit data

Key Functionalities

• Apportion payment in tax heads of bill

• Apportion advance amount in tax heads of demand during demand creation

Deployment Details

1. Deploy the latest version of egov-apportion-service service

2. Add apportion persister yaml path in persister configuration

Configuration Details

There is no separate configuration required. The TaxHead master that is configured in the billing service is only used

Integration Details

Integration Scope

Any payment service which wants to divide the paid amount into different tax head buckets can integrate with apportion service.

Integration Benefits

• Apportions amount in tax heads

Steps to Integration

1. To integrate, the host of egov-apportion-service should be overwritten in helm chart

2. /apportion-service/v2/bill/_apportion should be called to apportion the bill

3. /apportion-service/v2/demand/_apportion should be called to apportion advance amount in demands

Interaction Diagram

Reference Docs

Doc Links

API List

(Note: All the API’s are in the same postman collection therefore the same link is added in each row)

__

This section provides technical details about business service setup, configuration, deployment, and API integration.

• Bill Amendment

Overview

The main objective of the billing module is to serve the Bill for all revenue Business services. To serve the Bill, Billing-Service requires demand. Demands will be prepared by Revenue modules and stored by billing based on which it will generate the Bill.

Pre-requisites

• Prior Knowledge of Java/J2EE.

• Prior Knowledge of Spring Boot.

• Prior Knowledge of KAFKA

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

• Prior knowledge of the demand-based systems.

• Following services should be up and running:

  • user

  • MDMS

  • Id-Gen

  • URL-Shortening

  • notification-sms

Key Functionality

• eGov billing service creates and maintains demands.

• Generates bills based on demands.

• Updates the demands from payment when the collection service takes a payment.

Deployment Details

• Deploy the latest image of the billing service available.

Configuration Details

In the MDMS data configuration, the following master data is needed for the functionality of the billing.

MDMS

Business Service JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "BusinessService": [
    {
      "businessService": "PropertyTax",
      "code": "PT",
      "isBillAmendmentEnabled":"true",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": true,
      "minAmountPayable":100,
      "isAdvanceAllowed": false,
      "demandUpdateTime": 86400000,
      "isVoucherCreationEnabled": true,
      "billGineiURL" : "egov-searcher/bill-genie/billswithaddranduser/_get"
    },
    {
      "businessService": "WaterCharges",
      "code": "WC",
      "isBillAmendmentEnabled":"true",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": false,
      "isAdvanceAllowed": true,
      "demandUpdateTime": 86400000,
      "isVoucherCreationEnabled": false
    },
    {
      "businessService": "TradeLicense",
      "code": "TL",
      "collectionModesNotAllowed": [
        "DD","OFFLINE_NEFT","OFFLINE_RTGS","POSTAL_ORDER"
      ],
      "partPaymentAllowed": false,
      "isAdvanceAllowed": false,
      "demandUpdateTime": 604800000,
      "isVoucherCreationEnabled": true
    }
  ]
}

TAX-Head JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "TaxHeadMaster": [
    {
      "category": "ADVANCE_COLLECTION",
      "service": "PT",
      "name": "Pt advance carry forward",
      "code": "PT_ADVANCE_CARRYFORWARD",
      "isDebit": true,
      "isActualDemand": false,
      "order": "0",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt owner exemption",
      "code": "PT_OWNER_EXEMPTION",
      "isDebit": true,
      "isActualDemand": true,
      "order": "5",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt time rebate",
      "code": "PT_TIME_REBATE",
      "isDebit": true,
      "isActualDemand": true,
      "order": "2",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt unit usage excemption",
      "code": "PT_UNIT_USAGE_EXEMPTION",
      "isDebit": true,
      "isActualDemand": true,
      "order": "6",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt adhoc penalty",
      "code": "PT_ADHOC_PENALTY",
      "isDebit": false,
      "isActualDemand": false,
      "order": "1",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "propertytax",
      "code": "PT_TAX",
      "isDebit": false,
      "isActualDemand": true,
      "order": "0",
      "isRequired": false
    },
    {
      "category": "TAX",
      "service": "PT",
      "name": "Pt fire cess",
      "code": "PT_FIRE_CESS",
      "isDebit": false,
      "isActualDemand": true,
      "order": "7",
      "isRequired": false
    }
  ]
}

Tax-Period JSON

{
  "tenantId": "pb",
  "moduleName": "BillingService",
  "TaxPeriod": [
    {
      "fromDate": 1554076799000,
      "toDate": 1585679399000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2019",
      "financialYear": "2019-20"
    },
    {
      "fromDate": 1522540800000,
      "toDate": 1554076799000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2018",
      "financialYear": "2018-19"
    },
    {
      "fromDate": 1491004800000,
      "toDate": 1522540798000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2017",
      "financialYear": "2017-18"
    },
    {
      "fromDate": 1459468800000,
      "toDate": 1491004799000,
      "periodCycle": "ANNUAL",
      "service": "PT",
      "code": "PTAN2016",
      "financialYear": "2016-17"
    },
    {
      "fromDate": 1522540800000,
      "toDate": 1554076799000,
      "periodCycle": "ANNUAL",
      "service": "TL",
      "code": "TLAN2018",
      "financialYear": "2018-19"
    }
  ]
}

Integration Details

Integration Scope

Billing service can be integrated with any organization or system that wants a demand-based payment system.

Integration Benefits

• Easy to create and simple process of generating bills from demands

• The amalgamation of bills period-wise for a single entity like PT or Water connection.

• Amendment of bills in case of legal requirements.

Steps to Integration

1. Customer can create a demand using the /demand/_create

2. Organization or System can search the demand using /demand/_searchendpoint

3. Once the demand is raised the system can call /demand/_update endpoint to update the demand as per need.

4. Bills can be generated using, which is a self-managing API that generates a new bill only when the old one expires /bill/_fetchbill.

5. Bills can be searched using /bill/_search.

6. Amendment facility can be used in case of a legal issue to add values to existing demands using /amendment/_create and /amendment/_update can be used to cancel the created ones or update workflow if configured.

Interaction Diagram

Interaction Diagram V1.1:

Reference Docs

Doc Links

API List

Apportioning FAQs

What is apportioning?

Adjusting the receivable amount with the individual tax head.

Types of apportioning V1.1

Default order based apportioning(Based on apportioning order adjust the received amount with each tax head).V1.1

Types of apportioning V1.2: (TBD)

• Proportionate based apportioning (Adjust total receivable with all the tax head equally)

• Order & Percentage based apportioning(Adjust total receivable based on order and the percentage which is defined for each tax head).

Principle of apportioning

The basic principle of apportioning is, if the full amount is paid for any bill then each individual tax head should get nullify with their corresponding adjusted amount.

Example: Case 1: When there are no arrears all tax heads belong to their current purpose:

Case 2: Apportioning with two years of arrear: If the current financial year is 2014-15. Below are the demands

if any payment is not done, and we generating demand in 2015-16 then the demand structure will as follows:

DSS Backend Configuration Manual

Overview

DSS has two sides to it. One is the process in which the Data is pooled to ElasticSearch and the other being the way it is fetched, aggregated, computed, transformed and sent across. As this revolves around a variety of Data Set, there is a need for making this configurable. So that, tomorrow, given a new scenario is introduced, then it is just a configuration away from getting the newly introduced scenario involved in this flow of the process.

This document explains the steps on how to define the configurations for both sides of DSS. Analytics and Ingest Pipeline Services.

Abbreviations

Ingest: Micro Service which runs as a pipeline and manages to validate, transform and enrich the incoming data and pushes the same to ElasticSearch Index

Analytics: Micro Service which is responsible for building, fetching, aggregating and computing the Data on ElasticSearch to a consumable Data Response. Which shall be later used for visualizations and graphical representations.

JOLT: JSON to JSON transformation library written in Java where the "specification" for the transform is itself a JSON document

Modules / Domain Level: These are the Services in this context. Each of the services, such as Property Tax, Trade License, Water and Sewerages are considered as Modules / Domains

Chart: Each individual graphical representation is considered as a Chart in specific. For example, a Metric of Total Collection is considered as a Chart.

Visualization: Group of different Charts is considered as a Visualization. For example, the group of Total Collection, Target Collection and Target Achieved is considered as a Metric Collection of Charts and thus it becomes a Visualization.

Ingest Pipeline Configurations

Below is the list of configurations -

1. Topic Context Configurations

2. Validator Schema

3. JOLT Transformation Schema

4. Enrichment Domain Configuration

5. JOLT Domain Transformation Schema

Descriptions

Topic Context Configurations

Topic Context Configuration is an outline to define which data is received on which Kafka Topic.

Indexer Service and many other services are sending out data on different Kafka Topics. If the Ingest Service is asked to receive those data and pass it through the pipeline, the context and the version of the data being received has to be set. This configuration is used to identify which kafka topic consumed the data and what is the mapping for that.

Click here for Full Configuration

1. Validator Schema

Validator Schema is a configuration Schema Library from EveritBy passing the data against this schema, it ensures whether the data abides by the rules and requirements of the schema which has been defined.

Click here for an example configuration

1. JOLT Transformation Schema

JOLT is a JSON to JSON Transformation Library. In order to change the structure of the data and transform it in a generic way, JOLT has been used.

While the transformation schemas are written for each Data Context, the data is transformed against the schema to obtain a transformed data.

Follow the slide deck for JOLT Transformations

Click here for an example configuration

1. Enrichment Domain Configuration

This configuration defines and directs the Enrichment Process which the data goes through.

For example, if the Data which is incoming is belonging to a Collection Module data, then the Collection Domain Config is picked. And based on the Business Type specified in the data, the right config is picked.

In order to enhance the data of Collection, the domain index specified in the configuration is queried with the right arguments and the response data is obtained, transformed and set.

Click here for an example configuration

1. JOLT Domain Transformation Schema

As a part of Enhancement, once the domain level object is obtained, we might not need the complete document as is in the end data product.

Only those parameters which should be or can be used for aggregation and representation are to be held and others are to be discarded.

In order to do that, we make use of JOLT again and write schemas to keep the required ones and discard the unwanted ones.

The above configuration is used to transform the data response in the enrichment layer.

Click here for an example configuration

1. Use case:- JOLT Transformation Schema for collection V2

JOLT transformation schema for payment-v1 has taken as a use case to explain the context collection and context version v2. The payment records are processed/transformed with the schema. The schema supports splitting the billing records into an independent new record. So if there are 2 bill items in the collection/payment incoming data then this results in 2 collection records in turn.

Click here for an example configuration

Here: $i, the variable value that gets incremented for the number of records of paymentDetails

$j, the variable value that gets incremented for the number of records of billDetails.

Note: For kafka connect to work, Ingest pipeline application properties or in environments direct push must be disabled.

es.push.direct=false

Analytics Configurations

Below is the list of configurations

1. Chart API Configuration

2. Master Dashboard Configuration

3. Role Dashboard Mappings Configuration

Description

Chart API Configuration

Each Visualization has its own properties. Each Visualization comes from different data sources (Sometimes it is a combination of different data sources)

In order to configure each visualization and its properties, we have Chart API Configuration Document.

In this, Visualization Code, which happens to be the key, will be having its properties configured as a part of the configuration and are easily changeable.

Click here for an example configuration

1. Master Dashboard Configuration

Master Dashboard Configuration is the main configuration that defines which Dashboards that are to be painted on the screen.

It includes all the Visualizations, their groups, the charts which comes within them and even their dimensions as what should be their height and width.

Click here for an example configuration

1. Role Dashboard Mappings Configuration

Master Dashboard Configuration which was explained earlier hold the list of Dashboards that are available. Given the instance where Role Action Mapping is not maintained in the Application Service, this configuration will act as Role - Dashboard Mapping Configuration

In this, each Role is mapped against the Dashboard which they are authorized to see

This was used earlier when the Role Action Mapping of eGov was not integrated. Later, when the Role Action Mapping started controlling the Dashboards to be seen on the client-side, this configuration is just used to enable the Dashboards for viewing.

Click here for an example configuration

Adding Configurations

Adding Roles and Dashboards :

To add a new role, RoleDashboardMappingsConf.json (roles node) configuration file has to be modified as below

Below as in Figure 9. is a sample to add a new role object, new dashboard object

To add a new dashboard, MasterDashboardConfig.json (dashboards node) has to be modified as below in Figure 10.

Adding Visualizations in existing Dashboard

To add new visualisations, again MasterDashboardConfig.json (vizArray node) has to be modified as below as shown in Figure 11.

Note: vizArray is to hold multiple visualizations

Adding charts for visualizations

To add a new chart, chartApiConf.json has to be modified as shown below. A new chartid has to be added with the chart node object.

Metric chart Sample as shown in Figure 12.

Pie chart Sample as shown in Figure 13.

Line chart Sample as shown in Figure 14.

****

Table chart Sample: This chart comes in 2 kind - table and xtable.

table (as shown in Figure 15.) type allows to added aggregated fields added as available in the query keys, hence to extract the values based on the key, aggegationPaths needs to add along with their data type as in pathDataTypeMapping.

xtable(as shown in Figure 16.) type allows to add multiple computed fields with the aggregated fields dynamically added.

To add multiple computed columns, computedFields [] where actionName (IComputedField<T> interface), fields [] names as in existing in query key, newField as name to appear for computation must be defined.

https://github.com/egovernments/configs/blob/master/egov-dss-dashboards/dashboard-analytics/ChartApiConfig.json for the full configuration in detail.

Steps to create charts and visualise are:

• Create/Add a chart in chartApiConf.json

• Add a visualization for the existing dashboard in MasterDashboardConfig.json as defined above.

• Or in order to create/add a new dashboard create the dashboard in MasterDashboardConfig.json and create a role in RoleDashboardConfig.json

Configuration Changes for DrillThrough :

1. Example Drill through in Ward table in Property Dashboard.

wardDrillDown is the visualization code for PT Drill Down. kind is the attribute that shows the type of visualization code. Apart from two things all the attributes are common.

1. Example Drill through in ComplaintList table in PGR Dashboard.

complaintDrillDown is the visualization code for PGR Drill Down.

The above complaintDrillDown visualization code called in the drill chart parameter.

Overview

The consumer sometimes needs additional amounts (Amendments) added to their bill due to reasons from outside of the system. The addition of amounts happens with respect to the consumer code of the entity in the product(PT, WS, etc..,), any unpaid demand in the system is a candidate for amendments.

Pre-requisites

• Prior Knowledge of Billing-Service in Digit framework.

Key Functionality

Amendment mainly works with two types of functionality as follows:

• Amendment

• Demand

Bill Amendment provides a separate flow to enable workflow and validation for the process of adding additional amounts into the existing demands which were done through the respective modules only till this point in time. An amendment will be allowed only when the reason arises from out of the system to add or reduce the amount from the existing bill belonging to an entity. The reasons are as listed

1. Court case settlement

2. One time waiver

3. Write-offs

4. DCB correction (Old demands in paid status)

5. Remission for Property Tax

Criteria:

There are certain prerequisites to create an amendment,

1. presence of demand in the billing system

2. One of the Reason as Listed above

3. Valid document proof for the reason

4. No other Amendment already in workflow

Procedure:

The process of adding Amendment is as follows

Please follow the scenarios and let me know in case of doubts. There are two scenarios on how an amendment will be completed which is based on the paid status of the existing demands in the system.

1. when demand is unpaid/partially paid

1. create a demand (Or an existing demand can be used) with demand detail → DD1.

2. Do not pay the bill or make payment partially.

3. Create an amendment for the same consumer-code (with demand detail → DD2).

4. approve the amendment, the response should return an amendment with status CONSUMED.

5. search the demand or fetch bill for the consumer-code, demand/bill should contain demand details of demand and amendment together DD1 and DD2 in the same demand/bill.

2. when demand is completely paid,

1. create demand and make complete payment or choose a consumer-code which is fully paid.

2. create amendment (with demand detail → DD1).

3. Approve amendment, the response should be APPROVED this time.

4. create new demand for the consumer -code (with demand detail → DD3), demand response should contain two demand details DD1 and DD2 saved to the demand.

5. Now amendment search will return CONSUMED status after the demand is created.

IMPACT: Does not impact any other functionality other than adding demand details to demands on APPROVAL.

IMPACTED BY: Existence of demands in the system.

Configuration Details

Billing Service | Configuration-Details: ​Refer billing-service config for MDMS data. the amendment makes use of the same data set.

WORKFLOW CONFIG:

{
  "RequestInfo": {
    "apiId": "Rainmaker",
    "action": "",
    "did": 1,
    "key": "",
    "msgId": "20170310130900|en_IN",
    "requesterId": "",
    "ts": 1513579888683,
    "ver": ".01",
    "authToken": "{{authToken_amritsar}}"
  },
  "BusinessServices": [
    {
      "tenantId": "pb",
      "businessService": "BS.AMENDMENT",
      "business": "BS",
      "businessServiceSla": null,
      "states": [
        {
          "tenantId": "pb",
          "sla": null,
          "state": null,
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "OPEN",
              "nextState": "APPROVALPENDING",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVALPENDING",
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": true,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "EMPLOYEE"
              ]
            },
            {
              "tenantId": "pb",
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "INACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVED",
          "applicationStatus": "ACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        }
      ]
    }
  ]
}

Integration Details

Integration Scope

Amendment integration helps the respective Organization to add additional value to the demand without any change in the system.

Integration Benefits

• Easy to create and simple process of updating demands

• helps ease changes into the system which are not part of normal functionality - Amendment of bills in case of legal requirements.

Steps to Integration

This is integrated into the billing system by default.

1. Amendment facility can be used in case of a legal issue to add values to existing demands using /amendment/_create and /amendment/_update can be used to cancel the created ones or update workflow if configured.

Interaction Diagram

{yet to be addded}

Docs and Resource Links

API Definition

API SPEC FOR BILL-AMENDMENT

API LIST

Overview

The Collection service is to serve as a revenue collection platform for all the billing systems through cash, cheque, dd, swipe machine. It enables payment for all services provided by the eGov platform at a single point for the Citizen and counter collection in municipal alike.

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.

• Following services should be up and running:

  • egov-localization

  • egov-mdms

  • egov-idgen

  • egov-url-shortening

  • billing-service

Key Functionalities

• Allows citizens to create a payment.

• Allows employees to create the payment for the citizen indirectly.

• provides facilities to capture partial and advanced payment based on configs.

• allows payment cancellation to help with scenarios of bad checks and other failed payment scenarios.

• Integrates with billing-service for demand back-update of payment.

Deployment Details

• deploy the latest version of the collection-services docker build.

Configuration Details

The MDMS data configuration uses the same data updated by Billing-Service

Billing Service | Configuration-Details: Refer MDMS data config from here.

Following are the properties in the application.properties

Integration

Integration Scope

Collection service can be integrated with any organization or system that wants a payment system to keep track of its payments. Organizations can customize part of the application or its functionality based on their requirements.

Integration Benefits

• Easy payments and tracking of payments.

• Configurable functionalities according to client requirement

Steps to Integration

1. Customer can create a payment using the /payments/_create

2. Actors on the system can keep track of payments using /payments/_searchendpoint

3. Once the payment is done but it encounters a technical issue outside of the system then it can be cancelled with /payments/_workflow

4. For employees to access the payments API the respective module name should be appended after the payment API path - /payments/PT/_workflow - here PT refers to property module.

Interaction Diagram

Billing-Collection-Integration Refer integration with details and explanation.

Reference Docs

Doc Links

API List

Overview

The consumer sometimes needs additional amounts (Amendments) added to their bill due to reasons external to the system. The addition of amounts happen with respect to the consumer-code of the entity in the product(PT, WS etc..,), any unpaid demand in the system is a candidate for amendments.

Functionality

Amendment mainly works with two types of functionality as follows:

• Amendment

• Demand

Objective

The main objective of the Bill-Amendment module is to create Credit/ Debit Notes against the bills for consumers who need an additional amount to be added to their bill.

Feature List

• Create Amendment

• Search Amendment

• Update Demand

• Update Amendment

API DEFINITION

API SPEC FOR BILL-AMENDMENT

POSTMAN-COLLECTION

API COLLECTION BILL_AMENDMENT

Functionality

Bill Amendment provides a separate flow to enable workflow and validation for the process of adding additional amount into the existing demands which were done through the respective modules only till this point in time. An amendment will be allowed only when the reason arises from out of the system to add or reduce the amount from the existing bill belonging to an entity. The reasons are as listed below -

1. Court case settlement

2. One time waiver

3. Write-offs

4. DCB correction (Old demands in paid status)

5. Remission for Property Tax

Criteria

There are certain prerequisites to create an amendment,

1. Presence of demand in the billing system

2. One of the reasons listed above

3. Valid document proof for the reason

4. No other Amendment already in workflow

PROCEDURE

The process of adding Amendment is as follows

There are two scenarios on how an amendment will be completed which is based on the paid status of the existing demands in the system.

1. When demand is unpaid/partially paid

1. create a demand (Or an existing demand can be used) with demand detail → DD1.

2. Do not pay the bill or make payment partially.

3. Create an amendment for the same consumer-code (with demand detail → DD2).

4. approve the amendment, the response should return an amendment with status CONSUMED.

5. search the demand or fetch bill for the consumer-code, demand/bill should contain demand details of demand and amendment together DD1 and DD2 in the same demand/bill.

2. When demand is completely paid

1. create demand and make complete payment or choose a consumer-code which is fully paid.

2. create amendment (with demand detail → DD1).

3. Approve amendment, the response should be APPROVED this time.

4. create new demand for the consumer -code (with demand detail → DD3), demand response should contain two demand details DD1 and DD2 saved to the demand.

5. Now amendment search will return CONSUMED status after the demand is created.

IMPACT

Does not impact any other functionality other than adding demand details to demands on APPROVAL.

IMPACTED BY:

Existence of demands in the system.

WORKFLOW CONFIG

{
  "RequestInfo": {
    "apiId": "Rainmaker",
    "action": "",
    "did": 1,
    "key": "",
    "msgId": "20170310130900|en_IN",
    "requesterId": "",
    "ts": 1513579888683,
    "ver": ".01",
    "authToken": "{{authToken_amritsar}}"
  },
  "BusinessServices": [
    {
      "tenantId": "pb",
      "businessService": "BS.AMENDMENT",
      "business": "BS",
      "businessServiceSla": null,
      "states": [
        {
          "tenantId": "pb",
          "sla": null,
          "state": null,
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": false,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "OPEN",
              "nextState": "APPROVALPENDING",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVALPENDING",
          "applicationStatus": "INWORKFLOW",
          "docUploadRequired": true,
          "isStartState": true,
          "isTerminateState": false,
          "actions": [
            {
              "tenantId": "pb",
              "action": "APPROVE",
              "nextState": "APPROVED",
              "roles": [
                "EMPLOYEE"
              ]
            },
            {
              "tenantId": "pb",
              "action": "REJECT",
              "nextState": "REJECTED",
              "roles": [
                "EMPLOYEE"
              ]
            }
          ]
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "REJECTED",
          "applicationStatus": "INACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        },
        {
          "tenantId": "pb",
          "sla": null,
          "state": "APPROVED",
          "applicationStatus": "ACTIVE",
          "docUploadRequired": false,
          "isStartState": false,
          "isTerminateState": true,
          "actions": null
        }
      ]
    }
  ]
}

Description

This release for DSS focuses on improving user experience and ability given to the user to get deeper insights using drill through and comparison indicators in tables.

The release includes the following features:

• Breadcrumbs for better navigation

• Drill through options in tables and charts

• Comparison indicators in Table

Breadcrumbs for Navigation

In addition to the left navigation panel, the addition of breadcrumbs is also useful to provide a better sense of the current page insight. It is also very much helpful for mobile navigation. The user can navigate using the breadcrumbs by clicking on the required parent menu.

Technical Implementation Details

It Works based on the Current Route URL and previous Route URL

File Details

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/Breadcrumbs.js

Drill through options in tables and charts

The ability provided in DSS to configure the drill through for required options in tables as well as charts. The drill through options is useful in configuring the required hierarchy of data set. This helps users to go up to 'N' levels to get deeper insights

Technical Implementation Details:

Drill down /Drill through in Tables, is based on the drillDownChartId and filter.

Here chart id is used for the subsequent call to fetch the next table along with the applied/selected filters.

File Details

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/components/Charts/TableChart.js

Drill throughs in piecharts :

It is Similar to Dilldown in tables, here Drill through in piecharts are based on the drillDownChartId field in the parent piechart

File Details,

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/components/Charts/DonutChart.js

Comparison Indicators in Tables

Providing better insights about the metric performances of different dimensions, a comparison indicator is required inside data tables comparing usually with a different time range (last year/last month) and what is percentage change with time.

Technical Implementation Details:

For Comparing with previous year data in every table data, the same request object will be used by changing the time range to the previous year/month/week.

File Details

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/components/Charts/TableChart.js

The following Method along with parameters is used to fetch the previous year data.

getLastYearRequest(calledFrom, visualcode, active, filterList) 

after receiving last year data it is compared with current year data and will be shown insight data will be shown, comparison logic is present in uiTable.js

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/components/common/UiTable/UiTable.js

TimeFilter

The current time component is not very intuitive and user friendly. So New library react-date-range was used to enhance the time filter.

File Details

https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/components/common/DateRange/index.js

Event Duration Graphs

Ability to generate graphs showcasing time spent between multiple events like average turnaround time, complaint assigning time, etc.

A DSS_EVENT_DURATION_GRAPH was added in the PGR config

{

    "id": 412,

    "name": "DSS_EVENT_DURATION_GRAPH",

    "dimensions": {

        "height": 350,

        "width": 7

    },

    "vizType": "chart",

    "isCollapsible": false,

    "label": "",

    "charts": [

        {

            "id": "eventDurationGraph",

            "name": "Monthly",

            "code": "",

            "chartType": "line",

            "filter": "",

            "headers": []

        }

    ]

}

API Call Role Action Mapping

Description

A decision support system (DSS) is a composite tool that collects, organizes and analyzes business data to facilitate quality decision-making for management, operations and planning. A well-designed DSS aids decision makers in compiling a variety of data from many sources: raw data, documents, personal knowledge from employees, management, executives and business models. DSS analysis helps organizations to identify and solve problems, and make decisions.

Code Git Repos: https://github.com/egovernments/frontend/tree/master/web/dss-dashboard

Type of users

1. State-Level Admin

2. Commissioner

3. Domain-Level Employee

Dashboard List

There are three types of dashboards -

1. Home page (refer figure 1).

2. Overview page (refer figure 2).

3. Module level dashboard (refer figure 3).

1. Home page

The home page contains multiple cards, each card is clickable.

There are two types of cards, i.e, Overview card and module-level card.

Overview and Module level card is differentiated by vizType,

1. Overview card: On click of overview card, it will navigate to overview page. vizType for Overview is collection.

2. Module Level card: On Click of Module level card, it will navigate to Module level dahsboard. vizType is module (i.e Property Tax, Trade License etc).

Request Payload for dashboardConfig:

auth-token : which is for authenticate the request and it will fetch from a local storage key called “Employee.token”

DashboardConfig API Response

roleName: Which type of user.

Visualizations: Key contains all configuration for displaying the visualization like rows with charts etc please refer to figure 1.3.

In Figure 1.3, vizType key will define the module UI like

Collection Chart & Module Chart refer the figure 1

2. Overview Dashboard

****

3. Module Level Dashboard

Visualizations List

In dashboardConfig response visualizations key contains all rows & charts details(refer figure 1.3).

1.Each row contains the visual details like name,vizType,noUnit,isCollapsible,charts etc ****(refer figure 1.3).

1. name - Name of visualization.

2. vizType - type of visualization like COLLECTION,MODULE,METRIC-COLLECTION, PERFORMING-METRIC, CHART.

   1. COLLECTION - In home page, contains the collection data (refer figure 1).

   2. MODULE - In home page, contains the module level data (refer figure 1).

   3. METRIC-COLLECTION - In Overview/Module Level Page, contains the collection data (refer figure 2.1).

   4. PERFORMING-METRIC -In Overview/Module Level Page, contains the top/bottom performing data (refer figure 2.2).

   5. CHART - In Overview/Module Level Page, contains the below visualizations (refer figure 2.3 to figure 2.7).

      1. PIE CHART (refer figure 2.3)

      2. LINE CHART (refer figure 2.4)

      3. BAR CHART (refer figure 2.5)

      4. HORIZONTAL BAR CHART (refer figure 2.6)

      5. TABLE CHART (refer figure 2.7)

List of visualizations

Figure : 2.1 - Metric-collection.

Figure : 2.2 - PERFORMING-METRIC

Figure : 2.3 - CHART - PIE

Figure : 2.4 - Chart - LINE

Figure : 2.5 - Chart - BAR

Figure: 2.6 - Chart - HORIZONTAL BAR

Figure: 2.7 - Chart - TABLE

Figure: 2.8 - GLOBAL FILTERS

Figure: 2.9 - DOWNLOAD & SHARE BUTTON

ULB Dashboard

ULB Dashboard is having different filters, i.e ULB’s and Wards/Blocks. The data to the filters are loaded from below MDMS API -

https://dev.digit.org/egov-mdms-service/v1/_search

1. Each ULB dashboard, overview Dashboard and module-level pages contain different filters and are identified by roleName in configs API.

2. The Wards/Blocks filter is a dependable filter, which gets loaded on ULB selection.

3. In the ULB dashboard, the On-page ULB filter will be applied across all the charts and for the Performance chart, the default ULB filter will not be applied.

4. Overview and all module level page is having a ULB dashboard.

GLOBAL Filters (refer to figure 2.8)

Filters will be loaded from MDMS API.

https://dev.digit.org/egov-mdms-service/v1/_search

Filters will be loaded on the basis of roleName,

Admin role: For the Module level page, Date, DDR and ULB filter will be loaded

For Overview level page, Date, DDR, ULB and Service filter will be loaded

Commissioner role: For the Module level page, Date, ULB and Wards/Blocks filters will be loaded.

For the Overview page, Date, ULB and Service filters will be loaded.

3.Denomination filter:

Denomination filter having three option to display amount and number in a particular format.

1. Crore

2. Lack

3. Unit

Denomination filter will not be applied to the percentage and text (refer to figure 2.10). The type of data is identified by a symbol in the plots of charts API.

Figure 2.10

Custom Date Filter

If duration < 15 days, it will display data day-wise.

If duration <= 30 days, it will display data week-wise.

If duration >30, it will display data monthly-wise.

Tabs

Currently, the dashboard is having two types of tabs,

1. Revenue (refer figure: 4.1).

2. Service (refer figure: 4.1).

Tabs are identified by name in visualizations of config API.

Table Chart with drill-down

In table response, filter key & drillDownChartId is having value means its Drill down table.

Cards

1. Each card header is localized and having an info icon with a tooltip option that displays the header and can display a description.

2. The number of cards in a row and in a page is driven by the backend. Backend provides the row number to each card where it should be displayed.

3. Card containing option icon which contains Image download and Image share option.

4. Image download and share user id from vizArray in order to differentiate each card in a page.

Download and Share (refer to figure 2.9)

1.Download having two option to download data, i.e, Image and PDF

Share:

Share creates the Image/PDF and uploads it S3 using below API and returns file id,

https://mseva-uat.lgpunjab.gov.in/filestore/v1/files

Using file Id file will be fetched using below API

https://mseva-uat.lgpunjab.gov.in/filestore/v1/files/url

Each S3 image will be shortened using below API

https://mseva-uat.lgpunjab.gov.in/egov-url-shortening/shortener

5. Configurations

Github link for config: https://github.com/egovernments/frontend/blob/master/web/dss-dashboard/src/config/configs.js

BASE URL: End point of REST API for dashboard.

FILE Upload: End point of REST API for file upload.

FETCH FILE: End point of REST API for file fetch.

MDMS: End point of REST API for fetch MDMS Data.

SHORTEN URL: End point of REST API for Shorten URL, which is used for share via Email / What's app.

CHART COLOR CODE: Color code object for all charts.

MODULE LEVEL: for global filters, which contains services name & filter key.

SERVICES: for global filter, service filter.

6. Upload Localization keys:

code: pre-defined key for back-end.

message: message contains the value for the key.

module: rainmaker-dss

locale: contains locale data

for more details eGov team to be documented

Module name: rainmaker-dss

NPM Module Used

****https://docs.google.com/spreadsheets/d/1AdwSGxUZoSmVcSc3PtujGMRCKpNaAEYgAn_8XNTF2vM/edit?usp=sharing

Steps to setup DSS in Local

Step 1: Run as independent, switch to dss-dashboard folder

Step 2: We have to get the below details from the environment website and update the localstorage in the browser.

Employee.tenant-id Employee.user-info Employee.token Employee.module Employee.locale localization_en_IN locale

Step 3: Run Yarn install and yarn start to start working on dss in local setup.

DSS Features Enhancements V2:

DSS Features Enhancements V2 Technical Document for UI

This specifies the migration steps which is specific to payment index .

Step 1. Adding a target index

Add index name dss-payment_v2 as below:

In kibana, dev tools, apply the below command

Note: This name should be as the value present in ingest es.index.namemapping.json24 May 2021, 11:15 AM

Step 2. Optional changes required in Ingest application properties

Ingest pipeline application properties contain es.direct.push supposed to be set true for testing.

Step 3. Run migration Api, which migrate the data from the source index to target index.

Note: After migration ensure dss-payment_v2 data has been populated and available

In kibana, dev tools verify using below command

A decision support system (DSS) is a composite tool that collects, organizes and analyzes business data to facilitate quality decision-making for management, operations and planning. A well-designed DSS aids decision-makers in compiling a variety of data from many sources: raw data, documents, personal knowledge from employees, management, executives and business models. DSS analysis helps organizations to identify and solve problems, and make decisions.

The Tech documentation is below

The swagger API for the backend is below

https://github.com/egovernments/business-services/blob/master/Docs/dss-dashboard/DSS%20Analytics%20Dashboard%20YAML%20Spec%201.0.0.yaml

Swagger API for ingest

https://github.com/egovernments/business-services/blob/master/Docs/dss-dashboard/DSS%20Ingest%20YAML%20Spec%201.0.0.yaml

Target Upload File Template is below

__All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

According to the new collection service, which follows the payment structure for storing the information about payments and payment details, it is necessary to migrate the old collection structure into the payment structure.

In the old collection service, for every transaction, the receipt number is generated on the bill detail level, as the bill contains multiple bill details each transaction is mapped to multiple receipt number. So after payment of a single bill, multiple receipt numbers are generated for it. The mapping of the transactions to the receipt number is changed in the new collection service.

In the new collection service, the receipt number is generated on bill level, so for every transaction for each bill, one receipt number is generated. So each bill for a consumer code and business service have one receipt number.

The records from tables egcl_receiptheader, egcl_receiptdetails, egcl_instrument, egcl_instrumentheader need to be transferred into tables egcl_payment, egcl_paymentdetail, egcl_bill, egcl_billdetial, egcl_billaccountdetail.

For smooth transaction of data, the record from the old receipt has been mapped according to payment structure, so that the new payment response can be formed with receipt data.

The table below provides the mapping between receipt and payment structure with some remarks.

After the creation of payment response with receipt data, it has been pushed into kafka topic “egov.collection.migration-batch” and with the persister, payment data is inserted into tables egcl_payment, egcl_paymentdetail, egcl_bill, egcl_billdetial, egcl_billaccountdetail.

Indexer config for the legacy data index and new payments.

https://github.com/egovernments/configs/blob/master/egov-indexer/payment-indexer.yml

persister config -

https://raw.githubusercontent.com/egovernments/configs/master/egov-persister/collection-migration-persister.yml?token=AGAOX7TAAE6QPRZBXU3QZV266URNW

Please get these promoted before initiating the migration process. Migration happens through an API call, add role-actions based on your requirement. Otherwise, port-forwarding should work.

Find the API details below:

Endpoint: /collection-services/payments/_migrate?batchSize=100&offset= Body: { "RequestInfo": { "apiId": "Rainmaker", "action": "", "did": 1, "key": "", "msgId": "20170310130900|en_IN", "ts": 0, "ver": ".01", "authToken": "a6ad2a1b-821c-4688-a70e-4322f6c34e54" }

While restarting migration due to any failure, take the value of offset and tenantId printed in the logs and resume the migration process where it ended.

/collection-services/payments/_migrate?batchSize=100&offset=200&tenantId='pb.tenantId'

Collection-service build:- collection-services-db:9-COLLECTION_MIGRATION-e9701c4