Immunizations Service — Event Schemas

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Produced Events

All events use CloudEvents 1.0 envelope. Transport: NATS JetStream. Stream: IMMUNIZATIONS; subjects: IMMUNIZATIONS.<aggregate>.<event>.v1

---

IMMUNIZATIONS.immunization.recorded.v1

Emitted when a vaccine dose is successfully administered and recorded.

{
  "specversion": "1.0",
  "type": "IMMUNIZATIONS.immunization.recorded.v1",
  "source": "immunizations-service",
  "id": "evt_01J...",
  "time": "2026-04-15T08:32:10Z",
  "tenantid": "tenant_01J...",
  "datacontenttype": "application/json",
  "data": {
    "immunizationId": "imm_01J...",
    "patientId": "pat_01J...",
    "stablePatientId": "550e8400-e29b-41d4-a716-446655440000",
    "vaccineCode": {
      "system": "http://hl7.org/fhir/sid/cvx",
      "code": "120",
      "display": "DTaP-Hib-IPV"
    },
    "status": "completed",
    "doseNumber": 1,
    "seriesDoses": 3,
    "lotNumber": "LOT-2024-0041",
    "administeredAt": "2026-04-15T08:30:00Z",
    "performerId": "usr_01J...",
    "facilityId": "fac_01J...",
    "encounterId": "enc_01J...",
    "tenantId": "tenant_01J..."
  }
}

---

IMMUNIZATIONS.immunization.refused.v1

Emitted when a patient refuses a vaccine dose.

{
  "specversion": "1.0",
  "type": "IMMUNIZATIONS.immunization.refused.v1",
  "source": "immunizations-service",
  "id": "evt_01J...",
  "time": "2026-04-15T08:35:00Z",
  "tenantid": "tenant_01J...",
  "datacontenttype": "application/json",
  "data": {
    "immunizationId": "imm_01J...",
    "patientId": "pat_01J...",
    "stablePatientId": "550e8400-e29b-41d4-a716-446655440000",
    "vaccineCode": {
      "system": "http://hl7.org/fhir/sid/cvx",
      "code": "120",
      "display": "DTaP-Hib-IPV"
    },
    "status": "not-done",
    "statusReason": {
      "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
      "code": "PATOBJ",
      "display": "Patient objection"
    },
    "recordedAt": "2026-04-15T08:35:00Z",
    "performerId": "usr_01J...",
    "facilityId": "fac_01J...",
    "tenantId": "tenant_01J..."
  }
}

---

IMMUNIZATIONS.immunization.updated.v1

Emitted when an existing immunization record is amended or corrected.

{
  "specversion": "1.0",
  "type": "IMMUNIZATIONS.immunization.updated.v1",
  "source": "immunizations-service",
  "id": "evt_01J...",
  "time": "2026-04-15T10:00:00Z",
  "tenantid": "tenant_01J...",
  "datacontenttype": "application/json",
  "data": {
    "immunizationId": "imm_01J...",
    "patientId": "pat_01J...",
    "stablePatientId": "550e8400-e29b-41d4-a716-446655440000",
    "changedFields": ["lotNumber", "notes"],
    "previousStatus": "completed",
    "newStatus": "completed",
    "version": 2,
    "updatedAt": "2026-04-15T10:00:00Z",
    "updatedBy": "usr_01J...",
    "tenantId": "tenant_01J..."
  }
}

---

IMMUNIZATIONS.immunization.reported.v1

Emitted when a historical immunization record is imported.

{
  "specversion": "1.0",
  "type": "IMMUNIZATIONS.immunization.reported.v1",
  "source": "immunizations-service",
  "id": "evt_01J...",
  "time": "2026-04-15T11:00:00Z",
  "tenantid": "tenant_01J...",
  "datacontenttype": "application/json",
  "data": {
    "immunizationId": "imm_01J...",
    "patientId": "pat_01J...",
    "stablePatientId": "550e8400-e29b-41d4-a716-446655440000",
    "vaccineCode": {
      "system": "http://hl7.org/fhir/sid/cvx",
      "code": "120",
      "display": "DTaP-Hib-IPV"
    },
    "source": {
      "type": "paper_card",
      "reference": "card-scan-2026-04-15"
    },
    "administeredAt": "2025-12-01T00:00:00Z",
    "isHistorical": true,
    "tenantId": "tenant_01J..."
  }
}

---

IMMUNIZATIONS.forecast.updated.v1

Emitted when the immunization forecast is recalculated for a patient.

{
  "specversion": "1.0",
  "type": "IMMUNIZATIONS.forecast.updated.v1",
  "source": "immunizations-service",
  "id": "evt_01J...",
  "time": "2026-04-15T08:33:00Z",
  "tenantid": "tenant_01J...",
  "datacontenttype": "application/json",
  "data": {
    "forecastId": "fcst_01J...",
    "patientId": "pat_01J...",
    "stablePatientId": "550e8400-e29b-41d4-a716-446655440000",
    "calculatedAt": "2026-04-15T08:33:00Z",
    "recommendations": [
      {
        "vaccineCode": { "system": "http://hl7.org/fhir/sid/cvx", "code": "140", "display": "Influenza" },
        "doseNumber": 2,
        "forecastStatus": "due",
        "dueDate": "2026-05-15",
        "earliestDate": "2026-04-30",
        "latestDate": "2026-06-30"
      }
    ],
    "tenantId": "tenant_01J..."
  }
}

---

2. Consumed Events

Event	Source	Handler	Action
REGISTRATION.patient.registered.v1	registration-service	OnPatientRegisteredHandler	Seed empty forecast for new patient
REGISTRATION.patient.merged.v1	registration-service	OnPatientMergedHandler	Reassign immunization records from non-surviving to surviving patient; refresh forecast
REGISTRATION.patient.vital-status-changed.v1	registration-service	OnVitalStatusChangedHandler	Flag patient as deceased; suppress defaulter outreach
SCHEDULING.appointment.fulfilled.v1	scheduling-service	OnAppointmentFulfilledHandler	Trigger reminder to record immunization for fulfilled appointment type vaccination

---

3. Delivery Semantics

Property	Value
Delivery guarantee	At-least-once (outbox + NATS JetStream ACK)
Idempotency key	eventId (id field in CloudEvents envelope)
Ordering	Per-patient ordering via NATS subject IMMUNIZATIONS.immunization.{patientId} for record events
Retention	7 days on NATS stream
Dead-letter	IMMUNIZATIONS.dlq after 3 failed ACKs
Consumer group	Per-downstream-service durable consumer