Developer documentation‎ > ‎HL7 API‎ > ‎

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

PKB has two test environments available for you to develop against. The configuration details for each can be found in the WSDL, which you can use to automatically configure your connection if supported by your toolset.
There is an alternative URL for the N3 sandbox environment if you need to access it from the public internet during your testing; but we can provide better support for the public sandbox environment generally, so use that if you can.

Whichever test environment you choose, we will need to set up a test PKB Organisation for you before you can start sending HL7 messages.

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 URL. The URL for each of the two test environments is as follows:
  • https://sandbox.patientsknowbest.com:7443/services/hl7
  • https://n3sandbox.patientsknowbest.thirdparty.nhs.uk:7444/services/hl7
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 for content:

<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

Default Teams

All patients need to be created into a PKB Team.

Since your HL7 credentials represent your PKB Organisation, then the client should decide which PKB Team patients created via HL7 API interface should be placed in.

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, if you need to create a patient into a PKB Team other than your default, you will need this functionality. 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, you can only send a message as a PKB Team within your own PKB Organisation (or, although less common, you could connect as a PKB Team and send a message on behalf of your PKB Organisation). However, you cannot yet send a message on behalf of another PKB Organisation entirely.

Note: Once an alias has been configured, you will be required to provide an alias on every call. So for example, if you occasionally need to send a message using an alias for a PKB Team, but the rest as your PKB Organisation, then you will need 2 aliases - one for the PKB Team and one for the PKB Organisation.

Aliases are not case sensitive.


PKB Aliasing Checklist:
  1. Agree on alias values to send in MSH-4 in sandbox as outlined here. 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. b
Comments