egov-user-events

Objective:

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

Requirements:

• Prior Knowledge of Java/J2EE

• Prior Knowledge of SpringBoot

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

• Prior Knowledge of Kafka and related concepts like Producer, Consumer, Topic etc.

•  

Setup:

Step 1: Start the egov-mdms service present in the following repo:

https://github.com/egovernments/core-services/tree/master/egov-mdms-service
          Or port forward the egov-mdms service. 

Step 2: Start the egov-localisation service present in the following repo:

https://github.com/egovernments/core-services/tree/master/egov-localization

           Or port forward the egov-localisation service. 

Step 3: Start the egov-persister service present in the following repo:

https://github.com/egovernments/core-services/tree/master/egov-persister

           Or port forward the egov-persister service. 

Step 4: Start the egov-mdms service present in the following repo:

https://github.com/egovernments/core-services/tree/master/egov-mdms-service
          Or port forward the egov-user-events service. 

Configurable Properties:

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

Entities:

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

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

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

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

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

1. BROADCAST - These are messages broadcasted addressing a group of people. For instance, “There’s road blockage near the bus stand, please use a different route”

2. EVENTSONGROUND - These are events organised by a group of people addressing another group of people usually it is the ULB organising events for the citizens. It can be any activity like a 10K Marathon, Polio Drive, Property Tax collection drive etc. 

3. SYSTEMGENERATED - These events generated by different systems on the egov platform like PT, TL, PGR etc addressing a group of people. For instance, “Dear Citizen, Your TL has been approved please proceed to Pay here <PAY_NOW>”

4. OTHERS - Events that don’t belong to the types mentioned above.

These are configured in MDMS.

Event Category: Events are categorised into following:

1. PUBLICHEALTH - Events related to public health.

2. CULTURAL - Cultural events

3. WARDCOMMITEEMEETING - Events for recurring meetings of ward committee.

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

How does it work?:

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

Every event should contain information about the event type, event category, event name, description, recipient, actions, event details etc. Based on the type of the event, the list of mandatory fields varies. MDMS configurations required for this service to work can be found here: https://github.com/egovernments/egov-mdms-data/tree/master/data/pb/mseva

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

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

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

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

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

Please go through the code and descriptions over every method to understand the use-cases and flow-of-logic in a better way.

APIs:

1. /_create: API to create events in the system.

2. /_update: API to update events in the system.

3. /_search: API to search events in the system.

4. /notification/_count: API to fetch the count of total, unread, read notifications.

5. /lat/_update: API to update the last-login-time of the user. We store last-login-time of the user through this API thereby deciding which notifications have been read.

Postman Collection: https://www.getpostman.com/collections/14812d58dff5565bd3d9
API Contract: https://github.com/egovernments/municipal-services/blob/master/docs/user-events.yml

Configs:

Persister:

https://raw.githubusercontent.com/egovernments/egov-services/mseva-event-notif/core/egov-persister/src/main/resources/egov-user-event-persister.yml

MDMS:

https://github.com/egovernments/egov-mdms-data/tree/master/data/pb/mseva

Localization:

The entry should be technically created at pb level, but due to the multitenancy, I am not able to create an entry for ‘pb’ on dev, I have created for ‘pb.amritsar’. If the entries are created for ‘pb’ then set the following key in app.props: egov.localisation.is.statelevel to “true”.

Req:

{"RequestInfo":{"apiId":"asset-services","msgId":"search with from and to values","authToken":"a0eec36a-7f02-406c-9477-01dd2a02b3cb"},"tenantId":"pb.amritsar","messages":[{"code":"egovuserevents.notification.counterevent.ondelete","message":"<event_name> has been deleted. Please remove from your calendar.","module":"egov-user-events","locale":"en_IN"},{"code":"egovuserevents.notification.counterevent.onupdate","message":"Details of <event_name> have been updated.","module":"egov-user-events","locale":"en_IN"}]}

External Services:

PGR, PT and TL services have to be promoted with the builds containing changes for egov-user-event. The build ids will keep changing depending on when the promotion is going to take place, as some other work is also going on in those modules.

These builds contain changes for egov-user-events, whoever is moving these modules to Prod, should also merge these changes. For QA purposes, promote the following builds to QA for now.

Properties to be overriden in these modules are as follows:

PGR:

egov.usr.events.notification.enabled=true
egov.usr.events.create.topic=persist-user-events-async
egov.usr.events.rate.link=/citizen/otpLogin?mobileNo=$mobile&redirectTo=feedback/$servicerequestid
egov.usr.events.reopen.link=/citizen/otpLogin?mobileNo=$mobile&redirectTo=reopen-complaint/$servicerequestid
egov.usr.events.rate.code=RATE
egov.usr.events.reopen.code=REOPEN

PT:

egov.user.event.notification.enabled=true
egov.ui.app.host=https://egov-micro-dev.egovernments.org - host of the UI app.
egov.usr.events.create.topic=persist-user-events-async
egov.usr.events.pay.link=/citizen/otpLogin?mobileNo=$mobile&redirectTo=egov-common/pay?consumerCode=$consumerCode&tenantId=$tenantId
egov.usr.events.pay.code=PAY

TL:

egov.user.event.notification.enabled=true
egov.ui.app.host=https://egov-micro-dev.egovernments.org - host of the UI app.
egov.usr.events.create.topic=persist-user-events-async
egov.usr.events.pay.link=/citizen/otpLogin?mobileNo=$mobile&redirectTo=egov-common/pay?consumerCode=$consumerCode&tenantId=$tenantId
egov.usr.events.pay.triggers=PENDINGPAYMENT

Role - actions:

/egov-user-event/v1/events/_create - EMPLOYEE, SUPERUSER
/egov-user-event/v1/events/_update - EMPLOYEE, SUPERUSER
/egov-user-event/v1/events/_search - EMPLOYEE, SUPERUSER, CITIZEN
/egov-user-event/v1/events/notifications/_count - CITIZEN
/egov-user-event/v1/events/lat/_update - CITIZEN

Interaction Diagram:

Open