1 of 100

Platform

Release Notes

New release features, enhancements, and fixes

Release Summary

DIGIT 2.8 release includes 1 new module, several new products, functional and security features, regression testing, bug fixes of previously released modules and a few non-functional changes.

New Module

Citizen engagement - Survey service

Functional Changes

OBPS Tabular Reports in old UI/UX, Trade Licence Tabular Reports in old UI/UX
Notification based on channels - PGR, OBPS & mCollect
Help/FAQ section in Citizen UI - common framework - integration with all the modules
Bill Genie UI/UX revamp
Survey module
Water & Sewerage UI/UX Revamp, Bill amendment workflow update & UI/UX revamp, W&S disconnection
Water & Sewerage Privacy Exemplar, Standard Reports for W&S - Receipt Register, Collection Register, Defaulters Report - in old UI/UX
Birth & Death Tabular Reports - in old UI/UX
Enhancement on DSS, Finance Module State DSS, NSS Adaptor, Enhancements in National Dashboard- FAQ & About page.

Non-functional Changes

Navigation re-direction from New UI to OLD UI
Bulk Bill PDF generation and performance testing
W&S Bulk Bill generation and performance testing

New ‌Feature Additions

Enhancements

Success Metrics

Adoption Metrics

Adoption of new features will be tracked on the basis of the following metrics:

‌Document Resources and Links

UI Technical Documents

Updated docs

Backend Service Documents

Test Cases

Water & Sewerage - Privacy Exemplar

Survey Test Cases

New UI to Old UI

Birth & Death Reports

Help FAQ Section in Citizen UI - Common Framework (Product-Specific Pages)

PGR Notifications

W&S UX/UI Revamp

Bill Amendment For W&S

W&S Reports

Bill Genie

TL Reports

Finance DSS

BPA

DSS Test Case For 3 KPIs

OBPS Reports

Product Release Notes

ULB Level Setup

ULB level setup involves the configuration of ULB specific data parameters such as ULB boundaries, ULB bank accounts, and hierarchy details.

Boundary Hierarchies
Boundary Data
Cross Hierarchy Mapping
ULB Bank Accounts

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

Boundary Data

Introduction

This is the next step after collating all the boundary hierarchies which are being used in the state. In a hierarchy, there are certain types of boundary classification and in all the levels there will be a mapping which we could define as a parent-child mapping in order to link certain levels of the classification.

For example, a hierarchy could be:

Administration Hierarchy: City/ULB → Zone → Ward → Locality

In the above-mentioned hierarchy, a City/ULB is being divided into different into zones followed by zones into wards and at the end wards into the locality.

Data Table

Data has to be collected for every boundary hierarchy type and boundary type with a mapping between the boundary code and its parent boundary code. Following is the table which is to be used across all the hierarchy types.

Sr. No.

Boundary Code*

Boundary Name* (In English)

Boundary Name* ( In Local Language)

Parent Boundary Code*

Boundary Type*

Hierarchy Type Code*

Data given in the table is a sample data.

Procedure

Data Definition

Following is the definition of the data columns which are being used in the template:

Sr. No.

Column Name

Data Type

Data Size

Is Mandatory?

Description

Steps to fill data

Following are the steps which should be used to fill the template:

Download the data template attached to this page.
Get a good understanding of all the headers in the template sheet, their data type, size, and definitions by referring to the ‘Data Definition’ section of this document.
In case of any doubt, please reach out to the person who has shared this template with you to discuss and clear your doubts.
After Identifying all the boundary hierarchy, get the sub-classification of all the hierarchies.
Figure out the codes for all the sub-classification for a particular city/ULB.
Start filling the template from the top of the hierarchy in a drill-down approach.
A parent-child mapping code has to be created for every boundary level except for the top level.
Follow the steps until you reach the last sub-classification.
Verify the data once again by going through the checklist and taking care of each and every point mentioned in the checklist.

Checklist

The checklist is a set of activities to be performed one the data is filled into a template to ensure data type, size, and format of data is as per the expectation. These activities have been divided into 2 groups as given below.

Common Checklist

This checklist covers all the activities which are common across the entities.

Entity Specific Checklist

This checklist covers the activities which are specific to the entity.

Attachments

Cross Hierarchy Mapping

Introduction

This is the 3rd step that comes after the boundary data collection. Cross hierarchy mapping happens in case a child has a relationship with more than 2 parents. This double relationship between the child and parents could happen between different hierarchies as well.

For example: In Admin level boundary hierarchy a mohalla M1(child) could be a part of 2 Wards(parent) W1 and W2. In such a case a single Mohalla(child) has to be mapped to 2 Wards(parent).

Data Table

Below is the data table for the Boundary:

Hierarchy Type

Hierarchy Type 1*

Hierarchy Type 2*

Procedure

Data Definition

Sr. No.

Column Name

Data Type

Data Size

Is Mandatory?

Definition/ Description

Steps to fill data

Download the data template attached to this page.
Get a good understanding of all the headers in the template sheet, their data type, size, and definitions by referring to the ‘Data Definition’ section of this document.
In case of any doubt, please reach out to the person who has shared this template with you to discuss and clear your doubts.
Firstly Identify all the child levels which have a relation with more than 2 parent boundary types and their hierarchy types as well.
Fill up the boundary hierarchy (names/ codes) types in place of boundary type 1/2.
Then along with the codes start filling in one by one with the proper mapping between every child and parent.
The Sr. No should be in an incremental order for every new child level.
Prepare a new table for every different parent-child relation.
Verify the data once again by going through the checklist and taking care of each and every point mentioned in the checklist.

Checklist

Common Checklist

This checklist covers all the activities which are common across the entities.

Entity Specific Checklist

This checklist covers the activities which are specific to the entity. There is no entity-specific checklist activity applicable here.

Attachments

ULB Bank Accounts

Introduction

It is a ULB bank account which is operative at least to receive or deposit the day to day revenue collection done by the ULB. It is used by online payment integrator to disburse the amount in ULBs accounts which have been collected through a payment gateway into a pool account managed by the payment gateway.

Data Table

Below given data table represents the excel template attached. Data given in the table is a sample data.

Sr. No.

Code*

ULB Name*

Bank Name*

Branch Name*

Account Number*

Account Type*

IFSC*

Data given in the table is sample data.

Procedure

Data Definition

Sr. No.

Column Name

Data Type

Data Size

Is Mandatory

Definition/ Description

Steps to fill data

Download the data template attached to this page.
Have it open and go through all the headers and understand the meaning of them by referring 'Data Definition' section.
Make sure all the headers, its data type, field size and its definition/ description is understood properly. In case of any doubt, please reach out to the person who has shared this document with you to discuss the same and clear out the doubts.
Identify the bank account which is to be used to transfer the amount which is collected online for various services.
Start filling the data starting from serial no. and complete a record at once. repeat this exercise until the entire data is filled into a template.
Verify the data once again by going through the checklist and taking care of each and every checklist point/ activity mentioned in the checklist.

Checklist

The checklist is a set of activities to be performed after the data is filled into a template to ensure data type, size, and format of data is as per the expectation. These activities have been divided into 2 groups as given below.

Common Checklist

This checklist covers all the activities which are common across the entities.

To see the common checklist refer to the page Checklist consisting of all the activities which are to be followed to ensure complete and quality data.

Entity Specific Checklist

This checklist covers the activities which are specific to the entity.

Attachments

Boundary Data

Introduction

For example, a hierarchy could be:

Administration Hierarchy: City/ULB → Zone → Ward → Locality

In the above-mentioned hierarchy, a City/ULB is being divided into different into zones followed by zones into wards and at the end wards into the locality.

Data Table

Sr. No.

Boundary Code*

Boundary Name* (In English)

Boundary Name* ( In Local Language)

Parent Boundary Code*

Boundary Type*

Hierarchy Type Code*

Data given in the table is a sample data.

Procedure

Data Definition

Following is the definition of the data columns which are being used in the template:

Sr. No.

Column Name

Data Type

Data Size

Is Mandatory?

Description

Steps to fill data

Following are the steps which should be used to fill the template:

Download the data template attached to this page.
Get a good understanding of all the headers in the template sheet, their data type, size, and definitions by referring to the ‘Data Definition’ section of this document.
In case of any doubt, please reach out to the person who has shared this template with you to discuss and clear your doubts.
After Identifying all the boundary hierarchy, get the sub-classification of all the hierarchies.
Figure out the codes for all the sub-classification for a particular city/ULB.
Start filling the template from the top of the hierarchy in a drill-down approach.
A parent-child mapping code has to be created for every boundary level except for the top level.
Follow the steps until you reach the last sub-classification.
Verify the data once again by going through the checklist and taking care of each and every point mentioned in the checklist.

Checklist

Common Checklist

This checklist covers all the activities which are common across the entities.

Sr. No.

Activity

Example

Entity Specific Checklist

This checklist covers the activities which are specific to the entity.

Sr. No.

Activity

Example

Attachments

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

Release Notes

New release features, enhancements, and fixes

Release Summary

DIGIT 2.8 release includes 1 new module, several new products, functional and security features, regression testing, bug fixes of previously released modules and a few non-functional changes.

New Module

Citizen engagement - Survey service

Functional Changes

OBPS Tabular Reports in old UI/UX, Trade Licence Tabular Reports in old UI/UX
Notification based on channels - PGR, OBPS & mCollect
Help/FAQ section in Citizen UI - common framework - integration with all the modules
Bill Genie UI/UX revamp
Survey module
Water & Sewerage UI/UX Revamp, Bill amendment workflow update & UI/UX revamp, W&S disconnection
Water & Sewerage Privacy Exemplar, Standard Reports for W&S - Receipt Register, Collection Register, Defaulters Report - in old UI/UX
Birth & Death Tabular Reports - in old UI/UX
Enhancement on DSS, Finance Module State DSS, NSS Adaptor, Enhancements in National Dashboard- FAQ & About page.

Non-functional Changes

Navigation re-direction from New UI to OLD UI
Bulk Bill PDF generation and performance testing
W&S Bulk Bill generation and performance testing

New ‌Feature Additions

Feature

Description

Enhancements

Updated Feature

Description

Success Metrics

Adoption Metrics

Adoption of new features will be tracked on the basis of the following metrics:

‌Document Resources and Links

UI Technical Documents

Updated docs

Backend Service Documents

Master Migration Document

2.8 release master migration document

Bill Amendment (Billing-service)

W&S Bill Amendment workflow config migration

Follow the steps mentioned in the .
Verify once if workflow name is hardcoded except edited parts of UI, Backend - check in indices and report - checked not present except config
Verify if wf config is there for tenant level or state level only
An update has to be added as a patch to the first release of the amendment

Water & Sewerage

Latest persister file -
Latest persister file -

Note : Replace the existing persister files with the latest files linked above.

Water modify connection
Sewerage modify connection
Sewerage Disconnection
Water Disconnection

Privacy Feature

By default encryption & privacy is disabled for 2.8

To disable privacy for Property and W&S make changes in the MDMS- DataSecurity -> SecurityPolicy.json file.
For models- Property,PropertyDecrypDisabled, WnSConnection, WnSConnectionOwner, WnSConnectionDecrypDisabled, WnSConnectionOwnerDecrypDisabled, WnSConnectionPlumber, WnSConnectionPlumberDecrypDisabled; insert only one attribute in the attributeList as follows:

Insert the name and jsonPath which are not actually expected to be present in the RequestBody/ResponseBody
Files to be updated
References for reading
Once the above changes are done deploy the following builds:
1. Ws-services
2. Property-services
3. Sw-services
4. Inbox
5. Restart egov-user service
Impact of privacy framework
2. The masking/unmasking of data is entirely dependent on the roles of the users in the system, adding or removing these roles from the config will enable masking for each role.
3. There is no module-level control here, so if a W&S role is added to an employee of TL then data will be masked so cross-using of roles should be avoided.
4. The agreement with Manish is that the privacy be disabled until redesign with the module filter - Done
5. The policy should be defined for adding or removing fields from the encryption process.
W&S privacy (Skip over if encryption is not carried out)
1. Deploy the latest builds provided for the 2.8 release {builds}
3. Restart the MDMS service followed by the encryption service
4. - This file will fetch data from the Encryption of old data and upload it to the existing index so that the index will be encrypted or masked as per config.
6. Validating the encryption of old data {Doc Link}
7. Disable & enable decryption.privacy
  - water.decryption.abac.enabled=true
  - sewerage.decryption.abac.enabled=true
PT privacy (Skip over if encryption is not carried out)
1. Deploy the latest builds provided for the 2.8 release
3. Restart the MDMS service followed by the encryption service
7. Validating the encryption of old data {Doc Link}
8. Disable & enable decryptionprivacy
  - property-decryption-abac-enabled: "true"
Bill genie
1. No changes required
Bulk Bill PDF Generation and Performance Testing
1. Enhancement is part of the new build release.
W&S Bulk Bill Generation and Performance Testing
1. PR List
privacy integration - PT
1. Covered as part of privacy above
Notification based on channels - PGR
1. Localisation added as part of the release KIT
Notification based on channels - mCollect
1. Localisation added as part of the release KIT
OBPS/ BPA (Notifications only)
1. Localisation added as part of the release KIT
National Dashboard Adaptor Integration Testing
NationalDashBoard 3 New KPI
2. MasterDashboardConfig.json
Finance Module State DSS
MDMS & Configs -

BackWard Compatibility Results -

UI Changes

Please add all MDMS changes before deploying the UI code.

W&S: W&S UI/UX Revamp
W&S disconnection
- No changes needed, it will work automatically if we deploy.
Bill amendment W&S UI/UX RevampI
- No changes needed, it will work automatically if we deploy.
Bill Genie UI/UX revamp
- No changes needed, it will work automatically if we deploy.
OBPS Tabular Reports in old
- No changes needed, it will work automatically if we deploy. It is based on the configuration of the backend.
TL Tabular Reports
- No changes are needed, it will work automatically if we deploy. It is based on the configuration of the backend.
Standard Reports for WnS
- No changes are needed, it will work automatically if we deploy. It is based on the configuration of the backend.
Core UI Changes (Banner Images of Each module)

Old UI

Only Fire Noc and Tabular reports are PO signed off in the current release for the OLD UI, the rest of the modules are covered as part of backward compatibility tests shared above.

Platform Features

DIGIT is an open-source platform licensed under the MIT license (https://opensource.org/licenses/MIT) compliant with the NUIS digital blueprint.

Detailed mapping of DIGIT’s capabilities with the core requirements mentioned in the NUIS digital blueprint has been done below:

Key Principles

Description

Interoperability

Data specifications/models are available for domain entities. DIGIT is designed as an API-first platform wherein data specs/models are created for all key entities thus ensuring interoperability through open APIs and open standards. Taxonomies are available for the key domain entities/registries. These can later be harmonised with standard taxonomies in the domain as and when they are made available.

DIGIT data models and APIs are published as Open APIs freely available to everyone in the ecosystem. In Punjab, the DIGIT module was easily integrated with 3rd party payment apps like Paytm, Airtel Money, BBPS, etc to increase citizen access and improve collections. At present, DIGIT provides at least 3 key distinct APIs for all domain entities - create, update and search.

Deactivation/Cancellation of key entities in DIGIT is achieved by updating their status to inactive as per their defined specification/API contracts. Given the API-first and micro-services-driven nature of DIGIT, current APIs and models can be quickly harmonised with national standards as and when they are made available. DIGIT strives to leverage established domain standards (national/international) wherever available.

Data Privacy And Security By Design

Data Privacy

Data privacy capabilities are available to mark and protect sensitive data. The core service layer of DIGIT includes signing and encryption service as one of the core services that provide capabilities to sign/encrypt/mask sensitive data. It is designed such that it can work against software key stores and can be extended to integrate with any kind of hardware key store to store and protect signing and encryption keys.

Encryption requirements can be defined and adhered to for the storage of sensitive data. DIGIT requires the User PII data to be stored in its User service which is by default enabled for encryption of sensitive data as User Data Vault. All other services in DIGIT are required to access PII data by explicitly calling the User service - which in turn audits all access to PII. In addition, individual services in DIGIT can leverage DIGIT’s signing and encryption service (which is what User Service leverages to create User Data Vault) to further protect additional sensitive data available with the services.

DIGIT provides the capability to define workflows for data modification that can be configured to have approval steps to get needed consent for any data modification activities. DIGIT currently provides RBAC (Role-Based Access Control) based access control for access (search) to data.

Security

Appropriate access controls can be defined in the APIs to ensure authorised access to sensitive data. DIGIT is designed to handle authentication and authorisation as perimeter control at its API gateway layer to ensure unauthorised calls are not allowed to even contact the respective micro-services. DIGIT provides an RBAC (Role-Based Access Control) mechanism where users are explicitly provided access to relevant resources by assigning them appropriate roles. By default, DIGIT supports OAUTH-based authentication for individual users and APIs. However, the Authentication and Authorization filter on DIGIT is designed to be easily extendable to support any further Auth and Auth needs.

The perimeter security mechanism in DIGIT also helps developers in focusing on the functional developments in further services and offload the access control requirements for new resources and their APIs to the API gateway using simple configurations.

DIGIT also ensures that risks like the following are taken care of:

Privilege escalation – form field manipulation
Failure to restrict URL access
Insecure direct object references (IDOR)
Malicious file upload leads to cross-site scripting
Improper authentication
Missing account lockout
Request throttling attack
Weak encoding mechanism
Sensitive information in URL
Lack of automatic session expiration
Insecure banner implementation
Concurrent session
Clickjacking
Improper error handling

Transparency And Accountability Through Data

DIGIT has the capability to define key registries in OpenAPI 3.0 specs formats and easily achieve key APIs like create/update/search using its building blocks in core services mainly through configurations and using lightweight extensions on a needs basis.

DIGIT has the capability to protect person-specific sensitive data by encrypting them in the user data vault (User Registry) which allows configuration-based protection of sensitive PII. DIGIT requires additional registries to reference PII using this mechanism. In addition, registries in DIGIT can leverage its data protection (Signing and Encryption) core service to provide additional protection to registry-specific attributes.

Registry data in DIGIT can be signed for tamper-proofing using its signing and encryption core service. A proof of concept for this has already been done on the ePass module that was built on the DIGT platform. All key data modifications in DIGIT are access logged to provide an audit trail, which can be accessed through APIs. The upcoming version of DIGIT is planning to bring in the concept of immutable event logs to further strengthen this capability. DIGIT leverages open-source telemetry to provide the ability to gather telemetry data and extend it for the DIGIT-specific processing pipeline. This framework allows for additional event definitions and contextual extension of the telemetry processing pipeline thereby future-proofing this capability in DIGIT.

Reusability and Extensibility

DIGIT platform is designed as a collection of more than 50+ atomic microservices which are bundled together in a given context to provide end solutions. Microservices in DIGIT can be mainly categorized in three categories: Data services (Registries, reference Master data management, etc.), Tech infrastructure services (Authentication, authorisation, notification engine etc.) and domain services (Assessment, NOC etc.). Citizen, employee and administrative interfaces in DIGIT use these microservices to achieve the needed functionality.

Data models and APIs in DIGIT are defined as OpenAPI 3.0 specifications and can be extended by using a combination of configuration and extension techniques. E.g. if the additional attributes are only needed to be stored with format validation, it can be a simple schema extension, while if the additional business checks/functionality need to be implemented using the extended attributes then it can be achieved using pre/post request filters or extending underlying microservices.

DIGIT allows the extension of existing capabilities without needing architectural interventions. As described above extension of existing functionality on DIGIT can be achieved using additional configurations, additional extension services or request/response filters.

Several partners have extended DIGIT modules to cater to new use cases. For instance, DIGIT mCollect module caters to the collection of fees for more than 50 services on the counter, but it did not have a citizen interface for payment of these services online. Directorate General Defence Estates (DGDE) wanted to introduce this interface for the citizens of cantonment boards in India and were able to easily enhance the mCollect module to include this capability. Similarly, Punjab has reused several DIGIT core services to develop new modules on the platform with minimum effort.

DIGIT supports single-instance multi-tenancy to enable sharing of the underlying infrastructure, also all DIGIT data models and services are designed to be multi-tenanted.

DIGIT uses API first approach in its design and development to ensure loose coupling between its various components. These APIs are clearly defined using OpenAPI 3.0 specifications to ensure clear documentation.

Evolvability and Scale

As described above, the extension of existing functionality on DIGIT can be achieved using additional configurations, additional extension services or request/response filters. Similarly, new functionality can be added by re-bundling existing building blocks in the context of new use cases and implementing only additionally required services without requiring any architectural overhaul. Additionally due to its loosely coupled API-driven design DIGIT allows for new components to be implemented in the technology that is most useful for that use case.

API-driven, the microservices-based architecture of DIGIT enables its components to evolve separately. On DIGIT Individual components can evolve separately to enable the heterogeneous evolution of the system.

DIGIT uses SemVer 2.0 for versioning its microservices and interfaces. Semantic versioning is a formal convention for specifying compatibility using a three-part version number: major version; minor version; and patch. More details on this can be found at this link: https://semver.org/.

DIGIT is designed to be horizontally scalable. The microservices-based architecture of DIGIT also enables it to scale only needed components/services, thereby providing resource efficiency. E.g. Billing and Collection services can be scaled separately during financial year closing if the load pattern indicates an increasing volume of bill payments during that period.

DIGIT is designed to be hardware agnostic and can be run on any hardware. It has been tested on multiple commercial clouds and state-sponsored bare metal infrastructure. Components of DIGIT that need to use underlying hardware have been carefully chosen (in cases where DIGIT is using other open-source components) or designed (DIGIT’s own components) to provide a layer of abstraction that can be extended for any type of hardware.

Multi-channel Access

DIGIT is designed using API first approach, therefore enabling any user interface channel to leverage it. DIGIT’s own user interfaces (Web/mobile app, WhatsApp chatbot) are implemented using its APIs to ensure offered platform capabilities and data are accessible to any delivery channel based on configured policies. In states like Punjab and AP where DIGIT modules are being used, the citizens have been given multi-channel access - ULB counters, Web portals, Mobile App, WhatsApp Chatbot and 3rd party applications like Paytm, BBPS to avail local government services.

DIGIT’s access control mechanism can be configured to provide different levels of access based on channels and roles.

Ecosystem-driven

DIGIT platform and its user interfaces are completely open source. Also, all external components used in DIGIT are also Open Source. Due to its API-based and event-driven architecture DIGIT can be integrated with any existing stack. Wherever appropriate, DIGIT also provides out-of-the-box integrations with crucial stacks/platforms. The most common integrations are to payment gateways, SMS providers and SMTP email servers for a typical implementation.

More than 14 organizations have already partnered with us to implement DIGIT across multiple implementations in the country and have built more than 20 new solutions on top of the platform.

DIGIT also provides the capability to gather feedback from the ecosystem in a digital manner. Feedback capability in DIGIT can be looked at the following levels:

Service Delivery feedback on services offered through DIGIT - DIGIT provides a highly configurable and extensible Public Grievance module to enable this kind of feedback/redressal for functional users (Citizens, employees etc)
Service Usage feedback - DIGIT user interfaces include a telemetry SDK which is backed by telemetry infrastructure on the DIGIT platform. Coupled with API access logs, this enables DIGIT to gather user feedback through live action and can be used for fine-tuning interfaces and APIs
Design/Feature feedback - As an open-source project on GitHub, DIGIT provides a mechanism to provide comments/feedback on its various components using GitHub. This feedback can be leveraged to create a Point of View on the future roadmap for the platform.

Bill Amendment Service Configuration

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 the DIGIT framework.

Key Functionalities

Amendment mainly works with two types of functionality as follows:

Amendment
Demand

Bill Amendment provides a separate flow that triggers the workflow for validating the process of adding additional amounts to existing demands. This validation was earlier available only to the respective modules. An amendment is allowed only when there is a need to add or reduce the amount from the existing bill belonging to an entity. The reasons for such cases could be:

Court case settlement
One time waiver
Write-offs
DCB correction (old demands in paid status)
Property tax remission

Criteria:

Below are certain prerequisites to creating an amendment,

presence of demand in the billing system
any one of the reasons listed above
valid document proof for the reason
there is no other amendment already in the workflow

Procedure:

The process of adding an amendment in specific scenarios is given below.

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

1. when demand is unpaid/partially paid

Create a demand (Or an existing demand can be used) with demand detail → DD1.
Do not pay the bill or make a partial payment.
Create an amendment for the same consumer code (with demand detail → DD2).
Approve the amendment - the response should return an amendment with the status CONSUMED.
Search the demand or fetch the bill for the consumer code. The demand/bill should contain demand details of the demand and amendment together with DD1 and DD2 in the same demand/bill.

2. when demand is completely paid

Create demand and make complete payment or choose a consumer code which is fully paid.
Create amendment (with demand detail → DD1).
Approve amendment - the response should be APPROVED.
Create new demand for the consumer code (with demand detail → DD3). The demand response should contain two demand details DD1 and DD2 saved to the demand.
The amendment search returns 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

WORKFLOW CONFIG:

Integration Details

Integration Scope

Amendment integration helps organizations 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.

The amendment facility can be used in case of a legal issue to add values to existing demands using /amendment/_create. The parameter /amendment/_update is used to cancel the created updates or update configured workflows.

Doc Links

API Definition

API List

Collection Service V2

Overview

The Collection service is to serve as a revenue collection platform for all the billing systems through cash, cheque, demand draft, and swipe machines. 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.
The 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 payments 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 builds.

Configuration Details

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

Following are the properties in the application.properties

Integration Details

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 requirements.

Steps to Integration

Customers can create a payment using the /payments/_create.
Actors on the system can keep track of payments using /payments/_searchendpoint.
Once the payment is done but it encounters a technical issue outside of the system then it can be cancelled with /payments/_workflow.
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 the property module.

IFSC Code Migration - Collection Service

Port forward the collection service to the current environment where the IFSC CODE bank details data is to be migrated. Sample command - 1kubectl port-forward collection-services-76b775f976-xcbt2 8055:8080 -n egov
Import postman collection from API list which refers as /preexistpayments/_update and runs with the same localhost to where we port forwarded using the above command.
Expected result. In the EGCL_PAYMET table where IFSCODE data is present for those records, EGCL_PAYMET.ADDITIONALDETAILS bankdetails will be updated.

Interaction Diagram

Reference Docs

Doc Links

API List

Billing Service

Overview

The main objective of the billing module is to generate the bill for all revenue-based business services. To serve the bill, the Billing-Service requires demand. Demands will be prepared by the revenue modules and stored by billing based on which it generates 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 demand-based systems.
The following services should be up and running:
- user
- MDMS
- Id-Gen
- URL-Shortening
- notification-sms

Key Functionalities

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

Customers can create a demand using the /demand/_create
Organizations or Systems can search the demand using /demand/_searchendpoint
Once the demand is raised the system can call /demand/_update endpoint to update the demand as per need.
Bills can be generated using, which is a self-managing API that generates a new bill only when the old one expires /bill/_fetchbill.
Bills can be searched using /bill/_search.
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 heads 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 holds that if the full amount is paid for any bill then each individual tax head should get nullified with their corresponding adjusted amount.

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

Example: given below

Case 2: Apportioning with two years of arrear: Example: The apportioning details for the financial year 2014-15 are given below.

The table below illustrates the demand structure generated in case there are no payments for the specified financial year (2015-16).

DSS Features Enhancements

V2 Technical Document for UI

Overview

This release for DSS focuses on improving user experience and the 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 the drill-down 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:

Comparison with the previous year's data in every table data uses the same request object 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's data.

getLastYearRequest(calledFrom, visualcode, active, filterList)

After receiving last year's data it is compared with the current year's data. The comparison is shown as insight data. The 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 a new library react-date range is 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 is 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

DSS Dashboard - Technical Document for UI

Overview

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 identify and solve problems, and make decisions.

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

Type Of Users

State-Level Admin
Commissioner
Domain-Level Employee

Dashboard List

There are three types of dashboards -

Home page (refer figure 1)
Overview page (refer figure 2)
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, the overview card and the module-level card.

The overview and the module level cards are differentiated by vizType,

Overview card: Clicking on the overview card navigates to the overview page. vizType for overview is a collection.
Module Level card: Clicking on the module level card navigates to the module level dashboard. vizType is a module (i.e Property Tax, Trade License etc).

Request Payload for dashboardConfig

auth-token: authenticate the request and it fetches from a local storage key called “Employee.token”

DashboardConfig API Response

roleName: the type of user.

Visualisations: The key contains all configurations for displaying the visualisation 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 figure 1

2. Overview Dashboard

3. Module Level Dashboard

Visualisation List

In dashboardConfig response, the visualisation key contains all rows & charts details (refer figure 1.3). Each row contains the visual details like name, vizType, noUnit, isCollapsible, charts etc (refer figure 1.3).

name - name of visualisation
vizType - type of visualisation like COLLECTION, MODULE, METRIC-COLLECTION, PERFORMING-METRIC, CHART
- COLLECTION - The home page, contains the collection data (refer figure 1).
- MODULE - The home page, contains the module-level data (refer figure 1).
- METRIC-COLLECTION - In Overview/Module Level Page, contains the collection data (refer figure 2.1).
- PERFORMING-METRIC -In Overview/Module Level Page, contains the top/bottom performing data (refer figure 2.2).
- CHART - In Overview/Module Level Page, contains the below visualisations (refer figure 2.3 to figure 2.7).
  - PIE CHART (refer figure 2.3)
  - LINE CHART (refer figure 2.4)
  - BAR CHART (refer figure 2.5)
  - HORIZONTAL BAR CHART (refer figure 2.6)
  - TABLE CHART (refer figure 2.7)

Visualisations

ULB Dashboard

ULB dashboard contain different filters, i.e ULBs and Wards/Blocks. The data to the filters are loaded from MDMS API below - https://dev.digit.org/egov-mdms-service/v1/_search

Each ULB dashboard, overview dashboard and module-level pages contain different filters and are identified by roleName in configs API.
The Wards/Blocks filter is a dependable filter, which gets loaded on ULB selection.
In the ULB dashboard, the on-page ULB filter is applied across all the charts and for the performance chart, the default ULB filter is not applied.
Overview and all module level pages has a ULB dashboard.

GLOBAL Filters (refer to figure 2.8)

Filters are loaded from the MDMS API - https://dev.digit.org/egov-mdms-service/v1/_search. Filters are loaded on the basis of roleName.

Admin role: On the Module level page, Date, DDR and ULB filter are loaded.

On the Overview level page, Date, DDR, ULB and Service filter are loaded.

Commissioner role: On the Module level page, Date, ULB and Wards/Blocks filters are loaded.

On the Overview page, Date, ULB and Service filters are loaded.

Denomination filter: The Denomination filter has three options to display the amount and number in a particular format.

Crore
Lack
Unit

The denomination filter is not 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.

Custom Date Filter

If duration < 15 days, it displays data day-wise

If duration <= 30 days, it displays data week-wise

If duration >30, it displays data month-wise

Tabs

Currently, the dashboard contains two types of tabs -

Revenue (refer figure: 4.1)
Service (refer figure: 4.1)

Tabs are identified by name in visualisations of config API.

Table Chart with drill-down

Table chart visualisations have normal material UI data table features like search, sort etc.

In table response, if filter key & drillDownChartId contain any value users can drill-down the table.

Cards

Each card header is localised and has an info icon with a tooltip option that displays the header and can display a description.
The number of cards in a row and in a page is driven by the backend. The backend provides the row number to each card where it should be displayed.
Card contains option icon that enables users to either download images and or share images.
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)

Download offers two options - to download data as an image or a 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

The file Id is fetched using the API - https://mseva-uat.lgpunjab.gov.in/filestore/v1/files/url

Each S3 image is shortened using the API - https://mseva-uat.lgpunjab.gov.in/egov-url-shortening/shortener

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.

Upload Localisation 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://github.com/egovernments/DIGIT-OSS/blob/master/frontend/mono-ui/web/dss-dashboard/package.json

Steps to setup DSS in Local

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

Step 2: 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

Dashboard Analytics - Backend

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 is the way it is fetched, aggregated, computed, transformed and sent across. DSS must be configurable since the entire process involves playing around with a variety of data sets. This ensures easy configuration of data sets in new scenarios.

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

Commonly Used Terms

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.

Configuration Details

Discussed below are the ingest pipeline configuration details -

Topic Context Configurations
Validator Schema
JOLT Transformation Schema
Enrichment Domain Configuration
JOLT Domain Transformation Schema

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 receives the data and passes it through the pipeline, the context and the version of the data received have to be set. This configuration is used to identify which Kafka topic consumed the data and the mapping details.

Click here for the full configuration

Validator Schema

Validator schema is a configuration schema library from Everit. By passing the data against this schema, it ensures whether the data abides by the rules and requirements of the schema that has been defined.

Click here for an example configuration

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 transformed data.

Follow the slide deck for JOLT Transformations

Click here for an example configuration

Enrichment Domain Configuration

This configuration defines and directs the enrichment process that 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 specified business type 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

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

Use case:- JOLT Transformation Schema for collection V2

JOLT transformation schema for payment-v1 has been 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 bill details.

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

Chart API Configuration
Master Dashboard Configuration
Role Dashboard Mappings Configuration

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

Master Dashboard Configuration

Master dashboard configuration defines the dashboards that are to be painted on the screen.

It includes all the visualizations, their groups, the charts and even their dimensions in terms of height and width.

Click here for an example configuration

Role Dashboard Mappings Configuration

Role dashboard mapping ensures that each role is mapped against the dashboards that they are authorized to see.

Click here for an example configuration

Adding Configurations

Adding Roles and Dashboards

To add a new role, modify the RoleDashboardMappingsConf.json (roles node) configuration file as given below.

Note: Any number of roles & dashboards can be added

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

To add a new dashboard, modify the MasterDashboardConfig.json (dashboards node) as shown below in Figure 10.

Note: dashboards array add a new dashboard as given below

Adding Visualizations

To add new visualisations, modify the MasterDashboardConfig.json (vizArray node) as shown in Figure 11.

Note: vizArray is used to hold multiple visualizations.

Adding Charts

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 is of 2 types - table and xtable.table (as shown in Figure 15.) Type allows the addition of aggregated fields as available in the query keys. To extract the values based on the key, aggegationPaths have to be added along with their data type as in pathDataTypeMapping.

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

To add multiple computed columns, define the following params within computedFields []

actionName - (IComputedField<T> interface),
fields - [] names as existing in the query key,
newField - name to appear for the computation

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 DrillThroughs:

Example - drill through in ward table in the property tax dashboard.

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

Example - Drill through in the ComplaintList table in the PGR Dashboard.

complaintDrillDown is the visualization code for PGR Drill Down.

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

TL Service Configuration

Overview

This service is used to issue a license to the user after verification. The service is designed in such a way that it can be used to serve different type of licenses. Currently used to issue trade licenses, perform stakeholder registration and issue lockdown pass. The service is integrated with workflow where we can define the steps for approval of the application. Once the application is approved the license is generated.

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 tl-services persister config path added in it
PSQL server is running and database is created

Key Functionalities

Used for license generations in trade licenses, stakeholder registration and issue lockdown pass
Define roles to applicants on successful application to access Building Plan Approval services at the time of stakeholder registration
Generate application number and license number
Support workflows
Provide notification on various status changes for an application

Interaction Diagram

Deployment Details

Add MDMS configs required for Trade License and BPA stakeholder registration and restart MDMS service
Deploy the latest version of tl-services service
Add tl-service persister yaml path in persister configuration and restart persister service
Add Role-Action mapping for API’s
Create businessService (workflow configuration) according to trade license and stakeholder registration
Add tl-service indexer yaml path in indexer service configuration and restart indexer service

Configuration Details

Following application properties in the Trade License service are configurable.

Integration

Integration Scope

The trade-license service is currently used to issue trade licenses, perform stakeholder registration and issue lockdown pass.

Integration Benefits

Provide backend support for the different license registration process.
Mseva and SMS notifications on application status changes.
The elastic search index for creating visualizations and Dashboards.
Bpa Stakeholder registration provides new roles to the user to access the Building Plan Approval system.
Supports workflow which is configurable

Steps to Integration

To integrate, host of tl-services service should be overwritten in the helm chart.
{servicename}/_create/ _create should be added as the create endpoint for creating any license in the system
{servicename}/_search/ _search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria
{servicename}/_update/ _update should be added as the update endpoint. This method is used to update fields in existing records or to update the status of the application based on workflow.

Reference Docs

Doc Links

API List

In all below endpoints if the service name is BPAREG it is treated as a stakeholder registration application and if it is TL or if it is absent then the application is treated as trade license application.

Billing Collection Integration

Overview

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 provides the details of how system integrators enable bill collection facilities to customers using DIGIT as the 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.

Integration Approach

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

Authenticate with DIGIT
Get citizen bill using a service-specific query
Record the payment details against the bill
Optional - Get payment API to fetch the receipt details

The in-field team of the system integrator makes the calls to the integrator's own system (or a standard system like BBPS). Integration with DIGIT follows a server-to-server approach where the backend system of the integrator makes these calls to the DIGIT platform as per requirement. The diagram below depicts the high-level flow of calls between on-field devices like PoS to the integrator backend (Integrator System) and from the backend of the DIGIT integrator to DIGIT (DIGIT Platform).

Note: The process of calling payment API results in a receipt creation.

Integration Details

DIGIT uses Swagger 2.0 as its API standard and all its APIs are documented in Swagger. Wherever needed this document provides a link to our API documentation online. An example of typical request/response snippets necessary for integration is provided below in the respective sections.

DIGIT is a multi-tenanted system - hence all APIs in DIGIT except tenantid are 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 represents 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 identify the one to use). 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).

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 required to access the APIs.

Note: Apart from the userid/password, the system may enforce IP-based access control in which case the integrator may be required to share the IP or range of IPs from which the request will originate.

Use the API below to generate the access token based on the credentials provided. Given below is an example of the request and response. The OAuth token to be used from the response is highlighted in bold.

Request Snippet

curl -X POST \
    https://egov-micro-dev.egovernments.org/user/oauth/token \
    -H 'Authorization: Basic {Authorization Token}' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Postman-Token: 81c87b4c-f69d-464a-8c9a-990e698391ec' \
    -H 'cache-control: no-cache' \
    -d 'grant_type=password&scope=read&username={username}&password={Password}&tenantId={TenantId}&userType=Employee'

Response Snippet

{
"access_token": "6cf92021-8433-4da3-9a1e-8bc511983b2f",
"token_type": "bearer",
"refresh_token": "1f3097f3-39ab-4fd1-91a9-2ce48ac5b6bc",
"expires_in": 604799,
"scope": "read"
}

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).

Note: Different services may have different notions of consumer number, e.g. for Water Charges consumer number signifies the "Connection number" while for Property it is the "Property Id".

For some services, DIGIT also provides the facility to fetch bills by mobile number.

Note: 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 the partial payment use case each bill in the response of the fetch bill API indicates whether it allows partial payment and if yes, the minimum amount to be paid.

To fetch a bill from DIGIT, make sure that the OAuth token is generated as per the Authentication section above. Post that use the following API to fetch the bill -

https://www.getpostman.com/collections/900d99a85d083fb2d377
https://raw.githubusercontent.com/egovernments/business-services/master/Docs/billingservice/V-2.0.yml
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. The 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.

Note: 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, returns the original bill

DIGIT expects a receipt (result of calling payment API) to be created against the bill number returned in the fetch bill API.

Note: 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, make sure that the OAuth token is generated as per the Authentication section above. Post that use the following API to create the receipt -

https://www.getpostman.com/collections/824d6b50b728bccd86d4
https://raw.githubusercontent.com/egovernments/business-services/master/Docs/collection-services/V-2-0.yml
Choose Collection Service from the dropdown.
Go to Payment.
Go to Make Payment.

Turn-Io-Adapter

Transform API

Objective: Reap Benefit system is one of the vendors that provide the chatbot services using the as backend services to communicate with citizen through chatbot. As part of the requirement, we need to create a complaint in digit platform when ever citizens raise the complaint through Reap Benefit chatbot.

Overview

The turn-io-adapter service is a wrapper to transform Reap Benefit request format to DIGIT PGR request format. This service has transform API that constructs the required PGR request from the request message sent from the Reap Benefit system. Reap Benefit system consumes the tranform API to communicate with the DIGIT PGR module.

In this process, once a complaint is created it sends a WhatsApp message to the citizen with a track link. Whenever some action is taken by ULB employees on complaint, a WhatsApp message is sent to citizen.

Pre-requisites

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

Java 8
Rainmaker-PGR service is running

Key Functionalities

Complaints are generated on the DIGIT platform using the Reap Benefit system chatbot.
Messages are sent to citizen through WhatsApp when employees perform some action on the complaint.

Deployment Details

Deploy the following builds

rainmaker-pgr-db:v1.1.3-bb2961cf-13
turn-io-adapter:v1.1.3-bb2961cf-19
egov-searcher:v1.1.3-d43c421c-5
nlp-engine:v1.0.0-c3889d14-10

Frontend commits

Infra Configuration Details

2) Add /turn-io-adapter/_transform in egov-mixed-mode-endpoints-whitelist configuration

3) Once you are done with 2nd step restart zuul pod

MDMS Data

Add name filed in complaint category master in PGR. Link for the data -

Localisation Data

Push the localisation data for all the locality data with module as rainmaker-chatbot. Sample localisation object -

{ "code": "SC1", "message": "Azad Nagar - WARD_1", "module": "rainmaker-chatbot", "locale": "en_IN" }

Business Service / Workflow Configuration

Actions & Role Action Mapping

Actions

Role Mapping

RoleAction Mapping

Data Setup

This is the samplerequest for _transform api to create a complaint

Integration Details

Integration Scope

Turn-io-adapter is integrated with Rainmaker-pgr application. Turn-io-adapter application internally invokes the rainmaker-pgr service to generate complaints.

Steps to Integration

Turn-Io-adapter application to call turn-io-adapter/_transform to generate the complaint and takes the data from the PGR.

curl --location --request POST 'https://dev.digit.org/turn-io-adapter/_transform' \
--header 'Content-Type: application/json' \
--data-raw '{
    "contacts": [
        {
            "profile": {
                "name": "Rohit"
            },
            "wa_id": "9199999999992"
        }
    ],
    "messages": [
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "917391904467",
                        "name": "The_Subtle_Guy",
                        "type": "OWNER"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "inbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:33.809218Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "917391904467",
            "id": "ABEGkXORkERnAhBOXKjR8Jyyk-Iar8Gd2yeo",
            "text": {
                "body": "4"
            },
            "timestamp": "1621452093",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "fc89d3d7-bcab-4734-a82f-bf06fa99a980",
                        "name": "Complaint Selection",
                        "type": "THREAD"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "outbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:35.313898Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "15550152059",
            "id": "gBEGkXORkERnAglCxuTiC7G_ERg",
            "preview_url": false,
            "recipient_type": "individual",
            "text": {
                "body": "Please provide landmark or additional details of your locality.\\nOtherwise type and send *No*"
            },
            "timestamp": "1621452095",
            "to": "917391904467",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "917391904467",
                        "name": "The_Subtle_Guy",
                        "type": "OWNER"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "inbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:40.701184Z",
                    "labels": [
                        {
                            "confidence": 0.3339659565,
                            "metadata": {
                                "nlu": {
                                    "confidence": 0.3339659565,
                                    "intent": "await_reply",
                                    "model_name": "nlu-general-spacy-ngrams-20191014"
                                }
                            },
                            "uuid": "df376fa2-9358-4088-a6d0-8f3db031158b",
                            "value": "Unclassified"
                        }
                    ],
                    "rendered_content": null
                }
            },
            "from": "917391904467",
            "id": "ABEGkXORkERnAhBgzXDW_hlyiVg_IS6NxTMH",
            "text": {
                "body": "No"
            },
            "timestamp": "1621452100",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "fc89d3d7-bcab-4734-a82f-bf06fa99a980",
                        "name": "Complaint Selection",
                        "type": "THREAD"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "outbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:41.297301Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "15550152059",
            "id": "gBEGkXORkERnAgnMDgDG2-YCOv0",
            "preview_url": false,
            "recipient_type": "individual",
            "text": {
                "body": "Please enter the category of your issue from the options given below.\\n\\n1. Garbage\\n2. Street Lights\\n3. Water and Sewerage\\n4. Roads And Footpaths\\n5. Public Toilets\\n6. Land Violations\\n7. Animals and Insect"
            },
            "timestamp": "1621452101",
            "to": "917391904467",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "917391904467",
                        "name": "The_Subtle_Guy",
                        "type": "OWNER"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "inbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:44.672489Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "917391904467",
            "id": "ABEGkXORkERnAhARhnoBHV4O_DOlR9CNENoq",
            "text": {
                "body": "1"
            },
            "timestamp": "1621452104",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "fc89d3d7-bcab-4734-a82f-bf06fa99a980",
                        "name": "Complaint Selection",
                        "type": "THREAD"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "outbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:46.759132Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "15550152059",
            "id": "gBEGkXORkERnAgnskmr3neFP1ec",
            "preview_url": false,
            "recipient_type": "individual",
            "text": {
                "body": "Pick a issue from the options given below which describes closest to what you are facing.\\n\\n1. Garbage Needs To be Cleared\\n2. Damaged Garbage Bin\\n3. Burning Of Garbage"
            },
            "timestamp": "1621452106",
            "to": "917391904467",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "917391904467",
                        "name": "The_Subtle_Guy",
                        "type": "OWNER"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "inbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:51.967923Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "917391904467",
            "id": "ABEGkXORkERnAhBhofKX9wPf4-6xzUNnNJ5x",
            "text": {
                "body": "2"
            },
            "timestamp": "1621452111",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "fc89d3d7-bcab-4734-a82f-bf06fa99a980",
                        "name": "Complaint Selection",
                        "type": "THREAD"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "outbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:53.336395Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "15550152059",
            "id": "gBEGkXORkERnAglgp1wnhrkeJb0",
            "preview_url": false,
            "recipient_type": "individual",
            "text": {
                "body": "Please select from below option\\n\\n1. To submit complaint details\\n2. To re-enter the complaint details"
            },
            "timestamp": "1621452113",
            "to": "917391904467",
            "type": "text"
        },
        {
            "_vnd": {
                "v1": {
                    "author": {
                        "id": "917391904467",
                        "name": "The_Subtle_Guy",
                        "type": "OWNER"
                    },
                    "chat": {
                        "assigned_to": null,
                        "owner": "+917391904467",
                        "permalink": "https://app.turn.io/c/ac1ad367-1631-41b8-a29c-024ed19c1547",
                        "state": "OPEN",
                        "state_reason": "Re-opened by inbound message.",
                        "unread_count": 21,
                        "uuid": "ac1ad367-1631-41b8-a29c-024ed19c1547"
                    },
                    "direction": "inbound",
                    "faq_uuid": null,
                    "in_reply_to": null,
                    "inserted_at": "2021-05-19T19:21:58.364053Z",
                    "labels": [],
                    "rendered_content": null
                }
            },
            "from": "917391904467",
            "id": "ABEGkXORkERnAhCpESguA5JfsAlvKVTgoD0H",
            "text": {
                "body": "1"
            },
            "timestamp": "1621452118",
            "type": "text"
        }
    ],
    "thread": {
        "contact": {
            "arts": null,
            "birthday": null,
            "city": "pb.amritsar",
            "cityset": true,
            "complaint_category": "Garbage",
            "complaint_image": "No",
            "complaint_sub_category": "Dirty Water Supply",
            "complaintset": false,
            "complaintsetvalue": "To submit complaint details",
            "language": null,
            "locality": "JLC833",
            "localityset": true,
            "location": null,
            "math": null,
            "name": null,
            "opted_in": false,
            "opted_in_at": null,
            "space": null,
            "surname": null,
            "whatsapp_id": "917391904467",
            "whatsapp_profile_name": "Rohit"
        }
    },
    "RequestInfo": {
        "userInfo": {
            "id": 23342,
            "uuid": "f212e8aa-53ba-456f-9013-89fb806dc24b",
            "userName": "7878787878",
            "name": "Aditya",
            "mobileNumber": "7878787878",
            "emailId": "",
            "locale": "en_IN",
            "type": "CITIZEN",
            "roles": [
                {
                    "name": "Citizen",
                    "code": "CITIZEN",
                    "tenantId": "pb"
                }
            ],
            "active": true,
            "tenantId": "pb",
            "permanentCity": "pb.amritsar"
        }
    }
}'

My Applications UI Flow

Overview

Users can review the list of applications and their status registered under their mobile numbers in the My Applications tab. Each Application for the initial view displays the Application No, Service Category, Owner Name (Multiple with a comma), status, SLA, and Trade Name with the View Details option. If the status is pending for payment the View Details & Pay button is available that enables the users to look up more details about the application.

Once the user clicks on the View Details or View Details & Pay button, the Application Details Page is displayed with all the necessary information about the application.

The user can download the Application Acknowledgement Form (status - pending for payment ) or TL Certificate or the payment receipt using the Download Link button available at the top right corner of the page.

If the status is Pending for Payment for the application or Action required by a citizen (discussed elaborately here), a button will be visible to pay or edit at the end of the page respectively. On clicking on the Make Payment button it will redirect to the common pay screen through which the user can make the payment.

Timeline Component - timeline component is present at the end of the application details which tells about the current status and history of the application being initiated, Applied, Pending for Document Verification, Pending for Field Inspection, Pending approval, Pending payment, Approved etc.

Technical Implementation Details

The link for the Applications and Application Details main code is given below, it can be used to understand the working of the code, Below is the folder link.

The template for My Application List is present under https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Applications/Application.js and Application Details page is present inside - https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Applications/ApplicationDetails.js .

All the Application lists are retrieved by calling the search API "/tl-services/v1/_search". If the view is set as “bills”, all the application is loaded using the hook useFetchBill which calls the /billing-service/bill/v2/_fetchbill API. SLA value in the Application List Screen is calculated from the data received from workflow API : /egov-workflow-v2/egov-wf/process/_search

Following is the hook used for the trade search API.

const { isLoading, isError, data, error, ...rest } = view === "bills" ? Digit.Hooks.tl.useFetchBill(
    {
      params: { businessService: "TL", tenantId, mobileNumber },
      config: { enabled: view === "bills" }
    }
  ) : Digit.Hooks.tl.useTLSearchApplication({}, {
    enabled: view !== "bills"
  });

To get the Application details in key-value format, in order to make it more compatible, the following hook is being used, which is a common service to be used across modules.

 const { isLoading, isError, error, data: application, error: errorApplication } = Digit.Hooks.tl.useTLApplicationDetails({
    tenantId: tenantId,
    applicationNumber: id,
  });

MDMS

No MDMS data is being used here, all the data is being loaded from Search API/Fetch Bill API.

Localization

For My Applications also the localization keys are added in the ‘rainmaker-tl’ locale module same as other parts of the TL module. Change, update or add any new localization key is done in the same locale module only.

Trade License Renewal UI Flow

Renewal Flow

This feature allows the user to renew any trade license applications, which either has been expired or had to be renewed for current financial year (Approved and Paid), it also had integration with the payment component, in order to complete the flow all together for renewal.

Renewal can be two types:

DIRECT RENEWAL
EDIT RENEWAL

Renewal List

Once the user clicks on Renew Trade License button on the home page, it will redirect to the renewal list page which will display all the applications eligible for renewal corresponding to the mobile number on which the user has logged in. It will show the Trade name, License Number, Owner Name and status whether active or expired.

Once the user clicks on Renew Button, it redirects the user to the summary page just like in edit Trade license, with all the values pre-populated from the search API. The info card will be declared so that the user will understand how to proceed with either direct renewal or edit renewal.

Direct Renewal

If the user just wants to renew the same application without updating any data, it will cross-verify all the values in the summary page and then click on submit button directly at the end of the page, this will lead the application to the next status as pending for payment and user can go through payment flow from the acknowledgement screen also, by clicking on the Make Payment button.

Edit Renewal

If the user before renewal needs to update the application, they can do so by clicking on the change button on the summary screen, this will tell that the flow has been changed from direct to edit renewal, and the user will need to follow the same apply flow in order to complete the editing part of it. the values from the application will be pre-populated in the respective screens, to get the details about the edit flow, one can refer to this link. Send Back Flow - Edit.

Once the user clicks on submit button it will change the current action of the application to pending for document verification as the data has been updated.

Technical Implementation Details

Renewal Trade main index can be found in the below-given link:

https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Renewal/index.js

in this, we are calling the trade license search API, In order to get all the applications, through which the sorting is happened to classify which applications are eligible for renewal for the current financial year.

the hook which has been used for the API is:

const { isLoading, isError, error, data } = Digit.Hooks.tl.useTradeLicenseSearch({ filters: filter1 }, {});
  if (isLoading) {
    return <Loader />;
  }

The data from here then are sorted into the application which doesn’t have any open renewal application for the current financial year or which has a status of approved or expired. the significant method to get the renewal list of applications is mentioned below:

applicationsList.filter((response)=>response.licenseNumber).map((ob)=>{
    if(applications[ob.licenseNumber]){
    if(applications[ob.licenseNumber].applicationDate<ob.applicationDate)
    applications[ob.licenseNumber]=ob
    }
    else
    applications[ob.licenseNumber]=ob;    
    })

From here the Trade License List Component has been called which displays the list of the renewal application.

https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/Renewal/TradeLicenseList.js

The main functionality of converting the License Object received from the API to the object structure for formdata for apply flow, following is done in a similar way as the edit trade, and the same method is being used to convert the response object, to know more details please refer to Send Back Flow - Edit

Once the user has completed the flow as required or clicked the submit button directly, the method convertToEditTrade is being called, which re-arranges the data for the request body for the updated API /tl-services/v1/_update.

If it is a direct renewal only one update API is being called which updates the financial year only.

but if it is an edit renewal, two updated API is called after the first API successful call the application status gets changed to Initiated but after the second API call, it is changed to apply. with the next action pending for document verification.

The code for these can be found in the utils folder index please refer to the below link for the same:

https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/utils/index.js

MDMS

MDMS data which is being used here is the same as the Apply flow only, as the flow structure used for edit renew trade is the same as the Apply for Trade License. Please refer to the link for detailed MDMS information.

Trade License - Apply Flow

Localization

For Renew Trade also, the Localization keys are being added in the ‘rainmaker-tl’ locale module. Change, update or add any new localization key will be done in the same locale module only.

TL Apply Flow UI Details

Objective: To provide the facility for the user to create a trade license application for the current year by citizen users or counter employees.

Workflow Details

Apply for Trade License

Users can apply for a trade license application by clicking on the Apply for Trade License button. Users can add all the information as per the questions asked across the workflow. The summary screen at the end of the flow displays all details for review. Users can click on the submit button after review. The application for a trade license is created for the current financial year.

Apply Flow - The trade license registration screen is displayed after login which helps users identify the documents required to apply for a trade license. A citizen info card at the bottom of the page displays any additional information about the maximum size of the file that can be uploaded.

Trade License Details/Assessment Flow - This flow captures the trade-specific information required for registering the trade.

Trade Name - The user provides the name of the trade. An info card is displayed at the bottom of the screen stating that the license will be issued for the current financial year. The financial year value is retrieved from the MDMS.

Structure Type - The users can select yes or no based on whether the trade has mobility or not. If yes, the next screen prompts you to enter the vehicle type. If no, the next screen moves to the building type page.

Vehicle Type / Building Type - The options for vehicle and building type are fetched from the MDMS. The Building Type screen displays an information card about the pucca or kuccha options.

Commencement Date - It defines the date on which the trade started or will start in the future.

Trade Units - Users must provide the trade category as either goods or services. Based on the selected option the Trade Type is loaded from the MDMS as a drop-down list. The trade sub-type options are loaded based on the selected trade type. The unit of measure and UOM value get pre-populated from the MDMS as per the options selected above.

Users must enter at least one unit to move forward. Clicking on Add More Unit option enables users to enter additional units. Clicking on the delete icon on the top right corner of the unit card removes the unit.

Accessories - The Accessory page inquires if there are any accessories required for the business. Accessories may not be compulsory for all trades. If yes, it will move to the accessory details page. If not, it will skip it altogether and will load the address flow.

Accessory details - The options for accessories are retrieved from the MDMS. The Unit of Measure or UOM is pre-populated and cannot be edited. The users can edit the UOM value and the accessory count. In some cases, these are pre-populated from the MDMS. Clicking on Add More Trade Accessory button allows users to add multiple accessories.

TL Enhanced Flow

If the citizen selects Movable as the structure type in the previous screens, then the flow will jump to the owner details flow. Here the Same as Property Owner’s check box will not be visible.

If the citizen selects Immovable as the structure type then the user is allowed to add the property details. Once the property is added, the flow will redirect to the owner details flow where the Same as Property Owner check box is displayed. If the user checks it, the following details get auto-populated and the screen skips to the proof of Identity page.

Common PT integration with TL: After entering the trade details, users have the option to either search and integrate the already created property or create new lightweight property data for the trade license. This step can be skipped and users can proceed with the normal address details flow.

Once a property is selected user can see the details of the property on the property details page. Refer to the Common PT document for more details.

Address Details Flow - In the next flow, users have to enter the trade address details. This flow is straightforward, without any conditional routing.

Users can pinpoint the location in the Geo-location map, according to which pin code and city, as well as locality, is auto-filled.

Owner Details Flow - Finally, the users need to enter the trade owner details. Ownership can be Single or Multiple Owners. According to which the details are filled.

In the case of single/multiple owners, the following screen is displayed. The remaining flows remain the same.

Users can add multiple owners by clicking on the add owner button - a similar functionality as in trade units and accessories. The Add Owner button is not visible in case the user selects a single owner on the previous page.

The user must provide the owner's primary address and upload three documents that include address proof, owner identity and owner photograph.

Check Page and Acknowledgement Screen - Users can cross-verify the data entered throughout the flow in the Check page. Clicking on the change option adjacent to the data fields allows users to make any changes or updates to the data. The user is redirected back to a corresponding information page and the entire flow is repeated once again to submit the application.

The Applying of Trade License Create API is called. Create API snippet:1create: "/tl-services/v1/_create"

If the API response is successful, then the Acknowledgement Screen is displayed, otherwise Failed Acknowledgement Screen is displayed.

Clicking on the Download Acknowledgement Form button downloads the PDF copy of the acknowledgement.

Release 2.8 Enhancements & Changes

On the Trade Units page, values for trade type and trade subtype have been loaded by the following MDMS call:

const { isLoading, data: Data = {} } = Digit.Hooks.tl.useTradeLicenseMDMS(stateId, "TradeLicense", "TradeUnits", "[?(@.type=='TL')]");

The following validations have been added for the same :

When users select trade type and then subtype, it is compared with the available billing slab. The hook for this is given below. In case the billing slab is not there it will not allow users to move forward and an error message is displayed.

const { data: billingSlabTradeTypeData, isLoading : isBillingSlabLoading } = Digit.Hooks.tl.useTradeLicenseBillingslab({ tenantId: tenantId, filters: {} }, {
    select: (data) => {
    return data?.billingSlab.filter((e) => e.tradeType && e.applicationType === "NEW" && e.licenseType === "PERMANENT" && e.uom);
    }});

Once the correct trade type and subtype are added and the correct billing slab is there, the UOM value validation is added. This checks the value in the given range, mentioned in the billing slab object and displays an error if the value is outside of the range.

Technical Implementation Details

All screens are developed using the new-UI structure followed previously in FSM, PGR and PT, except for multi-component.

The link for the Apply Trade License Main Index is given here and it helps understand the starting point of the flow: https://github.com/egovernments/DIGIT-Dev/blob/master/frontend/micro-ui/web/micro-ui-internals/packages/modules/tl/src/pages/citizen/Create/index.js

The TL (Trade License) module is segregated into a specified structure. The screen configuration is inside the PageComponent folder, and the configuration for routing of the pages are mentioned under the config folder which is common for both citizen users and employees. Below is the snippet for folder structure and routing configuration.

export const newConfig = [
  {
    head: "",
    body: [
      {
        type: "component",
        component: "TLInfoLabel",
        key: "tradedetils1",
        withoutLabel: true,
        hideInCitizen: true,
      }
    ]
  },

The pages folder is where the high-level configuration for controlling the whole flow is mentioned, for citizens and employees. Citizen flows include Create, Edit Trade, Renewal, Applications and Search Trade. The index or the starting point of the entire flow is available in this folder.

In the Accessory-details page, the Billing slab search API "/tl-calculator/billingslab/_search" is called. This returns the array list of all the accessories for which the billing slab has been configured. If the response returns an empty array then the options are curated from the MDMS API mentioned in the MDMS data section.

After completing the flow the user can download the acknowledgement PDF form of the License created. PDF generation config link: https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/utils/getTLAcknowledgementData.js

The Utils folder basically contains all the methods used throughout the TL module. Additional common methods can be imported and added to this folder.

For creating an application the Create API from Trade License is called using the React hooks. This is declared in the hooks/elements/TL as TLService.

MDMS Data

There are multiple pages within the workflows where data is imported from the MDMS. The table below lists the pages .js files for distinct page components.

React Hooks are used to call MDMS data that is shared across the modules. Below is the code snippet for the MDMS call.

const { isLoading, data: Documentsob = {} } = Digit.Hooks.tl.useTradeLicenseMDMS(stateId, "TradeLicense", "TLDocuments");

Localization

Localization keys are added to the ‘rainmaker-tl’ locale module. In future, if any new labels are implemented in the Trade License (Citizen) it is pushed to the locale DB in the rainmaker-tl locale module. Below is an example of a few locale labels.

API Role Action Mapping

Send Back - Edit UI Flow

Edit Trade License

This feature allows the user to edit the application already created under their mobile number. After verifying employee can send the application back to the citizen with remarks on any changes that needed to be done, which can be edited by the user using this flow.

Edit Application

On the Application details page, on the employee side, if the application is marked with “Send Back to Citizen”, the edit option will appear dynamically at the end of the application details page, which the user can navigate through my applications.

After this, On clicking the button, the user can edit the trade license details by going through the Create Flow again. First, it will land on the Summary page, where for each section “change” button is there. Clicking on the Change button, the user will be redirected to the particular content, the only exception here will be the values will be pre-populated from the License object received from Trade License Search API, on completing the flow, Update API will be called and License application will get successfully updated.

Technical Implementation Details

Edit Trade License main index can be found in the link given below:

https://github.com/egovernments/digit-ui-internals/blob/main/packages/modules/tl/src/pages/citizen/EditTrade/index.js

Here the main code consists of the function which results in transforming the License object received in Search API to the object structure which is suitable for citizen Apply flow (owner details, units, accessories etc), as the user needs to go through Apply flow again with pre-populated details and update the value of any accordingly. it also consists of the routing for the pages in the Apply flow.

getTradeEditDetails() function is being used so that the License object which is received from the Trade Search API, is converted to the Apply flow relevant structure so that the values can be pre-populated for the user convenience, on completing the flow, the application is updated. The link for the same can be found below:

Similarly, for owners the method which is used to form the new request param array is gettradeownerarray

It is similar to Accessories and Units - the only difference is in UI. Users can’t select multiple owners and only add one owner, it needs to either add more than one owner or select a single owner in the ownership category and proceed. After the successful update, the application's next action will be “Pending for document verification” as there is an update in the data.

On completing the flow, the same object structure which was being used earlier in the flow gets changed into the request body structure for the update API: /tl-services/v1/_update, for this, the method which gets used is declared inside the Utils folder. Method name: convertToResubmitTrade and it can be found in the below link:

MDMS

MDMS data that is being used here is the same as the Apply flow only, as the flow structure used for edit trade is the same as the Apply for Trade License. Please refer to the link for detailed MDMS information.

Trade License - Apply Flow

Localization

For Edit Trade also, the localization keys are added to the ‘rainmaker-tl’ locale module. Change, update or add of any new localization key is done in the same locale module only.