HL7 Connection Guidance

Overview

PKB only accepts HL7 messages wrapped in a SOAP envelope.
Plain MLLP is not supported.

Security and authentication

An HTTPS connection is mandatory.
We will provide you with a username/password for (HTTPS) authentication linked to your PKB Organisation.
For our production server, we will need to know what IP address(es) you will be connecting from. We use this in 2 ways:
- We will whitelist it at the firewall level
- When an HL7 message is received, the incoming IP is checked against a specific whitelist for your PKB Organisation. If this check fails, the message will be rejected with a generic message.
We do not enforce IP whitelisting in our test environments.
Messages for patients for whom you do not have a consent record (e.g. those outside of your PKB Organisation) will still be accepted.

Configuration

WSDL-based configuration

Each HL7 endpoint has a corresponding WSDL, which you can use to automatically configure your connection (if supported by your toolset).

Please see our Connectivity page for technical details of where the WSDL can be found for your environment.

No built-in SOAP/Web Services support?

If you can make HTTP requests, you can still use the SOAP/Web Services interface.

Here's what's involved in submitting an HL7 message securely to PKB using the web services (SOAP) interface.

You can test it using Postman (an app for the Chrome browser).

Submit an HTTP POST to the relevant HL7 URL.

Please see our Connectivity page for technical details of where the HL7 SOAP message should be sent.

You'll need to provide your HTTP Auth:

username: _________

password: _________

The way to include that in the request using Postman is to add this HTTP header:

Header: Authorization

Value: Basic WU9VUl9VU0VSTkFNRTpZT1VSX1BBU1NXT1JE

(the second part of the value will need to be "your-username:your-password" encoded in Base64)

You'll also need to set the content type in a second HTTP header:

Header: Content-Type

Value: text/xml

The body (raw) of the message is this XML SOAP wrapper around your HL7 message.

It wraps your HL7 content in a "CDATA" tag so that you don't need to escape XML special characters like & < and >:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wss="http://wsssl.hl7api.patientsknowbest.com/">

    <soapenv:Header/>

    <soapenv:Body>

        <wss:acceptMessage>

            <arg0><![CDATA[

YOUR HL7 MESSAGE GOES HERE

            ]]></arg0>

        </wss:acceptMessage>

    </soapenv:Body>

</soapenv:Envelope>

Here's a full working example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wss="http://wsssl.hl7api.patientsknowbest.com/">

    <soapenv:Header/>

    <soapenv:Body>

        <wss:acceptMessage>

            <arg0><![CDATA[

MSH|^~\&|SendingApp|SendingOrg|HL7API|PatientsKnowBest|201302241503||ORU^R01|6566425|P|2.3

PID|||5981074299^^^NHS^NH~123456^^^RA9^MS~||PATIENT^DATA^^^||19800101|F|||1 WIMPOLE STREET^^LONDON^LONDON^CB1 8NR|||||||||||^||||||||

ORC|RE||0011B050802||IP||^^^201302241100^^R||201302241503|||KEEL^DR P.G. KERLING|DATA^PKB DATA INTEGRATION|||||||

OBR|1||0011B050802|CBC^BCBC^WinPath||201302241423|201302241100||||||\.br\\.br\\.br\\.br\? mi|201302241100|B^Blood,|KEEL^DR P.J. KEELING||||||201302241457||BHI|F||^^^^^R

OBX|1|NM|BHIMCH^MCH^WinPath||31.2|pg/cell|27 - 32||||F|||201302241100||

            ]]></arg0>

        </wss:acceptMessage>

    </soapenv:Body>

</soapenv:Envelope>

Source information

Partner connections

If you are connecting as a Partner, please see specific guidance here.

Default teams

All patients need to be created into at least one PKB Team.

Since your HL7 credentials represent your PKB Organisation, you need to decide which PKB Team patients created via HL7 API interface should be created into when no other Teams have been explicitly specified.

See our Team membership guidance for more information on how to manage the teams into which patients are placed.

Aliases

Occasionally, some customers have a need to send a message using their PKB Organisation level HL7 credentials, but have it processed as if it came from a specific PKB Team. For example, perhaps you want the source of a document to show as the relevant Team rather than just the Organisation. We can configure some aliases for you, such that you can send the corresponding alias in MSH-4 to indicate which PKB Team you're sending the message on behalf of.

At the moment, the target of an alias must be either your own Organisation or else a Team within your organisation. You cannot connect as one Organisation and alias to a different Organisation.

If you provide a value that does not match a known alias then PKB will interpret the message as having been sent by the Organisation.

Aliases are not case sensitive.

PKB Aliasing Checklist:

Agree on alias values to send in MSH-4 in sandbox. Client
Create teams (that align to aliases from step 1) in Sandbox. Client + PKB
Assign coordinators and any other requested users for teams. Client + PKB
Configure interface to always send one of the alias values from step 1. Client
Configure org and/or team alias options from admin GUI. PKB
Run UAT in sandbox. Client
Agree on alias values to send in MSH-4 in production. Client
Create teams (that align to aliases from step 7) in production. Client + PKB
Assign coordinators and any other requested users for teams. Client + PKB
Configure interface to always send one of the alias values from step 7. Client
Configure org and/or team alias options from admin GUI. PKB
Monitor interfaces to ensure no rejections due to aliases.