Partner connections

Owned by Andrew Turner (Unlicensed)
Last updated: Jul 04, 2022 by Mohammad Al-Ubaydli
3 min read

Overview

PKB is proud to partner with third party companies, some of which can be found here.

In a typical integration, the Partner is required to send data to PKB on behalf of an existing PKB Customer.

For example, perhaps a Hybrid Mail Management service intends to send documents to PKB on behalf of an NHS Trust, an existing PKB customer.

This page outlines how such a partner can do this when using the HL7 API.

These steps are a modification to our existing information about establishing a connection.

Technical requirements

Authentication

PKB will issue each Partner a unique username and password. For example, the partner might be issued:

  • username = partner_mailco

  • password = testing

To authenticate, use HTTP Basic authentication, as follows:

  1. Concatenate the username and password, separated by a colon. For example:

    1. partner_mailco:testing

  2. Base64 encode the result from step 1. For example:

    1. cGFydG5lcl9tYWlsY286dGVzdGluZw==

  3. Set the "Authorization" HTTP Header to be the value from step 2, prepended with "Basic ". For example:

    1. Authorization: Basic cGFydG5lcl9tYWlsY286dGVzdGluZw==

This is the same authentication mechanism that a Customer uses.

Authorisation

A Partner is only permitted to send data to PKB via HL7 when authorised to do so by an existing PKB Customer. In this example, an NHS Trust.

In order for PKB to track comprehensively the source of each data point, the Partner must indicate the Customer for which they are sending data.

To achieve this:

  1. PKB will assign each Customer an alias, and let the Partner know what that alias is

  2. The Partner will be required to send that alias value in MSH-4, inside the HL7 message

In a more complicated scenario, it is possible that the Customer connecting to the Partner is sending data on behalf of a different Customer, who remains the data controller. In order to future-proof the Partner specification for this design, both aliases will need to be sent in MSH-4, using the syntax: connecting-alias{data-controller-alias}

Where only one Customer is involved, the same alias should be sent twice.

In this example, if the Partner is sending data for a Customer who has been assigned an alias of trustalias, then the contents of MSH-4 will need to be: trustalias{trustalias}

Here is an example of an HL7 message with that value set:

MSH|^~\&|Hello7|trustalias{trustalias}|HL7API|PKB|20191029150209+0000||ADT^A28|f691896e-977f-4f06-91ee-625155ca71f8|P|2.4|

PID|||9191029996^^^NHS^NH||Patient^20191029^^^Mr||20191029|M|||123 Main Street^^London^London^CB11BC^GBR||||en|

Considerations

ADT A28/A31

It is discouraged for a Partner to send HL7 A28 or A31 messages containing allergy, diagnosis or medication segments. This is because a Customer can have only one set of allergy, diagnosis and medication information linked to an individual patient record. If a Partner were to send an A28/A31 message which contained allergy, diagnosis or medication information on behalf of their Customer then that information would overwrite any equivalent information that had been added by the Customer directly (e.g. from a PAS feed) or that had been added by professionals within the Customer organisation.

Soft matching

If an HL7 message sent by a Partner fails the soft matching checks applied to the integration then the message will be queued for review by the Organisation Administrator within the Customer organisation.

Data point IDs

The Partner shares the data point ID namespace with the Customer organisation.

The Partner HL7 messages will contain an external ID. For example an MDM message will contain a unique document number (TXA-12) and an SIU message will contain an appointment placer id (SCH-1).

If the Partner is maintaining (creating, updating, deleting) their own data points then they need to use a unique ID that will not conflict with the Customer's own IDs e.g. a UUID could be used.

If the Partner is amending (updating, deleting) an existing Customer data point then the Partner should include in their design a means to utilise the same ID that the Customer used on creation of the data point.