Configure the backend services to expand the scope of NalJalSeva
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Water Connection advance changes are added to allow the customer to pay the advance amount. This amount is adjusted when a new demand is generated. We can enable or disable advance based on the configuration.
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 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
billing-service
ws-calculator
egov-apportion-service
Accepts advance amount during water connection creation and while collecting payment
Creates demand for consumer-type water connection-advance
Adjusts the new demand with existing advance with apportion service
Deploy the latest version of ws-service, ws-calculator, billing-service, egov-apportion-service
Billing service tax head configuration
Tax-head master service configuration
Creating a new bill for the advance amount in BillServiceV2. Removing the following line while adding the bill objects to the list if (billAmount.compareTo(BigDecimal.ZERO) >= 0)
Passing Active status filter for demand search during apportioning in DemandService. DemandCriteria searchCriteria = DemandCriteria.builder().tenantId(tenantId) .status(Demand.StatusEnum.ACTIVE.toString()).consumerCode(Collections.singleton(consumerCode)). businessService(businessService).build();
New Demand audit history API in Demandcontroller. An API that returns the audit history of demandDetails. demand/_history
Create water connection API: Adding a check for payment type advance. If advance, passing a boolean isAdvanceCollection to calculationRequest to water calculator service.
Update water connection API: Adding a check for payment type advance. If advance, passing a boolean isAdvanceCollection to calculationRequest to water calculator service. Adding a check for advance in validateUpdate method to set the current demand to CANCELLED.
Calling estimation service getEstimationMap based on isAdvanceCalculation boolean. If true, reading taxAmount from criteria.getWaterConnection().getAdvance();
Changes in getEstimatesForTax for a new taxHeadCode ADVANCE_COLLECTION with value WS_ADVANCE_CARRYFORWARD
Getting the advance amount in getCalculation with taxHeadCode ADVANCE_COLLECTION
Calling generateDemand method based on isAdvanceCalculation. If true, create a demand object with consumerType “waterConnection-advance“.
Apportion service is used to apportion the amount paid against a bill among the different tax heads based on the implemented algorithm. The default algorithm uses the order of the tax head to apportion, the tax head with the lowest order is apportioned off first while the highest-order tax head is apportioned last.
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 an apportioned persister configuration path added to it
PSQL server is running and a database is created to store apportion audit data
Apportion payment in tax heads of bill
Apportion advance amount in tax heads of demand during demand creation
| Environment variables | Description |
|---|---|
Deploy the latest version of the egov-apportion-service service
Add apportion persister yaml path in persister configuration
There is no separate configuration required. The TaxHead master that is configured in the billing service is only used
Any payment service which wants to divide the paid amount into different tax head buckets can integrate with the apportion service.
Apportions amount in tax heads
To integrate, the host of egov-apportion-service should be overwritten in the helm chart
/apportion-service/v2/bill/_apportion should be called to apportion the bill
/apportion-service/v2/demand/_apportion should be called to apportion advance amount in demands
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row)
| Title | Link |
|---|---|
| Title | Link |
|---|---|
egov.apportion.default.value.order
If set to true will apportion of negative amount first irrespective of tax head order
Collection Service
Billing Service
API Swagger Documentation
/apportion-service/v2/bill/_apportion
/apportion-service/v2/demand/_apportion
The purpose of the NalJalSeva IFIX adapter service is to push the demand, bill, and payment events to IFIX from the NalJalSeva.
NalJalSeva IFIX adapter service is a wrapper for pushing data from the NalJalSeva to IFIX. When demand or payment is generated in the NalJalSeva system, the NalJalSeva IFIX adapter service listens to those topics and it calls the IFIX reference adapter service push API to publish the data to IFIX.
Before you proceed with the configuration, make sure the following pre-requisites are met -
Java 8
Kafka
Spring boot
Pushing demand, bill and payment events to the IFIX adapter
The following topics interact with the NalJalSeva IFIX adapter service - When we create demand for ws-services, then it sends an event as demand for IFIX. If it is expense demand, it sends the event as a bill for IFIX. If it is a ws-services payment, then it sends the event as a receipt for IFIX. If it is an expense payment, it sends the payment as an event for IFIX.
naljalseva-create-demand
naljalseva-update-demand
egov.collection.payment-create
Deploy the following build.
ifix-adapter:v1.0.0-4e24064-14
NalJalSeva IFIX adapter is integrated with the IFIX Reference adaptor service. NalJalSeva IFIX adapter Application internally invokes the IFIX Reference adaptor service to push the data.
NalJalSeva IFIX adapter application triggers IFIX-reference-adapter/events/v1/_push to push the demand, bill, and payment events from NalJalSeva to IFIX.
The main objective of the billing module is to serve the Bill for all revenue Business services. To serve the Bill, Billing-Service requires demand. Demands will be prepared by Revenue modules and stored by billing based on which it will generate the Bill.
Prior knowledge of Java/J2EE.
Prior knowledge of Spring Boot.
Prior knowledge of KAFKA
Prior knowledge of REST APIs and related concepts like path parameters, headers, JSON, etc.
Prior knowledge of the demand-based systems.
The following services should be up and running:
user
MDMS
Id-Gen
URL-Shortening
notification-sms
eGov billing service creates and maintains demands.
Generates bills based on demands.
Updates the demands from payment when the collection service takes a payment.
Deploy the latest image of the billing service available.
In the MDMS data configuration, the following master data is needed for the functionality of billing
Billing service can be integrated with any organization or system that wants a demand-based payment system.
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.
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 used to cancel the created ones or update workflow if configured.
Doc Links
API List
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:
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 is, that if the full amount is paid for any bill then each 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:
Case 2: Apportioning with two years of arrear: If the current financial year is 2014-15. Below are the demands
If any payment is not done, and we generate demand in 2015-16 then the demand structure will be as follows:
Schedulers are designed to run a particular service at a scheduled time, without triggering manually. We can have multiple schedulers for an application. It will consider the GMT format only.
The Python script reads the mdms-read-cronjob JSON from the MDMS service using a token from the CRONJOB user.
Identify the APIs set up in this MDMS using the provided script argument. The script uses the config from the MDMS to call the corresponding API.
A total of 7 schedulers are available in the NalJalSeva:
_schedulerTodaysCollection: This scheduler will run daily to send the day collection amount to the collection employee.
_jobscheduler/true: This is to send the notification to the ULB employee when the bulk demand auto-generation is failed.
_schedulermarkexpensebill: This scheduler is used to mark the expense as paid for the paid expenses once every fortnight.
_schedulernewexpenditure: This is used to send the notification once every fortnight regarding the no of expenditures created.
_schedulermonthsummary: This is to send the monthly summary details to the ULB employee. _schedulerpendingcollection: This is to send the total pending amount details to the respective ULB employee user once every fortnight.
_jobscheduler/false: This is used to generate the bulk demand automatically once every month.
We have 7 different schedulers in NalJalSeva, running in 4 different time slots. We need to set them all to run the same Python scripts with different arguments, which you can find in the file under command -> args.
Configure the scheduler's runtime under the cron -> schedule option.
Example of failedBulkDemand scheduler:
The cron schedule is set to "30 3 5 * *", which triggers the job at 3:30 AM GMT on the 5th day of every month. Converting this to IST, the job runs at 9:00 AM IST on the 5th day of each month.
The command failedbulkdemand is used to instruct the Python script to invoke only the API configured as "failedbulkdemand" in the mdms-read-cronjob.mdms JSON file.
PriorNote: In DevOps, the app name and schedule change based on the cron job file and set time. Arguments are set according to the job name in MDMS configuration.
labels: App: monthly-cronjob Group: mdms-read-cronjob <!-- Stays the same as we use the same Python script
cron: schedule: 30 3 4 * * // This depends on the time we need to run the scheduler
image: repository: api-cronjob tag: v1
command:
python3
cronJobAPIConfig.py
args:
monthly // This is the job name which differs from the requirement based on the scheduler type.
env:
name: JOB_NAME
valueFrom:
fieldRef:
resources: |
requests: {}
The remaining fields will be the same for all the schedulers.
Monthly: This will run and send the notification to the ULB employee or consumer on the 4th of every month morning at 9 am as per the scheduled time.
Fortnightevening: This scheduler will run on the 1st and 15th of every month evening at 6 pm to send the respective notification to the Consumer.
Failedbulkdemand: When the bulk demand generation is failed this scheduler will run and share the message to ULB employees to generate demand manually.
Dailyevening: This scheduler will run daily and send notifications to the collection operator daily.
Check the links below
MDMS object details and configuration:
{
"jobName": "monthly", // This will change based on the job name
"active": "true", // when the "active" param is set to true, the scheduler runs automatically. The scheduler does not run when set to false.
"method": "POST",
"payload": {
"RequestInfo": "{DEFAULT_REQUESTINFO}" // this is common in all the schedulers used to send the request info.
},
"header": {
"Content-Type": "application/json" // This is a common property for all schedulers.
}
}
Need to create a user with CRONJOB as name and type as SYSTEM and ROLE as SYSTEM AND EMPLOYEE here is the sample curl to create the user.
A Build ID (similar to the ID given below) is created when you build the cronjob. api-cronjob:develop-c0aa08a-2
Take the id only from this instead of a complete name like develop-c0aa08a-2. This id will be used as the id for your respective yaml files and the same will be deployed to the required environment to test the cron job.
For example:
Mdms-read-cronjob:develop-c0aa08a-2,
failedbulkdemand:develop-c0aa08a-2,
Fortnightevening:develop-c0aa08a-2,
monthly:develop-c0aa08a-2 Note: develop-c0aa08a-2 is the common build id for all the files which you are using.
Run the cronjob manually - Steps
Delete the existing cron jobs if they already exist with the same name.
kubectl delete cronjob mdms-read-cronjob -n mgramseva
Deploy these builds in QA environments, which are related to cronjob schedulers
mdms-read-cronjob:develop-c0aa08a-2, failedbulkdemand:develop-c0aa08a-2, fortnightevening:develop-c0aa08a-2,monthly:develop-c0aa08a-2
Test the cron job scheduler - Steps
kubectl get cronjob -n mgramseva -- to check the list of cron jobs
Create the job manually to test the messages. Below are the commands to create the jobs.
A message is received for the respective schedulers each time we run it.
We can increase the number to test again like failedbulkdemand-manually-1 next it will be failedbulkdemand-manually-2.
kubectl create job --from=cronjob/failedbulkdemand failedbulkdemand-manually-1 -n mgramseva
kubectl create job --from=cronjob/fortnightevening fortnightevening-manually-1 -n mgramseva
kubectl create job --from=cronjob/mdms-read-cronjob mdms-read-cronjob-manually-1 -n mgramseva
kubectl create job --from=cronjob/monthly monthly-manually-1 -n mgramseva
kubectl get job -n mgramseva -- to check the list of jobs
To check the cronjob image
kubectl describe cronjob mdms-read-cronjob -n mgramseva
To delete specific job
kubectl delete jobs mdms-read-cronjob-manually-1 -n mgramseva
Water Connection Penalty changes are added to get the penalty amount after the due date. The due date is configurable and penalty enable and disable are also configurable. If we want to have the penalty we can enable or we can disable it through configuration.
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 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
billing-service
Calculate water charges and taxes based on the billing slab.
Calculate meter reading charge for water connection
Generate demand for penalty feature
Scheduler for generating the demand(for non-metered connection)
Deploy the latest version of ws-service and ws-calculator
Add water-persist.yml & water-meter.yml file in the config folder in git and add that path in persister. (The file path is to be added in the environment yaml file in a param called persist-yml-path )
Billing service tax head configuration
ws-calculator penalty configuration:
Use case 1: Fixed percentage on outstanding without penalty
Use case 2: Fixed percentage on the current month
Use case 3: Fixed percentage on outstanding including penalty
Note: All the above are applied to the running month only.
Use case 4: Fixed percentage on outstanding applied for every month on the outstanding amount respectively (not implemented)
Use case 1: "type": "Fixed", "subType": "outstandingWithoutPenalty"
Use case 2: "type": "Fixed", "subType": "currentMonth",
Use Case 3: "type": "Fixed", "subType": "outstanding", We have Total 4 types of penalty in the system:
Fixed - Current month: This type of penalty is applied to the current month's amount based on the rate (%) given in the configuration.
Fixed - outstanding: This is the penalty applied on the total outstanding amount including previously applied penalties based on the rate (%) given in the configuration.
Fixed - outstandingWithoutPenalty: This is the penalty applied on the total outstanding amount excluding previously applied penalties based on the rate (%) given in the configuration.
Flat - Current month: This type of penalty is applied to the current month's amount based on the amount given in the configuration.
Flat - outstanding: This type of penalty is applied to the total pending amount till the current month's amount based on the amount given in the configuration.
Curl to create:
The NalJalSeva Rollout Dashboard Scripts gather data from the NalJalSeva database and services for the Metabase Rollout dashboard. This Python script transfers data daily from NalJalSeva to a database table, which is then used to create visual dashboards in Metabase.
Before you proceed with the configuration, make sure the following pre-requisites are met -
Python 3.9
NalJalSeva DB
NalJalseva user details who has access to MDMS service API
NalJalSeva MDMS service access
Collects data on specific points and inserts it into the rollout dashboard table in the database. User Story details:
IFIX-485: [1.0.1] Rollout Dashboards on MetabaseQA SIGNOFF
Deploy the following build -
rollout-dashboard-cronjob:develop-2a8d6a44-3
NalJalSeva Rollout Dashboard is not directly integrated with any of the services except this scripts fetch the data from the MDMS service and NalJalSeva DB
Configure the username, tenantId, and password of the user for which mdms service access is available in the environment-specific yaml file in DevOps. Refer to the example below -
Follow the steps below to run this in the local environment.
The Python script inserts the data into the table “roll_out_dashboard“ in NalJalSevaDb for every run, it cleans the old data and creates new data.
This table has to be loaded into the metabase by adding NalJalSeva DB to the metabase.
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.
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.
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 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.
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.
To enhance the data Collection, the domain index specified in the configuration is queried with the right arguments and the response data is obtained, transformed and set.
Domain configuration
Topic context configuration
transform_expense.electricity_bill_v1 configuration
transform_expense.om_v1 configuration
transform_expense.salary_v1 configuration
transform_ws_v1 configuration
Below is the list of configurations made changes or added newly for NalJalSeva.
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.
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
Configure the Kafka topics in the environments or Ingest pipeline application properties as shown below.
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:
Events push is used to manually push data from the NalJalSeva Adapter to the iFIX Adapter. Make sure the existing events are cleared or deleted to ensure reliable data transfer. Refer to the documentation here to find details on how to clean up the event data - . Post events clean up the system loads the project code for all the tenants. Then it pushes the data to the iFIX adapter.
Access to Kubectl of the environment targetted
Postman scripts
The Postman script fetches the data from the existing NalJalSeva database and passes it to the NalJalSeva adapter, from where it is pushed to the iFIX adapter.
Pass the offset and limits based on the total transactions present in the database.
Here, TenantId is mandatory. Limit and offset can vary based on the requirement. Business service is not required.
This fetches all payment records irrespective of tenant based on the limit and offset. The data is passed to the IFIX adapter one after the other.
The above curl fetches the demands based on the tenant ID and business service passed. Business service can be ‘WS' or ‘EXPENSE.SALARY’ or 'EXPENSE.MISC’ or 'EXPENSE.OM’ etc. For WS it is saved as demand and for EXPENSE it is saved as bill.
eChallan system enables employees to generate the challans for Adhoc services so that the payment can be recorded into the system along with service-specific details.
It also enables citizens to make payments online based on challan numbers.
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 an eChallan persister config path added to it
PSQL server is running and a database is created to store eChallan data
Allow employees to capture service details for miscellaneous services and collect payment
Allow employees to update/cancel challan
Search, download, and print echallan / bill for miscellaneous service
Generate and view echallan / bill pdf for all miscellaneous and ad-hoc services
Send an SMS and an email bill notification to the citizen with a payment link and bill link
| Environment variables | Description |
|---|
Actions
Role Action Mapping
Roles available:
Localization:
Add MDMS configurations required for eChallan Service and calculator and restart the MDMS service.
Deploy the latest version of eChallan Service and calculator.
Add eChallan Service persister yaml path in persister configuration and restart persister service.
Add role-action mapping for APIs.
Add pdf configuration file for challan and bill.
The eChallan service is used to generate e-challans / bills for all miscellaneous/ad-hoc services which citizens avail from ULBs.
Can perform service-specific business logic without impacting the other module.
Allows capturing the unique identifier of the entity for which the challan is generated.
In the future, if we decide to make the application accessible to citizens, it can be done effortlessly.
Workflow or service-specific workflow can be enabled at the challan service level at any time, without the need for any design changes.
Allow employees to update/cancel challan.
To integrate, overwrite the host of the echallan-services module in the Helm chart.
Add the echallan-services/eChallan/v1/_create as the create endpoint for creating eChallan in the system.
Add the echallan-services/eChallan/v1/_search as the search endpoint. This method handles all requests to search existing records depending on different search criteria.
Add echallan-services/eChallan/v1/_update as the update endpoint. This method is used to update fields in existing records or to update the status of applications based on workflow.
/echallan-services/eChallan/v1/_expenseDashboard Is added in echallan-service to show the data of expenses in matrix format.
/echallan-services/eChallan/v1/_chalanCollectionData it is added to get the main monthly dashboard data for the expense.
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row).
We use re-indexing to transfer all data to the appropriate indexer. This process involves two steps:
Run the connector from the playground.
Call the legacy indexer service, which internally queries the plain search service to retrieve data and send it to the appropriate indexer.
Access to kubectl of the environment targeted
Plain search APIs in the respective services
NalJalSeva uses 3 main indexes for re-indexing:
Water-services
e-challan-services
dss-collection_v2
ws-services re-indexing - Kafka Connector Curl to be run from playground pod
Plain Search Call
EChallan-Reindexing
Kafka Connector Call to be run from Playground pod:
Legacy Index call from postman:
Dss collection v2 re-indexing - Kafka Connector call to be run from playground pod
payment re-indexing run from postman call
| param | value | description |
|---|---|---|
| Title | Link |
|---|---|
| Title | Link |
|---|---|
| TaxHead | Amount | Order | FullPayment(2000) | PartialPayment1(1500) | PartialPayment2(750) | PartialPayment2withrebate(500) |
|---|---|---|---|---|---|---|
| TaxHead | Amount | TaxPeriodFrom | TaxPeriodTo | Order | Purpose |
|---|---|---|---|---|---|
| TaxHead | Amount | TaxPeriodFrom | TaxPeriodTo | Order | Purpose |
|---|---|---|---|---|---|
helps to define the pattern for the schedule cron.
fieldPath:
"url":", // This is the respective service URL to call that service as per the scheduler.
Here is the configuration for all the schedulers: .
.
transform_expense.electricity_bill_v1 configuration:
transform_expense.om_v1 configuration:
transform_expense.salary_v1 configuration:
transform_ws_v1 configuration:
For details on services such as re-indexing and Kafka connection, refer to the document.
| Postman links |
|---|
| Docs | APIs |
|---|
bs.businesscode.demand.updateurl
Each module’s application calculator should provide its updated URL. if not present then a new bill will be generated without making any changes to the demand.
bs.bill.billnumber.format
BILLNO-{module}-[SEQ_egbs_billnumber{tenantid}]
IdGen format for bill number
bs.amendment.idbs.bill.billnumber.format
BILLNO-{module}-[SEQ_egbs_billnumber{tenantid}]
is.amendment.workflow.enabled
true/false
enable disable workflow of bill amendment
Id-Gen service
url-shortening
MDMS
/demand/_create, _update, _search
/bill/_fetchbill, _search
/amendment/_create, _update
Pt_tax
1000
6
1000
1000
750
750
AdjustedAmt
1000
-250
-750
-750
RemainingAMTfromPayableAMT
0
0
0
0
Penality
500
5
500
500
AdjustedAmt
500
-500
RemainingAMTfromPayableAMT
1000
250
Interest
500
4
500
500
AdjustedAmt
500
-500
RemainingAMTfromPayableAMT
1500
750
Cess
500
3
500
500
AdjustedAmt
500
-500
RemainingAMTfromPayableAMT
2000
1250
Exm
-250
1
-250
-250
AdjustedAmt
-250
250
RemainingAMTfromPayableAMT
2250
1750
Rebate
-250
2
-250
-250
AdjustedAmt
-250
250
RemainingAMTfromPayableAMT
2500
750
Pt_tax
1000
2014
2015
6
Current
AdjustedAmt
0
Penality
500
2014
2015
5
Current
AdjustedAmt
0
Interest
500
2014
2015
4
Current
AdjustedAmt
0
Cess
500
2014
2015
3
Current
AdjustedAmt
0
Exm
-250
2014
2015
1
Current
AdjustedAmt
0
Pt_tax
1000
2014
2015
6
Arrear
AdjustedAmt
0
Pt_tax
1500
2015
2016
6
Current
AdjustedAmt
0
Penalty
600
2014
2015
5
Arrear
AdjustedAmt
0
Penalty
500
2015
2016
5
Current
AdjustedAmt
0
Interest
500
2014
4
Arrear
AdjustedAmt
0
Cess
500
2014
3
Arrear
AdjustedAmt
0
Exm
-250
2014
1
Arrear
AdjustedAmt
0
| This variable is to check the event Notification enabled or not. |
| This variable is to get the default limit value |
| This variable to check the max limit value. |
| This variable will give the business service name while creating the workflow. |
| This variable is to check the SMS notifications are enabled or not. |
| This variable is used to check the localizations are state level or not. |
| variable for collection list screen link for notifications |
| variable for monthly summary screen link for notifications |
| variable for new expenditure screen link |
| variable for paid expenditure screen link |
| variable for mnaul bulk demand generation screen link |
| variable for today’s collection screen link |
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.
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
Location
Localization
Id-Gen
Billing-service
URL-shortener
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
Consolidation
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).
MDMS CONFIG: https://github.com/egovernments/egov-mdms-data/tree/DEV/data/pb/PropertyTax
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 - property-services-registry.yml
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.
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 ticket, a different workflow configuration is used. For each use case, to identify which workflow to use can be identified from this mdms file.
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:
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
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
Property service can be integrated with any organization or system that wants to maintain a record of the property and collect taxes with ease.
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.
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.
User OTP service is used to generate OTP for user login, user registration and user password change.
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.
The following services should be up and running:
user
MDMS
Id-Gen
URL-Shortening
notification-sms
The user-otp service validates the user details and request type and sends OTP for a particular action.
Deploy the latest image of the user-otp service available.
User OTP service can be integrated with any organization or system that wants OTP-based validation for user login and registration.
Easy to create and simple process of generating bills from demands.
Easy to generate OTPs to validate mobile numbers for registration, login and password reset with simple API calls
OTP can be generated by calling /user-otp/v1/_send
Vendor Registry is a system that enables ULB employees to create and search vendors i.e. Desludging Operator (DSO) and driver entities with appropriate vehicle Entities for FSM Applications. This document contains details on how to set up the Vendor and describes the functionalities provided.
Before you proceed with the configuration, make sure the following pre-requisites are met -
Java 8
The Kafka server is up and running
egov-persister service is running and has a vendor-persister config path added to it
PSQL server is running and a database is created to store FSM Application data
The following services should be up and running:
egov-mdms-service
egov-user-service
boundary-service
vehicle
Added payment payment preference and agency attributes for DSO
Added gender attribute in the create and update APIs for Vendor
Updated the Vendor search API to add vehicleCapacity in the search parameter to search all vendors matching the vehicle capacity specified in the search parameter.
Deploy the latest version of the vendor
Add vendor-persister.yml file in the config folder in git and add that path in persister. (The file path is to be added in the environment yaml file in a param called persist-yml-path ) and restart egov-persister-service.
Integrate the below changes in vendor-persister.yml - https://github.com/egovernments/configs/commit/95dd26f926ec44d07448926ee4b6b7e031847a57
After adding Actions and role-action mappings, restart the egov-mdms-service.
Configurations we can manage through values.yml of the vendor in the infra ops repo are as follows: values.yml for a vehicle can be found.
Configurations sample in Values.yml
DSO for FSM System is a vendor, For every city/ULB DSO should be created with the Representative details as owner, associated vehicles and drivers.
Sample Curl
Any system or DIGIT module can integrated with Vendor Service, which helps to manage the Vendor with the vehicles, drivers and owner for the representative and login for the representative/owner to log into the system to carry our role-specific operations
Validation of DSO/Vendor availability
Fetch the vehicle assigned to the DSO
Fetch the Drivers assigned to the DSO
FSM to call vendor/v1/_search to fetch the DSOs
FSM can call vendor/v1/_search to fetch the DSOs and the respective vehicles and drivers
API List
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.
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
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.
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 )
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
Following are the properties in the application.properties file in the egov-user-events service which is configurable.
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>”
OTHERS - Events that don’t belong to the types mentioned above.
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: https://github.com/egovernments/egov-mdms-data/tree/master/data/pb/mseva
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.
eGov-user-events can be integrated with any organisation or system which wants to send the events generated for the user in the system
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.
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.
/egov-user-event/v1/events/lat/_update API is use to update the last-login-time of the user. We store the last login time of the user through this API thereby deciding which notifications have been read.
(Note: All the APIs are in the same Postman collection therefore same link is added in each row).
User service is responsible for user data management and providing functionality to log in and log out of the DIGIT system.
Before you proceed with the configuration, make sure the following pre-requisites are met -
Java 8
Kafka server is up and running
Encryption and MDMS services are running
PSQL server is running and the database
Redis is running
Store, update and search user data
Provide authentication
Provide login and logout functionality to the NalJalSeva platform
Store user data PIIs in encrypted form
Setup latest version of egov-enc-service and egov-mdms- service
Deploy the latest version of the egov-user service
Add Role-Action mapping for APIs
The following properties in the application.properties file in user service are configurable.
User data management and functionality to log in and log out into the DIGIT system using OTP and password.
Providing the following functionality to citizen and employee-type users
Employee:
User registration
Search user
Update user details
Forgot password
Change password
User role mapping (Single ULB to multiple roles)
Enable employees to login into the DIGIT system based on the password.
Citizen:
Create user
Update user
Search user
User registration using OTP
OTP based login
To integrate, the host of egov-user should be overwritten in the helm chart.
Use /citizen/_create endpoint for creating users into the system. This endpoint requires the user to validate his mobile Number using OTP. The first OTP will be sent to his mobile number and then that OTP will be sent as otpReference in the request body
Use /v1/_search and /_search endpoints to search users in the system depending on various search parameters
Use /profile/_update for updating the user profile. The user will be validated (either by OTP-based validation or password validation) when this API is called
/users/_createnovalidate and /users/_updatenovalidate are endpoints to create user data into the system without any validations (no OTP or password required). They should be strictly used only for creating/updating users internally and should not be exposed outside
Forgot password: In case the user forgets the password it can be reset by first calling /user-otp/v1/_send which will generate and send OTP on the employee’s mobile number, the password can then be updated using this OTP by calling the API /password/nologin/_update in which a new password along with the OTP has to be sent.
Use /password/_update to update the existing password by logging in. In the request body, both old and new password has to be sent. Details of the API can be found in the attached Swagger documentation
Use /user/oauth/token for generating tokens, /_logoutfor logout and /_details for getting user information from his token
Multi-Tenant User: The multi-tenant user functionality allows a user to perform actions across multiple ULBs. For example, an employee belonging to Amritsar can perform the role of Trade License Approver for Jalandhar by assigning a tenant-level role of tenantId pb.jalandhar to him. Following is an example of such a user:
If an employee has a role with a state-level tenantId he can perform actions corresponding to that role across all tenants
Refresh Token: Whenever the /user/oauth/token is called to generate the access_token , along with the access_token one more token is generated called refresh_token . The refresh token is used to generate new access_token whenever the existing one expires. Till the time the refresh token is valid the user won’t have to log in even if his access_token get’s expired, as it will be generated using refresh_token. The validity time of the refresh token is configurable and can be configured using the property: refresh.token.validity.in.minutes
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row)
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.
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
billing-service
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)
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.
Master Config:
Billing Slabs:
Criteria -
connection type
building type
calculation attribute
property usage type
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.
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.
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.
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.
After pushing the data into Kafka, the system consumes the records based on the batch configuration. For example, if the batch configuration is set to 50, the system will consume 50 calculation criteria at a time.
After consuming the records (calculation criteria), the system processes the batch to generate the demand. If the batch processing is successful, the processed consumer codes are logged.
If some records fail in the batch, the system pushes the batch into the dead letter batch topic. From there, the batch is processed one record at a time.
If the record is successful, the system logs the consumer code. If the record fails, the data is pushed into a dead-letter single topic.
Dead letter single topic contains information about failure records in Kafka.
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.
We need to configure the batch size for Kafka consumers. This configuration determines how much data is processed at a time.
The ws-calculator is integrated with ws-service. ws-services internally invoke the ws-calculator service to calculate and generate demand for the charges.
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.
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.
/waterCalculator/_jobscheduler API is used to generate demand for non-metered connections. This API can be called periodically.
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row).
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.
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.
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 |
|---|---|
MDMS configuration:
mdms-mgramseva/data at DEV · egovernments/egov-mdms-data 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 mdms-mgramseva/PTWorkflow.json at DEV · egovernments/egov-mdms-data
Persister configuration:
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:
Setup
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.
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.
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.
Create businessService (workflow configuration) according to trade water connection, modify water connection
Add ws-service indexer yaml path in indexer service configuration and restart indexer service.
This ws-service module is used to manage water service connections against a property in the system.
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.
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.
/ws-services/wc/_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.
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row)
Users are redirected to this screen once they select the preferred language in the previous screen.
Link → {base url}/mgramseva/selectLanguage/login
Users enter the registered Phone Number and Password.
Click on Continue.
First-time login users navigate to Reset Password Page.
Log in with the default password
YES →
NO →
Primary Files:
| Fields | Validations |
|---|
Stack
1 → Language selection screen. + Login screen.
Pop → Language selection screen.
Widgets utilized from the library
NalJalSeva is a Hybrid Application(web + App(Android + IOS)) built utilising Open Source Framework Flutter.
CrossPlatform Application
Faster
Single Codebase - Easy To Maintain
Large Community Support
Open Source
Flutter Version Utilised for Development
Flutter 2.2.3
Languages - > Dart 2.13.4
Users land on the Language Selection screen.
Link → {base url}/mgramseva/selectLanguage
Users can switch to different languages that the application supports.
Primary files:
Secondary files:
LocalStorage
0 → Language selection screen
Pop → Application closes
Widgets utilized from library
Users are redirected to this screen once they click on the Change Password option in the sidebar app drawer.
Link → {base url}/mgramseva/home/changepassword
Enter the Current Password
Enter and Confirm a New Password to set the login credentials for the next time login
Click the Change Password Button. The user login password is set to the new password.
This feature helps match the user password to the requirements and checks if the password contains
Minimum 6 digits
At least one special character ( !#$%^&...)
At least one letter
At least one number
Primary Files:
Stack
1 → Home Screen. + Change Password Screen
Pop → Home Screen
Widgets utilised from the Library
Users are navigated to the Edit Profile screen once they click on the option on the sidebar app drawer.
Link - → {base url}/mgramseva/home/editProfile
User can change their profile name, gender and email on this screen
Click on the Save button triggers a Details Saved Successfully message on the screen and saves the changes to the profile.
Primary Files:
| Fields | Validations |
|---|
| End Point | Request Method | Request Info |
|---|
Stack
1 → Home Screen. + Edit Profile Screen
Pop → Home Screen
Widgets utilised from the Library
| name | value | description |
|---|---|---|
| MDMS Fields | Description |
|---|---|
| name | value |
|---|---|
| Title | Link |
|---|---|
| Title | Link |
|---|---|
| Property | Value | Description |
|---|---|---|
| Description | name in values.yml | Current Value |
|---|---|---|
| API |
|---|
| Property | Value | Remarks |
|---|---|---|
| API Docs |
|---|
| APIs |
|---|
| Property | Value | Description |
|---|---|---|
| Docs | APIs |
|---|---|
| Environment variables | Description |
|---|
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.
| Docs | APIs |
|---|
config-mgramseva/water-persist.yml at DEV · egovernments/configs configs/water-meter.yml at master · egovernments/configs
The indexer provides the facility for indexing the data to elastic search. config-mgramseva/water-service.yml at DEV · egovernments/config-mgramseva
Write the configuration for the water service. config-mgramseva/water-service.yml at DEV · egovernments/config-mgramseva
Put the indexer config file into the config repo under egov-indexer folder.(GitHub - egovernments/configs at master )
| Title | Link |
|---|---|
| Title | Link |
|---|---|
| End Point | Request Method | Request Info |
|---|
| Widgets | File Path | Description |
|---|
Link to Learn Flutter -
Click on to navigate to the next screen.
| Key | Stored Data |
|---|
| API EndPoint | Input Params (Modules) | Description |
|---|
| Widgets Library |
|---|
| Fields | Validation |
|---|
| End Point | Request Method | Request Info |
|---|
| Widgets | File Path | Description |
|---|
| Widgets | File Path | Description |
|---|
is.workflow.enabled
true/false
enable disbale workflow
PT.CREATE
the name should match the config name in the workflow businessservice JSON
PT.LEGACY
PT.UPDATE
businessService
Name of workflow config
initialAction
Indicate the start(initial) action of the particular workflow mention in businessService.
inWorkflowStatusAllowed
This field indicate whether the property with application status as “inWorkflow” can be use with water and sewerage connection creation. If this field is true then for that particular use case, the property with “inWorkflow” status can be use with water and sewerage connection creation and vice versa
enable
If this filed is set as true, then the other fields associate with the particular object is use for property creation.
egov.idgen.ack.format
PB-AC-[cy:yyyy-MM-dd]-[SEQ_EG_PT_ACK]
egov.idgen.mutation.format
PB-MT-[CITY]-[SEQ_EG_PT_MUTATION]
egov.idgen.assm.format
PB-AS-[cy:yyyy-MM-dd]-[SEQ_EG_PT_ASSM]
egov.idgen.ptid.format
PB-PT-[cy:yyyy-MM-dd]-[SEQ_EG_PT_PTID]
citizen.allowed.search.params
accountId,ids,propertyDetailids,mobileNumber,oldpropertyids
employee.allowed.search.params
accountId,ids,propertyDetailids,mobileNumber,oldpropertyids
USER Service
url-shortening
MDMS
Billing-service
Location
Workflow
Persister
Localization
Id-Gen service
/Property/_create
/Property/_update
/property/_search
expiry.time.for.otp
3000
Expiry time of the otp
Kafka Consumer Group
SPRING_KAFKA_CONSUMER_GROUP_ID
egov-vendor-services
kafka topic to which service push data to save new Vendor
PERSISTER_SAVE_VENDOR_TOPIC
save-vendor-application
mdms service host
EGOV_MDMS_HOST
egov-mdms-service from egov-service-host
Vehicle Service host
EGOV_VEHICLE_HOST
vehicle from egov-service-host
User service host
EGOV_USER_HOST
egov-user-service from egov-service-host
Location Service Host
EGOV_LOCATION_HOST
egov-location from egov-service-host
kafka.topics.persister.save.events
save-user-events
This is the persister topic onto which user-events pushes records for persistence. This is for creating events.
kafka.topics.persister.update.events
update-user-events
This is the persister topic onto which user-events pushes records for persistence. This is for updating events.
kafka.topics.lat.details
user-events-lat
This is the persister topic onto which user-events pushes records for persistence. This is for storing last-access-time / last-login-time of the user.
kafka.topics.save.events
persist-user-events-async
Topic to which the user-events consumer is subscribed. Producers willing to create events must push records to this topic.
kafka.topics.update.events
update-user-events-async
Topic to which the user-events consumer is subscribed. Producers willing to update events must push records to this topic
mseva.notif.search.offset
0
Default pagination offset.
mseva.notif.search.limit
200
Default pagination limit.
egov.user.search.default.size
10
default search record number limit
citizen.login.password.otp.enabled
true
whether citizen login otp based
employee.login.password.otp.enabled
false
whether employee login otp based
citizen.login.password.otp.fixed.value
123456
fixed otp for citizen
citizen.login.password.otp.fixed.enabled
false
allow fixed otp for citizen
otp.validation.register.mandatory
true
whether otp compulsory for registration
access.token.validity.in.minutes
10080
validity time of access token
refresh.token.validity.in.minutes
20160
validity time of refresh token
default.password.expiry.in.days
90
expiry date of a password
account.unlock.cool.down.period.minutes
60
unlock time
max.invalid.login.attempts.period.minutes
30
window size for counting attempts for lock
max.invalid.login.attempts
5
max failed login attempts before account is locked
egov.state.level.tenant.id
pb
egov.waterservice.createwaterconnection
This variable contains the kafka topic name which is used to create new water connection application in the system.
egov.waterservice.updatewaterconnection
This variable contains the kafka topic name which is used to update the existing water connection application in the system.
egov.waterservice.updatewaterconnection.workflow.topic
This variable contains the kafka topic name which is used to update the process instance of the water connection application.
egov.idgen.wcapid.name
This variable contains the idgen format name for water application
egov.idgen.wcapid.format
This variable contains the idgen format for water application ex:- WS/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
egov.idgen.wcid.name
This variable contains the idgen format name for water connection
egov.idgen.wcid.format
This variable contains the idgen format for water connection ex:- WS_AP/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
API Swagger Documentation
Water Calculator Service
Water-Service Calculator
/ws-services/wc/_create
/ws-services/wc/_update
/ws-services/wc/_search
/ws-services/wc/_submitfeedback
/ws-services/wc/_getfeedback
/ws-services/wc/_revenueDashboard
/ws-services/wc/_revenueCollectionData
|
| username: {} password:{} scope: read grant_type: password tenantId: {} userType: EMPLOYEE |
| State Information for From MDMS Service |
ex : | Localization codes |
|
| To fetch details State info Logo background Image Languages supported |
| ALL the necessary Modules, with locale key and tenant Id | To Load the Localized data |
Button Bar |
| This variable is to check the SMS notifications are enabled or not. |
| This variable is to check the email notifications are enabled or not. |
| This variable is for download bill reciept path |
| This variable is to get the common link to the home page |
Current Password* | No Validation |
Set a New Password* |
|
Confirm New Password* | Match with New Password |
|
| "userName": {}, "existingPassword": {}, "newPassword": {}, "tenantId": {}, "type": {} |
| Text Field |
| Button |
| Text Field |
| Button |
| Text Field |
| Button |
| Radio Buttons for options |
Phone Number* |
|
Password* |
|
Name |
|
Email ID |
|
|
| "user": { "id": {}, "userName": {}, "salutation": null, "name": {}, "gender": {}, "mobileNumber": "9191919146", "emailId": {}, "altContactNumber": null, "pan": null, "aadhaarNumber": null, "permanentAddress": null, "permanentCity": null, "permanentPinCode": null, "correspondenceAddress": null, "correspondenceCity": null, "correspondencePinCode": null, "active": true, "locale": null, "type": "EMPLOYEE", "accountLocked": false, "accountLockedDate": 0, "fatherOrHusbandName": null, "relationship": null, "signature": null, "bloodGroup": null, "photo": null, "identificationMark": null, "createdBy": {}, "lastModifiedBy": {}, "tenantId": {}, "roles": [ {} ], } |
Users are redirected to the Update Password screen once they log in successfully the first time.
Link: → {base url}/mgramseva/selectLanguage/login/updatepassword
Enter the OTP sent on the user’s 10-digit mobile number.
Set the new password for logging into the application.
Click on Change Password to apply new password credentials for the user.
Users can see the allocated Gram Panchayat name and code in the table.
This feature helps match the user’s password and check if the password contains
Minimum 6 digits
At least one special character ( !#$%^&...)
At least one letter
At least one number
Primary Files:
Fetch the tenants from MDMS, based on the user roles in the user request filtering the tenants by comparing tenant IDs.
1 → Language selection screen + Login screen + Update password + Update password success
Pop → Login
Widgets utilized from the library
View →
Controller →
Users are redirected to the home page screen after successful login. This screen consists of multiple sections and user interactions. If the user is mapped to multiple tenants then a dropdown appears. The user can select the desired tenant to proceed further. Once the user selects the tenant, the feature cards are displayed on the screen based on the roles mapped for the selected tenant.
YES → WalkThrough/User Guidance Enabled
NO → Home Screen
If the user logs in for the first time a system walkthrough begins automatically.
Otherwise, users can view walkthroughs at any time by clicking on the help icon.
Create a global key for each card.
Create placeholder cards, pointers and description widgets.
On click, the position of the card is determined and the placeholder card appears on the overlay exactly.
Primary Files:
punjab-mgramseva/HomeWalkThroughContainer.dart at develop · egovernments/punjab-mgramseva,
punjab-mgramseva/HomeWalkThroughList.dart at develop · egovernments/punjab-mgramseva
Next → Changes the active index of the global key and repeat the same process outlined in the implementation logic skip,
End → closes the overlay
Home Screen - consists of multiple feature cards
Cards are displayed based on Role Access.
The home screen also consists of notifications. The notifications are customized for each user ID and user role.
Individual API calls are made with the user ID and with the user role that merges both and notifications are displayed accordingly.
Primary Files:
Users are redirected to this screen once they click on the Forgot Password link on the home screen.
This feature allows users to request OTP by entering a valid (registered) mobile number.
Follow the steps below to set a new password -
Click on the Forgot Password link visible on the login screen
Enter the registered mobile number
The remaining steps are explained in the Reset Password section.
Primary Files:
punjab-mgramseva/ForgotPassword.dart at develop · egovernments/punjab-mgramseva
2 → Language Selection Screen. + Login Screen + ForgotPassword
Pop → Login Screen Screen
Widgets utilised from the Library
Users are redirected to this screen once they click on the Continue button on the Forgot Password screen.
Link - → {base url}/mgramseva/selectLanguage/login/forgotPassword/resetPassword
Enter the OTP sent on the user’s 10-digit mobile number.
Set the new password for logging into the application.
Click on Change Password to apply new password credentials for the user.
This feature helps to provide the users with a clear indication of what the password should contain. Acceptable passwords must contain -
Minimum 6 digits
At least one special character ( !#$%^&...)
At least one letter
At least one number
Primary Files:
1 → Language Selection Screen. + Login Screen + Forgot Password + Reset Password.
Pop → Forgot Password Screen.
Widgets utilised from the Library
Enables employees to add expenses - the process of onboarding the end-users. Add Expenses card is available on the home screen for defined user roles having the EXPENSE PROCESSING permission.
Link → {base url}/mgramseva/home/addExpense
Clicking the Add Expense Record tile/card on the home screen navigates the user to the Add Expenses screen. The user enters the required details to add the expenses for the vendors.
If a user logs in for the first time then a walkthrough is populated following the same logic as in the home screen.
Clicking on the Submit button navigates the user to the Expenditure Added Successful acknowledgement screen.
This feature allows the user to take a picture or choose a single file. The Image Picker plugin is used to implement this.
Whenever this application is used on mobile, it prompts the user with two options - Camera and File Picker. If the application is opened on desktop or laptop browsers, the camera option is not available. The user has to select an image from the folder.
The maximum supported file size is 5 MB.
For validating the form we use the Form widget. Once the user selects a bill date the Bill Pay option is enabled. Otherwise, the auto-validation process is enabled. Based on the bill date, the party selection date is enabled. If the user selects the party selection date first, the bill date can be selected only after entering the party date. Whenever the bill paid option is true, the paid date field is enabled and mandatory. The date selection range allows date input only after the bill date and before the current date.
Primary Files -
Note: All fields are validated on Submit apart from the Mobile number which gets validated on change.
1 → Home Screen. + Add Expense Screen
Pop → Home Screen
Widgets utilised from the Library
Users are redirected to this screen once they click on the Collect Payment card or the Update Consumer Details card or the Download Bills and Receipts card on the home screen.
Link
→ {base url}/mgramseva/home/householdSearch?Mode=collect
→ {base url}/mgramseva/home/consumersearchupdate?Mode=update
→ {base url}/mgramseva/home/householdReceiptsSearch?Mode=receipts
Users can search the consumer/connection with their Mobile Number / Name / Old Connection ID / New Connection ID ( Search with any one of these)
Click on Search to get the household details of the Consumer/Connection.
Primary Files:
punjab-mgramseva/SearchConnection.dart at develop · egovernments/punjab-mgramseva
| Fields | Validations |
|---|---|
1 → Home Screen. + Search Connection Screen
Pop → Home Screen
Widgets utilised from the Library
Enables employees to create new Consumers or Connections - The process of onboarding the end-users.
Link
→ {base url}/mgramseva/home/consumercreate
The Create Consumer card is available on the home screen as per the defined user role.
Click on the Consumer Create card navigates the user to the consumer creation screen.
Users enter the required details for the creation of a consumer.
If a user logs in for the first time then a walkthrough is populated following the same logic as in the home screen.
Primary Files -
punjab-mgramseva/WalkFlowContainer.dart at develop · egovernments/punjab-mgramseva
punjab-mgramseva/walkthrough.dart at develop · egovernments/punjab-mgramseva
| Fields | Validations |
|---|---|
Note: All fields are validated on Submit except the Phone number which gets validated on change.
Consumer creation involves 2 sequential processes
Property Creation
Water connection Creation
After creating a property, the Property ID is linked to the WaterConnection Request JSON.
Water connection creation is of two types:
A metered connection that requires Meter ID and meter installation Date/ Last Meter Reading Date and an optional field to capture meter reading.
Non-Metered Connection which requires the last billing cycle as mandatory params captured in the field as shown below.
Users can switch between connection types by selecting a desired value from the Service Type DropDown.
For consumers, users can give either Advance or Arrears along with a Penalty by selecting the respective option using the radio buttons. If a user selects Advance, the field is shown or else Arrears and Penalty will be shown where the user can enter the required amount.
The radio button “Advance” will be displayed only if the config flag “Advance enabled” is activated in the MDMS billing service.
The “Penalty” field (displayed along with arrears) on selecting the Arrears radio button, will be displayed only if the config flag “Penalty enabled” is activated in the MDMS billing service. The user will be able to see the arrears field and can enter the arrears amount.
billing-service/demand/_search API is used for calculating the advance amount for the current bill. We can get the advance amount if taxHeadMasterCode contains 'WS_ADVANCE_CARRYFORWARD'. Here we have two properties - collection amount and tax amount. The tax amount is the advance amount that is added to the system and the collection amount is how much we utilised from the total advance amount. We can get the current advance from the taxAmount - collectionAmount
billing-service/demand/_search API is used to calculate the Penalty amount. We can get the penalty amount if taxHeadMasterCode contains 'WS_TIME_ADHOC_PENALTY'. We get the penalty amount from the tax amount property.
The due date is calculated by adding the billexpirtyDate days with the demand generation date.
If it is the first demand and it has the taxHeadMasterCode 10201, we show the Penalty placeholder in the bill details.
Model →
View →
Controller →
Components utilised from the Widgets Library
This page provides the UI screen technical details for the following features -
Users are redirected to this screen once they click on the Generate Demand card on the home screen.
This is used in cases when the scheduler is not running (due to technical errors) and the GP wants to run it manually.
Link → {base url}/mgramseva/home/billmanualgenerate
Default Values Set
The service category displays water charges by default
The service type displays a non-metered connection by default
Set the billing year from the drop-down which contains the list of financial years.
Set the Billing cycle which contains billing cycles for the selected financial year.
On clicking the Generate Demand Button, Bulk Demand is generated and the user is navigated to the success screen.
The Billing Cycle drop-down shows a list of months starting from the selected financial year from Date month till the current date month.
On selection of the desired month, the billing period value is set from the selected month’s first date to the selected month’s last date. (Eg. Selected Billing Cycle: June 2021, so Billing period: 01/07/2021 - 30/07/2021)
Primary Files:
1 → Home Screen. + Generate Bulk Demand Screen
Pop → Home Screen
Widgets utilised from the Library
Users are redirected to the Generate New Bill screen once they click on the Generate New Bill option in the household detail screen.
Link
→ {base url}/mgramseva/home/householddetails/billgenerate
Default Values Set
The service category defaults to water charges
The service type defaults to a metered connection
The property type defaults to the selected property type of the consumer
Previous Meter Reading: Takes input from the user only for a first-time bill generation and if the Previous meter reading is null, else it's defaulted if the meter reading is present.
New Meter Reading: Takes input from the user
Meter Reading Date: Defaulted to today’s date, the User can change it to the desired date.
Users have the option of downloading the bill or sharing it via WhatsApp
On click of the Collect Payment button, the user is navigated to the Payment Screen
Primary Files:
1 → Home Screen + Household Details Screen + Generate Bill Metered
Pop → Household Details Screen
Widgets utilised from the Library
This screen enables employees to update consumer details.
Users are redirected to this screen/page when they click on the Update Consumer Details card.
Link
→ {base url}/mgramseva/home/consumersearchupdate?Mode=update
→ {base url}/mgramseva/home/consumersearchresult
It redirects to Search Connection Page in update mode where users enter specific consumer details to search for consumers. The search result screen has the Edit Consumer button. Clicking on this button navigates the users to the Update Consumer screen.
| Fields | Validations |
|---|---|
Note: All fields are validated on Submit apart from the phone number which gets validated on change.
Components utilised from Widgets Library
Enables employees to modify/edit the expenses based on the status of the payment.
Link → {base url}/mgramseva/home/searchExpense/result/updateExpense
Update Expenses card is visible on the home screen for defined user roles that have EXPENSE PROCESSING permission. Clicking on the Update Expenditure card in the expense search results screen navigates the user to the Edit Expense Bills screen.
Users can edit the previously populated expense details for the vendors.
Clicking on the Submit button navigates the users to the Modified Expenditure Success screen.
Use Case 1: When the status is “Unpaid”
Allows modification of all the details except the Bill ID. Users can Mark the Bill as “Cancelled” by checking on the option.
Use Case 2: When the status is “Paid”
Cannot modify any details. But the users can Mark the Bill as “Cancelled” by checking the option.
Primary Files -
punjab-mgramseva/ExpenseDetails.dart at develop · egovernments/punjab-mgramseva
1 → Home Screen. + Search Expense Screen + Expense Results Screen + Edit Expense Bills Screen
Pop → Expense Results Screen
Widgets utilised from the Library
Users are redirected to this screen if they select the GPWSC Dashboard option on the home screen.
Link → {base url}/mgramseva/home/dashboard?tab=0
Users can select the year from the drop-down which contains the list of financial years.
From the text field, users can search for connections by using the connection ID.
Users can see the connections data based on the property type for each respective tab (Ex: All, Residential, Commercial).
Initially, only 10 connections are loaded for the selected tab. The pagination dropdown and right arrow click enable users to view more connections.
By selecting any connection ID users are navigated to the Connection update screen.
Primary Files:
punjab-mgramseva/Dashboard.dart at develop · egovernments/punjab-mgramseva
punjab-mgramseva/search_expense.dart at develop · egovernments/punjab-mgramseva
| End Point | Request Method | Request Info |
|---|---|---|
1 → Home Screen. + Dashboard collection screen + update connection screen
Pop → Dashboard collection screen → Home Screen
2 → Home Screen. + Dashboard collection screen + update connection screen + Update Success
Pop → Home Screen
Widgets utilised from the Library
Controller →
View →
Model →
Users are redirected to this screen when they select the GPWSC Dashboard option on the home screen.
Link → {base url}/mgramseva/home/dashboard?tab=1
Users can select the year from the drop-down which contains the list of financial years.
From the text field, users can search for the expenses using Bill ID or vendor name.
Users can see the expense data for paid and pending with respective tabs.
Initially, only 10 expenses are loaded for the selected tab. The pagination dropdown and right arrow click enable the user to load and view more expense records.
Selecting any Bill ID navigates the users to the Expense update screen.
Primary Files:
punjab-mgramseva/Dashboard.dart at develop · egovernments/punjab-mgramseva
punjab-mgramseva/search_expense.dart at develop · egovernments/punjab-mgramseva
| End Point | Request Method | Request Info |
|---|---|---|
1 → Home Screen. + Dashboard expenditure screen + update expense screen
Pop → Dashboard expenditure screen → Home Screen
2 → Home Screen. + Dashboard expenditure screen + update expense screen + expense update success
Pop → Home Screen
Widgets utilised from the Library
Model →
View →
Controller →
Users are redirected to this screen if they select the GPWSC Dashboard option on the home screen.
Link → {base url}/mgramseva/home/dashboard
Users can select the year from the drop-down which contains the list of the last 5 Financial years, on tap of any year respective months will be displayed.
Users can see the user satisfaction average scores of the selected month.
Users can see the Trend line graph plotted based on both Revenue and Expenditure.
By selecting any Month from the table, users are navigated to the Expenditure and Revenue Dashboard screen.
Users can see the WhatsApp Share button, by tapping on it users can share the Monthly dashboard as a screenshot via WhatsApp.
Primary Files:
punjab-mgramseva/Dashboard.dart at develop · egovernments/punjab-mgramsevaGitHub
punjab-mgramseva/revenue_charts.dart at develop · misdwss/punjab-mgramsevaGitHub
punjab-mgramseva/revenue_dashboard.dart at develop · misdwss/punjab-mgramsevaGitHub
Secondary Files:
punjab-mgramseva/revenue.dart at develop · misdwss/punjab-mgramsevaGitHub
1 → Home Screen + Monthly Dashboard + Revenue Dashboard + update connection screen
Pop → Revenue Dashboard screen → Home Screen
2 → Home Screen + Monthly Dashboard + Expenditure Dashboard + update expenditure screen
Pop → Expenditure Dashboard Screen → Home Screen
3 → Home Screen + Monthly Dashboard + Revenue Dashboard + update connection screen + Update Success
Pop → Home Screen
4 → Home Screen + Monthly Dashboard + Expenditure Dashboard + update expenditure screen + Update Success
Pop → Home Screen
Widgets utilised from the Library
Model →
View →
Controller →
The Revenue Collector uses the Collect Payment screen to collect payment against the demand generated for metered and non-metered connections or any arrears.
Collect Payment card is available on the home screen to the user role having the COLLECTION_OPERATOR permission.
Link → {base url}/mgramseva/household/details/collectPayment
Users can pay the total due amount that is set by default.
Or, users can also pay an advance amount or partial amount by changing the value in the payment amount field to a higher or lower value. If a partial amount is to be paid, then users need to provide a lower amount than the total due amount. If the advance amount is to be paid, users need to provide a higher amount than the total due amount.
Clicking on Collect Payment opens a confirmation popup to confirm if the amount entered is correct.
Clicking on Confirm navigates the user to the Payment Success screen. The user can download the receipt or share the receipt for the collected amount.
Users can also print mini receipts with the help of Bluetooth thermal printers by selecting the Print mini receipt option.
billing-service/demand/_search API is used to calculate the advance amount for the current bill. The advance amount is fetched from the logic - if taxHeadMasterCode is 'WS_ADVANCE_CARRYFORWARD'. This has two properties - collection amount and tax amount. The tax amount is the advance amount that is added to the system and the collection amount is the amount utilised from the total advance amount. We can get the current advance from the taxAmount - collectionAmount.
ws-calculator/waterCalculator/_getPenaltyDetails API is used to calculate the Time Penalty amount. The time penalty amount is fetched from the logic - if taxHeadMasterCode is'WS_TIME_PENALTY'. The time penalty amount is retrieved from the tax amount property of the latest demand.
The due date is calculated by adding the billexpirtyDate days to the demand generation date.
If the due date is crossed, billing-service/demand/_search API gives the Time Penalty applied.
billing-service/demand/_search API gives the Normal Penalty. The Penalty placeholder in the bill details is visible if it is the first demand and has the taxHeadMasterCode as 10201.
The arrears are broken into 'BL_(TaxHeadCode)' fetched from Bill Details-->Bill Account Details --> Tax Head Code. The amount of particular arrears is similar to the Bill Details--> Amount from the Fetch Bill API.
(For instance, if there are two bills with tax head codes is 10101 and 10102, then arrears break up is represented as BL_10101(Water Charges) with the corresponding amount and BL_10102(Water Charges-Arrears) with the corresponding amount).
Note:
The “Penalty” details displayed under the “Bill Details“ section is displayed only if the config flag “Penalty enabled” is set as true. If it is set as false, then the penalty details is not displayed.
The “Advance” details displayed under the “Bill Details“ section is displayed only if the config flag “Advance enabled” is set as true. If it is set as false, then the advance details is not displayed.
Primary Files: https://github.com/misdwss/punjab-mgramseva/blob/master/frontend/mgramseva/lib/screeens/common/collect_payment.dart
1 → Home Screen. + Search Connection Screen + Household Results + Household Details Screen + Collect Payment Screen
Pop → Household Details Screen
Widgets utilised from the Library
Users are redirected to this screen by selecting the Update Expense card on the home screen.
Update Expenses card is available on the home screen for defined roles that have EXPENSE PROCESSING permission.
Link → {base url}/mgramseva/home/searchExpense
Users can search the expense bills with the Vendor Name / Type of Expense / Bill ID ( Search with any one of these criteria )
Click on Search navigates the user to the expense results screen which lists the expenditure bills matching the search criteria.
Primary Files:
punjab-mgramseva/search_expense.dart at develop · egovernments/punjab-mgramseva
punjab-mgramseva/expense_results.dart at develop · egovernments/punjab-mgramseva
| Fields | Validations |
|---|---|
1 → Home Screen. + Search Expense Bills Screen
Pop → Home Screen
Widgets utilised from the Library
Users can provide their feedback by giving a rating. It's an Open URL. It does not require any Authentication user.
Link → {baseURL}mgramseva/feedBack?paymentId={}&connectionno={}&tenantId={}
Users can switch to multiple languages.
After submitting the feedback, users are navigated to the feedback submitted successfully acknowledgement screen.
| API | Params | Description |
|---|
Update the app in case of new release/enhancements
Show Update App popup to end users in case there is a new release in the Google Play Store or IOS App Store.
Add the file (link below) in the common-masters MDMS -
Update the version in the above-mentioned file whenever a new release is deployed to the Play Store or App Store.
Note: The version deployed in the Play Store and App Store should match the version in .
The MDMS call is made every time a user opens the app.
Once the ViewBuild() displays a pop-up on the landing page widget, it validates if the package version matches the version in MDMS.
Users are redirected to this screen once they select the Household Register tile/card on the home screen.
The Household Register tile/card is displayed to the user with COLLECTION_OPERATOR role.
Link → {base url}/mgramseva/home/householdRegister
From the text field, users can search for connections by using the connection ID.
Users can see all the connection data of the selected tenant till the current date based on their payment status (Ex: All, Paid, Pending).
Initially, only 10 connections are loaded for the selected tab. The pagination drop-down and right arrow click enable users to view more connections.
Selecting any connection ID redirects users to the View Consumer Details screen.
Click on the Download button to get all the household records in PDF format.
Click on Share to share the PDF on Whats App.
Primary Files:
1 → Home Screen. + Household Register Screen
Pop → Household Register Screen→ Home Screen
2 → Home Screen. + Household Register Screen + View Consumer Details Screen
Pop → View Consumer Details Screen → Household Register Screen
Widgets used from the Library
Model →
View →
Controller ->
| Fields | Validations |
|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| Fields | Validations |
|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| Field | Validation |
|---|---|
| API | Params | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| API | Params | Description |
|---|---|---|
| API | Description |
|---|---|
| Components File Links |
|---|
| Fields | Validations |
|---|---|
| API End Point | Input Params (Module) | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| Fields | Validations |
|---|---|
| API End Point | Input Params (Modules) | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| API | Params | Description |
|---|---|---|
| Components File Links |
|---|
| Fields | Validations |
|---|---|
| API | Params | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
punjab-mgramseva/revenue_charts.dart at develop · misdwss/punjab-mgramsevaGitHubpunjab-mgramseva/revenue_dashboard.dart at develop · misdwss/punjab-mgramsevaGitHub
| Fields | Validations |
|---|---|
| API End Point | Input Params (Modules) | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| API | Params | Description |
|---|---|---|
| Widgets | File Path | Description |
|---|---|---|
| End Point | Request Method | Request Info |
|---|
| Widgets | File Path | Description |
|---|
Enter the OTP sent *
r'^[0-9]+$' , 6 digit
Enter a New Password*
r'^(?=.*?[A-Za-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{6,}$'
Confirm New Password
Match with New Password
user/password/nologin/_update
POST
"otpReference": {}, "userName": {}, "newPassword": {}, "tenantId": {}, "type": “Employee”
egov-mdms-service/v1/_search
POST
"MdmsCriteria": { "tenantId": tenantId, "moduleDetails": [ { "moduleName": "tenant", "masterDetails": [ {"name": "tenants"} ], }, ] }
BuildTextField
Text Field
BottomButtonBar
Button
PasswordHint
Password Hint Card
user-otp/v1/_send
POST
"otp": { "mobileNumber": {}, "tenantId": {}, "type": "passwordreset", "userType": "Employee" }
Enter the OTP sent *
r'^[0-9]+$' , 6 digit
Enter a New Password*
r'^(?=.*?[A-Za-z])(?=.*?[0-9])(?=.*?[#?!@$%^&*-]).{6,}$'
Confirm New Password
Match with New Password
user/password/nologin/_update
POST
"otpReference": {}, "userName": {}, "newPassword": {}, "tenantId": {}, "type": “Employee”
BuildTextField
Text Field
BottomButtonBar
Button
PasswordHint
Password Hint Card
Vendor Name*
[A-Za-z ]
Mobile Number*
[0-9] & is mandatory only if a new vendor is added
Type of Expense*
None
Amount*
[0-9]
Bill Date*
Before Current Date and after party Bill Date.
Party Bill Date
Should be before the Bill Date
Bill Paid
None
Paid Date
After Bill date and less than current Date.
Attach Documents
Option to upload a single document, Supported files - PDF, JPEG, PNG (maximum 5MB)
/egov-mdms-service/v1/_search
[{"moduleName": "Expense", "masterDetails": [{"name": "ExpenseType"},]}, {"moduleName": "BillingService", "masterDetails": [{"name": "BusinessService"}, {"name": "TaxHeadMaster"},]}]
To get the Expense Type for the Dropdown
egov.org.in/vendor/v1/_search
tenantId: {}
To get the list of vendors in the selected tenant for the suggestion text box - Vendor Name
BuildTextField
Text Field
AutoCompleteView
Suggestion Text Field
SelectFieldBuilder
(Primary File)
SearchSelectFieldBuilder
(Secondary File)
Searchable Drop down
DatePickerFieldBulder
Date Picker
CommonSuccessPage
Success Screen
BottomButtonBar
Button
/ws-services/wc/_search
POST
tenantId: {}
oldConnectionNumber: {}
name: {}
connectionNumber: {}
mobileNumber: {}
/egov-mdms-service/v1/_search
[{"moduleName":"ws-services-masters","masterDetails":[{"name":"connectionType"}]},{"moduleName":"PropertyTax","masterDetails":[{"name":"PropertyType"}]},{"moduleName":"BillingService","masterDetails":[{"name":"TaxPeriod","filter":"[?(@.service=='WS' && @.fromDate <= 1631989800000 && @.toDate >= 1631989800000)]
To get the Property Type and service Type and billing cycle values for the Dropdown
egov-location/location/v11/boundarys/_search?
hierarchyTypeCode=REVENUE&boundaryType=Locality&tenantId={tenantID}
To get the values for Locality DropDow
Billing Year*
isMandatory
Billing Cycle*
isMandatory
egov-mdms-service/v1/_search
ws-services-masters
PropertyTax
BillingService
To Fetch the Details of
connectionType from ws-services-masters
TaxPeriod from BillingService where service=='WS' && @.fromDate <= $datestamp && @.toDate >= $datestamp
/ws-calculator/waterCalculator/_bulkDeman
POST
"tenantId": {}, "billingPeriod": {}
SelectFieldBuilder
(Primary File)
SearchSelectFieldBuilder
(Secondary File)
Searchable Dropdown
CommonSuccessPage
Success Screen
BottomButtonBar
Button
Previous Meter Reading*
r'^[0-9]+$'
5 - digit reading
if Meter Reading < 5 digit, prepend zeroes
New Meter Reading*
r'^[0-9]+$'
5 - digit reading
if Meter Reading < 5 digit, prepend zeroes
Meter Reading Date*
Shows dates till today's date
egov-mdms-service/v1/_search
ws-services-masters
PropertyTax
BillingService
To Fetch the Details of
connectionType from ws-services-masters
PropertyType from PropertyTax
TaxHeadMaster from BillingService where service=='WS'
/ws-calculator/meterConnection/_create
POST
"meterReadings": { "currentReading": {}, "currentReadingDate": {}, "billingPeriod": {}, "meterStatus": "Working", "connectionNo": {}, "lastReading": {}, "lastReadingDate": {}, "generateDemand": true, "tenantId": {}
}
MeterReading
Meter Reading 5 digit boxes field
SelectFieldBuilder
(Primary File)
SearchSelectFieldBuilder
(Secondary File)
Searchable Drop down
DatePickerFieldBulder
Date Picker
CommonSuccessPage
Success Screen
BottomButtonBar
Button
/egov-mdms-service/v1/_search
[{"moduleName":"ws-services-masters","masterDetails":[{"name":"connectionType"}]},{"moduleName":"PropertyTax","masterDetails":[{"name":"PropertyType"}]},{"moduleName":"BillingService","masterDetails":[{"name":"TaxPeriod","filter":"[?(@.service=='WS' && @.fromDate <= 1631989800000 && @.toDate >= 1631989800000)]
To get the Property Type and service Type and billing cycle values for the Dropdown
egov-location/location/v11/boundarys/_search?
hierarchyTypeCode=REVENUE&boundaryType=Locality&tenantId={tenantID}
To get the values for Locality Dropdown
billing-service/demand/_search
consumerCode, businessService, tenantId
To Fetch Demand Details
property-services/property/_search
propertyIds, tenantId
To Fetch Property Type
ws-services/wc/_search
connectionNumber, tenantId
On Demand this API is Made
Vendor Name*
[A-Za-z ]
Mobile Number*
[0-9] & is mandatory only if a new vendor is added
Type of Expense*
None
Amount*
[0-9]
Bill Date*
Before Current Date and after party Bill Date
Party Bill Date
Should be before the Bill Date
Bill Paid
None
Paid Date
After Bill date and less than current Date
Attach Documents
Option to upload a single document, Supported files - PDF, JPEG, PNG (maximum 5MB)
Mark this Bill as Cancelled
None
/egov-mdms-service/v1/_search
[{"moduleName": "Expense", "masterDetails": [{"name": "ExpenseType"},]}, {"moduleName": "BillingService", "masterDetails": [{"name": "BusinessService"}, {"name": "TaxHeadMaster"},]}]
To get the Expense Type for the Dropdown
egov.org.in/vendor/v1/_search
tenantId: {}
To get the list of vendors in the selected tenant for the suggestion text box - Vendor Name
BuildTextField
Text Field
AutoCompleteView
Suggestion Text Field
SelectFieldBuilder
(Primary File)
SearchSelectFieldBuilder
(Secondary File)
Searchable Drop down
DatePickerFieldBulder
Date Picker
CommonSuccessPage
Success Screen
BottomButtonBar
Button
Pagination
Pagination
BuildTextField
Text Field
BillsTable
Table
LabelText
Subtitle
Pagination
Pagination
BuildTextField
Text Field
BillsTable
Table
LabelText
Subtitle
dashboard-analytics/dashboard/getChartV2
POST
aggregationRequestDto : {}
requestDate : {}
headers : {}
RequestInfo : {}
ws-services/wc/_revenueCollectionData
POST
tenantId : {} fromDate : {} toDate : {}
RequestInfo : {}
echallan-services/eChallan/v1/_chalanCollectionData
POST
tenantId : {} fromDate : {} toDate : {}
RequestInfo : {}
/filestore/v1/files
POST
tenantId : {}
module : {}
/egov-url-shortening/shortener
POST
url : {}
Pagination
Pagination
BuildTextField
Text Field
BillsTable
Table
LabelText
Subtitle
NestedDatePicker
Nested Date Picker
Partial Amount (If Partial Amount is selected)
r'^[0-9]+$' , Can not be 0
Payment Method
Defaulted to Cash
egov-mdms-service/v1/_search
[{"moduleName":"BillingService","masterDetails":[{"name":"BusinessService","filter":"[?(@.code=='WS')]"}]}]
To get the billGeneiURL, Calculation of Water services and collectionModesNotAllowed
billing-service/bill/v2/_fetchbill
consumerCode : {}
businessService : WS
tenantId : {}
To fetch the bills of the connection/Consumer
billing-service/demand/_search
consumerCode, businessService, tenantId
To Fetch Demand Details
ws-calculator/waterCalculator/_getPenaltyDetails
{ "tenantId": "", "consumerCodes": "", "isGetPenaltyEstimate": "true"},
{
"GetBillCriteria":
{"tenantId": "", "isGetPenaltyEstimate": true, "consumerCodes": [""] }
}
To get the Time Penalty Amount
BuildTextField
Text Field
BottomButtonBar
Button
RadioButtonField
Radio Buttons for options
ConfirmationPopUp
Dialog box to confirm and proceed to next step
CustomDetailsCard
Secondary theme color Card to display Details Eg. Penalty Card
/egov-mdms-service/v1/_search
[{"moduleName": "Expense", "masterDetails": [{"name": "ExpenseType"},]}, {"moduleName": "BillingService", "masterDetails": [{"name": "BusinessService"}, {"name": "TaxHeadMaster"},]}]
To get the Expense Type for the Dropdown
BuildTextField
Text Field
SelectFieldBuilder
(Primary File)
SearchSelectFieldBuilder
(Secondary File)
Searchable Drop down
BottomButtonBar
Button
/ | POST |
|
| POST |
|
| POST |
|
BuildTextField
Text Field
Button
Button
BuildTextField
Text Field
BottomButtonBar
Button
property-services/property/_create
Property Creation Request JSON
ws-services/wc/_create
| Pagination |
| Text Field |
| Table |
| Title |
| Subtitle |
Fields
Validation
Phone Number*
r'^[0-9]+$'
Owner Mobile Number
r'^(?:[+0]9)?[0-9]{10}$'
Name of the Consumer
r'^[A-Za-z ]'
Old Connection ID
No Validation
New Connection ID
No Validation
consumer Name*
[A-Za-z ]
Gender*
None
Spouse/Parent’s Name*
[A-Za-z ]
Phone Number*
[0-9]
Old Connection No
None
Category
None
Sub Category
None
Door Number
None
Street Name/Number
None
Gram Panchayat Name*
None- Disabled
Propert Type*
None
Service Type*
None
Meter Id
[a-zA-Z0-9]
Meter Reading
[0-9]
Billing Cycle
None
Arrears
[0-9.]
Advance
[0-9.]
Penalty
[0-9.]
consumer Name*
[A-Za-z ]
Gender*
None
Spouse/Parent’s Name*
[A-Za-z ]
Phone Number*
[0-9]
Old Connection No
None
Category
None
Sub Category
None
Door Number
None
Street Name/Number
None
Gram Panchayat Name*
None- Disabled
Propert Type*
None
Service Type*
None
Meter Id
[a-zA-Z0-9]
Meter Reading
[0-9]
Billing Cycle
None
Arrears
[0-9.]
Advance
[0-9.]
Penalty
[0-9.]
/ws-services/wc/_search
POST
tenantId : {} offset ; {} limit : {} fromDate : {} toDate : {} iscollectionAmount: {} isPropertyCount: {} propertyType: {} connectionNumber: {} freeSearch: {}
sortOrder ; {} sortBy : {}
/echallan-services/eChallan/v1/_create
POST
tenantId : {} offset ; {} limit : {} fromDate : {} toDate : {} vendorName : {} challanNo : {} toDate : {} freeSearch : {} status : {} isBillCount : {}
sortOrder ; {} sortBy : {} isBillPaid : {}
Owner Mobile Number
r'^(?:[+0]9)?[0-9]{10}$'
Name of the Consumer
r'^[A-Za-z ]'
Old Connection ID
No Validation
New Connection ID
No Validation
|
| API to submit user feedback |
Water Connection Request JSON defined in punjab-mgramseva/water_connection.dart at develop · egovernments/punjab-mgramseva
