Customer Interface Requirements

Logical ids

See https://wiki.hub.patientsknowbest.com/wiki/spaces/api/pages/5003673621

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

Examples of incorrect Patient references

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

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

Business identifiers

All Identifier elements must contain both a system and value. This applies to Identifier elements on the root of the resource, as well as those in sub-elements.

Example of a correct Patient identifier

Example of an incorrect Patient identifier

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

Coding

All Coding elements must contain both a system and value, or neither.

Examples of a correct Coding

Both code and system are present

Neither code nor system are present

Example of an incorrect Coding

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

Modifier extensions/elements

Modifier extensions or elements, which alter the interpretation of a resource or sub-element in an unbounded way, are not observed or utilised in any way.

In a future versions of the API the intention is to programmatically prohibit these from being sent into the upstream endpoint.

See https://www.hl7.org/fhir/R4/extensibility.html#isModifier for more details.

Contained resources

It is a requirement that all resources are written to their specific API endpoint. If one resource must reference another, this should be done through the use of logical id references as described above.

Contained references are therefore not permitted as the break the model of being able to retrieve all the relevant data via the specific API endpoint. In a future versions of the API the intention is to programmatically prohibit these extensions from being sent into the upstream endpoint.

Multi-patient resources

Some resources may be syntactically valid to belong to more than one Patient, for example a multi-patient group Appointment.

While there is currently no validation preventing resources of this form from being sent in, please note that these are not currently supported for extraction via the aggregated endpoint due to authorization limitations.