Developer documentation‎ > ‎HL7 API‎ > ‎Roadmap‎ > ‎

Partner Connections

Status

In specification. API spec subject to change.

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 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|

    Comments