Connecting to PKB
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.