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 decryption access 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:

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:

• 1. Agree on alias values to send in MSH-4 in sandbox. Client

  2. Create teams (that align to aliases from step 1) in Sandbox. Client + PKB

  3. Assign coordinators and any other requested users for teams. Client + PKB

  4. Configure interface to always send one of the alias values from step 1. Client

  5. Configure org and/or team alias options from admin GUI. PKB

  6. Run UAT in sandbox. Client

  7. Agree on alias values to send in MSH-4 in production. Client

  8. Create teams (that align to aliases from step 7) in production. Client + PKB

  9. Assign coordinators and any other requested users for teams. Client + PKB

  10. Configure interface to always send one of the alias values from step 7. Client

  11. Configure org and/or team alias options from admin GUI. PKB

  12. Monitor interfaces to ensure no rejections due to aliases.