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

Only some resource types are used to populate the information shown in the PKB web interface. Please see the Aggregated FHIR endpoint CapabilityStatement for the current list.

For those resource types that do populate the web interface:

• The Data Model page shows a summary of which fields are shown in the UI. For example: it can be seen on the Appointment page that the serviceType is shown (but only the “code” component) and that the Common ID is not shown at all.

• Where available, more detailed information about how the web interface uses the FHIR resource to generate its content is shown in the corresponding web specification. For example: the way that PKB converts MedicationRequest and MedicationStatement resources for display can be found in the Medication web spec.

When I send data to my Customer endpoint, should I use a Bundle or manage resources individually?

We support either managing resources individually using standard REST interactions, or else providing resources in a Bundle.

If sending resources in a Bundle, be careful to use either a batch or transaction interaction, which requires that the Bundle is sent to the server root. Creating the Bundle by posting to the Bundle type service will not lead to the Bundle contents being inspected and made available in their corresponding type services.

When I send data to my STU3 Customer endpoint, how will PKB convert that to an R4 representation for use by the Aggregated FHIR endpoint?

The conversion is performed by the HAPI FHIR library. Users interested in the details should consult the HAPI FHIR docs: Version Converters

Which resource types does PKB aggregate?

The PKB aggregator will copy over only supported resource types from the upstream boxes (e.g. Customer FHIR endpoints) to the Aggregated FHIR endpoint.

The supported resources are listed in the Aggregated FHIR endpoint capabilities page.

When a resource type is “released”, it means that resources of that type will be included in responses from the Aggregated FHIR endpoint, and will be made available in the PKB web interface (see “Which FHIR fields does PKB draw from to populate the various elements in the web interface?” for more information). However, data from these resources are not yet included in responses from the Custom REST API or the Facade FHIR API.

Note: just because a resource is aggregated (i.e. copied to the Aggregated FHIR endpoint from upstream endpoints) this does not necessarily mean the resource type is merged (i.e. multiple resources from upstream boxes combined into a single resource on the Aggregated FHIR endpoint).

Which resource types are merged together by the aggregator?

Resources which have merge logic applied are listed in the Merge logic section of the Aggregated FHIR endpoint Validation and business rules documentation. The purpose of the merge logic is to combine multiple resources from multiple upstream sources which represent the same real world concept.

Each resource type shows the Grouped by and Equivalence test criteria by which resources from multiple upstream sources will be compared. If these criteria are met, the resources will be merged into a single resource in the Aggregated FHIR endpoint, according to the rules in the Merge logic section.

If a resource type is not listed, then upstream resources (e.g. those provided to a Customer FHIR endpoint) are copied over to the Aggregated FHIR endpoint without being combined with any other resources.

What changes does the PKB Enricher make to resources before they are returned from the Aggregated FHIR endpoint?

Before a resource is returned from the Aggregated FHIR endpoint, the PKB Enricher makes the following changes:

• Any specialty code for which a display name has been provided by the customer will have the relevant “display” element of the Coding set to that display name. This is a display-time replacement of the value on the persisted resource.

Which resources types can I access from the Aggregated FHIR endpoint?

The Aggregated FHIR endpoint is currently only available for PKB internal use, e.g. to populate the web interface for released resource types.

Even if a resource type is aggregated, you cannot fetch it back from the Aggregated FHIR endpoint directly.

This section will be updated once the functionality is available for external use.

How are HL7 codings mapped to FHIR?

The code value itself is sanitised to remove repeated whitespace. E.g. “a b” will become “a b”

The code system will be converted to a URL, appended with the org UUID, so e.g. a system of my-system for an org of 35e93e3b-952d-405e-b656-667468d24ceb will become: http://fhir.patientsknowbest.com/codesystem/my-system-35e93e3b-952d-405e-b656-667468d24ceb

For information not originally entered via FHIR (e.g. sent in an HL7 message) how will PKB represent that information in FHIR resources I retrieve from the Aggregated FHIR endpoint?

PKB migrates data not originally sent to a Customer FHIR endpoint into various FHIR resources, which are then exposed on the Aggregated FHIR endpoint. For example, a non-FHIR appointment will be migrated to a FHIR Appointment resource, which conforms to the http://fhir.patientsknowbest.com/structuredefinition/aggregated-appointment profile.

Each of these profiles has a dedicated StructureDefinition page which explains in more detail how we populate each element. For example, the Aggregated Appointment profile can be found here: https://wiki.patientsknowbest.com/space/api/3365077229/Aggregated+Appointment.

The profiles document the mappings from the abstract PKB Data Model into the FHIR elements. The corresponding Data Model page will indicate how each item is populated from the various input sources. For example, the Appointment Data Model page indicates that the HL7 SCH-11.4 field (appointment start time) maps to the abstract Data Model component of [[Appointment.Start Timestamp]]. The Aggregated Appointment profile page then indicates that the Start Timestamp component is mapped to the start element of the Appointment resource. Therefore, callers should expect to find the SCH-11.4 start timestamp value returned from the Aggregated FHIR endpoint in the Appointment.start element.

Is there a delay before data will be available from the Aggregated FHIR Endpoint?

For information sent to a Customer FHIR endpoint, there might be a delay of a few seconds before the information is available from the Aggregated FHIR endpoint.

There might also be a delay of a few seconds when entering information into PKB via other routes, such as the web interface.

For information sent to PKB via route that is processed asynchronously, such as data sent to the HL7 API, there might be a delay of a few minutes before the information is migrated into Aggregated FHIR endpoint.

Note: for resource types that have been released, and therefore used to populate the PKB web interface, a delay before the information is available from the Aggregated FHIR endpoint will also lead to a delay before the information is visible in the web interface.

How can I found out more information about PKB-defined extensions, code systems and identifier systems returned from the Aggregated FHIR endpoint?

Each PKB-defined canonical URL will have a corresponding page in our public documentation. Searching the PKB wiki for the URL of interest should return the relevant page.

Where possible, each URL will also resolve directly to the correct page in the documentation.

What is the difference between an extension and a profile?

An extension describes one piece of information that might be returned in a resource. For example, the sharing-disabled extension indicates whether sharing has been disabled for a particular medical record.

A profile describes the content of an entire resource. For example, the Aggregated Appointment profile describes how non-FHIR data will be mapped to a FHIR resource that is exposed by the Aggregated FHIR endpoint.

Both extensions and profiles are represented by a FHIR StructureDefinition resource. The StructureDefinition page provides an overview of the PKB extensions and profiles.

What do the different time stamps mean and which ones should I be using?

Independently of any resource-specific content (e.g. the Appointment resource has a “start” element to indicate when the appointment starts), there are some metadata timestamps which can be found on most resources. These are outlined below.

May be sent by a Customer

• recorded-date

  • This captures a human-centric time stamp of when this information was entered into the source system. When PKB migrates non-FHIR data to FHIR format, this extension is used for both [[Data Point.Entered Timestamp]] and [[Version Details.Entered Timestamp]], which capture equivalent concepts.

  • This is useful for determining how current the information is.

  • This is not affected by database maintenance tasks (re-migration and re-aggregation).

  • This extension can appear in meta.extension or on a specific element within the resource.

  • Customers may provide this extension (on the meta element only)

Must not be sent by a Customer

• meta

  • extension

    • ex:createdAt

      • This captures a system-centric time stamp of when this resource was first created.

      • This is useful for determining when the resource was first available from the Aggregated FHIR endpoint.

      • This is not affected by database maintenance tasks (re-migration and re-aggregation).

      • This extension can only appear in meta.extension.

      • Customers must not provide this extension; this is maintained automatically by the server - any values provided to a Customer endpoint will be ignored.

    • upstream-last-updated

      • The value is determined from the upstream resource using conditional logic: recorded-date if available, else meta.lastUpdated

      • This extension is helpful for use cases that need to:

        • determine a human-centric modification time stamp without being affected by any database maintenance tasks performed by PKB (re-migration and re-aggregation maintenance tasks will both cause the meta.lastUpdated time stamp to move forward on resources in the Aggregated endpoint, even though the human-centric modification time stamp of the content has not changed)

        • and determine that time stamp from a single attribute which uses a sensible default such that it can never be empty

      • Currently only populated on the Appointment resource, which is the only resource type for which such a use case currently exists.

      • This is not affected by database maintenance tasks (re-migration and re-aggregation).

      • This extension can only appear in meta.extension.

      • Customers must not provide this extension; this is maintained by PKB.

  • lastUpdated

    • This captures when the resource was last updated.

    • It is useful for determining a system-centric modification time stamp; most real world use cases are likely to find one of the time-related extensions better suited for use in business logic. Since this is not an extension callers can query over this value.

    • This is affected by database maintenance tasks (re-migration and re-aggregation).

    • Customers must not provide this value; lastUpdated is always maintained by the server - any values provided to a Customer endpoint will be ignored.

• created-date

  • Primarily used for non-clinical entities, this extension captures [[Version Details.Created Timestamp]], which represents the first time this entity was added to the medical record database and is not modified when that entity is changed over time. This is not to be confused with the ex:createdAt extension, which records when the FHIR resource was first created on the relevant server, which could be significantly different because pre-FHIR data will be migrated potentially a long time after it was first created in PKB.

  • This is useful for determining when the resource/element was first available in the medical record database (which might be significantly earlier than it was first available in the Aggregated FHIR endpoint).

  • This is not affected by database maintenance tasks (re-migration and re-aggregation).

  • This extension can appear in meta.extension or on a specific element within the resource.

  • Customers must not provide this extension; this is maintained by PKB.

• entered-date

  • This must not be used. It is identical in meaning to recorded-date.

• version-persisted

  • This captures a system-centric time stamp indicating when this version of the resource was persisted into the medical record database, as captured by [[Data Point.Persisted Timestamp]] and [[Version Details.Persisted Timestamp]]. This is potentially significantly different from when it was entered in the source system, or even when it was received by PKB (there might be a processing delay).

  • This is useful for determining when this specific version of the resource/element was first available in the medical record database.

  • This is not affected by database maintenance tasks (re-migration and re-aggregation).

  • This extension can appear in meta.extension or on a specific element within the resource.

  • Customers must not provide this extension; this is maintained by PKB

How does source tracking work?

Resource types sent to a Customer FHIR endpoint which are to form part of the patient’s record always have some way of referring to the patient (e.g. Condition.subject, Appointment.participant). The Customer can declare the source of such data by ensuring the target Patient resource uses Patient.managingOrganization to refer to an Organization which represents the source of the data. Optionally, PKB can configure a default Organization to be used when the source is not provided explicitly. The PKB web interface will display the name of this Organization as the “source”. Note that in this way a single Customer can provide data from multiple Organizations on the same endpoint.

• If no managingOrganization is present, PKB will use the default Organization. It is an error for there to be no managingOrganization on an integration with no default Organization configured; every resource sent to a Customer endpoint must have a source Organization.

• The details of the managingOrganization are controlled by the Customer; this information is not authenticated by PKB.

• The managingOrganization is not populated on a Patient returned from the Aggregated FHIR endpoint, because Patient is a resource type that is merged and source-tracking on merged resource types is handled differently (see below).

meta.security contains codes that indicates the resource ID of the relevant source entities. Customers should not set these values themselves; PKB will ensure the codes are set correctly. These codes are an implementation optimisation, e.g. removing the need for a caller to fetch the chained managingOrganization. The possible code systems are:

• source-organization (note that this refers to a FHIR Organization resource which may or may not correspond to a PKB Organisation)

• source-patient

• source-practitioner

• source-team

Note that these codes are not populated for resource types that are merged, because source-tracking on merged resource types is handled differently (see below).

The http://fhir.patientsknowbest.com/structuredefinition/upstream extension adds an additional level of source tracking, by tracking which of the upstream endpoints the information returned by the Aggregated FHIR endpoint actually came from.

• For resource types that are not merged, this extension is added to the top level of the resource. Unlike the managingOrganization details (and hence the the resource ID codes found in meta.security) the upstream extension does represent authenticated information (i.e. connections to the Customer endpoint are authenticated; this extension captures the identifier of the endpoint, which is not within the control of the sender).

• For resource types that are merged, this extension is added to each element that gets added to the merged resource returned from the Aggregated FHIR endpoint. If multiple sources have the same information, it is possible for there to be multiple upstream extensions on the same element.

• The extension contains 2 elements:

  • upstream-source-id. A textual identifier of the upstream endpoint on which the source resource can be found.

  • upstream-resource-id. The resource type and resource id of the upstream source resource (e.g. Patient/d9190fed-382d-40ee-bf50-f9ce23981cfc)