Aotearoa Immunisation Register (AIR) FHIR Implementation Guide
2.7.0 - ci-build New Zealand

Aotearoa Immunisation Register (AIR) FHIR Implementation Guide - Local Development build (v2.7.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Careplan View

View Consumer Planned Events

The ‘$view’ API on the 'Careplan' profile used to view all the planned events contained within a Consumers vaccination schedule.

  • The request generates a bundle of CarePlan FHIR Resources that contain all planned activities ( i.e Planned Events and Expected Events) represented in an Immunization Recommendation FHIR Resource and their matching preformed activities represented in one or more Immunization FHIR Resources. All reflect a point-in-time list of Immunisation Planned Events and Expected Events across all Antigen Group Vaccination Schedules that have been assigned to that Consumer and are Active at the time of making the request.

  • By default, the API will return a point-in-time view of all Active (i.e. not Cancelled) Planned Events and Expected Events, past, present and future, that are assigned to the specified Consumer. The matching Consumers vaccination records will also be returned.

  • Each CarePlan Resource presents one consumer AG schedule.

  • Each CarePlan activity references one planned event dose (IR) and any matched immunisation events (IEs).

  • Planned Events will be ordered by due date ascending.

  • If the Consumer with the NHI in the Search request is not on-boarded in ImmSOT then the consumer will be on-boarded , AGVS Schedules will be assigned and planned events will be created then the API logic will be executed and the planned events will be returned.

  • If the NHI in the request or any linked NHIs (Live or Dormant) is suppressed an empty result will be returned, with a redacted code in the meta data.

  • If a dormant NHI is used in the request the same results will be return as if the live NHI was used.

$view API Sequence Diagram – Normal Success Scenarios

User<<Application>><<Gateway>><<FHIR Service>>ImmSOT DBUserUser«Application»Client«Application»Client«Gateway»API-Gateway«Gateway»API-Gateway«FHIR Service»ImmSOT Service«FHIR Service»ImmSOT ServiceImmSOT DBImmSOT DB[01]Request to view consumer'splanned vaccination events[02]Client request a token[03]Return OAuth token (JWT)[04]Initiate /CarePlan/$viewrequest with NHI with theOAuth token (JWT)[05]validate token andpermissions[06]Forward /CarePlan/$viewrequest[07]Validate token andpermissions[08]Check whether Consumer issuppressed?[09]Consumer is not  suppressed?[10]Find planned events,expected events, andimmunization events[11]Consumer planned events,expected events, andimmunization events details[12]Create FHIR Bundle response[13]Return FHIR Bundle withConsumer CarePlan resources[14]Forward response to Client[15]Map FHIR Bundle to Clientdata model and displayCarePlan info(incl. planned events)// Sequence diagram for the /Careplan/$view - successful response

Normal Success Response Example

Response code is HTTP/1.1 200 Ok

{
  "resourceType": "Bundle",
  "id": "AIRBundleCarePlanExample",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://air.api-dev.digital.health.nz/fhir/R4/CarePlan?_include=*&patient=ZCZ1947"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://air.api-dev.digital.health.nz/fhir/R4/CarePlan/AGVSRotavirus-ZCZ1947",
      "resource": {
        "resourceType": "CarePlan",
        "id": "AGVS-Rotavirus-ZCZ1947",
        "meta": {
          "versionId": "1"
        },
        "text": {
          "status": "extensions",
          "div": ""
        },
        "instantiatesUri": [
          "https://air.api-dev.digital.health.nz/fhir/R4/AGVS-Rotavirus"
        ],
        "status": "active",
        "intent": "plan",
        "title": "Rotavirus Immunisation Schedule for Joe Bloggs",
        "description": "This schedule shows the Rotavirus vaccination schedule per the NZ National Immunisation Schedule (NIS) for Joe Bloggs (NHI ZCZ1947) as at May 15, 2024...",
        "subject": {
          "reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZCZ1947",
          "identifier": {
            "system": "https://standards.digital.health.nz/ns/nhi-id",
            "value": "ZCZ1947"
          }
        },
        "created": "2024-05-15",
        "activity": [
          {
            "extension": [
              {
                "url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-performed-activity",
                "valueReference": {
                  "reference": "RV-ZCZ1947-1"
                }
              },
              {
                "url": "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-planned-activity-reference",
                "valueReference": {
                  "reference": "AGVS-RV-ZCZ1947-1"
                }
              }
            ]
          }
        ]
      },
      "search": {
        "mode": "match"
      }
    },
    {
      "fullUrl": "https://air.api-dev.digital.health.nz/fhir/R4/Immunization/RV-ZCZ1947-1",
      "resource": {
        "resourceType": "Immunization",
        "id": "RV-ZCZ1947-1"
        // rest of the Immunization resource
      }
    },
    {
      "fullUrl": "https://air.api-dev.digital.health.nz/fhir/R4/ImmunizationRecommendation/AGVS-RV-ZCZ1947-1",
      "resource": {
        "resourceType": "ImmunizationRecommendation",
        "id": "AGVS-RV-ZCZ1947-1"
        // rest of the ImmunizationRecommendation resource
      }
    }
  ]
}

Empty Success Response Example

Response code is HTTP/1.1 200 Ok

{
  "resourceType": "Bundle",
  "type": "searchset",  
  "entry": [
    // No entries are returned in this case ...
  ]
}

$view API Sequence Diagram – Redacted Success Scenario

User<<Application>><<Gateway>><<FHIR Service>>ImmSOT DBUserUser«Application»Client«Application»Client«Gateway»API-Gateway«Gateway»API-Gateway«FHIR Service»ImmSOT Service«FHIR Service»ImmSOT ServiceImmSOT DBImmSOT DB[01]Request to view consumer'splanned vaccination events[02]Client request a token[03]Return OAuth token (JWT)[04]Initiate /CarePlan/$viewrequest with NHI with theOAuth token (JWT)[05]validate token andpermissions[06]Forward /CarePlan/$viewrequest[07]Validate token andpermissions[08]Check NHI whther Consumeris suppressed?[09]Consumer is suppressed[10]Generate redacted response[11]Return an empty bundle withredacted metadata securitytag[12]Transform response for UIconsumption[13]Display user-friendly error(e.g., "Access to this NHIImmunization related info isrestricted")CarePlan/$view when NHI is suppressed

Redacted Success Response

Response code is HTTP/1.1 200 Ok

ImmSOT will return a success response with an empty result and will add an additional metadata security attribute with the value “REDACTED” as below. Consuming client applications can use this metadata tag to differentiate between an empty response (i.e ImmSOT does not have the data) and an empty result because the consumer immunisation information is suppressed.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "meta": {
    "security": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code": "REDACTED",
        "display": "redacted"
      }
    ],
    // No other meta information should be provided...
  },
  "entry": [
    // No entries are returned in this case ...
  ]
}

$view API Sequence Diagram – Failure Scenario

User<<Application>><<Gateway>><<FHIR Service>>ImmSOT DBUserUser«Application»Client«Application»Client«Gateway»API-Gateway«Gateway»API-Gateway«FHIR Service»ImmSOT Service«FHIR Service»ImmSOT ServiceImmSOT DBImmSOT DB[01]Request to view consumer'splanned vaccination events[02]Client request a token[03]Return OAuth token (JWT)[04]Initiate /CarePlan/$viewrequest with NHI with theOAuth token (JWT)[05]validate token andpermissions[06]Forward /CarePlan/$viewrequest[07]Validate token andpermissions[08]Check NHI whther Consumerexists?[09]Consumer does not exist inImmOST (and in NHI)[10]Generate error response[11]Return an OperationsOutcome, consuemer notfound[12]Transform response for UIconsumption[13]Display user-friendly error(e.g., "The NHI you provideddoes not exist in ImmSOT")CarePlan/$view when NHI does not exist in ImmSOT

Example Failure Response

Response code is HTTP/1.1 404 Not Found

{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"diagnostics": "Consumer not found"
}
]
}