NHS Booking and Referral Standard

Environments

BaRS Sandbox is available from the BaRS API specification. It demonstrates key functionality without the overhead of security requirements, giving developers the opportunity to understand the product before progressing development.

BaRS Integration (INT) is a live-like environment for suppliers progressing with development and testing to use. To use INT, you will need to follow the instructions to Connect as a sender or Connect as a receiver.

BaRS Production (PROD) is the live environment. Suppliers will need to have progressed through assurance before applying to connect to the PROD environment.

Path-to-Live has full details of all available testing environments and the functionality they offer.

Connecting to environments

In each BaRS workflow there are two roles: Sender and Receiver. In applications with response workflows, both parties act as a Sender and a Receiver, and will need to follow the instructions to connect to environments as both.

The Sender obtains a token from the API-M platform to make requests of the BaRS API Proxy, which brokers the request through the Receiver, secured via TLS-MA (Transport Layer Security-Mutual Authentication).

BaRS is based on internet-first principles and there is no requirement for Health and Social Care Network (HSCN) connectivity.

Connect as a sender

APIM provides the security model for BaRS.

To connect to the BaRS proxy as a sender follow these steps:

Step 1: follow the NHS Developer authentication and authorisation process NHS Developer authentication and authorisation

Step 2: trust the Certificate Authorities (CA) mentioned below. For INT this will be downloadable from http://pki.nhs.uk/int/G2/auth/NHSINTAuthG2.crt ( you can examine the .cer file if you have one )

openssl x509 -in barsintreceiver.cer -text -noout

Step 3: The above steps enables access to the APIM platform. To authorise the access to the BaRS Proxy (which is hosted on the APIM Platform), you must provide the following to the BaRS Team (via email england.bookingandreferralstandard@nhs.net):

• App Name*
• App ID (PROD)*
• App ID (INT) (both App IDs are needed to connect to PROD)*
• App Description*
• Name of the Organisation
• ODS code of the Organisation
• Product Name (as stated in the SCAL or TCC)
• JWKS resource URL (if self hosting)
• KID for JWKS (if APIM host and defined in earlier steps)
• Public key (if APIM host and generated in earlier steps)

The starred (*) items can be found by logging into the Digital Onboarding Service and selecting 'Environment access' under the Introduction and onboarding section.

Connect as a receiver

BaRS uses TLS-MA to communicate with Receiving endpoints. Receiving endpoints need a certificate under the NHS Root CA to facilitate TLS-MA. The receiver needs to follow these steps to access Integration (INT) and Production (PROD) environments.

How to connect to the BaRS proxy as a Receiver:

Step 1: Apply for your domain apply for a new nhs.uk domain. You must complete Section 5: For domain names visible only on the public internet

Step 2: Request a certificate under the NHS Root CA. The FQDN must be an nhs.uk address. There are different certificate chains for INT and PROD:

• INT Certificate chains (Note: these may be out of date)
• PROD Certificate chains (Note: these may be out of date)

Your domain must be registered before you begin the process to obtain your certificate generating a certificate request. The fully qualified domain name (FQDN) is equal to the certificate name (CN) by convention.

Step 3: Create a Certificate Signing Request (*.csr). This is the file you will send to us so we can generate a signed certificate for your endpoints. Create a private key; a password is optional.

openssl genpkey -algorithm RSA -out private.key -aes256

Create the *.csr, use the following command:

openssl req -new -key private.key -out request.csr

Note: Generate the CSR with only the common name field populated, which must match the FQDN. All other fields can remain blank. The email field MUST be blank. Please note FQDNs MUST be in the .nhs.uk domain as we can only issue certificates in this domain.

Step 4: Send the .csr file to be signed by NHS England and get the client certificate. To do this, follow these environment specific steps:

Client certificate: Integration (INT)

Step 1: Contact ITOC to make a Combined endpoint and service registration request

In the form:

• Select Create/renew a certificate only (No endpoint)
• Specify Integration environment
• FQDN must match your domain and CN on the cert e.g. 'BaRS-INT-<ODS Code>.<Supplier name>.thirdparty.nhs.uk'
• In "Additional comments/notes" state ‘BaRS’ certificate request *Add ‘N/A’ in the "Existing party key" field because there is no relation to SDS endpoints.

Step 2: Receive certificate from ITOC

Step 3: Email england.bookingandreferralstandard@nhs.net with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue

Client certificate: Production (PROD)

Production endpoints can only be requested when Solution Assurance issue the supplier with the Technical Conformance certificate

Step 1: Send the .csr to dir@nhs.net, indicating this is for a BaRS Receiver endpoint

Formats for FQDN on PROD:

• Supplier hosted (multi-tenanted) solutions ‘BaRS-PROD-<ODS Code>.<Supplier name>.thirdparty.nhs.uk’

• Service Provider hosted (on-premise) solutions ‘BaRS-PROD-<ODS Code>.<Provider name>.nhs.uk’

Step 2: Receive certificate from DIR Team

Step 3: Email england.bookingandreferralstandard@nhs.net with Receiver URL for BaRS/API-M to add to the Endpoint Catalogue

Step 4: Make changes to your firewall exceptions to receive messages from the BaRS proxy.

Installing and configuring your application to use the certificate

Step 1: INT and PROD copy the cert text including -----BEGIN CERTIFICATE as the first line and END CERTIFICATE----- as the last. Save this text locally as a file called barsinreceiver.cer (change the name to suit).

Step 2: Create a .pfx file so you can serve HTTPS (TLS) endpoints. You can use the command below to export a *.pfx file from the *.key file you made earlier (when you made the *.csr file) along with the *.cer file you were emailed.

openssl pkcs12 -export -out barsintreceiver.pfx -inkey barsintreceiver.key -in barsintreceiver.cer

Step 3: Create a password for your .pfx file.

Step 4: Make configuration changes to reference the *.pfx file and password

(C# example, Other languages will vary but be similar)

// Configure Kestrel to use the certificate
builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenAnyIP(8080, listenOptions =>
    {
        listenOptions.UseHttps(certPath, certPassword);
    });
});

TKW

What is TKW?

TKW - Toolkit Workbench - is a tool to assist development and assurance of supplier solutions to meet BaRS (Booking and Referral Standard) requirements.

The tool supports testing of key high-level workflows e.g. a booking routine, including some asynchronous ones, and is also capable of inspecting low level technical requirements. It reports the output in Validation Reports which indicate where and why a test has failed. In addition, it supports consistent error states which are often difficult to create but are required for development and assurance.

The BaRS TKW tooling is embedded into the INT environment, encompassing all the same end-to-end BaRS infrastructure that is mirrored in Production, rather than being downloaded and used in isolation. This ensures the same steps to deploy solutions to Production are followed during deployment to INT, and allowing testing of requests/responses to occur under Production-like conditions. Similarly, we're able to incorporate other key components, similar to those used in Production workflows, such as the UserTest Directory of Services (DoS). In the current BaRS Applications, the TKW tool relies on values in the UserTest DoS to elicit particular behavioural responses. The Sender will populate what are termed 'sentinel' values, such as the NHSD-Target-Identifier, with a particular value and TKW will respond with a certain Capability Statement, MessageDefinition etc. (See the 'Scenarios' section for detail).

It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Using TKW Portal

Suppliers must register a Portal account to start working with TKW but Senders and Receivers will use the tool in slightly different ways due to the nature of the requests/responses they require. Senders, needing somewhere to send requests and Receivers needing something to make requests of their solution.

During the registration process, the 'Target Identifier' and 'ODS Code' values are important to ensure requests are sent and received appropriately. As a Sender (to TKW), the HTTP Header NHSD-End-User-Organisation must include the ODS Code they registered with because TKW will collate requests based on this value. When reports are downloaded and viewed, only requests with that specific ODS Code in the header will be visible. As a Receiver, once logged into the portal and selecting the request(s) TKW is required to make of your endpoint, they will be directed to the Target Identifier registered against and, equally, downloaded reports will only relate to that specific value.

• Navigate to https://maitportal.testlab.nhs.uk/
• Click Register and complete the form below

• Email bookingandreferralstandard@nhs.net for a Target Identifier (this represents you on the Endpoint Catalogue)
• MAIT Team will need enable your account, email bookingandreferralstandard@nhs.net to advise this has been created
• Verify the account via email
• Configure Multi-Factor Authentication
• Access Portal Home screen

Sender

Once registered, requests can be made of TKW in any given workflow e.g. booking, validation etc. and the tool will record and provide downloadable validation reports for each request made.

The Scenarios (including Stateful Scenarios) outlined below highlight how to elicit particular behaviour required, note the specific sentinel values for NHSD-Target-Identifier and patient NHS Number. As a Sender, the various requests can be made and TKW will repond accoridngly.

NB: It is important for Senders to remember TKW is a stateless receiver and is not checking the relationship between requests (except in a handful of stateful scenarios - outlined below). This is important when developing workflows such as linking a booking and referral and transactional Integrity.

Receiver

A receiver can access the portal (once registered) to send either individual tests or an entire suite of tests to themselves. From the top menu bar, click 'Receive Requests' and the screen below will present -

The receiver selects the request they wish the TKW to make of their endpoint and clicks 'Execute Selected Tests' (bottom of the page). TKW will indicate when the requests have been processed.

Once all requested tests have been completed, the Validation Report can be downloaded -

• from the top menu, select 'Download Reports'
• then click on the button 'Download Reports' (this packages the report and makes it available to download locally)
• from the top menu, select 'Receiver Reports'
• click on the hyperlink of the required report to download locally (.zip format)

Scenarios

The TKW will respond to the scenarios outlined below. It does not hold the state of any prior request (unless specified in the Stateful scenarios) and the specific 'sentinel' values (in bold) must be used to elicit the required response where stated.

NB: where 'Any' NHSD-Target-Identifier is specified, only those highlighted in "UserTest DoS Services" table below will work for TKW.

NB: the endpoints for TKW are case sensitive eg use the following /metadata /MessageDefinition /$process-message /Slot /Appointment /ServiceRequest

Headers

The follow is a list of headers needed for the requests, these follow the pattern needed by BARS as follows Headers

        bash
        curl --location 'https://int.api.service.nhs.uk/booking-and-referral/FHIR/R4/metadata' \
        --header 'X-Request-Id: 99672436-ae1e-42e4-81a6-5a298563ccfa' \
        --header 'X-Correlation-Id: f44f6c3c-fdd5-4c8c-a091-d825eca1d763' \
        --header 'NHSD-Target-Identifier: eyJzeXN0ZW0iOiJodHRwczovL2ZoaXIubmhzLnVrL0lkL2Rvcy1zZXJ2aWNlLWlkIiwidmFsdWUiOiIyMDAwMDcyNDg5In0=' \
        --header 'NHSD-End-User-Organisation: ewogICJyZXNvdXJjZVR5cGUiOiAiT3JnYW5pemF0aW9uIiwKICAiaWRlbnRpZmllciI6IFsKICAgIHsKICAgICAgInZhbHVlIjogIldBU1AiLAogICAgICAic3lzdGVtIjogImh0dHBzOi8vZmhpci5uaHMudWsvSWQvb2RzLW9yZ2FuaXphdGlvbi1jb2RlIgogICAgfQogIF0sCiAgIm5hbWUiOiAiTXkgc2VydmljZSBwcm92aWRlciBuYW1lIgp9' \
        --header 'Authorization: Bearer yourBearerToken'
    

Capability

MessageDef

Booking

Referral

Validation

Response

UserTest DoS Services

The sentinel values linked to UserTest DoS services can be found by searching with the following criteria.

INT Test Patient (traceable on SPINE)

The patient.Identifier sentinel values used to trigger Scenarios in TKW can be found on the INT Spine. The full patient details are outlined below.

Stateful Scenarios

TKW supports a limited stateful response for 111 to ED requests. This is a simulation of the real-world receiving end-point and mimics the expected behaviour of a Reciever solution.

This stateful behaviour is only demonstrated for a specific patient (NHS Number 9707606312) and per NHSD-End-User-Organisation - i.e. state will be persisted only between requests made by the same End User Organisation.

Note The stateful server will reset each night which will return all users back to the initial state.

State Transition Table indicating the responses the stateful TKW scenarios will support and the expected responses-