🌠eGov Notification Push
Overview
The eGov Notification Push service sends mobile push notifications in HCM. It delivers alerts like stock updates, task reminders, and workflow notifications to field devices through Firebase Cloud Messaging (FCM).
The service handles two jobs:
Maintain the device-token registry. Mobile devices register their FCM token against a user, facility, and role set.
Deliver push messages. Upstream services publish notification requests, and this service resolves the target devices and sends the message through FCM.
At a glance
Used by: the mobile app and upstream notification producers.
Input: device-token registrations, Kafka notification events, or direct send requests.
Output: persisted device-token mappings and push delivery attempts through FCM.
Source of truth: this service owns the device-token registry in
eg_push_device_tokens.Main paths: register tokens, resolve audience, and send push messages.
Dependencies
Firebase Cloud Messaging (FCM) — the external Google service that actually delivers the push. Authenticated with the FCM service-account credentials (supplied as an environment value, never checked into the repo).
Kafka — both the inbound notification-event topic and the outbound device-token persister topics.
egov-persister (deployed via the
configs/repo) — turns the device-token Kafka events into rows in Postgres; the service does not write the registry directly.Postgres — stores the device-token registry (table
eg_push_device_tokens). Flyway migrations underdb/migration/maincreate and evolve this table on start.tracer (
2.9.2-SNAPSHOT) — correlation-id propagation, error handling, OpenTelemetry/Jaeger tracing.Upstream callers — health-notification-service (and any service emitting push events) are the producers of the inbound notification events; the mobile app is the producer of device-token registrations.
Data Model
The service stores one main kind of state:
device-token registrations
Each row links a device token to a user and its targeting context.
The exact column sizes vary by migration version.
Business Flow
On login or app start, the mobile app registers its device token, linked to the user, facility, and roles. One token can be registered against several facilities.
During the campaign, an upstream service decides which facility or user needs an alert and publishes a push-notification event on Kafka.
The service resolves the audience through explicit device tokens, user UUIDs, or facility and role lookups in its own store.
The message is sent to FCM, which delivers the notification to each device. Phones that have uninstalled the app are cleaned out when FCM returns an
UNREGISTEREDtoken error.When FCM is disabled, the message is logged to the console so flows can still be tested without live delivery.
API Details
Context path: /egov-notification-push
Base paths:
/device-token/v1— manage the phone-to-user registry/push/v1— send a push on demand
From a client's point of view:
device-token APIs accept write requests, then persist asynchronously through Kafka
POST /push/v1/_sendresolves recipients and sends immediatelythe Kafka consumer path is still the main delivery path for campaign notifications
Endpoints
POST /device-token/v1/_register
Register a phone's FCM token for a user (with facility ids and roles). Persisted async via Kafka.
POST /device-token/v1/_unregister
Remove a token everywhere for a user (e.g. on logout), regardless of facility.
POST /device-token/v1/_delete
Delete a token, optionally scoped to specific facilities.
POST /device-token/v1/_search
Fetch the latest device token(s) for a set of user ids.
POST /push/v1/_send
Send a push on demand: resolves user UUIDs / device tokens, fires to FCM, returns how many devices were targeted.
Kafka entry point (async, the main path). A notification event lands on the configured push topic (default egov.core.notification.push, tenant-prefixed in central-instance mode) and is consumed by PushNotificationListener, which resolves the audience and sends to FCM. Device-token writes are published to save-push-device-token-health / delete-… / unregister-… for egov-persister to write to Postgres.
Kafka Topics
egov.core.notification.push
in
Inbound push-notification requests (central-instance: {tenantId}- prefixed pattern)
save-push-device-token-health
out
Persist device-token registration
delete-push-device-token-health
out
Persist device-token deletion
unregister-push-device-token-health
out
Persist device-token unregistration
Process Flow

Use this reading order:
Register device tokens. The mobile app writes token updates through the device-token APIs.
Persist the registry. The service emits Kafka events and egov-persister writes
eg_push_device_tokens.Trigger a notification. An upstream service publishes to Kafka, or a caller uses
POST /push/v1/_send.Resolve the audience. The service maps users, facilities, roles, or raw tokens to target devices.
Send through FCM. FCM handles actual delivery, and stale tokens are cleaned up when possible.
Registration and delivery are two separate flows.
The service reads the device-token registry directly from Postgres, but writes it through Kafka + egov-persister.
Delivery itself is offloaded to FCM.
Register token flow
The mobile app calls
_register,_delete, or_unregister.The service validates the request and emits the matching Kafka event.
egov-persister writes the change into
eg_push_device_tokens.Later searches read the latest token state from Postgres.
Kafka push delivery flow
An upstream service publishes a notification event on the inbound push topic.
PushNotificationListenerconsumes the event.The service resolves recipients from explicit device tokens, user UUIDs, or facility and role filters.
The service batches tokens when needed and sends the payload to FCM.
Tokens reported as
UNREGISTEREDare removed from the registry.
On-demand send flow
A caller sends
POST /push/v1/_send.The service resolves device tokens from the request body.
The service is sent directly to FCM.
The response returns the number of targeted devices.
Failure & Retry Handling
Consumer is fail-soft.
PushNotificationListenerwraps processing in atry/catchand logs errors. A bad message does not crash the consumer.No automatic retry on consumer failure. Failed push events are not retried automatically. Check service logs and the configured tracer error topic
notification-push-deadletter.No audience = no-op. If no device tokens resolve (e.g. no phones registered for that facility/role), the send is skipped with a warning rather than erroring.
Stale-token cleanup. When FCM reports a token as
UNREGISTERED(app uninstalled), that token is deleted from the registry so it isn't tried again — keeps the store self-healing.Multicast is batched. Large audiences are split into FCM batches (default 500); a per-token failure inside a batch is logged and does not stop the rest of the batch.
FCM off → console fallback. With
fcm.enabled=falsetheConsolePushServicesimply logs the notification; nothing is delivered, but flows still complete. With FCM on but credentials missing/blank, the app fails fast at startup (Firebase init throws).Async registry writes.
_register/_delete/_unregisterreturn200before the row is persisted. If the persister config for these topics is missing/stale in an environment, tokens are accepted but never stored — a classic "it worked in QA" trap.
HCM v2.1: Notification Service Consolidation & Push Enhancements
Standalone, buildable service: The full service (Java source,
pom.xml,Dockerfile,start.sh, tests, DB migrations) is now merged into this repo. Previously this folder held only resources and was deployed from elsewhere — that no longer applies.Device-token registry: Phones can register, unregister, delete, and search their FCM tokens via
/device-token/v1/*. Tokens are persisted to Postgres (eg_push_device_tokens) through Kafka and egov-persister.FCM push delivery with console fallback: Delivery goes through Firebase (single or batched multicast). When FCM is disabled, notifications are logged to console instead, so non-prod environments can test the flow without sending real pushes.
Facility- and role-based targeting: Notifications can target a facility and optionally a list of recipient roles (e.g.,
WAREHOUSE_MANAGER,DISTRIBUTOR). The listener resolves matching device tokens automatically. Supports one token across multiple facilities and role-based filtering.On-demand send API:
/push/v1/_sendallows immediate push by user UUIDs and/or raw device tokens, returning the count of devices targeted.Multi-tenant / central-instance support: In central-instance mode, topics are tenant-prefixed and the DB schema is derived from the tenant ID.
Known Risks & Limitations
No retry / dead-letter replay on the consumer. Failed push events are logged and dropped; there is no built-in re-processing, so a transient FCM outage means those notifications are simply missed.
Delivery is best-effort. FCM accepting a message does not guarantee the phone shows it; this service has no read-receipt or delivery-confirmation back-channel.
Hard dependency on the FCM service-account credentials. With FCM enabled, a missing or malformed credential value crashes the service at startup.
Registry writes depend on external persister config. If the device-token persister mappings aren't deployed in an environment, registrations silently never persist.
Role filtering is substring-based. Roles are stored as a comma-separated string and matched with
LIKE, so role codes that are substrings of one another could over-match — worth a QA check if role names overlap.No Swagger / formal API contract is published yet; integrators work from this README and the controllers.
Last updated
Was this helpful?