Aggregated Data Enrichment

1 Overview
2 Enrichment cases
- 2.1 Source information
- 2.2 Appointments
  - 2.2.1 Location ODS code
  - 2.2.2 Specialty display text
  - 2.2.3 Deeplink extension element
  - 2.2.4 Participant display information
- 2.3 Patient managingOrganization array

Overview

Data which is retrieved from the aggregated endpoint may have additional data added to it. This process is referred to as “enrichment”.

Enrichment may be ephemeral, in that data is added to the resources retrieved as part of response to an API call after they are retrieved from the database, or persistent, in that data is added to the database as part of the aggregation process.

Enrichment depends on the resource being requested, and not all resources are eligible for enrichment. Some enrichment cases are not available by default and are subject to agreement following discussion with the PKB integrations team.

Enrichment cases

Source information

Every data point retrieved through the aggregated endpoint contains some form of source information indicating how it was entered and by whom. This could be the patient themselves, or a Practitioner or Organization. This source information is stored as coding elements in the security array of the meta.

These codings are enriched with user-friendly display text which can be surfaced into the UI of calling applications to avoid having to do subsequent hits to the endpoint to retrieve the relevant resources.

An example showing a data point which has source Practitioner and Organization information:

"meta": {
      "security": [
        {
          "code": "0f42dccf-ea3d-4b0b-93b4-7de1158d6cce",
          "display": "Dr Dren's GP Practice",
          "system": "http://fhir.patientsknowbest.com/codesystem/source-organization"
        },
        {
          "code": "93574d39-07ce-47e4-bc3f-2b8cb9b5e53a",
          "system": "http://fhir.patientsknowbest.com/codesystem/source-practitioner",
          "display": "Dr David Tong"
        }
      ]
    }

Appointments

Appointments are specifically enriched with large amounts of information reflecting their complex nature. In addition to the source information enrichment described above, the following information is added to an Appointment resource:

Location ODS code

An participant component is added of type “Location” which holds the ODS code of the source of the Appointment, if applicable. If the source of the Appointment does not have an ODS code, this additional element is not added. Existing location actors are unaffected.

An example is below, showing this new location participant alongside an existing one:

"participant": [
      {
        "actor": {
          "display": "Existing location",
          "type": "Location"
        },
        "status": "accepted"
      },
      {
        "actor": {
          "identifier": {
            "system": "https://fhir.nhs.uk/Id/ods-organization-code",
            "value": "A12345"
          },
          "type": "Location"
        },
        "status": "accepted"
      }
    ]

Specialty display text

The specialty of an Appointment, if present, coded and for an Organization which has the relevant ValueSets configured, is enriched with the display text from that Value Set. Specialties which were sent in textually originally are unaffected.

"specialty": [
    {
      "coding": [
        {
          "code": "300",
          "display": "Opthamology"
        }
      ]
    }
  ]

Deeplink extension element

An extension is added to the root extension array on the Appointment resource to serve as a link to that specific Appointment within the PKB GUI as accessed through NHS Login. This extension is primarily for the purpose of the NHS Wayfinder integration, but is present for all callers who can make use of it in their workflows.

"extension": [
      {
        "extension": [
      {
        "url": "https://fhir.nhs.uk/StructureDefinition/Extension-Portal-Link",
        "valueUrl": "https://testing.pkb.com/nhs-login/login?phrPath\u003d%2Fdiary%2FviewAppointment.action%3FuniqueId%3De0398b66-e5cb-46c6-ac2a-776e0d6731a8"
      }
    ]

Participant display information

As per source information, participants within an Appointment have appropriate user-friendly display text added to their elements to prevent repeated API roundtrips.

"participant": [
    {
      "actor": {
        "display": "Dr Betty Newbie",
        "reference": "Practitioner/a24aa82a-c12f-40bd-b744-eba294601da0",
        "type": "Practitioner"
      },
      "status": "accepted"
    },
    {
      "actor": {
        "display": "Bob Smith",
        "reference": "Patient/f2840a77-6b79-4e09-92ce-b84b759a5da2",
        "type": "Patient"
      },
      "status": "accepted"
    }
]

Patient managingOrganization array

PKB surfaces an array which maps upstream Patient logical ids alongside the organizations that data has come from, as denoted by the managingOrganization element provided to the upstream FHIR server. Note that this enrichment case is currently subject to approval and is not generally available without prior discussion with PKB.

This is typically used in a read-write system where a customer is utilising both an upstream FHIR server and the aggregated endpoint, as it allows for workflows which involve retrieving the Patient resource from the downstream endpoint, creating new data pointing at the relevant upstream Patient logical id, and then persisting this new data to the upstream FHIR server.

The managingOrganization information is captured as a series of extension arrays on the root extension array of the Patient resource. Each extension array instance contains the following information:

The managingOrganization upstream element, including the upstream logical resource id and any other data. This upstream logical id is expressed as a URI type containing the public URL of the upstream FHIR server this was derived from.
The managingOrganization downstream element, including the downstream logical resource id where an upstream logical resource id was provided. The downstream element is enriched with the display name of the Organization from the downstream endpoint.
The upstream resource id which this managingOrganization was derived from, which is always a Patient
The upstream source id of this information, for internal debugging purposes

A full example showing multiple extensions as they would display on a Patient resource is below:

"extension": [
    {
      "extension": [
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization-downstream",
          "valueReference": {
            "display": "Balmora District Hospital",
            "reference": "Organization/0207ffbf-7649-3578-8dab-195493e1fc40"
          }
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization-upstream",
          "valueUri": "<customer1_fhir_server_url>/fhir/Organization/20a9aa36-f9bb-477a-8676-ebd16db63244"
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-resource-id",
          "valueString": "Patient/d17f3b76-3afc-4835-88ac-d17535ab49c4"
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-source-id",
          "valueString": "customer1"
        }
      ],
      "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization"
    },
    {
      "extension": [
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization-downstream",
          "valueReference": {
            "display": "Dr Peterson's GP Practice",
            "reference": "Organization/ed9f4afb-8018-3fef-9c9a-296f83c4d6d1"
          }
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization-upstream",
          "valueUri": "<customer2_fhir_server_url>/fhir/Organization/290609e4-eda5-49aa-b3de-c4fb69427c36"
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-resource-id",
          "valueString": "Patient/d17f3b76-3afc-4835-88ac-d17535ab49c4"
        },
        {
          "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-source-id",
          "valueString": "customer2"
        }
      ],
      "url": "https://fhir.patientsknowbest.com/structuredefinition/managing-organization"
    }
]