Appointment Partners

Existing behaviour

PKB already had a lightweight approach to managing the interaction between an appointment stored in PKB and a patient facing appointment management system that allowed a patient to manage (e.g. reschedule, cancel) that appointment.

See our Appointment URL Links page for more information.

This page outlines the new richer and more reliable user experience with appointment management partners.

Appointment Partners

In the first phase of upgrading our appointment partner functionality, PKB will:

• start tracking a management URL with each appointment

• provide a URL to our management partners to enable a reciprocal flow back to PKB from the partner

Prerequisites

1. Before an appointment partner can make use of this functionality, they must first be granted access credentials by PKB as part of our existing HL7 Partner process. This is a one-off configuration task.

2. For each shared customer (PKB organisation) that wishes to make use of this integration, the customer must confirm with PKB that they authorise the appointment partner to update their appointment data (e.g. by providing a management URL). PKB will then issue a textual alias to the appointment partner to capture the relationship between the partner and the customer.

Workflow

1. Whenever an appointment partner wishes to add or update a management URL to an appointment in PKB, they send a supported HL7 SIU message. This message must include the necessary information required to identify the appointment, along with a custom ZAP segment which contains the management URL. The HL7 logic for SIU update messages will ignore any additional fields not provided, as is currently the case. This means that the appointment partner can simply omit the key appointment details (e.g. start time, location) and PKB will not overwrite or delete these. The following information is required:

   1. MSH-4. This must contain the alias for the relevant customer. Our syntax requires this to be provided twice in the format: alias{alias} - see our HL7 Partner pages for more information.

   2. PID-3. This must contain the patient identifier (e.g. NHS number).

   3. PID-7. This should contain the patient's DOB to assist with our soft matching logic.

   4. SCH-1. This must contain the appointment placer ID, typically issued by the customer PAS, that uniquely identifies the appointment

   5. ZAP-1. The management URL for the appointment. This is a static URL, but it may contain static path or query parameters (e.g. both https://appointments-r-us.co.uk/manage/123 and https://appointments-r-us.co.uk/manage?123 are supported).

2. When a user wishes to amend an appointment from within PKB, we will redirect the user to the management URL, appending additional query parameters to the request. The additional parameters are:

   1. pkbCallback. This will contain a URL the partner should redirect users back to after they have finished managing their appointment. This is a static URL per appointment that may contain both path and query parameters.

   2. (Optional parameter) assertedLoginIdentity. For NHS SSO as per Single Sign On (SSO). This will be provided if possible to provide seamless login into the partner system.

   3. (Optional parameter) prompt. Again as per NHS SSO specification.

3. After the user has completed the management of the appointment in the partner system, the partner can redirect the user to the URL provided in the pkbCallback, appending the following parameters:

   1. (Optional parameter) assertedLoginIdentity. For NHS SSO as per Single Sign On (SSO). This should be provided if possible to provide seamless login for the user back into PKB.
      In case the user was redirected to the partner system with Single Sign On (SSO) or the user used NHS login on redirect to log into the partner system this parameter is mandatory.

      1. The text within the partner system for providing seamless login for the user back into PKB should be user-friendly and along the lines of ‘Back to Patients Know Best’ or “Return to Patients Know Best'

   2. (Optional parameter) prompt. Again as per NHS SSO specification.

4. Any updates to the appointment made by the partner should be sent on to PKB in the usual way (for example via the hospital Trust Integration Engine) so the appointment can be updated as quickly as possible in PKB so as not to confuse the end user. PKB may choose to notify the end user that changes may not appear instantly.

NOTE: Optional parameters are optional as a user flow might not be able to provide it, but they are mandatory to implement. So in case a user used some other way of authentication than NHS login, those parameters cannot be provided, but in every other case assertedLoginIdentity is mandatory the rest needs to be provided according to Single Sign On (SSO) specification.

Workflows which will have to be witness tested

1. User is redirected to partner system without Single Sign On (SSO) information, as it is not available, user logs into partner system using something else other than NHS login. User finishes work in the partner system, user can be correctly redirected to PKB. User might have to re-login to PKB.

2. User is redirected to partner system without Single Sign On (SSO) information, as it is not available, user logs into partner system using NHS login. User finishes work in the partner system, user can be correctly redirected to PKB with necessary information for Single Sign On (SSO). User automatically logged into PKB with Single Sign On (SSO). Either every browser cookie or at least the PKB related ones needs to be manually cleared before redirecting the user back to PKB otherwise it might not show Single Sign On (SSO) flow.

3. User is redirected to partner system with Single Sign On (SSO) information, user automatically logged into partner system using Single Sign On (SSO). User finishes work in the partner system, user can be correctly redirected to PKB with necessary information for Single Sign On (SSO). User automatically logged into PKB with Single Sign On (SSO). Either every browser cookie or at least the PKB related ones needs to be manually cleared before redirecting the user back to PKB otherwise it might not show Single Sign On (SSO) flow.

   1. pkbCallback provided by PKB contains no query parameters, Single Sign On (SSO) parameters appended correctly

   2. pkbCallback provided by PKB contains query parameters, Single Sign On (SSO) parameters appended correctly retaining existing query parameters

4. User was redirected to partner system successfully for a given appointment. User finished work and logged out. Later user logs into partner system, no PKB login or redirection this time, checks the same appointment as the user was redirected to earlier, on the same screen where otherwise the redirect button to PKB would be shown, no redirect button is present.

Examples (with dummy values)

1. The partner sends an SIU_14 message to notify PKB of the management URL

MSH|^~\&|app|alias_123{alias_123}|HL7API|PKB|202204051011||SIU^S14|id.123|P|2.8

PID|||9999999999^^^NHS^NH||||20200101

SCH|ID123

ZAP|https://appointments-r-us.co.uk/manage/123

2A. User viewing appointment in PKB through the NHS App decides to amend appointment

We generate a new NHS SSO token as per Single Sign On (SSO) and append that and our callback URL parameters, and then redirect the user to the generated URL.

https://appointments-r-us.co.uk/manage/123?pkbCallback=X&assertedLoginIdentity=Y&prompt=Z

Or with dummy values provided instead of X, Y and Z:

https://appointments-r-us.co.uk/manage/123?pkbCallback=https%3A%2F%2Fmy.patientsknowbest.com%2Fpatient%2F1234%2Fappointment%2F5485&assertedLoginIdentity=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkdW1teW5oc3NzbyI6ImRhdGEifQ.b1cblYoJ-M1kY_3ydWpgRGUMlCxPpDbEjekNABFtGds&prompt=none

Please note the prompt parameter may not be provided.

2B. User viewing appointment signed directly into PKB without NHS authentication

The assertedLoginIdentity is irrelevant in this case. We add our callback URL parameter and redirect the user to the generated URL. Please see https://pkbdev.atlassian.net/wiki/spaces/api/pages/3363307576 for some examples of how a partner may choose to authenticate the redirected user without NHS SSO.

https://appointments-r-us.co.uk/manage/123?pkbCallback=X

Or with dummy values provided instead of X, Y and Z:

https://appointments-r-us.co.uk/manage/123?pkbCallback=https%3A%2F%2Fmy.patientsknowbest.com%2Fpatient%2F1234%2Fappointment%2F5485

3A. User finishes managing appointment with partner through the NHS App

End user has finished managing the appointment. Partner generates a new NHS SSO token as per Single Sign On (SSO) and appends that and optionally the prompt parameter to the pkbCallback URL received in the request. End user is then redirected to the generated URL. Note it is important the SSO parameters are correctly appended with either ? or & depending on if the pkbCallback URL contains existing query parameters.

https://my.patientsknowbest.com/patient/1234/appointment/5485?assertedLoginIdentity=Y&prompt=Z

3B. User logged in directly to partner finishes managing appointment without NHS authentication

End user has finished managing the appointment. The assertedLoginIdentity is irrelevant in this case. Partner should redirect the end user to the pkbCallback URL.

https://my.patientsknowbest.com/patient/1234/appointment/5485

Web UI changes

PKB will upgrade our web interface so that appointments which have had a management URL provided will display an additional "Manage" option. When a patient clicks on this option they will be redirected to the appointment partner's management interface to interact with their appointment.

Open

When the patient has “managed” their appointment in the partner’s appointment system they will have the option to return to PKB, on doing so the following information message will be displayed at the top of the page which they left i.e. the appointment overview page or a specific appointment page.

Open

PKB customer sites: deploy | developer | information governance | procurement | manual