Customer

Owned by Andrew Turner (Unlicensed)
Last updated: Jul 26, 2023 by Tom Pick
3 min read

Overview

Each customer is allocated 1 dedicated instance for each of their inbound FHIR feeds to PKB. Full read/write support for all REST interactions, for all resource types, available in customer's choice of STU3 or R4. Read/write access to each endpoint is restricted to the customer who owns it.

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/write all standard FHIR resources

What you cannot do with this endpoint

  • Read data from other sources

Capabilities

A Customer FHIR endpoint can be made available in either STU3 or R4 versions of FHIR.

The endpoint supports the full range of REST interactions for all resource types in the corresponding version of FHIR. This includes support for providing resources using a batch/transaction interaction.

The CapabilityStatement on each endpoint details the full capabilities available for use.

Resources will only be available outside of your Customer endpoint (e.g. in the PKB web interface) if the resource type is supported by the Aggregated FHIR endpoint.

Endpoint

Each Customer endpoint will be given a dedicated subdomain URL on the corresponding server environment.

For example, PKB's sandbox environment has a server host address of: https://sandbox.patientsknowbest.com

The corresponding Customer FHIR endpoint for Acme might be: https://acme.fhir-api.sandbox.patientsknowbest.com

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

Customer FHIR endpoints only support system-level access, and consequently user-level access (such as NHS Login) cannot be used to access them.

Validation and business rules

Enforced business rules

A Customer endpoint will only apply simple syntax validation to the FHIR resources provided. No other business rules or profile validation will be performed.

Unenforced business rules

  • A Customer should not send any resource that includes a modifierExtension. These are not supported by PKB.

  • A Customer should not send any resource that uses a modifier element to:

    • negate a concept. Unless otherwise specified, PKB will assume all resources represent positive assertions. For example, you should not send in a MedicationStatement resource with a status of “not-taken”. Existing data can be deleted; PKB will maintain the version history but will remove deleted data from the medical record.

    • delete a concept. Unless otherwise specified, PKB will assume all resources represent data to be included in the medical record. For example, you should not send in a MedicationStatement resource with a status of “entered-in-error”. Existing data can be deleted; PKB will maintain the version history but will remove deleted data from the medical record.

  • A Customer should not send an resource that belongs in the medical record of more than 1 Patient. For example, an Appointment for a group therapy session in which multiple patients are present. PKB is a patient-focused health record and does not support data that references multiple patients.

Aggregation criteria

If you would like your FHIR resources to be included in the Aggregated FHIR endpoint then you must make sure your data meets the constraints enforced by the aggregator - see the business rules information for details.

A Customer cannot currently check the processing outcome of the attempt to include a resource in the aggregated data set.

Examples

See the Examples page for step-by-step examples of how to send and fetch FHIR data.

Roadmap

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