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...
We are using re-indexing to get all the data to the respective indexer. We have 2 steps for this. The first is to run the connector from the playground. This is followed by a legacy indexer service call from the indexer service, which internally calls the respective plain search service to get the data and send it to the respective indexer.
Access to kubectl of the environment targetted
Postman scripts
Plain search APIs in the respective services
We have two services for water and sewerage
water-services
sewerage-services
Connect to playground pod.
Delete the Kafka connector if already exists with the Kafka connection, using the below command through playground pod.
Run below Kafka connector curl from playground pod:
port forward to egov-indexer pod and run below curl throw postman.
Delete the Kafka connection after all the data has been re-indexed by following the below command through the playground pod.
Alias water-services-enriched as water-services through the Kibana server.
Connect to playground pod.
Delete the Kafka connector if already exists with the Kafka connection, using the below command through playground pod.
Run below Kafka connector curl from playground pod:
port forward to egov-indexer pod and run below curl throw postman.
Delete the Kafka connection after all the data has been re-indexed by following the below command through the playground pod.
Alias water-services-enriched as water-services through the Kibana server.
Water Calculator Service is used for creating meter readings, searching meter readings, updating existing meter readings, calculation of water charges, demand generation, SMS & email notification to ULB officials on-demand generation and estimation of water charge on basis of meter reading for existing water application until the application is disconnected.
There are no additional billing slabs to be configured for water disconnection, the calculation happens with the meter reading if added and uses existing billing slabs.
Criteria -
connection type
building type
calculation attribute
property usage type
The combination of the above can be used to define the billing slab. Billing Slab is defined in MDMS under ws-services-calculation folder with the WCBillingSlab. The following is the sample slab.
For the disconnection application fee, the estimation will return all the related tax heads based on the criteria.
Following are the exemptions and taxes that are calculated:
Form fee
Scrutiny fee
Meter charge (For metered connection)
Other charges
Security charges
Tax and cess
The water charge is based on the billing slab, and for water disconnection application charge will be based on the slab and tax based on the master configuration.
Interest
Below is a sample of the master data JSON for interest:
Penalty
Below is a sample of the master data JSON for penalty -
Round Off
If the fraction is greater than equal to 0.5 the number is rounded up else it’s rounded down. eg: 100.4 will be rounded to 100 while 100.6 will be rounded to 101.
Whenever _calculate API is called demand is first searched based on the connection no and the demand from and to period. If demand already exists the same demand is updated else new demand is generated with consumer code as connection no and demand from and to a period equal to the financial year start and end period.
In case of the update, if the tax head estimates change, the difference in amount for that tax head is added as 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:
The disconnection charges will be the addition of both demand details taxAmount and we can generate demand until the workflow is in PENDING_FOR_DISCONNECTION_EXECUTION.
Note : if there no pending payment when the connection gets approved then the workflow gets updated from PENDING_APPROVAL_FOR_DISCONNECTION to PENDING_FOR_DISCONNECTION_EXECUTION (it skips payment step in the workflow internally).
Here the disconnection charges will be 120+30 = 150
RoundOff is bill based i.e every time bill is generated round off is adjusted so that the payable amount is the whole number. Individual WS_ROUNDOFF in demand detail can be greater than 0.5 but the sum of all WS_ROUNDOFF will always be less than 0.5.
Final water charges calculation
Final Water Charges = Last Billing Period Amount * Days (Proposed disconnection date - Last Billing Date) / No. of days in last billing period
The additional parameter is being sent in the calculation request for the disconnection application.
disconnectRequest = true if the request is for _calculate API disconnection application.
(Note: All the APIs are in the same postman collection therefore the same link is added in each row)
Water Calculator Service is used for creating meter reading, searching meter reading, updating existing meter reading, calculation of water charge, demand generation, SMS & email notification to ULB officials on-demand generation and estimation of water charge(one-time cost) which involves cost 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
Kafka server is up and running
egov-persister service is running and has water service persister configs path added in it
PSQL server is running and a database is created to store water connection / application data
Following services should be up and running:
egov-perister
egov-mdms
ws-services
billing-service
Calculate water charge and taxes based on 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 water-persist.yml & water-meter.yml file in config folder in git and add that path in persister . (The file path is to be added in environment yaml file in param called persist-yml-path )
Criteria :
connection type
building type
calculation attribute
property usage type
The combination of the above can be used to define the billing slab. Billing Slab is defined in MDMS under ws-services-calculation folder with the WCBillingSlab. The following is the sample slab.
If all criteria will match for that water connection this slab will use for calculation.
For application one-time fee, the estimation will return all the related tax head based on criteria. For estimation, all configuration is present in ws-services-calculation.
All the above master configuration is used for estimation.
Following are the exemptions and taxes that are calculated:
Form fee
Scrutiny fee
Meter charge (For metered connection)
Other charges
Road cutting charges
One time fee
Security charges
Tax and cess
Water charge is based on billing slab, for water application charge will be based on slab and tax based on master configuration.
Interest
Below is a sample of master data JSON for interest :
Penalty
Below is a sample of master data JSON for penalty :
Round Off
If the fraction is greater than equal to 0.5 the number is round up else it’s round down. eg: 100.4 will be rounded to 100 while 100.6 will be rounded to 101.
Actions
Role Action Mapping
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 function will create a corresponding demand detail.
Whenever _calculate API is called demand is first searched based on the connection no or application no and the demand from and to period. If demand already exists the same demand is updated else new demand is generated with consumer code as connection no or application no and demand from and to a period equal to financial year start and end period.
In the case of an update, if the tax head estimates change, the difference in amount for that tax head is added as 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:
RoundOff is bill based i.e every time bill is generated round off is adjusted so that the payable amount is the whole number. Individual WS_ROUNDOFF in demand detail can be greater than 0.5 but the sum of all WS_ROUNDOFF will always be less than 0.5.
Description :
For generating the demand for non metered connection we have a feature for generating the demand in batch. The scheduler is responsible for generating the demand based on the tenant.
The scheduler can be hit by scheduler API or we can schedule cron job or we can put config to kubectl which will hit scheduler based on config.
After the scheduler been hit we will search the list of the tenant (city) present in the database.
After getting the tenants we will pick up tenant one by one and generate the demand for that tenant.
We will load the consumer codes for the tenant and push the calculation criteria to Kafka. Calculation criteria contain minimal information (We are not pushing large data to Kafka), calculation criteria contain consumer code and one boolean variable.
After pushing the data into Kafka we are consuming the records based on the batch configuration. Ex:-> if the batch configuration is 50 so we will consume the 50 calculation criteria at a time.
After consuming the record(Calculation criteria) we will process the batch for generating the demand. If the batch is successful so will log the consumer codes which have been processed.
If some records failed in batch so we will push the batch into dead letter batch topic. From the dead letter batch topic, we will process the batch one by one.
If the record is successful we will log the consumer code, If the record is failed so we will push the data into a dead letter single topic.
Dead letter single topic contains information about failure records in Kafka.
Use cases:
If the same job trigger multiple time what will happen?
If the same job triggers multiple times we will process again as mentioned above but at the demand level we will check the demand based on consumer code and billing period, If demand already exists then we will update the demand otherwise we will create the demand.
Are we maintaining success or failure status anywhere?
Currently, we are maintaining the status of failed records in Kafka.
Configuration :
We need to configure the batch size for Kafka consumer. This configuration is for how much data will be processed at a time.1ws.demand.based.batch.size=10
ws-calculator will be 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 will be separated out from the WS service. So in future, if calculation logic needs to modify then changes can be carried out for each implementation without modifying the WS service.
Once the water connection is activated for metered-connection, employee can add meter reading details using this API - /ws-calculator/meterConnection/_createwhich in-turn will generate the demand. For the Non-Metered connections, the scheduler APIs need to be called periodically to generate the demand.
For the Metered Connection service, to get the previous meter reading /meterConnection/_search API is used.
To Activate the Water Service application, the user needs to pay the ONE_TIME_FEE for the connection. To calculate the ONE_TIME_FEE /waterCalculator/_estimate API is used.
To generate the demand for metered or non-metered water connection /waterCalculator/_calculate API is used.
User can pay partial / full / advance amount for the Metered or Non-Metered connection bill. In these cases, Billing service would call back /waterCalculator/_updateDemandAPI to update the details of the demand generated.
/waterCalculator/_jobscheduler API is use to generate demand for Non-metered connections. This API can be called periodically.
/waterCalculator/_applyAdhocTax API is used to add Rebate or Penalty on any bill and based on that the bill amount will be adjusted.
(Note: All the APIs are in the same Postman collection therefore the same link is added in each row)
Water service is the eGov application, which helps and gives flexibility to municipalities and citizens to handle the water service like applying for the water connection and searching for water connections. The application goes through different stages that the states identify for given roles. If that role takes the action then the application goes to the next state. Based on the state, a citizen gets a notification (SMS and in-app ). Citizens also can pay for 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
The 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.
Apply for a water connection.
Searching for water connections.
Apply for property creation.
Can take different actions based on state (Workflow)
Notification based on the application state.
Table UML diagram
master-config.json for water service
Property creation through WNS module https://github.com/egovernments/egov-mdms-data/blob/DEV/data/pb/PropertyTax/PTWorkflow.json
https://github.com/egovernments/configs/blob/DEV/egov-persister/water-persist.yml https://github.com/egovernments/configs/blob/master/egov-persister/water-meter.yml
Actions
Role Action Mapping
Create businessService (workflow configuration) using the __/businessservice/_create. Following is the product configuration for the water service.
Workflow for property creation through Water and Sewerage module
The indexer provides the facility for indexing the data to elastic search. https://github.com/egovernments/configs/blob/DEV/egov-indexer/water-service.ymlhttps://github.com/egovernments/configs/blob/DEV/egov-indexer/water-services-meter.yml
Setup
Write the configuration for the water service. https://github.com/egovernments/configs/blob/DEV/egov-indexer/water-service.ymlhttps://github.com/egovernments/configs/blob/DEV/egov-indexer/water-services-meter.yml
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.
Modify connection
After connection activation or legacy connection, we can edit the connection. This process is based on a defined workflow. Any action is based on defined roles on the action level. For the edit connection, we need to upload some supporting documents and mandatory info.
Workflow config for edit connection
Create businessService (workflow configuration) using the __/businessservice/_create. Following is the product configuration for editing the water connection.
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 who 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 connector 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 their road type details and road cutting area. 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 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 APIs.
Create businessService (workflow configuration) accordingly for 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.
Elastic search index for creating visualizations and Dashboards.
Supports workflow which is configurable
To integrate, a host of ws-service modules should be overwritten in the helm chart.
/ws-services/wc/_create should be added as the create endpoint for creating water application/connection 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)
After connection activation or legacy connection, the user can choose to disconnect the connection either temporarily or permanently. This process is based on a defined workflow. Any action is based on defined roles on the action level.
For disconnecting the connection, the user needs to send extra parameters as below :
disconnectionReason - to add the reason for disconnection
isDisconnectionTemporary - Whether the disconnection is temporary or permanent (if the disconnection is temporary then isDisconnectionTemporary will be true else false)
disconnectRequest - This will always be true for disconnection applications.
disconnectionExecutionDate - This is the date when the application is disconnected.
and also user needs to upload some supporting documents and mandatory info.
URLs for the external API references
eGov mdms: egov.mdms.host = https://dev.digit.org/
eGov -idGen: egov.idgen.host = https://dev.digit.org/
localization service: egov.localization.host = https://dev.digit.org/
idGen Id formats : egov.idgen.wdcid.name=waterservice.disconnection.id egov.idgen.wdcid.format=WS_AP/[CITY.CODE]/[fy:yyyy-yy]/DC-[SEQ_WS_APP_[TENANT_ID]]
egov-mdms-data/IdFormat.json at QA · egovernments/egov-mdms-data
This new feature is developed using the same existing base APIs for new and modified connections. The changes for disconnection follow a similar approach as that of New Connection. The config and persister changes required are mentioned below.
Persister configuration
Some changes are required in the existing persister files which can be referred to from the following links:
Workflow config for edit connection
Create businessService (workflow configuration) using the /businessservice/_create. Following is the product configuration for editing the water connection.
Disconnection notifications will be sent to the property owners and connection holders based on different application states.
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 as the connection holder. It goes the same for disconnection applications.
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.
To integrate, the host of ws-service module should be overwritten in the helm chart.
/ws-services/wc/_create should be added as the create endpoint for creating water application/connection 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 applications based on workflow.
(Note: All the APIs are in the same postman collection therefore the same link is added in each row)
Water & Sewerage my connection feature for citizen users - technical implementation doc
Objective: Provide the UI technical implementation details for the My Connections feature available for citizen users.
Users can review the list of connections and their status registered under their mobile number in the My Connections tab. Each connection in the initial view will display the Consumer No, Service Name, Consumer Name, status, and property Address with the View Details option, through which the User can look up more details about the connection.
Once the user clicks on the View Details button, the Connection Details page is displayed with all the necessary information about the connection.
The link provided in the connection details page is similar to the link provided in the applications details page, eg Consumption details, for more reference
The path for the My Connections and Connection Details common Index is given below. It provides an understanding of the working of the code.
File path - packages/modules/ws/src/pages/citizen/MyConnection/index.js
The template for My Connection is present within packages/modules/ws/src/pages/citizen/MyConnection/WSConnection.js. The Connection Details page is available within packages/modules/ws/src/pages/citizen/MyConnection/ConnectionDetails.js. The Connection list is retrieved by calling the search API "/ws-services/wc/_search" & "/sw-services/swc/_search" using the searchType as CONNECTION for the filter params.
Hooks used for fetching the connections for Water and Sewerage are:
The code to the linked page, Consumption Details is available in the file: packages/modules/ws/src/pages/citizen/MyConnection/ConsumptionDetails.js
No MDMS data is used here. All data is loaded from the Search API.
For My Applications, the localization keys are added in the ‘rainmaker-ws’ locale module same as My connections and create. Changes, updates or addition of any new localization key is done in the same locale module only.
Technical Doc
DSS has two sides to it. One is the process in which the data is pooled into 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 W&S.
What is analytics?
Analytics: Micro Service which is responsible for building, fetching, aggregating and computing the data on ElasticSearch to a consumable data response. This is later used for visualizations and graphical representations.
Analytics Configurations: Analytics contains multiple configurations. We need to add the changes related to Water & Sewerage(W&S) in this dashboard analytics. Here is the location: Below is a list of configurations that need to be changed to run W&S successfully.
Chart API Configuration
Master Dashboard Configuration
Role Dashboard Mappings Configuration
Each visualization has its own properties. Each visualization comes from different data sources (Sometimes it is a combination of different data sources). In order to configure each visualization and its properties, we have 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 W&S.
Master dashboard configuration is the main configuration which 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 contains the list of dashboards which 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 authorised 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.
common-masters/uiCommonConstants.json
roleaction.json
Action test.json
W&S-DSS consists of multiple graphs which represent the data of W&S. Each graph has its own configuration which will describe the chart and its type.
DSS consists of the following charts in W&S:
Revenue Tab
Overview
Total Cumulative Collection
Top ULB By Performance
Bottom ULB by Performance
W&S Collection by Usage Type
W&S Collection by Channel Type
W&S Key Financial Indicators
W&S Tax Heads
Service Tab
Overview
Total Cumulative Connection
Water Connection By Usage
Sewerage Connections By Usage
Connection By Channel
W&S Connection Ageing
Overview
The overview graph contains multiple data information as below in the selected time period.
Today’s Collection: This represents today’s collection amount for Water and Sewerage Application Fee + Consumption Charges.
Total Collection: This represents the total collection amount for Water and Sewerage Application Fee + Consumption Charges.
Target Collection: This represents the target collection amount for the Water and Sewerage connections.
Target Achievement: This represents the target achieved in percentage. This is calculated by the formula- (Total Collection/Target Collection)*100%
This Graph contains the Water and Sewerage collection amount information on a monthly basis as a cumulative line graph for each water and sewerage collection separately. This will change as per the denomination amount filter selection.
line - this graph/chart is data representation on date histograms or date groupings.
This graph represents the ULBs based on the Target achieved in bar chart representation with the % of target achieved in descending order.
This graph represents the ULBs based on the target achieved in bar chart representation with the % of target achieved in ascending order.
W&S Collection by Usage Type
This graph shows the collection amount based on the usage/property type and this amount will change as per the denomination filter change.
This graph shows the collection amount based on the collection channel type(eg-online, counter, etc) and this amount will change as per the denomination filter change.
This tabular chart representation graph shows multiple W&S information like Target Collection, Total Collection, Total Transactions, Total Connections and Target Achievement (in %). And this table shows the data at the district level and also has the drill-down chart for each district to ulb and from ulb to ward level data for the same.
xtable type allows to the addition of multiple computed fields with the aggregated fields dynamically added.
To add multiple computed columns, computedFields [] where actionName (IComputedField<T> interface), fields [] names as in exist in query key, newField as name to appear for computation must be defined.
On click of any district name will enter into drill-down charts, which will represent that specific District data.
On click of the ULB will navigate to wards under that specific ULB and each ward shows the specific data regarding that ward.
This tabular chart representation graph shows multiple W&S information like Total Collection, Penalty, Interest and Target Collection. And this table shows the data at the district level and also has the drill-down chart for each district to ulb and from ulb to ward level data for the same.
table type allows to addition of multiple aggregated fields.
On click of any district name will enter into drill-down charts, which will represent that specific District data.
On click of the ULB will navigate to wards under that specific ULB and each ward shows the specific data regarding that ward.
Overview
The overview graph contains multiple data information as below in the selected time period.
Total Applications: This represents the total number of applications for new, modify, and disconnection requests.
SLA Compliance: This represents the total SLA achieved in percentage.
Total Active Connections: This represents the total active water and sewerage connections.
Water-Metered Connections: This represents the total active metered water connections.
Water-Non Metered Connections: This represents the total active non-metered water connections.
Sewerage Connections: This represents the total active sewerage connections.
Total Cumulative Connections
This Graph contains the Water and Sewerage connections information on a monthly basis as a cumulative line graph for each water and sewerage connection separately.
line - this graph/chart is data representation on date histograms or date groupings.
This graph shows the active Water connections based on the usage/property type.
Sewerage Connections by Usage Type
This graph shows the active Sewerage connections based on the usage/property type.
This graph shows the active water and sewerage connections by channel type(eg-online, counter, etc).
W&S Connection Ageing
This tabular chart representation graph shows W&S applications that have been submitted and have been pending to be worked on. Information like Pending from 0 to 3 days, Pending from 3 to 7 days, Pending from 7 to 15 days, Pending for more than 15 days, and Total Pending Applications is shown in the chart. And this table shows the data at the district level and also has the drill-down chart for each district to ulb and from ulb to ward level data for the same.
xtable type allows the addition of multiple computed fields with the aggregated fields dynamically added.
To add multiple computed columns, computedFields [] where actionName (IComputedField<T> interface), fields [] names as in exist in query key, newField as name to appear for computation must be defined.
On click of any district name will enter into drill-down charts, which will represent that specific District data.
On click of the ULB will navigate to wards under that specific ULB and each ward shows the specific data regarding that ward.
isRoundOff: This property is introduced to round off the decimal values. Ex: if the value is 25.43 by using isRoundOff property in the configuration we will get it as 25. if the value is 22.56 round of value will be 23. This can be used for insights configuration as well for overview graphs.
Key(eg: fsmTotalrequest): This is the Visualization Code. This key will be referred to in further visualization configurations.
This is the key which will be used by the client application to indicate which visualization is needed for display.
chartName: The name of the Chart which has to be used as a label on the Dashboard. The name of the Chart will be a detailed name.
In this configuration, the Name of the Chart will be the code of Localization which will be used by the Client Side.
queries: Some visualizations are derived from a specific data source. While some others are derived from different data sources and are combined together to get a meaningful representation.
The queries of aggregation which are to be used to fetch the right data in the right aggregated format are configured here.
queries.module: The module/domain level, on which the query should be applied on. Water and sewerage are W&S.
queries.indexName: The name of the index upon which the query has to be executed is configured here.
queries.aggrQuery : The aggregation query in itself is added here. Based on the Module and the Index name specified, this query is attached to the filter part of the complete search request and then executed against that index
queries.requestQueryMap: Client Request would carry certain fields which are to be filtered. The parameters specified in the Client Request are different from the parameters in each of these indexed documents.
In order to map the parameters of the request to the parameters of the ElasticSearch Document, this mapping is maintained.
queries.dateRefField: Each of these modules have separate indexes. And all of them have their own date fields.
When there is a date filter applied against these visualizations, each of them has to apply it against their own date reference fields.
In order to maintain what is the date field in which index, we have this configured in this configuration parameter.
chartType: As there are different types of visualizations, this field defines what is the type of chart/visualization that this data should be used to represent.
Chart types available are:
metric - this represents the aggregated amount/value for records filtered by the aggregate es query
pie - this represents the aggregated data on grouping. This is can be used to represent any line graph, bar graph, pie chart or donut
line - this graph/chart is data representation on date histograms or date groupings
perform - this chart represents groping data as performance-wise.
table - represents a form of plots and values with headers as grouped on and a list of its key, values pairs.
xtable - represents an advanced feature of the table, it has additional capabilities for dynamic adding header values.
valueType: In any case of data, the values which are sent to the plot, might be a percentage, sometimes an amount and sometimes it is just a count.
In order to represent them and differentiate the numbers from the amount from the percentage, this field is used to indicate the type of value that this Visualization will be sending.
action: Some of the visualizations are not just aggregations of data sources. There might be some cases where we have to do a post-aggregation computation.
For Example, in the case of the top 3 Performing ULBs, the Target and Total Collection are obtained and then the percentage is calculated. In these kinds of cases, the action that has to be performed on the data obtained is defined in this parameter.
documentType: The type of document upon which the query has to be executed is defined here.
drillChart: If there is a drill down on the visualization, then the code of the Drill Down Visualization is added here. This will be used by Client Service to manage drill-downs.
aggregationPaths: All the queries will be having Aggregation names in them. In order to fetch the value out of each Aggregation Response, the name of the aggregation in the query will be an easy bet. These aggregation paths will have the names of Aggregation in it.
insights: It is to show the data with the comparison of last year with arrow symbols, it will show the data in how much % is increased or decreased.
_comment: In order to display information on the “i” symbol of each visualization, Visualization Information is maintained in this field.
Water & Sewerage my applications feature for citizen users - technical implementation doc
Objective: Provide the UI technical implementation details for the My Applications feature available for citizen users.
Users can review the list of applications and their status registered under their mobile numbers in the My Applications tab. Each application for the initial view displays Application No., Service Name, Consumer Name, Property Id, Status, SLA and Property Address with the View Details option, through which the user can look up more details about the application.
Once the user clicks on the View Details button, the Application Details page is displayed with all the necessary information about the application.
There are two links provided in the application details screen. One is for Property Details which allows users to see the in-depth details of the property associated with the application. The other is available on the Connection Details page to view the Additional Details of the connection for the application.
Timeline Component
The Timeline component is present at the end of the application details which tells about the current status and history of the application (open to edit, approve, reject, or closed).
The file path for the My Applications and Application Details common Index is given below. It provides an understanding of the working of the code.
File path: packages/modules/ws/src/pages/citizen/WSMyApplications/index.js
The template for My Application is available within packages/modules/ws/src/pages/citizen/WSMyApplications/ws-application.js. The Application Details page is available within packages/modules/ws/src/pages/citizen/WSApplicationDetails.js. The Application list is retrieved by calling the search API "/ws-services/wc/_search" & "/sw-services/swc/_search"
Hooks used for fetching the applications for Water and Sewerage are:
No MDMS data is used here. The data is loaded from the Search API.
For My Applications, the Localization keys are added to the ‘rainmaker-ws’ locale module same as My connections and Create. Changes, updates or addition of any new localization key is done in the same locale module only.
Water and Sewerage disconnection application for citizen users - technical implementation doc
Objective: To provide user facilities to disconnect an active W&S connection when they are not using the service. So, that they don’t have to pay for any charges
To disconnect, connection should be in ACTIVE state. Connections which are under WORKFLOW or INACTIVE are not eligible for disconnection.
In cases dues are pending, user has to clear the dues before applying for Disconnection.
‘Disconnect’ option itself is not displayed in the action list for the connection which are INACTIVE.
Route
My Connections → View Connection Details → Disconnect
Clicking on Disconnect it navigates to the Water and Sewerage Disconnection Application Document required screen.
File Path:
File Path:
Date Validation
On Clicking on Next button in the document required screen,
if the proposed date is after <slaDays for disconnection> it will route to Application form Water & Sewerage Disconnection, else it will throw an error in the form of toast messgae, “Date should be after <slaDays for disconnection> from application create Date“.
To get the SLA days /egov-workflow-v2/egov-wf/businessservice/_search?businessServices=DisconnectWSConnection API call is made on load of Application Form Page
Technical Implementation Details:
Initial MDMS call is being made on page load
Mdms data :
On Clicking on Next button in the Application Form Screen , it will route to Upload Documents Screen
On Clicking on Next button in the Upload Documents Screen , it will route to Summary Check Page Screen
In Check Page you can edit the entered data for Disconnection.
On Clicking on Submit button in the Check Page Screen , it will make water or sewerage create and update API calls.
Data fetch , load and render :
ws-services/wc/_create
Payload: WaterConnection: {
...data,
isdisconnection : true,
isDisconnectionTemporary: true (if Temporary Disconnection selected else false),
disconnectionReason: ““
},
disconnectRequest: true
sw-services/swc/_create
Payload: WaterConnection: {
...data,
isdisconnection : true,
isDisconnectionTemporary: true (if Temporary Disconnection selected else false),
disconnectionReason: ““
},
disconnectRequest: true
ws-services/wc/_update
Payload: WaterConnection: {
...data,
isdisconnection : true,
isDisconnectionTemporary: true (if Temporary Disconnection selected else false),
disconnectionReason: ““
},
disconnectRequest: true
sw-services/swc/_update
Payload: WaterConnection: {
...data,
applicationType: if(Water Application) "DISCONNECT_WATER_CONNECTION" else (if Sewerage Application) "DISCONNECT_SEWERAGE_CONNECTION",
processInstance: {
...data?.processInstance,
businessService: if(Water Application) "DisconnectWSConnection" else (if Sewerage Application) "DisconnectSWConnection",
action: "SUBMIT_APPLICATION", }
},
After the Success of the Create and Update calls it routes users to the Disconnection Acknowledgement screen.
Clicking on the Download Acknowledgement Form button downloads the Water or Sewerage Disconnection Acknowledgement PDF.
| Environment Variables | Description |
|---|---|
Put the indexer config file into the config repo under egov-indexer folder. (egovernments/configs )
| Title | Link |
|---|---|
| Title | Link |
|---|---|
| URL | Roles | Action ID |
|---|
Postman collection for W&S-dss: ,
| URL | Roles | Action ID |
|---|
Documents:
Disconnection Type:
File Path:
File Path:
File Path:
Link
/ws-calculator/meterConnection/_create
/ws-calculator/meterConnection/_search
/waterCalculator/_calculate
/waterCalculator/_updateDemand
Link
/ws-services/wc/_create
/ws-services/wc/_update
/ws-services/wc/_search
Title
Link
/ws-calculator/meterConnection/_create
/ws-calculator/meterConnection/_search
/waterCalculator/_estimate
/waterCalculator/_calculate
/waterCalculator/_updateDemand
/waterCalculator/_jobscheduler
/waterCalculator/_applyAdhocTax
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 contain the idgen format name for water application
egov.idgen.wcapid.format
This variable contain the idgen format for water application ex:- WS/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
egov.idgen.wcid.name
This variable contain the idgen format name for water connection
egov.idgen.wcid.format
This variable contain the idgen format for water connection ex:- WS_AP/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
API Swagger Documentation
Water Calculator Service
/ws-services/wc/_create
/ws-services/wc/_update
/ws-services/wc/_search
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Title
Link
API Swagger Contract
Water Service Document
Water and Sewerage modify create application feature for employees - technical implementation doc
Objective: The Apply and Modify feature in the WS module allows counter employees to create or modify Water and Sewerage applications.
Every application is a part of the workflow.
Once a new application connection is activated, the system generates the consumer code. This code is used to route users to the connection details screen from the search/connection screen. Clicking on the Take Action button displays multiple options based on conditions. Clicking on the Modify Connection option routes users to the modify screen.
To disconnect, the connection should be in an ACTIVE state. Connections which are under WORKFLOW or INACTIVE are not eligible for Modify.
Connection details: Employee: Water and Sewerage Connection Details
Creating an application on the water and sewerage module generates an acknowledgement form that can be downloaded by users. Processing the applications pending field inspection and user payment generates the Estimation Letter and Sanction Letter respectively. Find the configuration details for enabling the download of these documents.
Acknowledgement Download
Users can download the acknowledgement after submitting the W&S Create application.
Data fetch, load and render:
ws-services/wc/_create
sw-services/swc/_create
Case 1: In the case of Water connections:
Clicking on the Submit button calls the ws-services/wc/_create API and creates the application. The update API ws-services/is called after getting a successful response on creating the application.
Case 2: In the case of Sewerage connections:
Clicking on Submit button calls the sw-services/swc/_create API and creates the application. The update API sw-services/swc/_updateis called after getting a successful response on creating the application.
Successful create and update calls routes users to the acknowledgement screen.
For the application PDF, all related code is written to the W&S folder in the below-mentioned file.
Water and Sewerage disconnection application details feature for employees - technical implementation doc
Objective: The Water and Sewerage 'Apply Disconnection' is the major feature in WS Module. It allows Counter Employees to create Water and Sewerage Applications.
Every application is a part of the workflow.
Once a new application connection is activated, the system generates a consumer code. This code is used to route users to the connection details screen from the search/connection screen.
Clicking on the Take Action button displays multiple options based on conditions. Clicking on the Apply for Disconnection option routes users to the Disconnect Document Required screen.
To disconnect, the connection should be in an ACTIVE state. Connections which are under WORKFLOW or INACTIVE are not eligible for disconnection.
In cases dues are pending, the user has to clear the dues before applying for Disconnection.
The Disconnect option itself is not displayed in the action list for the connection which is INACTIVE.
Connection details:Employee: Water and Sewerage Connection Details
Clicking on the Apply button routes users to the Disconnection apply screen.
Acknowledgement screen
Successful create and update calls routes users to the acknowledgement screen.
Users get the acknowledgement form once they have created and submitted their application successfully. Processing of applications pending field inspection and user payment enables the download of the estimation letter and the sanction letter respectively. The section below provides the configuration for the document downloads.
Users can download the acknowledgement after submitting the W&S Create Application.
Data fetch, load and render
ws-services/wc/_create
sw-services/swc/_create
Case 1: In the case of Water connections:
Clicking on Submit button calls the ws-services/wc/_create API and creates the application. The update API ws-services/wc/_updateis called after getting a successful response on creating the application.
Case 2: In the case of Sewerage connections:
Clicking on Submit button calls the sw-services/swc/_create API and creates the application. The update API sw-services/swc/_update is called after getting a successful response on creating the application.
The code for the application PDF is written in the below-mentioned file.
Water and Sewerage connection details feature for employees - technical implementation doc
Objective: Provide the details of the connection to the employees and citizens.
The Connection Details page provides the details about the connection, the property which is used to create the connection and the owner details of the property. The same can be downloaded as a PDF file or printed directly from the page.
Employees will be able to open the “View Consumption Details” page from the “Connection Details” page for the Metered Reading Connection. The Consumption Details page will provide more options like adding details of the consumed water charges.
Users have the option to add new meter readings. Clicking on it displays a pop-up, where the user can fill in the asked details and click on submit to add a new meter reading for the connection.
The hook used for fetching connection details -
Connection Details File Path: https://github.com/egovernments/DIGIT-Dev/blob/master/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/employee/connectionDetails/ConsumptionDetails.js
Meter Reading File Path: https://github.com/egovernments/DIGIT-Dev/blob/develop/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/employee/connectionDetails/connectionDetails.js
Hook details for connection details search and others:
Downloads File Path: https://github.com/egovernments/DIGIT-Dev/blob/develop/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/employee/connectionDetails/connectionDetails.js
Download Receipt Method:
Connection Details Receipt Method:
Localisation keys used on this page are added under “rainmaker-ws” locale module and the same should be used if any new keys are added to this page.
Water & Sewerage create applications feature for citizen users - technical implementation doc
Objective: Provide the UI technical implementation details for the Create applications feature available for citizen users.
To provide user facilities to add new W&S connection applications and view the details of the connection and application currently on their number. It also allows the users to update the connection or edit the application.
Water & Sewerage Create
Users can add new connections using the Apply For New Connection button. The workflow adds valid information, as per the question asked. At the end of the flow, a Check page is displayed on which the user can cross-verify the information entered. The application is created upon submission.
Water & Sewerage Create Flow:
WNS information screen is displayed after login, which helps the user to understand the necessary documents needed to complete the new registration for a new connection.
Property Details Flow:
Users can either add the property details by using the property search of commonPT or can choose to create a lightweight property using the commonPT create. Both screens lead users to the property details page, which displays a summary of the property selected or created.
Connection Details Flow:
Here users can either select to go with the owners of the property or can choose to add connection holder details. Users have 3 options to choose from in context to the type of connection required:
Water Connection
Sewerage Connection
Water and Sewerage Connection
Based on the selection, the create API is called.
Document Details:
Users can upload all documents related to the data entered. The list of documents is controlled by the MDMS data and hence can be modified as per requirements.
Check Page & Acknowledgement Screens:
Users can cross-verify the data entered throughout the flow on the Check page. If any changes or updates are required to the data users can do this by clicking on the Edit option available in front of the section header. This routes them to the specific page where data needs to be changed and then the whole flow needs to be repeated again in order to submit the application.
For the final Initiation of the application Update API is being called, which is used to particularly send the data of document details:
If the API response is successful, then the Acknowledgement Screen is displayed. Else, the Failed Acknowledgement Screen is displayed.
The structure followed here is the same as in the previous modules. The path for the WNS Main Index is given below and can be used to understand the starting point of the flow:
/DIGIT-Dev/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/citizen/WSCreate/index.js
The module had been segregated into a specified structure. The screen configuration is inside the PageComponent Folder, and the configuration for routing of the pages is mentioned in the config folder which is common for both citizen users as well as employees.
The Create API is called based on the service selected on the Connection Details page. The following hook call can be found on the respective pages :
/DIGIT-Dev/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pageComponents/WSSewerageConnectionDetails.js
/DIGIT-Dev/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pageComponents/WSWaterConnectionDetails.js
After the check page, the Update API is called and this is available on the Acknowledgement page:
/DIGIT-Dev/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/citizen/WSCreate/WSAcknowledgement.js
After completing the flow, the users can download the acknowledgement PDF form of the application created and the config for the PDF generation is available in the link given below:
/DIGIT-Dev/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/utils/getWSAcknowledgementData.js
Throughout the flow, a few of the page data is imported from the MDMS. Following is the list of pages using MDMS data. The pages .js files are available in the page component column.
For calling the MDMS data React Hooks are used so that it could be shared throughout the modules. Below is the little code snippet for the call used for MDMS.
The localization keys are added under the ‘rainmaker-ws’ locale module. In future, if any new labels are implemented in the Water and Sewerage they should also be pushed in the locale DB within the rainmaker-ws locale module.
Water and Sewerage employee application UI technical implementation doc
Objective: Provide employees with purposeful workflow actions.
The same screen is used for both Application Details and Modify Application Details workflows. The details are provided below for the applicable scenarios.
Clicking on the application number from the inbox/search screen/connection search, routes to the application details screen. A search call is made before rendering the screen and details are populated based on the search response.
Application Details Screen
Refer to Employee: Ad-hoc Rebate/Penalty and View Breakup in application details
Once the Pending for Field Inspection stage is complete (if the status is pending approval) an Estimation Letter is generated.
Once the payment stage is complete (and the status is pending for connection activation), the Sanction letter and receipt are generated.
Application Details File Path: https://github.com/egovernments/DIGIT-Dev/blob/develop/frontend/micro-ui/web/micro-ui-internals/packages/modules/ws/src/pages/employee/ApplicationDetails.js
Hook details for application details search:
The timeline view is common for all modules. File path: https://github.com/egovernments/DIGIT-Dev/blob/develop/frontend/micro-ui/web/micro-ui-internals/packages/modules/templates/ApplicationDetails/index.js
const applicationDownloadObject = { order: 3, label: t("WS_APPLICATION"), onClick: handleDownloadPdf, };
const wsEstimateDownloadObject = { order: 1, label: t("WS_ESTIMATION_NOTICE"), onClick: () => getFiles([applicationDetails?.applicationData?.additionalDetails?.estimationFileStoreId], stateCode), };
Sanction Fee Method Reference:
const sanctionDownloadObject = { order: 2, label: t("WS_SANCTION_LETTER"), onClick: () => getFiles([applicationDetails?.applicationData?.additionalDetails?.sanctionFileStoreId], stateCode), };
Receipt Method Reference:
const appFeeDownloadReceipt = { order: 4, label: t("DOWNLOAD_RECEIPT_HEADER"), onClick: () => getRecieptSearch(applicationDetails?.applicationData?.tenantId ? applicationDetails?.applicationData?.tenantId : Digit.ULBService.getCurrentTenantId(), reciept_data?.Payments?.[0], applicationDetails?.applicationData?.applicationNo, receiptKey ), };
Localisation keys are added in the ‘rainmaker-ws’ locale module.
Employee Roles and Credentials - The credentials and details are available in the document attached below:
Water and Sewerage modify application feature for employees - technical implementation doc
Objective: Provide employees with specific workflow actions.
The same screen is used for both application details and to modify application details. The page provides the details of these workflows based on the conditions.
Clicking on the Application Number in the inbox/search screen/connection search routes users to the application details screen. A search call is made before rendering the screen and details are populated based on the search response.
Modify Application Details Screen
Timeline View:
Water & Sewerage Workflow Table
Hook details for application details search:
It is common for all modules, find the path here: https://github.com/egovernments/DIGIT-Dev/blob/develop/frontend/micro-ui/web/micro-ui-internals/packages/modules/templates/ApplicationDetails/index.js
Method Reference:
const applicationDownloadObject = { order: 3, label: t("WS_APPLICATION"), onClick: handleDownloadPdf, };
Localisation keys are added in the ‘rainmaker-ws’ locale module.
Water & Sewerage Workflow:
View breakup, ad-hoc rebate and penalty details in applications feature for employees - technical implementation doc
Objective: Provide the UI screens and configuration details for the ad-hoc rebate or penalty feature and the view breakup option available in water and sewerage applications.
The Water and Sewerage ad-hoc Rebate/Penalty is a feature in WS Module. It allows employees to add rebates or penalties for Water and Sewerage Applications.
Clicking on the Add Rebate/Penalty option opens the popup with the fields.
Clicking on the Add button on the pop-up screen closes the pop-up window and the filled-in data is updated in the Fee Estimate card.
Note: After adding add rebate/penalty, we must perform at least one action, then only it will save the data in WS/SW service. Estimated API will give the results based on the data, presently we are saving the data in the additional details of the WS/SW service.
The View Breakup feature in the WS module allows employees to view the details of tax heads for water and sewerage applications.
After logging in with Water and sewerage employee roles the user gets the option to view the breakup in the new WS/SW Application in the Fee Estimate card in the WS/SW application details.
Clicking on the View Breakup option opens the popup with the updated data.
Once the user logs in with "WS_APPROVER", "WS_FIELD_INSPECTOR", "SW_FIELD_INSPECTOR", "SW_APPROVER". If the roles and actions buttons are visible on the screen, then the user gets the option to add Ad-hoc Rebate/Penalty to a new WS/SW application in the Fee Estimate card in the WS/SW application details.
Localisation keys are added under the ‘rainmaker-ws’ locale module.
This document provides the steps for configuring water & sewerage reports. There are 3 Water & Sewerage reports that can be generated:
Receipt Register Report
Collection Register Report
Defaulter Report
To configure the Water & Sewerage report, follow the steps below:
In action-test.json:
Above is the sample for Defaulter Report, in a similar way other reports can also be configured.
Objective: To provide the facility of abstraction of private details of users. It will also help in masking sensitive details and unmasking the information by authorized roles whenever needed.
Masking / Un-Masking of Data
Particular entries of an object from the search API will appear masked if it is enabled in the MDMS (mentioned in the technical implementation section below). This is based on roles and if the value is masked in UI, the eye icon will be available adjacent to it. Clicking on this icon allows users to unmask it.
Once the user clicks on the eye icon, the corresponding search API is called with plainAccessRequestobject in the request info. This allows the data to be unmasked in the response object and leads to the refreshing of values and the whole data is visible. The eye icon will not be visible anymore.
Let us take an example of an object in the MDMS file i.e. WnSConnection
Here the unique identifier is defined as applicationNo, so from UI plain request object which is sent in Search API contains recordId as applicationNo. Similarly, the list of attributes mentioned here is received as masked by default in the response object from the Search API. The roles mentioned in the roles array defines the roles for which these attributes were to be masked.
Masking in details Page
In the UI code repository, If any particular data has to be masked then we have to send a Privacy object along with corresponding data to ApplicationDetailsTemplate
Example:
For water application details the connection holder details have to be masked. The privacy object is passed from the applicationdetails hook.
Relationship object of connection holder details below:
UnMaskComponent is the main component which handles all the unmasking action through the eye icon. The following component must be integrated if the eye icon needs to be implemented in any given place.
This loads the MDMS data and filters it out as per the specified model for which the unmaskComponent is being called. Next, it calls the checkprivacy obejct to verify if privacy is enabled for that particular role and model (refer to below code for privacy check).
This triggers the search hook called again with plainAccessRequest (mentioned in the above picture), but for that privacy object has to be sent in the hook for re-triggering.
Unmasking in Edit Details page
For enabling the eye icon in the text field similar steps have to be followed :
The search API Hook used to prefill the data in the edit screen should have a privacy object being sent in it.
Unmask component has to be defined with the corresponding component.
SecurityPolicy.json is used to handle all privacy-related action
Water and Sewerage disconnection application details feature for employees - technical implementation doc
Objective: Provide employees with specific workflow actions.
This page provides the workflow details and actions for water and sewerage disconnection application details.
Clicking on the Application Number in the inbox/search screen routes users to the disconnection application details screen. A search call is made before rendering the screen and details are populated based on the search response.
Application Details Screen
Application Form
Disconnection Notice
Water & Sewerage Disconnection Workflow Table
Hook details for application details search:
Localisation keys are added in the ‘rainmaker-ws’ locale module.
Migration Document for Bill Amendment W&S
This document contains the steps to create new workflow configs specific to WS and SW modules for Bill Amendment.
Create the new Workflow configs in the same tenant-Id as the one you want to replace in the applications. New configs for WS and SW bill amendment are as follows:
Curl for WS Bill Amendment Config:
Curl for SW Bill Amendment Config:
eg:--
List all the states from the process instances of the old workflow(business service) config. select uuid,state from eg_wf_state_v2 where businessserviceid=(select UUID from eg_wf_businessservice_v2 where businessservice='BS.AMENDMENT' and tenantid='pb');
List the states from the new business service created for replacement using this query SELECT UUID, state FROM eg_wf_state where businessService='WS.AMENDMENT' AND business='WS' AND tenantid='pb'
SELECT UUID, state FROM eg_wf_state where businessService='SW.AMENDMENT' AND business='SW' AND tenantid='pb'
Replace the state-ids of the old workflow in the eg_wf_processinstance table with stateids of the new workflow.
Write an update query (one for each state UUID) to rewrite the process-instance table, as shown above - update eg_wf_processinstance_v2 set status={new state uuid} AND businessservice={WS.AMENDMENT} and modulename={WS} where businessservice={BS.AMENDMENT} and status={old state uuid} and businessid like '%WS%';
update eg_wf_processinstance_v2 set status={new state uuid} AND businessservice={SW.AMENDMENT} and modulename={SW} where businessservice={BS.AMENDMENT} and status={old state uuid} and businessid like '%SW%';
Note: businessid like '%SW% or businessid like '%WS% will be used depending on the New businessService that you are using. moduleName in the above query would take WS or SW in sync with the new businessService
The status and businessservice columns should be set to the new values from the newly created business-service master create based on the old status and id of the process-Instance.
Rename or delete the old business service (BS.AMENDMENT) to avoid any of the applications using it wrongly in future. {update eg_wf_businessservice set businessservice='BS.AMENDMENT-deprecated' where businessservice='BS.AMENDMENT'}
UI/BACKEND will have to replace their configs to fetch the workflow configs for WS and SW. Changes required from UI: Bill Amendment Workflow _create and _update APIs - replace businessservice BS.AMENDMENT with WS.AMENDMENT/SW.AMENDMENT and moduleName BS with WS/SW as per the requirement. Bill Amendment Inbox - replace businessservice BS.AMENDMENT with WS.AMENDMENT/SW.AMENDMENT as per the requirement.
| API | Roles | Action ID |
|---|---|---|
| S.No. | API | Roles | Action ID |
|---|---|---|---|
| API | Action ID | Role |
|---|---|---|
| PageComponent | MDMS Detail | Module Detail Name | |
|---|---|---|---|
| API | Roles | Action ID |
|---|---|---|
| API | Action ID | Roles |
|---|---|---|
Employee Roles and Credentials: The login credentials and details are available in the document here:DIGIT Login Credentials
| S.No | API | Action ID | Roles |
|---|---|---|---|
Employee Roles and Credentials: The login credentials and details are available in the document here:DIGIT Login Credentials
WS/SW Application details:
WS/SW Application details:
Route:
Fee Estimation File Path: and the initial data and logic is from the Application details in
Fee Estimation Pop-up functionality is present in the
Route:
View Breakup File Path: and the initial data and logic is from the Application details in
View Breakup pop-up functionality is present in the
| API | Action ID | Roles |
|---|
Employee Roles and Credentials: The employee roles and credentials are available in the document here:
The masking of data and its dependency on roles is defined in the following MDMS file:
Here uuid is the record id which we have to send for a particular model; fieldName is the name defined in the MDMS as well as the exact param which we receive in the response object; model is the model from SecurityPolicy MDMS; showValue is sent as true if we want to append any data with the newly unmasked data. Usually, this is used for property address and loadData is an object in which we sent the body and params for the API call that must be made in order to get the unmasked data. Refer code -
ApplicationDetailsTemplate has the eye icon already integrated with Row Component, which can be enabled by passing the above privacy object. Refer code -
If the checkprivacy is returned true, the eye icon is visible and clicking on it calls the updateprivacy method defined in useprivacycontext hook: Refer -
For all methods related to privacy, refer to the document here:
Refer: Index page for edit details:
| MDMS Detail | Module Details Name | Master Detail Name |
|---|
Application Details File Path:
Disconnection Notice Download File Path:
Application Form Download File Path:
The timeline view is common for all modules. Timeline view file path:
| S.No. | API | Action ID | Roles |
|---|
Find the login credentials and details in the document here:
/egov-mdms-service/v1/_search
WS_CEMP, SW_CEMP
954
/ws-services/wc/_create
WS_CEMP, SW_CEMP
1899, 1917
/sw-services/swc/_create
WS_CEMP, SW_CEMP
1899, 1917
/ws-services/wc/_update
WS_CEMP, SW_CEMP
1899, 1917
/sw-services/swc/_update
WS_CEMP, SW_CEMP
1899, 1917
/filestore/v1/files/url
EMPLOYEE
1
/egov-mdms-service/v1/_search
WS_CEMP, SW_CEMP
954
2
/ws-services/wc/_create
WS_CEMP, SW_CEMP
1899, 1917
3
/sw-services/swc/_create
WS_CEMP, SW_CEMP
1899, 1917
4
/ws-services/wc/_update
WS_CEMP, SW_CEMP
1899, 1917
5
/sw-services/swc/_update
WS_CEMP, SW_CEMP
1899, 1917
6
/filestore/v1/files/url
EMPLOYEE
/ws-calculator/meterConnection/_search
1913
EMPLOYEE
/billing-service/bill/v2/_fetchbill
1862
EMPLOYEE
/ws-services/wc/_search
1900
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
/sw-services/swc/_search
1919
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
/property-services/property/_search
1897
EMPLOYEE
WSDocsRequired
List of documents required for each category
ws-services-masters
Documents
WSConnectionHolderDetails
Gender List
common-masters,
PropertyTax
GenderType,
OwnerType
WSWaterConnectionDetails
Pipe Size
ws-services-calculation
PipeSize
WSDocumentDetails
List of documents to be uploaded
ws-services-masters
Documents
/egov-mdms-service/v1/_search
CITIZEN
954
/ws-services/wc/_create
CITIZEN
1899, 1917
/sw-services/swc/_create
CITIZEN
1899, 1917
/ws-services/wc/_update
CITIZEN
1899, 1917
/sw-services/swc/_update
CITIZEN
1899, 1917
/filestore/v1/files/url
CITIZEN
Role
Action
Next State
Status
Citizen/ Counter Employee/WS_CEMP/ SW_CEMP
INITIATE
INITIATED
INITIATED
Citizen/Counter Employee/WS_CEMP / SW_CEMP
EDIT
EDIT/ DOCUMENTVERIFICATION
Pending for Document Verification
Citizen/Counter Employee/WS_CEMP / SW_CEMP
Send Back to Citizen
Pending for Citizen Action
Pending for Citizen Action
WS_DOC_VERIFIER / SW_DOC_VERIFIER
VERIFY &FORWARD
FIELDVERIFICATION
Pending for Field Verification
WS_FIELD_INSPECTOR / SW_FIELD_INSPECTOR
VERIFY &FORWARD
PENDINGAPPROVAL
Pending for APproval
WS_APPROVER / SW_APPROVER
APPROVE
PENDINGPAYMENT
Pending for Payment
Citizen/Counter Employee/WS_CEMP / SW_CEMP
PAY
Approved
Approved
WS_APPROVER / SW_APPROVER
REJECT
Rejected
Rejected
WS_CLERK/SW_CLERK
Activate Connection
Connection activated
Connection activated
/access/v1/actions/mdms/_get
870
/user/_search
604
/localization/messages/v1/_search
1531
/egov-workflow-v2/egov-wf/businessservice/_search
1743
EMPLOYEE
/ws-services/wc/_search
1900
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
/sw-services/swc/_search
1940
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
/property-services/property/_search
1897
PT_CEMP,PT_DOC_VERIFIER,PT_FIELD_INSPECTOR,PT_APPROVER
/ws-services/wc/_create
1899
WS_CEMP
/filestore/v1/files/url
1528
EMPLOYEE
/ws-services/wc/_update
1901
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
/sw-services/swc/_update
1939
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
/ws-calculator/waterCalculator/_estimate and /sw-calculator/sewerageCalculator/_estimate
1966,
1967
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
/egov-hrms/employees/_search
1752
Role
Action
Next State
Status
Citizen/ Counter Employee/WS_CEMP/ SW_CEMP
INITIATE
INITIATED
INITIATED
WS_APPROVER / SW_APPROVER
VERIFY &FORWARD
PENDINGAPPROVAL
Pending for APproval
WS_APPROVER / SW_APPROVER
APPROVE
Approved
Approved
WS_APPROVER / SW_APPROVER
REJECT
Rejected
Rejected
Role
Action
Next State
Status
Citizen/ Counter Employee/WS_CEMP/ SW_CEMP
INITIATE
INITIATED
INITIATED
WS_APPROVER / SW_APPROVER
VERIFY &FORWARD
PENDINGAPPROVAL
Pending for APproval
WS_APPROVER / SW_APPROVER
APPROVE
Approved
Approved
WS_APPROVER / SW_APPROVER
REJECT
Rejected
Rejected
12
/ws-calculator/waterCalculator/_estimate and /sw-calculator/sewerageCalculator/_estimate
1966,
1967
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
1
/access/v1/actions/mdms/_get
870
13
/egov-hrms/employees/_search
1752
4
/egov-workflow-v2/egov-wf/businessservice/_search
1743
EMPLOYEE
9
/filestore/v1/files/url
1528
EMPLOYEE
3
/localization/messages/v1/_search
1531
7
/property-services/property/_search
1897
PT_CEMP,PT_DOC_VERIFIER,PT_FIELD_INSPECTOR,PT_APPROVER
6
/sw-services/swc/_search
1940
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
11
/sw-services/swc/_update
1939
SW_CEMP,SW_DOC_VERIFIER,SW_FIELD_INSPECTOR,SW_CLERK
2
/user/_search
604
5
/ws-services/wc/_search
1900
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
10
/ws-services/wc/_update
1901
WS_CEMP,WS_DOC_VERIFIER,WS_FIELD_INSPECTOR,WS_APPROVER,WS_CLERK
|
|
|
/ |
|
|
|
|
|
|
|
|
|
|
|
List of Privacy object and roles associated to it |
|
|
# | Action | Role | From State | To State |
1 | Initiate Application | Citizen/ Counter Employee |
| Initiated |
2 | Submit Application | Citizen/ Counter Employee | Initiated | Pending for document verification |
3 | Verify and Forward | Document Verifier | Pending for document verification | Pending for field inspection |
4 | Verify and Forward | Field Inspector | Pending for field inspection | Pending approval for disconnection |
5 | Send Back | Document Verifier | Pending for document verification | Pending for counter employee action |
6 | Send Back | Field Inspector | Pending for Field inspection | Pending for document verification |
7 | Send Back | Approver | Pending approval for disconnection | Pending for field inspection |
8 | Send Back To Citizen | <roles having access> | <Current Status> | Pending for citizen action |
9 | Re-submit | Citizen/ Counter Employee | Pending for citizen action OR Pending for counter employee action | <To the status application was sent back to citizen> |
12 | Approve | Approver | Pending approval for disconnection | Pending for payment |
13 | Reject | <roles having access> | <Current Status> | Rejected |
14 | Payment/ Collection | Citizen/ Counter Employee | Pending for payment | Pending for disconnection execution |
15 | Execute Disconnection | Clerk | Pending for disconnection execution | Disconnection Executed
|
1 |
|
|
|
2 |
|
|
|
3 |
|
|
|
4 |
|
|
|
5 |
|
|
|
6 |
|
|
|
7 |
|
|
|
8 |
|
|
|
9 |
|
|
|
10 |
|
|
|
11 |
|
|
|
12 | / |
|
|
13 |
|
|
|
uuid | state |
94055bb3-210c-4184-93ac-99e288ab00d9 |
|
b0fc6007-8b02-4753-8e50-1fdb29e559da | APPROVALPENDING |
b9ea9101-09ff-4a8e-97c1-d43b3311af73 | REJECTED |
ea5668ee-d8db-4c16-839b-64299e12f8fc | APPROVED |
468ce854-e19d-4a0f-97a0-66745f2034af | PENDING_FOR_CITIZEN_ACTION |
uuid | state |
New uuid |
|
New uuid | APPROVALPENDING |
New uuid | REJECTED |
New uuid | APPROVED |
New uuid | PENDING_FOR_CITIZEN_ACTION |
Title | Link |
report config folder |
Report service |
Backend technical documentation
This document highlights the changes that need to be done in a Water and Sewerage module to support the privacy feature.
Prior knowledge of Java/J2EE
Prior knowledge of Spring Boot
MDMS service
Encryption service
The Security Policy MDMS file must have the model configuration for fields to be encrypted/decrypted. The following models have been used for W&S in the SecurityPolicy.json file:
Also, add the following under roleBasedDecryptionPolicy of User model(already existing):
Refer to the SecurityPolicy.json file for full reference.
For modules, there is no such hard rule or pattern for naming the model, but it should be related to that service. ex: 1.) For user service we have two security policy models User which is used when a user tries to search other user data. The PII data will be available in masked, plain or encrypted form depending on the visibility set for an attribute in the MDMS. The other model is UserSelf which is used when a user tries to search their own data. The data is available as per the configuration set there.
For report and searcher config the model name should be similar to the value that we are setting in the field decryptionPathId. ex:- Employee Report. Employee Report Security Model.
2.) For W&S we have 2 models -WnSConnection and WnSConnectionOwner which are meant for ConnectionHolderDetails.
2 different models for connectionHolder data are required since some data for connectionHolder comes from the W&S tables and the remaining is fetched from the User table. So to maintain consistency we had to have 2 different models.
For an attribute where its firstLevelVisibility is set as "Masked" whenever the respective search API is called without the plain Access Request, the masked value is returned as the API response for that attribute. for ex:- if for mobile number attribute’s firstLevelVisibility is masked and its plain value is 9089243280 then in response, the value is displayed as ******3280. The masking pattern is defined in the MaskingPattern MDMS file and the pattern is picked up based on the patternId. Similarly, if the firstLevelVisibility is set as "ENCRYPTED" we will get the encrypted value of that plain data (which is present in DB) in response.
NOTE: For adding of new attribute for encryption, the following things need to be kept in mind:
We do not have a direct approach to it, but a workaround is as follows:
We need to make sure which property has to be encrypted and what is the path of the property in the Request/Response object of W&S. If PII data is for connectionholder and is coming from WnS tables directly, then with the Proper name and path of the object we can add a new Property in existing model WnSConnection.
The inclusion of any new attribute here would need encryption of the old data for this new property.
For that, in MDMS, we will have to replace the existing model attributes with only new attributes and hit the _encryptOldData API. Once old data encryption is done, we can put back all the required attributes (old and +new) in the model.
Also, before starting the encryption of old data, we will have to check the latest record of the table eg_ws_enc_audit / eg_sw_enc_audit / eg_pt_enc_audit(for PT) . If the latest record has offset and record count value other than 0 then insert a random record with offset and record count as 0 and createdtime and encryptiontime as a current timestamp in millis in utc.
Any data other than that of connectionHolder would need a new model to be created and changes at the code level as well. For old data encryption of new property other than that of connectionHolder, we will have to have code changes as well.
For further info about adding models refer here.
Upgrade services-common library version.
Upgrade the tracer library version.
Add enc-client library
In ws-services encryption and decryption endpoints should be declared as follows:
In sw-services encryption and decryption endpoints should be declared as follows:
EncryptionDecryptionUtil.java
We need an interfacing file for handling the encryption and decryption of attributes and for interacting with the enc-client library directly. For reference follow the below code snippet:
You may find the file here in the repo.
UnmaskingUtil.java
UnmaskingUtil.java file helps in extracting the plain data of the Owner from the User service. This file also contains a method that swaps the PlumberInfo in a similar manner.
For reference follow the below code snippet:
You may find the file here in the repo.
The following method is added in WaterServiceImpl.java for encrypting the entire data
Method to decrypt the water/sewerage data:
The following method is added in WaterServiceImpl.java for decrypting the entire data
_search API Changes
During the search call the PII data needs to be masked in the response received. For this, the searchCriteria needs to be encrypted before fetching details and eventually the data retrieved needs to be decrypted and then returned to the user.
Following changes need to be made in WaterServiceImpl.java
You may find the file here in the repo.
If you want to get all the PII data in the plain format then in the search request add the search param “isInternalCall“ as “true”
If the user wants only specific fields to be unmasked then add the plainAccessRequest in the RequestBody in the following format:
plainAccessRequest contains :
1. recordId which will take the uuid of the user as an input for which PII data has to be unmasked, and
2. plainRequestFields will take an array of attributes that need to be unmasked. These attributes should comply with the attributes used in the Mdms SecurityPolicy.json’s models created.
For unmasking PlumberInfoMobileNumber, recordId will take the applicationno as value.
_create and _update API Changes
In _create and _update API calls the data needs to be encrypted before the data for application/connection is pushed to respective topics.
A sample code line for encrypting data in these calls is as follows:
A sample code line for decrypting data in these calls is as follows:
The entire method for create call can be found here: create method
and update call can be found here: update method
Before using the privacy feature in any environment, the encryption of existing data in the dB should be done.
An API for the same is written in the service and needs to be triggered by port-forwarding the respective service pod.
The data encryption API uses the existing plainSearch method and the encryption shall take place tenantId-wise. If tenantId is not specified then all the tenants are picked from the MDMS repository and the encryption happens for all the tenants. However, if the tenantId is specified, then the encryption happens only for that tenantId.
The following method is added to execute the oldDataEncryption
In WaterController.java
n WaterEncryptionService.java This service is solely for old data encryption and can be referred from here: https://github.com/egovernments/DIGIT-Dev/blob/8ec8592b73470c6dcdb1508caa1e6b1cf8ebb2ca/municipal-services/ws-services/src/main/java/org/egov/waterconnection/service/WaterEncryptionService.java A new persister file needs to be added for keeping track of progress of oldDataEncryption. Refer this ws-enc-audit-persister.yml and sw-enc-audit-persister.yml for the same.
Here is the Postman collection for all property, water and sewerage services for old Data encryption : https://www.getpostman.com/collections/b3858ec2020462a6407d
There is no need to re-index the base indexes(viz. water-services/ sewerage-services) once the API for old data encryption is executed as this will happen during the API execution itself. For any new data getting created, the new data will get saved in the encrypted format only in the indexes.
There are some changes in the Indexer file that need to be made for W&S to get the encrypted data from the external service like Property-service.
To enable or disable decryption in privacy, we need to make changes to only the privacy variable present in the environment file in DevOps.
For enabling, its value should be “true” else “false”.
For water-services variable is as follows:
For sewerage-services:
For user-service:
The variable can be found in the file here.
Note: Privacy decryption means: For any new application creation/ old application updation Internal data will be stored in the encrypted form itself, just that during decryption disabled it would give PLAIN text rather than masked one.
All the above changes need to be done for sw-services as well.
For detailed steps to configure the above changes refer to document: Detailed Steps to configure privacy in W&S module
This is one of the major application of the egov stack which helps municipal and citizens to handle sewerage services like creating sewerage connection, searching sewerage connection, sewerage connection, also creating property if it doesn't exist and creating and updating workflow were depending on different roles of the logged-in user he/she can perform various actions like editing or perform document verification and many more specified in workflow documentation and SMS & email notification sent to the owner for various actions performed in the workflow.
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 sewerage service persister config path added in it
PSQL server is running and a database is created to store sewerage 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.
The sewerage service provides multiple functionalities starting from serving as a central repository where one can create sewerage connection, update sewerage connection, search for a particular sewerage connection based on different criteria like mobile number, sewerage connection nos etc. and also creating property if it doesn't exist, creating and updating workflow were depending on different roles of the logged-in user he/she can perform various actions like editing or perform document verification and many more specified in workflow documentation and SMS & email notification sent to the owner for various actions performed in the workflow. The different services provided by the sewerage services are
Creating sewerage connection
Updating sewerage connection
Apply for Property creation.
Searching sewerage connection based on a few criteria mentioned in swagger documentation later
Creating property if it doesn't exist
Creating and updating workflow.
Table UML Diagram
****
MDMS configuration
master-config.json for sewerage service
Property creation through WNS module https://github.com/egovernments/egov-mdms-data/blob/DEV/data/pb/PropertyTax/PTWorkflow.json
Persister configuration: https://github.com/egovernments/configs/blob/qa/egov-persister/sewerage-persist.yml
Actions & Role Action Mapping
Actions
Role Action Mapping
Workflow business service config
Create businessService (workflow configuration) using the __/businessservice/_create. Following is the product configuration for sewerage service
Workflow for property creation through Water and Sewerage Module
Indexer config for sewerage-service
The indexer provides the facility for indexing the data to elastic search. https://github.com/egovernments/configs/blob/DEV/egov-indexer/sewerage-service.yml
Setup
Write the configuration for sewerage service. https://github.com/egovernments/configs/blob/DEV/egov-indexer/sewerage-service.yml
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.
Modify connection
After connection activation or legacy connection, we can edit the connection. This process based on a defined workflow. Any action is based on defined roles on the action level. For edit connection, we need to upload some supporting documents and mandatory info.
Workflow config for edit connection
Create businessService (workflow configuration) using the __/businessservice/_create. Following is the product configuration for editing sewerage connection.
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 sewerage 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 sewerage connection. For each road which goes under the cutting process, we have to fill in their road type details and road cutting area. Based on this information, the application one-time fee estimate is calculated.
This sw-service module is used to manage sewerage service connections against a property in the system.
Provide backend support for the different sewerage connection registration processes.
Mseva and SMS notifications on application status changes.
The elastic search index for creating visualisations and Dashboards.
Supports workflow which is configurable
To integrate, the host of sw-service module should be overwritten in the helm chart.
/sw-services/swc/_create should be added as the create endpoint for creating sewerage application/connection in the system
/sw-services/swc/_search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria
/sw-services/swc/_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)
TheSewerage Calculator Service is used for creating meter readings, searching meter readings, updating existing meter readings, calculating sewerage charges, demand generation, SMS & email notification to ULB officials on-demand generation and estimation of sewerage charges on basis of meter reading for existing sewerage application until the application is disconnected.
There are no additional billing slabs to be configured for sewerage disconnection, the calculation happens with the meter reading if added and uses existing billing slabs.
Criteria
connection type
building type
calculation attribute
property usage type
The combination of the above can be used to define the billing slab. Billing Slab is defined in MDMS under ws-services-calculation folder with the WCBillingSlab. The following is the sample slab (Same as the water connection).
For the disconnection application fee, the estimation will return all the related tax heads based on the criteria.
Following are the exemptions and taxes that are calculated:
Form fee
Scrutiny fee
Other charges
Security charges
Tax and cess
The sewerage charge is based on the billing slab, and for sewerage disconnection application charge will be based on the slab and tax based on the master configuration.
Interest
Below is a sample of the master data JSON for interest:
Penalty
Below is a sample of the master data JSON for penalty:
Round Off
If the fraction is greater than equal to 0.5 the number is rounded up else it’s rounded down. eg: 100.4 will be rounded to 100 while 100.6 will be rounded to 101.
Whenever _calculate API is called demand is first searched based on the connection no and the demand from and to period. If demand already exists the same demand is updated else new demand is generated with consumer code as connection no and demand from and to a period equal to the financial year start and end period.
In case of the update, if the tax head estimates change, the difference in amount for that tax head is added as new demand detail. For example, if the initial demand has one demand detail with SEWERAGE_CHARGE equal to 120.
After updating if the SEWERAGE_CHARGE increases to 150 we add one more demand detail to account for the increased amount. The demand detail will be updated to:
The disconnection charges will be the addition of both demand details taxAmount and we can generate demand until the workflow is in PENDING_FOR_DISCONNECTION_EXECUTION.
Note: if there is no pending payment when the connection gets approved then the workflow gets updated from PENDING_APPROVAL_FOR_DISCONNECTION to PENDING_FOR_DISCONNECTION_EXECUTION (it skips the payment step in the workflow internally).
Here the disconnection charges will be 120+30 = 150
RoundOff is bill based i.e every time bill is generated round off is adjusted so that the payable amount is the whole number. Individual SW_ROUNDOFF in demand detail can be greater than 0.5 but the sum of all SW_ROUNDOFF will always be less than 0.5.
Final sewerage charges calculation
Final Sewerage Charges = Last Billing Period Amount * Days (Proposed disconnection date - Last Billing Date) / No. of days in last billing period
The additional parameter is being sent in the calculation request for the disconnection application.
disconnectRequest = true if the request is for _calculate API disconnection application.
(Note: All the APIs are in the same postman collection therefore the same link is added in each row)
Sewerage Calculator Service is one of the major business logic services which is used for calculation of sewerage charge, generating demand, update existing demand, SMS & email notification to the ULB officials on-demand generation and also triggering demands(job scheduler) at some intervals and estimation of sewerage charge(one-time cost) which involves cost 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
Kafka server is up and running
egov-persister service is running and has sewerage service persister configs path added in it
PSQL server is running and a database is created to store sewerage connection / application data
Following services should be up and running:
egov-perister
egov-mdms
sw-services
billing-service
Sewerage calculator services present in municipal services provide multiple functionalities like calculating sewerage charges, generating demands for a particular sewerage connection, updating demands, SMS & email notification to the ULB officials on-demand generation and also triggering demands(job scheduler) at some intervals and estimation of sewerage charge(one-time cost) which involves cost like road-cutting charge, form fee, scrutiny fee etc. The different functionalities provided by sewerage calculator services are:
Sewerage charge calculation
Demand generation(here as its always non-metered demand will be generated based on time period)
Sewerage charge estimation (one-time cost which involves cost like road-cutting charge, form fee, scrutiny fee etc.)
Deploy the latest version of sw-service and sw-calculator
Add sewerage-persist.yml file in config folder in git and add that path in persister . (The file path is to be added in environment yaml file in param called persist-yml-path )
Criteria :
connection type
building type
calculation attribute
property usage type
The combination of the above can be used to define the billing slab. Billing Slab is defined in MDMS under sw-services-calculation folder with the SCBillingSlab. The following is the sample slab.
If all criteria will match for that sewerage connection this slab will use for calculation.
For application one-time fee, the estimation will return all the related tax head based on criteria. For estimation, all configuration is present in sw-services-calculation.
All the above master configuration is used for estimation.
Following are the exemptions and taxes that are calculated:
Form fee
Scrutiny fee
Other charges
Road cutting charges
One time fee
Security charges
Tax and cess
Sewerage charge is based on billing slab, for sewerage application charge will be based on slab and tax based on master configuration.
Interest
Below is a sample of master data JSON for interest :
Penalty
Below is a sample of master data JSON for penalty**:**
Round Off
If the fraction is greater than equal to 0.5 the number is round up else it’s round down. eg: 100.4 will be rounded to 100 while 100.6 will be rounded to 101.
Role Action Mapping
Once sewerage is sent to the calculator, its tax estimates are calculated. Using the tax head estimates demand details are created. For every tax head, the estimated demand generates function will create a corresponding demand detail.
Whenever _calculate API is called demand is first searched based on the connection no or application no and the demand from and to period. If demand already exists the same demand is updated else new demand is generated with consumer code as connection no or application no and demand from and to a period equal to financial year start and end period.
In the case of an update, if the tax head estimates change, the difference in amount for that tax head is added as new demand detail. For example, if the initial demand has one demand detail with SEWERAGE_CHARGE equal to 120
After updating if the SEWERAGE_CHARGE increases to 150 we add one more demand detail to account for the increased amount. The demand detail will be updated to:
RoundOff is bill based i.e every time bill is generated round off is adjusted so that the payable amount is the whole number. Individual SW_ROUNDOFF in demand detail can be greater than 0.5 but the sum of all SW_ROUNDOFF will always be less than 0.5.
For generating the demand for non metered connection we have a feature for generating the demand in batch. The scheduler is responsible for generating the demand based on the tenant.
The scheduler can be hit by scheduler API or we can schedule cron job or we can put config to kubectl which will hit scheduler based on config.
After the scheduler been hit we will search the list of the tenant (city) present in the database.
After getting the tenants we will pick up tenant one by one and generate the demand for that tenant.
We will load the consumer codes for the tenant and push the calculation criteria to Kafka. Calculation criteria contain minimal information (We are not pushing large data to Kafka), calculation criteria contain consumer code and one boolean variable.
After pushing the data into Kafka we are consuming the records based on the batch configuration. Ex:-> if the batch configuration is 50 so we will consume the 50 calculation criteria at a time.
After consuming the record(Calculation criteria) we will process the batch for generating the demand. If the batch is successful so will log the consumer codes which have been processed.
If some records failed in batch so we will push the batch into dead letter batch topic. From the dead letter batch topic, we will process the batch one by one.
If the record is successful we will log the consumer code, If the record is failed so we will push the data into a dead letter single topic.
Dead letter single topic contains information about failure records in Kafka.
Use cases
If the same job trigger multiple time what will happen?
If the same job triggers multiple times we will process again as mentioned above but at the demand level we will check the demand based on consumer code and billing period, If demand already exists then we will update the demand otherwise we will create the demand.
Are we maintaining success or failure status anywhere?
Currently, we are maintaining the status of failed records in Kafka.
Configuration
We need to configure the batch size for Kafka consumer. This configuration is for how much data will be processed at a time.1sw.demand.based.batch.size=10
sw-calculator will be integrated with sw-service. sw-services internally invoke the sw-calculator service to calculate and generate demand for the charges.
SW calculator application is used to calculate the sewerage application one time Fees and connection charges based on the different billing slabs that's why the calculation and demand generation logic will be separated out from SW service. So in future, if calculation logic needs to modify then changes can be carried out for each implementation without modifying the SW service.
To Activate the Sewerage Service application, the user needs to pay the ONE_TIME_FEE for the connection. To calculate the ONE_TIME_FEE sw-calculator/sewerageCalculator/_estimate API is use.
To generate the demand for non-metered sewerage connection /sw-calculator/sewerageCalculator/_calculate API is use.
User can pay partial / full / advance amount for the Non-Metered connection bill. In these cases, Billing service would call back /sw-calculator/sewerageCalculator/_updateDemandAPI to update the details of the demand generated.
/sw-calculator/sewerageCalculator/_jobscheduler API is use to generate demand for Non-metered connections. This API can be called periodically.
/sw-calculator/sewerageCalculator/_applyAdhocTax API is used to add Rebate or Penalty on any bill and based on that the bill amount will be adjusted.
(Note: All the API’s are in the same postman collection therefore same link is added in each row)
__
__
Detailed steps to configure privacy in W&S module
To make sure that after enabling privacy, the system works as expected, we will require some configurations to be made in the environment. This document contains all the steps to ensure successful implementation and working of the Water & Sewerage module.
The following are the changes required to move the water and sewerage application to other environments:
Add a new role for REINDEXING so as to push encrypted data in the index in roleactions.json and roles.json files. Reference for these file changes can be taken from the following commit: UM-4763 :: 2.8 UAT Promotion MDMS Changes by prashant-eGov · Pull Request #2835 · egovernments/egov-mdms-data (Please pick the changes for the required files- roleactions.json and roles.json only)
Add a copy of the existing water-service index with a different topic name(update-ws-encryption and update-sw-encryption) for the encryption process.
Reference: Enc-WnS indexer and persister changes by hinamakhija-eGov · Pull Request #2510 · egovernments/configs
Some changes need to be made for existing indexes in the water-service and sewerage-service indexer files. The changes with respect to these files can be referred to from the following commit: [UM-4382]- Updated indexer for water service by hinamakhija-eGov · Pull Request #2342 · egovernments/configs [UM-4382]-Updated indexer for sewerage by hinamakhija-eGov · Pull Request #2345 · egovernments/configs
Restart the indexer.
Add the following json mappings in the existing mappings (parallel to water-services and sewerage-services key) for water-services and sewerage-services in kibana so that the PII data is not visible during search(The data do remain in the index and also search with respect to this happens as is).
Sample index at the bottom
Add 2 new persister files responsible for managing old data encryption. ws-enc-audit-persister.yml and sw-enc-audit-persister.yml.
Update the path of these files in the DevOps repo in the specific environment file.
Restart the persister
Deploy new ws-service and sw-service builds.
Port-forward the ws-service and sw-service pods and hit the curl to start encryption. The curls can be referred from here:
Water-encryption curl:
Sewerage-encryption curl:
In the params list in both the above curls, “tenantIds” param can either be provided with a single tenantId or a list of tenantIds for encrypting the data with respect to the provided tenantIds. However, to encrypt the data for all tenantIds in the system, tenantIds param itself should be removed.
To validate if the encryption is completed, you can check with the following dB queries:
select * from eg_ws_enc_audit order by createdtime desc;
select count(*) from eg_ws_id_enc_audit;
This query can validate whether all records are there or not. The count should match the total count of records in the eg_ws_connection table.
select * from eg_ws_id_enc_audit;
This can help you check what all properties have been updated so far. This table contains the id, applicationnumber, connectionnumber and tenantid.
Sample Index for point 5:
After connection activation or legacy connection, the user can choose to disconnect the connection either temporarily or permanently. This process is based on a defined workflow. Any action is based on defined roles on the action level. For disconnecting the connection, the user needs to send extra parameters in the RequestBody as below :
disconnectionReason - to add the reason for disconnection
isDisconnectionTemporary - Whether the disconnection is temporary or permanent (if disconnection is temporary then isDisconnectionTemporary will be true else false)
disconnectRequest - This will always be true for disconnection applications.
disconnectionExecutionDate - This is the date when the application is disconnected.
and also user needs to upload some supporting documents and mandatory info.
URLs for the external API references:
eGov mdms: egov.mdms.host = https://dev.digit.org/
eGov -idGen : egov.idgen.host = https://dev.digit.org/
localization service: egov.localization.host = https://dev.digit.org/
idGen Id formats: egov.idgen.sdcid.name=sewerageservice.disconnection.id egov.idgen.sdcid.format=SW_AP/[CITY.CODE]/[fy:yyyy-yy]/DC-[SEQ_SW_APP_[TENANT_ID]]
egov-mdms-data/IdFormat.json at QA · egovernments/egov-mdms-data
This new feature is developed using the same existing base APIs for new and modified connections. The changes for disconnection follow a similar approach as that of New Connection. The config and persister changes required are mentioned below.
Persister configuration
https://github.com/egovernments/configs/blob/UAT/egov-persister/sewerage-persist.yml
Workflow config for edit connection
Create businessService (workflow configuration) using the /businessservice/_create. Following is the product configuration for editing the water connection.
Disconnection notifications will be sent to the property owners and connection holders based on different application states.
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 this goes to the disconnection application.
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.
To integrate, the host of sw-service module should be overwritten in the helm chart.
/sw-services/swc/_create should be added as the create endpoint for creating sewerage application/connection in the system
/sw-services/swc/_search should be added as the search endpoint. This method handles all requests to search existing records depending on different search criteria
/sw-services/swc/_update should be added as the update endpoint. This method is used to update fields in existing records or to update the status of applications based on workflow.
(Note: All the APIs are in the same postman collection therefore the same link is added in each row)
file
So, in the URL mentioned above in apiRequest, change the role from EMPLOYEE to REINDEXING_ROLE.
Reference for changes :
[UM-4382]- Updated indexer for water service by hinamakhija-eGov · Pull Request #2342 · egovernments/configs
[UM-4382]-Updated indexer for sewerage by hinamakhija-eGov · Pull Request #2345 · egovernments/configs
This role is a newly defined role in MDMS as already mentioned in the changes at the top.
This Role helps in getting the Encrypted data in accordance to firstLevelVisibilty defined for it.
For W&S, we need encrypted MobileNumber in the index because W&S inbox uses Elastic search and we require mobileNumber search for the same hence owner MobileNumber has to be there mandatorily in the index for search.
The changes need to be made in all the topics for W&S indexes. For more details find the changes here.
Put indexer config file to the config repo under egov-indexer folder. (egovernments/configs )
__All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.
Environment Variables
Description
egov.sewarageservice.createconnection
This variable contains the kafka topic name which is used to create new sewerage connection application in the system.
egov.sewarageservice.updateconnection
This variable contains the kafka topic name which is used to update the existing v connection application in the system.
egov.sewerageservice.updatesewerageconnection.workflow.topic
This variable contains the kafka topic name which is used to update the process instance of the sewerage connection application.
egov.idgen.scapid.name
This variable contain the idgen format name for sewerage application
egov.idgen.scapid.format
This variable contain the idgen format for sewerage application ex:- WS/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
egov.idgen.scid.name
This variable contain the idgen format name for sewerage connection
egov.idgen.scid.format
This variable contain the idgen format for sewerage connection ex:- WS_AP/[CITY.CODE]/[fy:yyyy-yy]/[SEQ_EGOV_COMMON]
Title
Link
API Swagger Documentation
Sewerage Calculator Service
Title
Link
/sw-services/swc/_create
/sw-services/swc/_update
/sw-services/swc/_search
Link
/sw-services/swc/_create
/sw-services/swc/_update
/sw-services/swc/_search
Link
/sw-calculator/sewerageCalculator/_calculate
/sw-calculator/sewerageCalculator/_updateDemand
Title
Link
/sw-calculator/sewerageCalculatorr/_estimate
/sw-calculator/sewerageCalculator/_calculate
/sw-calculator/sewerageCalculator/_updateDemand
/sw-calculator/sewerageCalculator/_jobscheduler
/sw-calculator/sewerageCalculator/_applyAdhocTax
Title
Link
API Swagger Contract
Sewerage Service Document
