Aggregated

Overview

This is a read-only, R4 FHIR API which aggregates data from all input routes, both FHIR and non-FHIR. The aggregation will perform STU3->R4 mappings as required. Complex access control applies since this contains data from multiple sources.

The data types available from this endpoint will be iteratively expanded over time, starting with Appointments. Please see the roadmap section for details of when other data types will be supported.

Although a Customer can read all data they send to their own Customer FHIR endpoint, such data must always go through the Aggregated FHIR endpoint in order to be made available to other users. Once support for a data type has been added to the aggregator, other system components (e.g. the web interface, Custom REST API, Facade FHIR endpoint) will be upgraded to read from the Aggregated FHIR endpoint, so that these will return data added to a Customer FHIR endpoint, ensuring that these data are available to users who will not be querying the Aggregated FHIR endpoint directly.

What you can do with this endpoint

  • Read data from other sources, even if it was provided in non-FHIR format

What you cannot do with this endpoint

  • Write data

  • Read resource types that have not been included in PKB's aggregation logic. Please see the Capabilities section for a list of which resource types have been included so far.

  • Read resources that you do not have authorisation to see. For example, a resource from a different organisation tagged with a privacy label that has not been granted to the caller.

Capabilities

Please see the "rest" section of the corresponding CapabilityStatement for details of which endpoints are supported:

https://pkbdev.atlassian.net/wiki/spaces/api/pages/3364389010/Capabilities+Aggregated

Note: the above CapabilityStatement reflects which resource types are included in the aggregation logic, and therefore available from the Aggregated FHIR endpoint. Searches over other resource types will return an empty search result; you should not assume a “successful” response implies the corresponding resource type has been added to the aggregation logic.

Endpoint

Pending

Authentication

Customer

OAuth 2.0 System Client Credentials

Callers should obtain an access token by using the OAuth 2.0 Client Credentials workflow.

Note: the token endpoint is different from the one used for the Facade and Messaging FHIR endpoints, and the tokens are not interoperable.

Partner

Pending

App

NHS Login

Pending - will support NHS Login “asserted login identity” flow

Patients without NHS Login

Pending

Non-patient users

Pending

Validation and business rules

When designing an end-to-end integration that involves fetching data from the Aggregated FHIR endpoint, consideration must be given to relevant business logic applied at each stage of the data pipeline: input, processing and output.

Input

  • Customer endpoint rules. Customers have a lot of freedom in what can be sent to a Customer FHIR endpoint, but there are a few rules that must be adhered to (see linked documentation).

Note: data not sent to a Customer FHIR endpoint can still be returned from the Aggregated FHIR endpoint; rules for such non-FHIR data are outside the scope of this FHIR documentation.

Processing

Once the resource has been accepted to the Customer FHIR endpoint, the PKB aggregator will attempt to aggregate that resource into the Aggregated FHIR endpoint. There are several business rules that apply to that processing:

  • Supported resource types. Remember to check the capabilities of the Aggregated FHIR endpoint to confirm that the aggregator supports the relevant resource type(s).

    • Searches over unsupported resource types will return an empty search result; you should not assume a “successful” response implies the corresponding resource type has been added to the aggregation logic

    • Additionally, Customers must not provide a reference from a supported resource type to an unsupported resource type, since this is not supported by our aggregation logic

  • Business rules that define whether a resource will be included in the Aggregated FHIR endpoint. The rules are outlined below.

    • Resources which do not meet these rules will be silently excluded from the data in the Aggregated FHIR endpoint

  • Relevant merge logic. The aggregator will attempt to merge some resources together. There are resource type-specific rules about if/how this is down, which are outlined below.

    • Please also take note of the implications of the merge logic for corrective workflows

Output

The PKB web interface expects particular information to be in particular places within the FHIR resource. These rules are discussed below.

Inclusion criteria for the Aggregated FHIR endpoint

Note that these rules apply to inbound data sent to a Customer FHIR endpoint. FHIR resources returned from the Aggregated FHIR endpoint can contain other data and might not always conform to these rules.

Rule

Description

Rule

Description

References

When populating a Reference, Customer integrations must ensure that they…

  • populate the “reference” element of a Reference. Business identifiers provided in the “identifier” element of a reference will not be resolved by PKB.

  • are not contained references; they must refer to a resource with a persistent identity

  • do not refer to resources on a different server (absolute references are discouraged, but if provided will never be followed and will always be treated as if the server component had not been provided - see below)

  • do not refer to an unsupported resource type from a supported resource type (our aggregation logic does not support this)

Resources that do not provide correct references will normally be skipped during the aggregation process, and will therefore not be returned from the Aggregated FHIR endpoint. Some errors might lead to an error state that will need support from PKB helpdesk to resolve.

Additionally, absolute references are strongly discouraged. The aggregator will assume any absolute reference is an artefact of upstream data construction and will remove the server component. For example, if a reference is provided to http://example.com/Patient/123, then the aggregator will assume this is equivalent to a local reference of Patient/123, and that is the reference value that will be returned from the Aggregated FHIR endpoint.

Example of a correct Patient reference

{ "resourceType": "MedicationStatement", "subject" : { "reference" : "Patient/123" } ... }

Examples of incorrect Patient references

The following is incorrect because the patient is referenced by business identifier:

{ "resourceType": "MedicationStatement", "subject" : { "identifier" : { "system": "https://fhir.nhs.uk/Id/nhs-number", "value": "9999999999" } } ... }

The following is incorrect because the patient referenced is a contained resource:

{ "resourceType": "MedicationStatement", "contained": [ { "resourceType": "Patient", "id": "patient-123", ... } ], "subject" : { "reference" : "#patient-123" } ... }

Identifier/code systems

When providing a resource of a type that is merged during aggregation:

  • If the merging is based on the identifier element, then at least one identifier must be provided.

  • The relevant identifier or coding element which is used to group those resources together must contain a system for every identifier or coding provided.

Example of a correct Patient identifier

Examples of incorrect Patient identifiers

The following is incorrect because the Patient identifier does not contain a system element.

Person.link

If providing a Person resource, a link to a target Patient must be provided.

PractitionerRole.practitioner/organization

If providing a PractitionerRole resource, a link to a target Practitioner and Organization must be provided.

Merge logic

The PKB aggregator will attempt to identify resources from multiple sources that contain information about the same entity, and merge those into a single resource.

For example, a single patient might have Patient resources on multiple Customer FHIR endpoints, including multiple resources on a single Customer FHIR endpoint. These resources might not contain the same information. The aggregated Patient resource returned from the Aggregated FHIR endpoint will contain the result of attempting to merge the upstream Patient resources together.

The table below provides more information on the relevant business rules.

Resources types not listed are not merged during the aggregation process.

Note: remember that (as per Inclusion criteria for the Aggregated FHIR endpoint) the system must be populated for every identifier or coding provided in the element which is used to group the relevant resource type for merging. Also, at least one identifier must be provided for any resource that is merged based on identifier.

Corrective workflows

Elements included in the identity criteria of a particular resource type must not be updated. Instead, the resource containing the incorrect information must be deleted and then a new resource with the correct information sent. In addition, the new resource should be PUT to the same ID as the previous resource, in order to avoid dead references from any other resources pointing back to the newly-corrected resource.

Resource type

Grouped by

Equivalence test

Merge logic

Resource type

Grouped by

Equivalence test

Merge logic

Medication

code.coding

1 or more matching Coding entries.

A Coding matches if and only if the following 2 attributes match:

  • code. case sensitive.

  • system. case sensitive.

Extensions

  • Inclusion

    • All extensions from the root of the resource will be copied over

    • Extensions on primitives will not be copied over

    • Extension on the coding element will not be copied over

    • Extensions in other locations will be copied over

  • Multiplicities

    • If a single upstream resource has more than one instance of the same extension

      • If the extension is on the root of the resource, only one will be copied into the aggregated resource

      • Otherwise, all instances of the extension will be copied over (provided they qualify for inclusion)

    • If there is more than one upstream resource with the same extension URL then one from the most recently updated resource will be used

Elements

  • If the element accepts multiple values:

    • The element in the aggregated resource contains one list entry for each entry in each upstream resource

  • Else:

    • The element in the aggregated resource contains the value from the most recently updated upstream resource

Organization

identifier

1 or more matching Identifier entries.

An Identifier matches if and only if the following 2 attributes match:

  • value. case sensitive.

  • system. case sensitive.

Extensions

  • Inclusion

    • All extensions on the root of the resource will be copied over

    • Extensions on primitives will not be copied over

    • Extensions on the identifier element will be copied over but will not be updated

    • Extensions in other locations will be copied over

  • Multiplicities

    • If a single upstream resource has more than one instance of the same extension

      • If the extension is on the root of the resource, only one will be copied into the aggregated resource

      • Otherwise, all instances of the extension will be copied over (provided they qualify for inclusion)

    • If there is more than one upstream resource with the same extension URL then one from the most recently updated resource will be used

Elements

  • If the element accepts multiple values:

    • The element in the aggregated resource contains one list entry for each entry in each upstream resource

  • Else:

    • The element in the aggregated resource contains the value from the most recently updated upstream resource

Patient

identifier

1 or more matching Identifier entries.

An Identifier matches if and only if the following 2 attributes match:

  • value. case sensitive.

  • system. case sensitive.

Extensions

  • Inclusion

    • All extensions on the root of the resource will be copied over

    • Extensions on primitives will not be copied over

    • Extensions on the identifier element will be copied over

    • Extensions in other locations will be copied over

  • Multiplicities

    • If a single upstream resource has more than one instance of the same extension

      • If the extension is on the root of the resource, only one will be copied into the aggregated resource

      • Otherwise, all instances of the extension will be copied over (provided they qualify for inclusion)

    • If there is more than one upstream resource with the same extension URL then one from the most recently updated resource will be used

Elements

  • If the element accepts multiple values:

    • The element in the aggregated resource contains one list entry for each entry in each upstream resource

  • Else:

    • The element in the aggregated resource contains the value from the most recently updated upstream resource

Person

link.target

 

Person has custom merge logic applied. If you wish to use this resource type, please discuss your use case with us first.

Practitioner

identifier

1 or more matching Identifier entries.

An Identifier matches if and only if the following 2 attributes match:

  • value. case sensitive.

  • system. case sensitive.

Extensions

  • Inclusion

    • All extensions on the root of the resource will be copied over

    • Extensions on primitives will not be copied over

    • Extensions on the identifier element will be copied over

    • Extensions in other locations will be copied over

  • Multiplicities

    • If a single upstream resource has more than one instance of the same extension

      • If the extension is on the root of the resource, only one will be copied into the aggregated resource

      • Otherwise, all instances of the extension will be copied over (provided they qualify for inclusion)

    • If there is more than one upstream resource with the same extension URL then one from the most recently updated resource will be used

Elements

  • If the element accepts multiple values:

    • The element in the aggregated resource contains one list entry for each entry in each upstream resource

  • Else:

    • The element will not be copied over. The element may be populated to a value determined by PKB.

PractitionerRole

identifier

 

Person has custom merge logic applied. If you wish to use this resource type, please discuss your use case with us first.

Business rules affecting the display of aggregated FHIR resources

General rules

See also: FHIR FAQs: How does source tracking work?

Rule

Description

Rule

Description

Source organization

The PKB web interface shows the source of data. The source organization of a data point will be determined from the http://fhir.patientsknowbest.com/codesystem/source-organization code in meta.security. Customers should not set this value directly; PKB will assign this on the server side, based on these rules:

  • For FHIR resources sent to a FHIR Customer endpoint, the relevant Organization will normally be the one referenced by the managingOrganization attribute of the Patient resource to which the resource belongs. Alternatively, PKB can configure a default Organization to be used as the source when no other value is explicitly provided.

  • For other resources (i.e. those not sent via FHIR) PKB will automatically assign the correct source organization value.

Resource specific rules

See also: FHIR FAQs: Which FHIR fields does PKB draw from to populate the various elements in the web interface?

Resource

Description

Resource

Description

Appointment

Please see the Appointment web specification.

Condition

Please see the Diagnosis web specification.

MedicationRequest

MedicationStatement

Please see the Medication web specification.

Examples

Please see the Examples page for step-by-step examples of how to interact with this endpoint.

Roadmap

Please see the Aggregated Roadmap page for planned changes to this endpoint.