1 of 100

NalJalSeva

Introducing NalJalSeva

Application designed to collect, manage revenue and expenditure

About NalJalSeva

A digital solution powered by DIGIT that enables the gram panchayat water committee to collect & manage revenue and expenditure.

NalJalSeva meets the objectives of the Jal Jeevan Mission launched by the Department of Drinking Water & Sanitation (DDWS), which aims to "provide safe and adequate drinking water through individual household tap connections by 2024 to all households in rural India." The solution empowers the village communities with the ease of consumer management, billing, collection, expense management and monitoring water supply schemes.

The NalJalSeva mobile app enables rural local bodies to manage revenue and expenditures related to water supply projects. It is designed for water management committee members and collection agents. The collection agents can add consumers (or households) and generate bills and receipt acknowledgements. The app provides an intuitive interface for users at the local governance level along with insightful dashboards for effective decision-making.

Features

NalJalSeva offers multiple features required to manage revenues and expenditures (listed below).

Create and maintain household registers
Collect payments
Download bills & receipts
Add and update expense records

Section Overview

This section contains all docs and information required to understand NalJalSeva, its key features, functional scope, and configuration details. Click on the links below to learn more about deploying, configuring, customizing, and using the NalJalSeva app.

Navigation Tips

Click on the embedded links within the content to browse topic details
Use the contents links available on the right side of the screen to move to a specific heading
Find the list of Related Docs links at the bottom of each page to browse through additional product details

Contact Us

NalJal

Approach

NalJalSeva: Empowering Rural Water Management With DIGIT

NalJalSeva, powered by the DIGIT platform, is designed for rural communities to independently manage their water supply infrastructure. The solution allows users to add new consumers, generate demand, collect revenue, and record expenditure transactions. It simplifies record-keeping, maintains a consumer database, monitors user charges, and provides a unified system for benchmarking rural governance and operations.

The NalJalSeva solution design impacts the financial and operational governance outcomes in multiple ways. Some of these include:

Empowering Local Communities: Villages gain full control over their water systems, promoting long-term sustainability.
Digital Governance: Built on DIGIT, NalJalSeva streamlines revenue and expense management, ensuring smooth operation.
Transparent and Accountable: Financial and operational activities are visible to local governments, ensuring transparency and accountability.

Problems Addressed By NalJalSeva

The Finance Department and Water Supply and Sanitation Department have limited visibility over the fiscal sustainability of water schemes and get hit by the sudden demand for large funds to clear electricity bills.

The Department of Water Supply & Sanitation (DWSS) face several problems due to the lack of financial visibility of schemes:

Unreliable and poor-quality water—Ineffective fiscal resource tracking often results in underfunding of water quality or treatment schemes.
Inability to collect adequate water charges — Manual methods of revenue collection from households on account of water charges often lead to shortfalls. Pending dues often accumulate and adversely impact financial planning and proposed schemes.
Lack of visibility of revenue and expenditure information - Inadequate financial transparency offers limited insight into how funds are being managed and spent by the local governing bodies. This creates financial blind spots, leading to misallocation of resources and unplanned expenses.

NalJalSeva helps digitise the revenue and expense records of Gram Panchayat Water Supply Committees. The dashboards and data insights provide DWSS and FD officials with visibility into the GPWSC's financial status.

The app offers capabilities to:

track and manage the revenue and expenditure records using the digital platform
share reports over WhatsApp
access updated insights on consumer satisfaction/quality of services provided by local governing bodies
view dashboards for a snapshot of collections and expenditures to the Sarpanch/other rural administrative officials

Approach

NalJalSeva integrates with the Fiscal Information Exchange (iFIX) platform to promote transparency and accountability in fiscal transactions. The fiscal events are posted on the platform in a standardised format making it easier to track and manage financial performance. The events are aggregated and processed to provide rich insights on key performance metrics which are available to users in the form of fiscal sustainability dashboards.

The illustration below provides a visualisation of how multiple actors interact with the distinctive Gram Panchayat Water Supply & Sanitation system registries to manage and coordinate various fiscal events. The key actors or stakeholders of the system include system administrators, department workers, local governing bodies, citizens and collection agents. Streamlined interaction between these actors is crucial for effective operations and management of fiscal events to facilitate sustainable and equitable access to basic services within the community.

The NalJalSeva app offers multiple benefits that promote the efficiency and transparency of water management services within local governing bodies.

Digital book-keeping - maintains all receipt and expense records in digital format reducing the reliance on physical documents.
Account management - simplified consumer and vendor account creation or management
Low-effort operations - easy to use and environmentally friendly
Minimise manual work - a simple mobile app that saves the time and effort of managing revenue & expenditure transactions

Demo Video

A quick walkthrough of NalJalSeva app

Value Proposition

Product Specifications

Features & Functions

NalJalSeva is an app-based solution designed for rural water governance and financial management. It supports local governance by providing tools to support consumer management, billing and collection added to financial reporting.

The solution enables the governance bodies to maintain financial records following established procedures and practices.

Key Features Of Nal Jal Seva

The solution offers an end-to-end solution for managing rural water supply schemes, focusing on maintaining transparency and simplifying financial transactions. It enhances governance and simplifies tasks for local authorities while ensuring accountability.

Workflows

Click on the links below to explore the NalJalSeva workflows:

Login & Forgot Password

Overview

The users receive a link via SMS. Clicking on this link redirects the users to the login page of the NalJalSeva app. The users can log in from this screen or even reset their password in case they are logging in for the first time.

Design & Workflow

Water Charges

Overview

Users can check the configured Water Charge details in the dashboard for the selected tenant/Scheme.

Design & Workflow

Users can click on the VWSC and Water Charges Info card on the home page to view the tabulated rate information details.

Generate Bills For Metered Connections

Overview

Unlike non-metered connections with a billing cycle for demand & bills generated automatically, a metered connection needs more inputs, which helps in volumetric billing.

Design & Workflow

A revenue collector can see a CTA to “Generate a new Bill” on the Household details screen.

Clicking “Generate a new Bill” takes users to the bill generation screen where new meter reading details are entered.
The field on the bill generation screen for metered connections is displayed in the table below.
Clicking on “Generate bill” takes the user to the bill generation successful screen.
Logic for Bill ID number - “RB - dd/mm/yyyy-yy/running_sequence_number”.

Input Metric

Description

Comments

To find details on Demand Generation Logic refer to the Demand/Bill Generation for metered connection.

All 5 digits in the meter reading must be entered. Show error message “ Old Meter Reading entered is Invalid” or “ New Meter Reading entered is invalid” respectively.
The New Meter reading should be greater than the Old Meter Reading.
The meter reading date is by default set to <today's date> but the user has the option to change it.

Add Expense

Overview

The Add Expense feature enables users to add expense details.

Design & Workflows

The expense entry for the O&M is captured on this screen.

Update Expense

Overview

The update expense feature allows users to modify and update expense details.

Design & Workflows

Expense modification is allowed based on the status of the payment as highlighted in the scenarios below.

Edit User Profile

Overview

Naljalseva users can edit their basic information like name, add gender, email and change the password using the hamburger menu on any screen.

Design & Workflows

Users can click on the hamburger menu from any screen. A slider from the left opens up.

Users can -

Change Language
Edit profile
Logout

Changing language changes localization as per standards

Edit profile takes users to the next screen where changes can be made to the user profile

Name - Can be changed
Phone number - Cannot be changed
Gender - This field is not present by default. Whatever the user enters is stored and saved
Email ID - It is an empty field. User input is stored as the user’s email id

Clicking on save shows a nudge to the user” Details saved successfully”. Upon closing, this user remains on the screen but the fields show as edited.

View Household Register

Overview

The View Household Register enables users to view household details.

Design & Workflow

Users can click on the Household Register on the home screen and navigate to this screen. This provides a single-view snapshot of all pending collections by consumers to date.

View Tabular Dashboard For Expense

Overview

The View Tabular Dashboard for expenses provides a view of all expenses incurred during the month.

Design & Workflows

Clicking on the Dashboard on the home screen navigates the user directly to the revenue dashboard of the current month. From here, the user can switch to the expenditure tab to get a view of expenses. This provides a tabular view of all expenses incurred in that month.

Data Points

Following are the data points/actions needed on the screen:

Item

Description

The table on the screen is a horizontal scrollable one with the leftmost column fixed.

HRMS

Update Employee

Overview

Employee details can be updated using the Edit employee details option.

Design & Workflows

State users - can edit block user details

Search Employee

Overview

Employee can be searched by name, employee ID and Number.

Design & Workflows

State User search Employee Search by name, employee ID and Number.

Block-based search is available for state users.

Search based on employee status

Block User Search Employee

Search Employee By name, employee ID and Number.

The search screen will show the below details

Employee Id
Employee Name
Mobile Number
Type of user

Role-based search is also available for block users -

We have search option for inactive/ active users -

State Dashboard

Overview

The state dashboard option is available to State Users logged in to HRMS.

Design & Workflows

Rollout Dashboard

Overview

The Rollout Dashboard option is available to all State Users.

Design & Workflows

This is the dashboard that gives you a view of the total connections across active users and the total demand generated across the whole state.

Here we have options to select the date range within which you want to see the data. Further, there is a drill down where we can select districts, blocks, panchayat and schemes as well.

User Manual

A step-by-step guide to using the NalJalSeva App

Introduction NalJalSeva

NalJalSeva is a standalone app-based module that enables the GPWSC committee to create new consumers, generate demand, collect revenue, record expenditure transactions etc.

NalJalSeva enables GPWSCs to maintain financial records of GPWSCs following established procedures and practices.

Follow the step-by-step (links below) guide to use the app:

Common Functions

Edit Profile & Change Password

Users can -

Division User

View & Edit Consumer

View Consumer

Users are redirected to the View Consumer screen from the home screen via

Collect payments → Search Screen → Consumer Details Screen
Download bills & receipts → Search screen → Consumer Details Screen
Dashboard → Collections → Click on Consumer ID
Household Register → Click on Consumer ID

Enter the search parameters - Consumer Mobile Number, Name of the Consumer or New Connection ID to filter your results.

Click on the Search button to view the consumer list.

Click on View Consumer Details.

Edit Consumer

Users can edit the consumer details if any changes need to be made in the consumer record.

Click on the Update Consumer Details card on the home page. Search and find the applicable consumer using the given search filters.

Click the Edit Consumer Details button on the applicable consumer search record to make the necessary changes.

Edit the required details on the screen.

Check the option Mark this connection as Inactive to indicate that the given consumer connection is inactive.

Click on the Submit button to save these changes.

Village Water & Sanitation Committee (VWSC) User

Generate Bills

The Administrative user for a GPWSC/Village, i.e., a Sarpanch or anyone with admin access, needs to generate a bill (i.e., generation of monthly bills) for all the consumers. This activity is to be done at the beginning of the month and must be done only once per month. Sarpanch or anyone with admin access has the option to generate the bill for all consumers at once.

Steps

Click on the Generate Bill card on the homepage to raise bills for all or selected consumer connections.

Reference Implementations

Punjab

The journey of PFM Mission in Punjab began in January 2021 with signing of a tri party MoU among The Department of Governance Reforms and Public Grievances (DGR & PG), the Department of Finance (FD), Punjab, and eGov Foundation to provide a systemic solution to enhance public finance management in the state.

The pilot was agreed to be carried out in the Department of Water Supply and Sanitation (DWSS).

Multiple learning sessions with the DWSS officials were conducted to gain in-depth knowledge on current processes and systems, pressing challenges, and how the Mission can design potential solution(s) to the identified problem/s. After these discussions, the following problem statement was identified:

Visibility into financial sustainability of GPWSC run schemes:

The water charges (funds) collected by the GPWSC for their schemes and expenditures made thereof are not visible to the DWSS or the Department of Finance (FD)
Such transparency is necessary since DWSS funds the asset creation and provides for O&M and electricity charges shortfall of GPWSC, if any

To solve the above problem statement, eGov Foundation in consultation with the DWSS, Government of Punjab, identified Anandpur Sahib (APS) as the pilot division to implement mGramSeva. mGramSeva, a mobile application, envisions to capture all the Revenue and Expenditure details in digitized format which will bring in accountability and transparency of GPWSC funds, as well as enable and empower frontline leaders of the Panchayats.

The mGramSeva solution adoption highlights are given below:

In APS division there are more than 76 schemes and 100 villages which are GPWSC run schemes, for which the water bills are generated manually
No automated or digital system currently in place to notify the household through SMS for bills generated
Manual recording all the receipts and expenses in cash book
Sarpanch does not have access to real time information on collection and expenditure

NalJalSeva Platform

Setup NalJalSeva

Install AWS

Setup AWS account

Purchase Certificate

We currently use the free Let's Encrypt SSL certificate, which is valid for 90 days and must be manually renewed afterwards. There are also several paid SSL certificate options available globally.

Setup Git Repository

Overview

This page provides step-by-step details on setting up a git repo for code, configs, V1 MDMS, and Infra As Code.

Steps

Fork the following repos that contain the master data and default configurations. Customize the data (master data, ULB, Tenant details, Users, etc) as per specific implementation requirements in the respective GitHub organization accounts.

Create Git Account In The Client Name

Overview

This page provides the steps to follow to create a Git account in the client name.

Steps

To create a Git account in the client name, follow the steps below:

Create User API

This page provides a comprehensive guide on using the CreateNovaildate API to create users with specific roles based on their responsibilities within the system. Adjust the parameters and roles as needed for your specific requirements.

Steps

The API allows users to create a new user with specified details that include username, name, gender, mobile number, activation status, user type, tenant ID, and password. Refer to the details available below.

Additionally, users can be assigned specific roles based on their responsibilities.

Create New Tenant

This documentation outlines the process of setting up a new tenant in MDMS (Master Data Management System). To achieve this, it involves cloning the MDMS repository locally and utilizing a Python script that interacts with an Excel file containing essential information for the new tenant setup.

Pre-requisites

Clone the repository to your local machine.

Configure NalJalSeva

Configure Backend Services

Configure the backend services to expand the scope of NalJalSeva

User OTP

User OTP service is used to generate OTP for user login, user registration and user password change.

Pre-requisites

Prior Knowledge of Java/J2EE.

Configure UI Screens

curl --location --request POST 'http://localhost:8090/ws-services/wc/_create' \
--header 'authority: mgramseva-qa.egov.org.in' \
--header 'accept: */*' \
--header 'accept-language: en-GB,en-US;q=0.9,en;q=0.8' \
--header 'content-type: application/json; charset=utf-8' \
--header 'cookie: _ga_MY9HZBBBC8=GS1.1.1646915127.24.1.1646915152.0; _ga=GA1.1.1108799280.1643257024; _ga_8H6W5DYGX0=GS1.1.1655294682.124.0.1655294682.0' \
--header 'origin: https://mgramseva-qa.egov.org.in' \
--header 'referer: https://mgramseva-qa.egov.org.in/mgramseva/home/consumercreate' \
--header 'sec-ch-ua: " Not A;Brand";v="99", "Chromium";v="102", "Google Chrome";v="102"' \
--header 'sec-ch-ua-mobile: ?0' \
--header 'sec-ch-ua-platform: "Linux"' \
--header 'sec-fetch-dest: empty' \
--header 'sec-fetch-mode: cors' \
--header 'sec-fetch-site: same-origin' \
--header 'user-agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36' \
--data-raw '{
    "RequestInfo": {
        "apiId": "mgramseva",
        "ver": 1,
        "ts": "",
        "action": "_create",
        "did": 1,
        "key": "",
        "msgId": "20170310130900|en_IN",
        "authToken": "cded20ed-d1f7-40ca-bd8e-978e319fdcea",
        "userInfo": {
            "id": 705,
            "uuid": "36b747f4-bd94-4be7-b0cc-e59af2ff970b",
            "userName": "8122091926",
            "name": "Vasanthi",
            "mobileNumber": "8122091926",
            "emailId": "[email protected]",
            "locale": null,
            "type": "EMPLOYEE",
            "roles": [
                {
                    "name": "GP Admin",
                    "code": "GP_ADMIN",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "Bulk Demand Processing",
                    "code": "BULK_DEMAND_PROCESSING",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Profile update",
                    "code": "PROFILE_UPDATE",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Dashbaord Viewer",
                    "code": "DASHBOARD_VIEWER",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Expense Processing",
                    "code": "EXPENSE_PROCESSING",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Dashbaord Viewer",
                    "code": "DASHBOARD_VIEWER",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "Expense Processing",
                    "code": "EXPENSE_PROCESSING",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "GP Admin",
                    "code": "GP_ADMIN",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "GP Admin",
                    "code": "GP_ADMIN",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Profile update",
                    "code": "PROFILE_UPDATE",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Bulk Demand Processing",
                    "code": "BULK_DEMAND_PROCESSING",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "Profile update",
                    "code": "PROFILE_UPDATE",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Profile update",
                    "code": "PROFILE_UPDATE",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "Collection Operator",
                    "code": "COLLECTION_OPERATOR",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Bulk Demand Processing",
                    "code": "BULK_DEMAND_PROCESSING",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Bulk Demand Processing",
                    "code": "BULK_DEMAND_PROCESSING",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Collection Operator",
                    "code": "COLLECTION_OPERATOR",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Dashbaord Viewer",
                    "code": "DASHBOARD_VIEWER",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Dashbaord Viewer",
                    "code": "DASHBOARD_VIEWER",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Expense Processing",
                    "code": "EXPENSE_PROCESSING",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Expense Processing",
                    "code": "EXPENSE_PROCESSING",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Dashbaord Viewer",
                    "code": "DASHBOARD_VIEWER",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Bulk Demand Processing",
                    "code": "BULK_DEMAND_PROCESSING",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "GP Admin",
                    "code": "GP_ADMIN",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb.lodhipur"
                },
                {
                    "name": "GP Admin",
                    "code": "GP_ADMIN",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Expense Processing",
                    "code": "EXPENSE_PROCESSING",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Collection Operator",
                    "code": "COLLECTION_OPERATOR",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Profile update",
                    "code": "PROFILE_UPDATE",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb.massewal"
                },
                {
                    "name": "Employee",
                    "code": "EMPLOYEE",
                    "tenantId": "pb.dabourlower"
                },
                {
                    "name": "Super User",
                    "code": "SUPERUSER",
                    "tenantId": "pb.lalpur"
                },
                {
                    "name": "Collection Operator",
                    "code": "COLLECTION_OPERATOR",
                    "tenantId": "pb.dabourupper"
                },
                {
                    "name": "Collection Operator",
                    "code": "COLLECTION_OPERATOR",
                    "tenantId": "pb.lodhipur"
                }
            ],
            "active": true,
            "tenantId": "pb",
            "permanentCity": null
        }
    },
    "WaterConnection": {
        "id": null,
        "connectionNo": null,
        "propertyId": "PB-PT-2022-06-15-1722",
        "applicationNo": null,
        "tenantId": "pb.lodhipur",
        "action": "SUBMIT",
        "status": null,
        "meterInstallationDate": 1651343400000,
        "documents": null,
        "proposedTaps": 1,
        "noOfTaps": 1,
        "paymentType":"arrears",
        "arrears": 112,
        "penalty":50,
        "connectionType": "Metered",
        "oldConnectionNo": "",
        "meterId": "121212",
        "propertyType": "RESIDENTIAL",
        "previousReadingDate": 1651343400000,
        "previousReading": 56,
        "proposedPipeSize": 10,
        "connectionHolders": [
            {
                "id": null,
                "uuid": null,
                "userName": null,
                "password": null,
                "aadhaarNumber": null,
                "permanentAddress": null,
                "permanentCity": null,
                "permanentPinCode": null,
                "correspondenceCity": null,
                "correspondencePinCode": null,
                "correspondenceAddress": null,
                "pwdExpiryDate": null,
                "accountLocked": null,
                "active": null,
                "type": null,
                "tenantId": null,
                "altContactNumber": null,
                "ownerInfoUuid": null,
                "isPrimaryOwner": null,
                "ownerShipPercentage": null,
                "institutionId": null,
                "designation": null,
                "emailId": null,
                "isCorrespondenceAddress": null,
                "mobileNumber": "9182541372",
                "fatherOrHusbandName": "Sravan",
                "name": "Sravani",
                "status": null,
                "gender": "FEMALE",
                "ownerType": "NONE",
                "documents": null,
                "roles": null
            }
        ],
        "additionalDetails": {
            "initialMeterReading": 56,
            "meterReading": 56,
            "locality": "WARD1",
            "category": null,
            "subCategory": null,
            "aadharNumber": null,
            "propertyType": "RESIDENTIAL",
            "street": "",
            "doorNo": "",
            "collectionAmount": null,
            "collectionPendingAmount": null,
            "action": null
        },
        "processInstance": {
            "action": "SUBMIT"
        }
    }
}'

User Events

eGov-User-Events service provides a common point to manage all the events generated for the user in the system. Events include updates from multiple applications like PT, PGR, TL etc, events created by the employee addressing the citizen etc. This service provides APIs to create, update and search such events for the user.

Pre-requisites

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

Java 8
The Kafka server is up and running
egov-persister service is running and has egov-user-events persister config path added to it
PSQL server is running and the database is created

Key Functionalities

Provide a common platform to create, manage and notify events.
Events can be created either through an API call or by pushing records to the Kafka queue.

Deployment Details

Add mdms configs required for egov-user-events.
Add Role-Action mapping for API’s.
Deploy the latest version of egov-user-events
Add egov-user-events file in config folder in git and add that path in persister. (The file path is to be added in environment yaml file in a param called persist-yml-path )

Configuration Details

Add master data in the MDMS service with the module name as mseva. Following is some sample master data for the service:

Event Categories

Event Types:

Using /localization/messages/v1/_upsert , add localisation (templates) for notification messages to be sent. Following are the product notification templates:

Copy

Configurable Properties

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

Property

Value

Remarks

Entities:

Events: Model to capture the events information. This object captures all the details of an event which is either being created or updated.

EventDetails: Captures details of the event such as organiser, location, time etc are captured here. This is the child object to the Events object. This has significance only because the type of the event is ‘EVENTSONGROUND’.

Action: This captures the user actions involved in the event. Say the pay now option, reopen option, download certificate option etc.

Recipient: Every event is addressed to a crowd to which a notification of the same is sent. This model captures information about the recipients of the notification of this event or can also be framed as details of the address of the event.

Event Type: Events are divided into multiple types as follows:

BROADCAST - These are messages broadcasted addressing a group of people. For instance, “There’s road blockage near the bus stand, please use a different route”
EVENTSONGROUND - These are events organised by a group of people addressing another group of people usually it is the ULB organising events for the citizens. It can be any activity like a 10K Marathon, Polio Drive, Property Tax collection drive etc.
SYSTEMGENERATED - These events are generated by different systems on the egov platform like PT, TL, PGR etc addressing a group of people. For instance, “Dear Citizen, Your TL has been approved please proceed to Pay here <PAY_NOW>”

These are configured in MDMS.

Event Category: Events are categorised into the following:

PUBLICHEALTH - Events related to public health.
CULTURAL - Cultural events
WARDCOMMITEEMEETING - Events for recurring meetings of the ward committee.

These event categories are mapped to event types internally. The categories mentioned here are for EVENTSONGROUND type. These are configured in MDMS.

How does it work?

This service manages user events on the egov-platform, which means all the events about which the user (essentially citizen) has to be notified are stored and retrieved through this service. Events can be created either by an API call or by pushing records to the Kafka queue.

Every event should contain information about the event type, event category, event name, description, recipient, actions, event details etc. Based on the type of the event, the list of mandatory fields varies. MDMS configurations required for this service to work can be found here:

Once the event is sent for creation, the service validates all the required fields and assigns a recipient list to that event. An event can be addressed to a particular person, group of people, user type and also roles. Events like updates on the TL application are addressed to the owner of the TL only, Events like Polio Drive are addressed to the entire ULB, and Events like mass Bill generation are addressed only to those who are required to pay those bills. Similarly, a recipient list is generated based on the request and stored in the system.

When an event is updated a counter event is generated, Counter events are of 2 types: Counter event on Delete and Counter event on Update. When an event in ACTIVE status is made INACTIVE or CANCELLED, a counter-event on delete is generated. When details of an event are updated irrespective of the status a counter event on update is generated. These counter-events are stored along with the actual event in the system. However, when a counter-event on delete is generated, its corresponding actual event is marked INACTIVE.

One of the important aspects of this service is the search API. Searching for the events stored in the user-events system is different for different roles. When CITIZEN searches, all the events addressed to that citizen are retrieved, the events that contain corresponding counter-events are deduplicated and only the latest ACTIVE events are returned.

We have a use-case where past events have to be marked INACTIVE, this applies to all the BROADCAST and EVENTSONGROUND types of events which are time-capped. If a BROADCAST event is active from 1/Jan to 10/Jan, it’ll be marked inactive post 10/Jan, after which the CITIZEN stops receiving any updates to that event. This changing of the status of the events is achieved by a lazy-update technique instead of a cron job. Due to this, the search API not only returns the events but also updates the status of events before returning them to the user based on whether it has expired.

When an EMPLOYEE searches, all the EVENTSONGROUND posted in his particular ULB are returned by default irrespective of the status. He/She can perform actions on those events, which if active, are notified to the CITIZEN.

An EMPLOYEE can search event based on the date the range, whatever the event created or last modified in that range, will appear in the search response. So, to get the details about an event in a particular date range pass the value in the fromDate and toDate fields of search criteria.

fromDate and toDate fields accept epoch values only.

And to get details about the Delete event, pass Status as CANCELLED and to get details about the Broadcast event pass eventType as BROADCAST.

Review the code and descriptions of every method to understand the use cases and flow of logic in a better way.

Integration Details

Integration Scope

eGov-user-events can be integrated with any organisation or system which wants to send the events generated for the user in the system

Integration Benefits

Easy manages user events on the system, which means all the events about which the user (essentially citizen) has to be notified are stored and retrieved through this service.

Integration Steps

An employee can create events in the system using /egov-user-event/v1/events/_create endpoint
Employees can update events in the system using /egov-user-event/v1/events/_update endpoint
Events are searched in the system using /egov-user-event/v1/events/_search endpoint
/egov-user-event/v1/events/notifications/_count API is used to fetch the count of total, unread, and read notifications.

Reference Docs

Doc Links

API Docs

API List

APIs

(Note: All the APIs are in the same Postman collection therefore same link is added in each row).

Property

One of the major applications of the eGov stack is that it helps municipalities and citizens handle property tax payments and other related functions on the property such as assessments, mutation, and so on.

Pre-requisites

Prior knowledge of Java/J2EE
Prior knowledge of Spring Boot
Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON etc.
Prior knowledge of Git
Prior knowledge of the demand-based systems
The following services should be up and running:
- user
- MDMS
- Persister

Key Functionalities

The Property Service provides multiple functionalities starting from serving as a central repository where property information is registered for reference of citizens and other municipality-provided services such as water connection and sewerage management. An assessment can be done to calculate and pay tax on the property. The different services provided by the property services are -

Property Registry
Assessment
Mutation
Bifurcation

Registry Explanation

The registry flow helps the citizen/Employee to create a property in the system with the minimal information required.
Other workflows such as assessment or mutation can be triggered on the existing ACTIVE Property in the registry.
The property can be created, updated, cancelled, and searched followed by the process of Mutation and Assessment.
The same entry in the registry can be referred to by other modules for various business purposes (Water charges).

Configuration Details

MDMS CONFIG:

Persister File Configuration

The persister file configuration for property services can be found in the Config repo of eGov Git, which needs to be added in the persister service -

Workflow Configurations

Each flow in the property has a workflow associated with it, which can be controlled by following configurations.

The Boolean field can enable/disable Workflow - the same field controls the update and creates the workflow.

name

value

description

Workflow configuration for a property is created if the source is from the WATER CONNECTION module.

For the creation of property from the water and sewerage module, as per the use case mentioned in this , a different workflow configuration is used. For each use case, to identify which workflow to use can be identified from this .

Use Case 1, which involves property creation from the Water and Sewerage module, necessitates a single-step workflow. In the MDMS file mentioned above, ensure that the businessService with PT.CREATEWITHWNS object is enabled, allowing the field to be set as true. Property creation from the Water and Sewerage module will feature a one-step workflow, for properties in an ACTIVE state.

Fields in the above MDMS file:

MDMS Fields

Description

Note: Each object mentioned above represents a specific use case outlined in this ticket. Therefore, only one object (use case) enable field should be set to true at any given time.

Sample workflow config for use case 1 where property creation is from water and sewerage module with one-step workflow.

Sample workflow config - (The same PT.CREATE can be used for update workflow also since both involve the same functionality)

PT.LEGACY workflow config

Notifications:

To enable or disable notifications notif.sms.enabled=true

#notif urls - makes use of the UI app host in notification service egov.notif.commonpay = citizen/egov-common/pay?consumerCode={CONSUMERCODE}&tenantId={TENANTID} egov.notif.view.property = citizen/property-tax/my-properties/property/{PROPERTYID}/{TENANTID} egov.notif.view.mutation = citizen/pt-mutation/search-preview?applicationNumber={APPID}&tenantId={TENANTID}

The current localization messages for notification -

Configs in App.props

name

value

Integration Details

Integration Scope

Property service can be integrated with any organization or system that wants to maintain a record of the property and collect taxes with ease.

Integration Benefits

Easy to create and simple process of self-assessment to avoid the hassle.
Helps maintain property data which can be used in the integration of other essential services like asset management, water connection and so on.
provides additional functionalities like mutation and assessment of properties.

Integration Steps

Customers can create a property using the /property/_create
Search the property using /property/_searchendpoint
/property/_update endpoint to update the property demand as needed.
Mutation can be carried out with the help of /property/_update itself, no extra API is required.

Reference Docs

Doc Links

Title

Link

API LIST

Title

Link

Water Calculator

Water Calculator Service is used to create meter readings, search meter readings, update existing meter readings, calculate water charges, generate demand, notify ULB officials using SMS & email on-demand generation and estimation of water charges (one-time cost) which involves costs like road-cutting charge, form fee, scrutiny fee, etc.

Pre-requisites

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

Java 8
The Kafka server is up and running
egov-persister service is running and has the water service persister configs path added to it
PSQL server is running and a database is created to store water connection/application data
The following services should be up and running:
- egov-persister
- egov-mdms
- ws-services

Key Functionalities

Calculate water charges and taxes based on the billing slab
Calculate meter reading charge for water connection
Generate demand
Scheduler for generating the demand (for non-metered connection)

Environment variables

Description

Deployment Details

Deploy the latest version of ws-service and ws-calculator
Add the water-persist.yml and water-meter.yml files to the config folder in git. Update the environment YAML file by adding a parameter called persist-yml-path with the path to these files.

Configuration Details

MDMS Configuration

Master Config:

Billing Slabs:

Criteria -

connection type
building type
calculation attribute
property usage type

The above combination is used to define the billing slab. Billing Slab is defined in MDMS under the ws-services-calculation folder with the . Find below a sample slab.

The calculation applies the specified slab based on the water connection criteria.

Estimation:

Water charge and tax

The water charge is based on the billing slab, and the water application charge will be based on the slab and tax based on the master configuration.

Actions & Role Action Mapping

Actions

Role Action Mapping

Add New BillingSlab/RateMaster

The charge for the given connection for a given billing cycle will be defined/identified by the system with the help of the CalculationAtrribute MDMS and WCBillngSlab MDMS.

CalcualtionAttribute helps to identify the type of calculation for the given ConnectionType below MDMS of

Metered Connection water consumption is the attribute used for the calculation of charge for the billing cycle i.e Based on the units consumed for a given billing cycle for a given connection would identify the actual charge from the WCBIllingSlab MDMS based on the propertyType, calcautionAttribute derived for a connection and ConnectionType.
Non-Metered Connection Flat is the attribute used for the calculation of the charge for a given billing cycle, i.e. for a Non-Metered connection, there would be a flat charge for the given billing cycle. The amount can be derived from the WCBillingSlab MDMS based on the propertyType, calcautionAttribute derived for a connection and ConnectionType.

Demand Generation

Once water is sent to the calculator, its tax estimates are calculated. Using these tax head estimates, demand details are created. For every tax head, the estimated demand generates a corresponding demand detail.

When the _calculate API is called, demand is first searched based on the connection number or application number and the demand period. If demand already exists, it is updated with the new information. Otherwise, a new demand is generated for the financial year period.

During an update, if the tax head estimates change, the difference in amount for that tax head is added as a new demand detail. For example, if the initial demand has one demand detail with WATER_CHARGE equal to 120.

After updating if the WATER_CHARGE increases to 150 we add one more demand detail to account for the increased amount. The demand detail will be updated to:

Round-off in the bill is based on the total amount, ensuring that the payable amount is a whole number. Each WS_ROUNDOFF in the demand detail can be greater than 0.5, but the sum of all WS_ROUNDOFF values is always less than 0.5.

Demand Generation Scheduler (For Non-metered Connection)

Description

To generate demand for non-metered connections, we have a feature for batch demand generation. The scheduler is responsible for generating demand based on the tenant.

The scheduler can be triggered using the scheduler API, scheduled as a cron job, or configured in Kubectl to hit the scheduler based on the configuration.
After the scheduler is triggered, we can search for the list of tenants (cities) in the database.
After obtaining the list of tenants, iterate through the list and generate the demand for specific tenants.
Load the consumer codes for the tenant and push the calculation criteria to Kafka. The calculation criteria contain minimal information, including the consumer code and one boolean variable.

Use cases

If the same job triggers multiple times what will happen?

If the same job triggers multiple times the system processes it again as mentioned above but at the demand level, it checks the demand based on consumer code and billing period. In case the demand already exists then it updates the demand or else creates the demand.

Are we maintaining success or failure status anywhere?

Currently, we are maintaining the status of failed records in Kafka.

Configuration

We need to configure the batch size for Kafka consumers. This configuration determines how much data is processed at a time.

Integration Details

Integration Scope

The ws-calculator is integrated with ws-service. ws-services internally invoke the ws-calculator service to calculate and generate demand for the charges.

Integration Benefits

WS calculator application is used to calculate the water application one-time fees and meter reading charges based on the different billing slabs. That's why the calculation and demand generation logic is separated from the WS service. So in future, if calculation logic requires modification the changes can be carried out for each implementation without modifying the WS service.

Integration Steps

Once the water connection is activated for the metered connection, the employee can add meter reading details using the API - /ws-calculator/meterConnection/_create. This generates the demand. The scheduler APIs should be called periodically for non-metered connections to generate the demand.
For the metered connection service, the /meterConnection/_search API is used to get the previous meter reading,
To generate the demand for metered or non-metered water connection /waterCalculator/_calculate API is used.
Users can pay partial/full/advance amounts for the metered or non-metered connection bill. The billing service would call back /waterCalculator/_updateDemandAPI to update the demand-generated details in such cases.

Reference Docs

Docs

APIs

(Note: All the APIs are in the same Postman collection therefore the same link is added in each row).

Dashboard

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.

As this revolves around a variety of Data Sets, there is a need for making this configurable. So that, tomorrow, given a new scenario is introduced, then it is just a configuration away from getting the newly introduced scenario involved in this process flow.

This document explains the steps on how to define the configurations for the Analytics Side Of DSS for NalJalSeva.

What is analytics?

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.

Analytics Configurations: Analytics contains multiple configurations. we need to add the changes related to NalJalseva in this dashboard-analytics.

Dashboard analytics link -

Below is a list of configurations that need to be changed to run NalJalSeva successfully.

Chart API Configuration

Each Visualization has its 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 a 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.

Here is the sample ChartApiConfiguration.json data for the NalJalSeva.

Master Dashboard Configuration

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

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

Role Dashboard Mappings Configuration

Master Dashboard Configuration which was explained earlier holds the list of Dashboards that are available.

Given the instance where Role Action Mapping is not maintained in the Application Service, this configuration will act as Role - Dashboard Mapping Configuration.

In this, each role is mapped against the dashboard which they are authorized to see.

This was used earlier when the Role Action Mapping of eGov was not integrated.

Later, when the Role Action Mapping started controlling the Dashboards to be seen on the client side, this configuration was just used to enable the Dashboards for viewing.

Transform collection schema for V2
- This transform collection v1 configuration file is used to map the incoming data. This mapped data will go inside the data object in the DSS collection v2 index.

Here: $i, the variable value that gets incremented for the number of records of paymentDetails $j, the variable value that gets incremented for the number of records of billDetails.
This configuration defines and directs the Enrichment Process which the data goes through.
For example, if the incoming data belongs to a Collection Module, then the Collection Domain Config is picked. Based on the Business Type specified in the data, the right config is picked.

Enrichment Domain Configuration

Domain configuration
Topic context configuration
transform_expense.electricity_bill_v1 configuration
transform_expense.om_v1 configuration

Below is the list of configurations made changes or added newly for NalJalSeva.

Topic Context Configuration

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

Based on expense and water-service business service we added transform configurations as per below.

transform_expense.electricity_bill_v1 configuration:

transform_expense.om_v1 configuration:

transform_expense.salary_v1 configuration:

transform_ws_v1 configuration:

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

es.push.direct=false
If DSS collection index data is indexing directly ( without Kafka connector) to ES through the ingest pipeline then, make the application properties or in environments, direct push must be enabled.
es.push.direct=true

Creating Kafka Sync Connector - push the data to the Elasticsearch

Configure the Kafka topics in the environments or Ingest pipeline application properties as shown below.

For details on services such as re-indexing and Kafka connection, refer to the document.

Dashboard Service Changes

Main-Monthly Dashboard

For the main monthly dashboard, we are using the service API to fetch the data and show it in the main monthly dashboard table.

Ws-services:

/ws-services/wc/_revenueCollectionData Should be added to get the main monthly dashboard details. It is used to show the table data based on the no of months for selected financial year.

eChallan-Service:

/echallan-services/eChallan/v1/_chalanCollectionData it is added to get the main monthly dashboard data for the expense.

Dashboard-Metrics:

To show the data in metrics format in a specific month dashboard we are using service API which will fetch the data based on dashboard type.

Ws-services:

/ws-services/wc/_revenueDashboard Should be added to get the revenue dashboard metrix data. It will show the data of revenue collection information

eChallan-Service:

/echallan-services/eChallan/v1/_expenseDashboard Is added in echallan-service to show the data of expenses in matrix format.

MDMS- changes for the dashboard:

Actions & Role Action Mapping

Actions:

Role Action Mapping:

Available Roles:

Postman collection for dashboards

Postman links

Water

Water service is a DIGIT application that helps and gives flexibility to municipalities and citizens to manage water service requirements like applying for a water connection or searching for water connections. The application goes through various steps as defined by the states. The application is passed through different users who verify and inspect the application details before moving it to the next stage. Based on the state, citizens get notifications (SMS and in-app ). Citizens can also pay application fees or employees can collect the fee for the application.

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 a water service persister config path added to it
PSQL server is running and a database is created to store water connection/application data
knowledge of eGov-mdms service, eGov-persister, eGov-idgen, eGov-sms, eGov-email,eGov-user, eGov-localization, eGov-workflow-service will be helpful.

Key Functionalities

Add old water connection to the system with/without arrears
Create a new Water Connection
Searching for water connections
Notification based on the application state

Environment variables

Description

Interaction Diagram

Configuration Details

MDMS configuration:

master-config.json for water service

ConnectionType:

Two connection types supported Metered and Non metered.

CheckList:

A checklist is used to define the Q&A for the feedback form and its validation.

Category:

A predefined list of categories is allowed.

SubCategory:

A pre-defined list of subcategories is allowed.

Property creation through WNS module

Persister configuration:

Actions & Role Action Mapping

Actions:

Role Action Mapping:

Roles available:

Workflow business service config:

Create businessService (workflow configuration) using the /businessservice/_create. Following is the product configuration for water service:

Indexer config for water service:

The indexer provides the facility for indexing the data to elastic search.

Setup

Write the configuration for the water service.
Provide the absolute path of the checked-in file to DevOps, to add it to the file-read path of egov-indexer. The file will be added to the egov-indexer's environment manifest file for it to be read at the start-up of the application.
Put the indexer config file into the config repo under egov-indexer folder.( )
Run the egov-indexer app, Since it is a consumer, it starts listening to the configured topics and indexes the data.

Notification

Notification will be sent to the property owners and connection holders based on different application states.

Capturing Connection Holders

We can add connection holders to the water connection which will be the owner of the connection. We can fill in the connection holders' details or we can just make the property owner to the connection holder.

The connection holder will get a notification based on a different state of the application. We are pushing the data of the connection holders in the user service too.

Multiple Road Type Support

We can add road-cutting details of multiple roads to the water connection. For each road that goes undercutting process, we have to fill in the road type and the cutting area details. Based on this information, the application one-time fee estimate is calculated.

Deployment Details

Add mdms configs required for water connection registration and restart mdms service.
Deploy the latest version of the ws-services service.
Add water-service and water-services-meter persister yaml path in persister configuration and restart persister service.
Add Role-Action mapping for API’s.

Integration Details

Integration Scope

This ws-service module is used to manage water service connections against a property in the system.

Integration Benefits

Provide backend support for the different water connection registration processes.
Mseva and SMS notifications on application status changes.
The elastic search index for creating visualizations and Dashboards.
Supports configurable workflows.

Integration Steps

To integrate, the host of the ws-service module should be overwritten in the helm chart.
/ws-services/wc/_create should be added as the endpoint for creating water applications/connections in the system.
/ws-services/wc/_search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria.

Reference Docs

Doc Links

Title

Link

API List

Title

Link

(Note: All the APIs are in the same Postman collection therefore the same link is added in each row)