Aggregated
- Andrew Turner (Unlicensed)
- Tom Pick (Unlicensed)
- Mohammad Al-Ubaydli
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 |
|---|---|
References | When populating a Reference, Customer integrations must ensure that they…
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:
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 |
|---|---|---|---|
Medication | code.coding | 1 or more matching Coding entries. A Coding matches if and only if the following 2 attributes match:
| Extensions
Elements
|
Organization | identifier | 1 or more matching Identifier entries. An Identifier matches if and only if the following 2 attributes match:
| Extensions
Elements
|
Patient | identifier | 1 or more matching Identifier entries. An Identifier matches if and only if the following 2 attributes match:
| Extensions
Elements
|
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:
| Extensions
Elements
|
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 |
|---|---|
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:
|
Resource specific rules
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.