Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🌠Beneficiary IDGen

Overview

Beneficiary IDGen is the shared ID factory and vending machine for a health campaign. Beneficiaries (and other entities) need unique, human-readable IDs — often pre-printed on cards, wristbands, or QR stickers handed out in the field. It's primarily used for beneficiaries who don't have a national ID (or equivalent government-issued identifier) to provide, giving them a system-generated identity they can be tracked and served under instead.

It has two main jobs:

  1. Generate a tenant-specific pool of unique, human-readable beneficiary IDs from a configured format.

  2. Dispatch a safe, non-overlapping batch of those IDs to a specific user and device in the field.

Think of it as: generate IDs ahead of time → dispatch them safely to devices → reconcile their status later.

At a glance

  • Used by: setup or admin flows for generation, and DISTRIBUTOR users for field dispatch.

  • Input: tenant, ID format configuration, requested counts, dispatch context, and update criteria.

  • Output: generated pool records, dispatched ID allocations, search results, and audit logs.

  • Source of truth: Postgres id_pool stores the ID pool state. Redis only enforces dispatch quotas.

  • Generate: pre-mints IDs into the pool.

  • Dispatch: allocates IDs to one user and one device without overlap.

The Health Campaign Management app itself is offline-first — field staff often work in areas with low or no internet connectivity, so the app can't assume it can call IDGen live every time a new beneficiary or entity needs an ID.

To work around this, IDGen supports a pre-fetch/download model: when the field worker has connectivity (typically right after login, or whenever a sync window is available), the app downloads a batch of pre-generated IDs in advance and caches them locally. As new beneficiaries are registered in the field — even fully offline — the app assigns IDs from this local pool instead of waiting on a live call to IDGen.

The number of IDs downloaded per batch is configurable via MDMS, so this can be tuned per campaign (e.g. based on expected daily registration volume, device storage constraints, or field team size) without needing a code change.

In short: IDGen isn't just a request/response ID generator — it's designed as a vending machine that dispenses IDs in bulk upfront, so the offline app always has a local supply to draw from until the next sync, at which point it can top up.

It prepares IDs before campaign runtime, then hands them out in controlled batches during execution.

Dependencies

  • egov-mdms-service — supplies the ID format template for each tenant. Format tokens such as [seq...], [fy:...], [cy:...], [city], [tenantid], and random [d{n}] patterns are expanded into final IDs. A DB fallback exists if idformat.from.mdms=false.

  • PostgreSQL — stores the ID pool and dispatch audit trail. Main tables are id_pool and id_transaction_log. Postgres sequences back the [seq] portion of configured formats.

  • Redis (via Redisson) — stores per-user and per-device dispatch counters for total and per-day limits, with TTL-based expiry.

  • Kafka — carries async generation requests, bulk updates, persister writes, and dispatch audit events.

  • egov-persister — persists save-in-id-pool, update-id-pool-status, and save-dispatch-id-log events into Postgres.

  • health-services-common / -models — shared producers, validators, POJOs, and ResponseInfo utilities.

  • mdms-client and tracer — inherited support for MDMS access, correlation IDs, and exception handling.

Data Model

The service stores two kinds of state:

  • generated ID pool records

  • dispatch audit records

Key relationships:

  • each generated beneficiary ID lives in id_pool

  • dispatch assigns IDs from that pool to a user and device

  • id_transaction_log records who received which IDs and when

Flyway migrations for these tables live under db/migration/main.

Web Sequence Diagrams

Pool generation flow
Dispatch and allocation flow
Status update and reconciliation flow

Business Flow

The service follows a simple four-step flow:

  1. Generate pool. A setup or admin flow calls _generate with the tenant and requested count.

  2. Dispatch IDs. A field device calls _dispatch to receive a reserved batch.

  3. Re-sync or search. The client can call _dispatch with fetchAllocatedIds=true, or use _search to inspect pool records.

  4. Update status. The client calls _update later to reconcile the issued IDs.

Generation is asynchronous because large pools can take time to mint.

Dispatch is online and allocation-safe.

The service ensures that two devices do not receive the same ID.

API Details

From a client's point of view:

  • _generate is asynchronous

  • _dispatch and _search are synchronous

  • _update is asynchronous bulk processing

Endpoint
Purpose

POST /id_pool/_generate

Queue asynchronous generation of a tenant-specific pool of IDs. Returns immediately after the work is chunked and queued.

POST /id_pool/_dispatch

Allocate a block of unused IDs to one user + device, subject to total and daily limits. With fetchAllocatedIds=true, returns IDs already assigned to that device instead.

POST /id_pool/_search

Search ID pool records by ID list, status, and tenant.

POST /id_pool/_update

Accept an async bulk status update request for pool records, such as marking IDs as used.

Internal Flow

This section explains how the service implements the API behaviour internally.

Generation path. _generate splits the requested count into chunks and publishes them to id-gen-consumer-bulk-create-topic. The service's own consumer mints IDs from the configured format, then emits save-in-id-pool for persistence.

Dispatch path. _dispatch selects unused IDs from Postgres using locking semantics, checks total and daily quotas in Redis, assigns the IDs to the user and device, and emits audit events on save-dispatch-id-log.

Update path. _update publishes to id-gen-consumer-bulk-update-topic. The consumer validates the request and emits status changes on update-id-pool-status.

There is no published Swagger contract for this service under docs/health-api-specs/contracts/.

Kafka Topics

Topic
Dir
Purpose

id-gen-consumer-bulk-create-topic

in

Bulk id-pool create requests

id-gen-consumer-bulk-update-topic

in

Bulk id-pool update requests

save-in-id-pool

out

Persist generated IDs into the pool

update-id-pool-status

out

Update ID status after dispatch or later reconciliation

save-dispatch-id-log

out

Persist dispatch audit logs

Process Flow

Use this reading order:

  1. Queue generation. _generate validates the request, splits it into chunks, and queues the work.

  2. Mint and persist. The consumer expands the format, generates unique IDs, and persists them into id_pool.

  3. Dispatch atomically. _dispatch draws from the unused pool, applies limits, and assigns IDs to one user and device.

  4. Inspect or reconcile. _search reads back pool state, and _update applies later lifecycle changes.

  5. Audit the action. Dispatch and update flows write audit data for tracing and reconciliation.

The generate and update paths are asynchronous.

Dispatch happens in-line, but uses DB locking and Redis counters to stay safe.

End-to-end request lifecycle

Failure & Retry Handling

  • Generation never blocks the caller and never half-fails the request. _generate returns once chunks are queued; the actual minting happens in the consumer. If a chunk fails, it is logged and the request is not retried automatically.

  • Dispatch is concurrency-safe. The pool draw uses FOR UPDATE SKIP LOCKED, so simultaneous dispatches skip locked rows rather than deadlock or double-allocate.

  • Dispatch limits are enforced. Per-user and per-device total and per-day caps are checked against Redis counters. Exceeding them returns USER_DEVICE_LIMIT_EXCEEDED.

  • No IDs left returns NO IDS AVAILABLE — a signal that the pool needs topping up via _generate.

  • Random-format buffer. When a format contains a random pattern, the batch is over-generated by a configurable buffer percentage to absorb collisions. The pool insert uses ON CONFLICT (id) DO NOTHING, so duplicate random IDs are dropped rather than failing the batch.

  • Persister dependency trap. If persister wiring for these topics is missing or stale in an environment, the API can accept generate or update work while rows silently never appear in Postgres.

Known Risks & Limitations

  • The pool must be filled before it can be drawn from. _dispatch only hands out IDs that _generate has already minted. An empty or exhausted pool returns NO IDS AVAILABLE.

  • Two stores must agree. The authoritative pool is in Postgres, but dispatch quotas live in Redis. If Redis is flushed or lost, quota tracking resets even though Postgres still shows IDs as dispatched.

  • Limits are per user + device, keyed by date in a configured timezone. "Per day" boundaries follow id.timezone or app.timezone. A bad timezone shifts when a quota resets.

  • Generation failures are swallowed in the consumer — logged, but not retried. There is no dead-letter queue today, so a failed chunk simply means fewer IDs in the pool.

  • _update validation assumes a single tenant per bulk request. It reads tenantId from the first record, so mixed-tenant batches are not supported.

  • ID status and format correctness are largely convention-driven. A malformed MDMS IdFormat surfaces during generation time, not at configuration time.

Recent Changes

HCM v2.1: Dependency & Plumbing Update

  • No functional, API, or database migration changes in this window — updates are limited to dependencies and plumbing.

  • Version bump: 1.1.0-SNAPSHOT → 1.1.1-SNAPSHOT.

  • Tracer upgrade: Bumped to 2.9.2 for DataAccessException handling; direct tracer dependency removed in favour of the transitive one from health-services-common.

  • Shared library bumps: health-services-common 1.1.1 → 1.1.3, health-services-models 1.0.29 → 1.0.30.

  • OpenTelemetry BOMs added: Added to dependency management, with OTEL exporters explicitly disabled in application.properties (otel.traces/logs/metrics.exporter=none).

  • No changes to controllers, services, repositories, the ID-pool/dispatch logic, or Flyway migrations.

Last updated

Was this helpful?