Milestone One (M1) - ABHA & Identity Layer

Context Milestone One (M1) was the starting point of AMRIT’s ABDM integration. In this milestone, we built and validated the ABHA identity flows: creating and verifying ABHAs (Ayushman Bharat Health Accounts), mapping them to AMRIT beneficiaries, and implementing the sandbox’s required v0.5 OTP-based care context linking.

The implementation was delivered within AMRIT’s FHIR-API module, with persistence across MySQL/Postgres and MongoDB. OTP tracking and linking were also added for sandbox compliance.

1. Objectives of M1

• Register AMRIT facility and services in ABDM sandbox.

• Set up secure session management with ABDM Gateway.

• Implement ABHA creation & verification APIs (QR, Aadhaar-assisted, manual).

• Map ABHA ↔ AMRIT beneficiary records.

• Implement the v0.5 OTP flow for care context linking (for sandbox compliance).

2. Architecture & System Context

Modules & Services

• HealthIDServiceImpl → Implements ABHA creation & verification (methods like ndhmGenerateOTP, ndhmCreateHealthID, ndhmVerifyHealthID).

• ABHAServiceImpl → Orchestrates Aadhaar-assisted enrollment flows.

• CareContextService → Implements v0.5 OTP care-context linking (generateOTPForCareContext, addCareContext).

Entities

• HealthIDResponse → Maps to relational table t_healthid.

• BenHealthIDMapping → Handles beneficiary ↔ ABHA mapping (prevents duplicates).

Tech stack

• Spring Boot REST APIs

• Quartz scheduler (integrated here; extended in M2 for bundle generation)

• MySQL/Postgres (ABHA identities, link requests, OTP records)

• MongoDB (ABDM callbacks & sandbox payloads)

• Redis (introduced here for token caching; heavier usage in M2)

3. Sandbox Registration

• AMRIT facility registered in HFR (Health Facility Registry).

• HIP and HIU IDs provisioned via sandbox portal.

• Sandbox credentials (CLIENT_ID, CLIENT_SECRET) stored in common_ci.properties.

• X-CM-ID set to sbx (sandbox).

4. Session Management

• API: POST /sessions → retrieves JWT session token (valid ~15 min).

• Tokens managed via fire-api module (automatic refresh + retry).

• Required headers in every call:

  • Authorization: Bearer <session-token>

  • X-Request-ID: <uuid>

  • X-HIP-ID: <AMRIT_HIP_ID>

  • X-HIU-ID: <AMRIT_HIU_ID>

  • X-CM-ID: sbx

  • Content-Type: application/json

5. ABHA Creation & Verification

Implemented Flows

• QR Scan Flow: Scan ABHA QR → verify via /search & /verify.

• Manual Entry Flow: Enter ABHA manually → verified.

• Aadhaar-Assisted Flow: Enter Aadhaar → ABDM generates ABHA → OTP verified.

Service Mapping

• HealthIDServiceImpl → OTP generation & creation APIs.

• ABHAServiceImpl → Aadhaar-assisted OTP flows.

Transaction ID Usage

• Each /generateOtp, /verifyOtp, /createHealthID call included a txnId.

• Persisted in HealthIDResponse.txnId to tie together multi-step flows.

• Provided auditability across retries and callbacks.

6. Database Entities

Relational (Postgres/MySQL)

• OtpRequests (otpservice schema)

  • Tracks OTP lifecycle (ABHA creation, OTP-based linking).

  • Key fields: request_id, abha_number, otp_sent_to, status, created_at.

• InitiatedLinkRequest (hipservice schema)

  • Tracks care-context link initiation in v0.5 OTP flow.

  • Fields: request_id, txn_id, link_reference_number, status, created_at.

• t_healthid

  • Stores ABHA profiles returned after verification.

  • Populated via HealthIDResponse entity.

• m_benhealthidmapping

  • Maps beneficiaryRegId ↔ healthIdNumber.

  • Prevents duplicate ABHA registrations.

MongoDB (AmritHRP)

• GenerateTokenAbdmResponses

  • Stores sandbox responses to /generateToken requests.

  • Includes link token, ABHA address, txnId.

• PatientCareContexts

  • Persists ABHA ↔ care-context mappings established via OTP linking.

• NDHMResponses

  • Stores raw sandbox callbacks for audit/debugging.

7. API Endpoints (FHIR-API)

• /healthID/generateOTP

• /healthID/verifyOTPAndGenerateHealthID

• /healthID/getBenhealthID

• /healthID/getBenIdForhealthID

• /healthIDRecord/mapHealthIDToBeneficiary

• /healthIDRecord/addHealthIdRecord

These were exposed via HealthIDController and implemented in HealthIDServiceImpl.

8. v0.5 OTP Care Context Linking

Flow

1. CareContextService.generateOTPForCareContext() → calls ABDM /init.

2. ABDM sends OTP → logged in OtpRequests.

3. User verifies OTP → CareContextService.addCareContext() attaches context.

4. ABDM confirms success → persisted in Mongo (PatientCareContexts).

Example Init Callback

{
  "requestId": "uuid-123",
  "timestamp": "2025-09-22T10:00:00Z",
  "transactionId": "txn-12345",
  "abhaNumber": "ABHA-987654321000"
}

9. Error Handling & Edge Cases

• Duplicate ABHA: Prevented via existsByHealthIdNumber.

• Existing ABHA: Linked instead of recreated.

• OTP Blocking: Sandbox blocked after ~3 OTP/day → caching + retry logic.

• TxnId persistence: Always stored to avoid orphaned flows.

• Callback failures: Logged into NDHMResponses (Mongo) for replay/debug.

10. Repo / Service Mapping

• Services:

  • HealthIDServiceImpl → OTP, create, verify.

  • ABHAServiceImpl → Aadhaar-assisted flows.

  • CareContextService → OTP linking.

• Entities:

  • HealthIDResponse → table t_healthid.

  • BenHealthIDMapping → ABHA ↔ beneficiary mapping (m_benhealthidmapping).

• Modules:

  • fhir-api → Gateway session management.

  • otpservice → OTP tracking (Postgres).

  • hipservice → Link initiation tracking (Postgres).

  • AmritHRP → ABDM responses, tokens, care contexts (Mongo).

  • Redis → caching of session/OTP data.