diff --git a/BaRS-Images/SequenceDiagrams/BaRS_StandardPattern_Cancellation_Find_Id.svg b/BaRS-Images/SequenceDiagrams/BaRS_StandardPattern_Cancellation_Find_Id.svg new file mode 100644 index 00000000..f4152b9e --- /dev/null +++ b/BaRS-Images/SequenceDiagrams/BaRS_StandardPattern_Cancellation_Find_Id.svg @@ -0,0 +1,4 @@ + + + +
User
Sender
BaRS Proxy
Endpoint
Receiver
User
Sender
BaRS Proxy
Endpoint
Receiver
with ID
Find Patients Appointments
Get Appointment/ServiceRequest (ID)
Get Appointment/ServiceRequest (ID)
Appointment/ServiceRequest resource
Find Endpoint
Endpoint
Appointment/ServiceRequest resource
Show Appointments
Alt: with NHS No.
Get Appointment(s)/ServiceRequest(s) (NHS No.)
Get Appointment(s)/ServiceRequest(s) (NHS No.)
Appointment(s)/ServiceRequest (s) bundle
Find Endpoint
Endpoint
Appointment(s)/ServiceRequest (s) bundle
Alt: with patient demographics
Get Appointment(s)/ServiceRequest(s) (Name, DoB and/or Postcode)
Get Appointment(s)/ServiceRequest(s) (Name, DoB and/or Postcode)
Appointment(s)/ServiceRequest (s) bundle
Find Endpoint
Endpoint
Appointment(s)/ServiceRequest (s) bundle
Continue Cancellation workflow as outlined for use-case
\ No newline at end of file diff --git a/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg b/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg index c4a1816b..32ba26c4 100644 --- a/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg +++ b/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg @@ -1,4 +1,4 @@ - + -

Receiver Accepts message
Receiver Accepts mes...
Sender Sends Message
Sender Sends Message
Processing begins
Processing begins
Connection Timeout
Connection Timeout
Processing Fails
4xx/5xx
Processing Fails...
Await response
Await response
Wait
Wait
Timeout Received
Timeout Received
Resend
Resend
Apply Transaction Integrity rules
Apply Transaction In...
Reject w/425(Too Early)
Reject w/425(Too Ear...
Wait
Wait
Unconfirmed
Unconfirmed
Receiver
Receiver
Sender
Sender
409 Response
409 Respon...
Resend
Resend
Failure Confirmed
Failure Confirmed
Apply Transaction Integrity rules
Apply Transaction In...
Reject with original 4xx/5xx
Reject with original...
425 Response
425 Response
Text is not SVG - cannot display
\ No newline at end of file +

Receiver Accepts message
Sender Sends Message
Processing begins
Connection Timeout
Processing Fails
4xx/5xx
Await response
Wait
Timeout Received
Resend
Apply Transaction Integrity rules
Reject w/425(Too Early)
Wait
Unconfirmed
Receiver
Sender
408 Response
Resend
Failure Confirmed
Apply Transaction Integrity rules
Reject with original 4xx/5xx
425 Response
\ No newline at end of file diff --git a/BaRS-Images/WorkFlows/CADCallAssist-1.0.2.svg b/BaRS-Images/WorkFlows/CADCallAssist-1.0.2.svg new file mode 100644 index 00000000..4a0d5309 --- /dev/null +++ b/BaRS-Images/WorkFlows/CADCallAssist-1.0.2.svg @@ -0,0 +1,4 @@ + + + +

CAD to CAD Simplified Workflow - Use Case: Call Assist Request

Supporting 999 AST
National Telephony
                                                 Home 999 AST
Route to Home Trust
Record Demographics
Complete 999 Triage
Confirm Location
BT EISEC
Create case
Receive Call
Pre Triage Sieve
Reason for Call
Pre alert
Record Nature of Call
New Workflow
Existing Workflow
Pre alert
Pre alert
No
Update Transfer details
Business
Ack HTTP
Response
Receive acknowledgment
BaRS HTTP
Response
BaRS Update
BaRS HTTP
Response
Process case update
Business Ack
- Action
Triggered
Acknowledge receipt of update
Manage stack
Continue Updates
Yes
Create case
Request Assistance
BaRS
Referral
Close case
End
Continue Updates
No
Receive acknowledgment
Update MDT
Dispatch resource
Business
Ack HTTP
Response
Business Ack
- Action
Triggered
Scene safety update
Yes 
Update Location detaIs
Update demographics
Update triage
Acknowledge receipt of case
Call Assist Required
Identify Supporting Trust
Yes
Review Request
Accepted
Rejected
Review Response
End
Transfer Case
BAU flow
No
Receive Response
Home Trust available?
No
Yes
Out of Area workflow
BaRS
Response
Send Response
Update Case
BaRS
Referral
BaRS HTTP
Response
BaRS HTTP
Response
BAU
Process
\ No newline at end of file diff --git a/BaRS-Images/WorkFlows/CADMutualAid-1.0.2.svg b/BaRS-Images/WorkFlows/CADMutualAid-1.0.2.svg new file mode 100644 index 00000000..46239ab3 --- /dev/null +++ b/BaRS-Images/WorkFlows/CADMutualAid-1.0.2.svg @@ -0,0 +1,4 @@ + + + +

CAD to CAD Simplified Workflow - Use Case: Mutual Aid Request

Supporting 999 AST
National Telephony
                                                 Home 999 AST
Route to Home Trust
Record Demographics
Complete 999 Triage
Confirm Location
BT EISEC
Create case
Receive Call
Pre Triage Sieve
Reason for Call
Pre alert
Record Nature of Call
New Workflow
Existing Workflow
Pre alert
Pre alert
Update Transfer details
Business
Ack HTTP
Response
Receive acknowledgment
BaRS HTTP
Response
BaRS Update
BaRS HTTP
Response
Process case update
Business Ack
- Action
Triggered
Acknowledge receipt of update
Manage stack
Continue Updates
Yes
Create case
Request Mutual Aid
BaRS
Referral
Manage stack
Continue Updates
Receive acknowledgment
Update MDT
Dispatch resource
Business
Ack HTTP
Response
Business Ack
- Action
Triggered
Scene safety update
Yes 
Update Location detaIs
Update demographics
Update triage
Acknowledge receipt of case
Mutual Aid Required?
Identify Supporting Trust
Yes
Review Request
Accepted
Rejected
Review Response
End
Share Case
BAU flow
No
Update MDT
Dispatch resource
BaRS HTTP
Response
Receive Response
Home Trust available?
No
Yes
Out of area workflow
BaRS Response
Send Response
Update Case
BaRS Referral
BaRS HTTP
Response
BAU
Process
\ No newline at end of file diff --git a/BaRS-Images/WorkFlows/CADOutOfArea-1.0.2.svg b/BaRS-Images/WorkFlows/CADOutOfArea-1.0.2.svg new file mode 100644 index 00000000..140734d3 --- /dev/null +++ b/BaRS-Images/WorkFlows/CADOutOfArea-1.0.2.svg @@ -0,0 +1,4 @@ + + + +

CAD to CAD Simplified Workflow - Use Case: Out of Area Referral (including IRP routed calls)

No
No
Update Transfer details
Scene safety update
Business
Ack HTTP
Response
Receive acknowledgment
BaRS HTTP
Response
BaRS Update
BaRS HTTP
Response
Yes 
Acknowledge receipt of case
Process case update
Business Ack
- Action
Triggered
Acknowledge receipt of update
Manage stack
Update demographics
Update triage
Update Location detaIs
Continue Updates
Yes
Suitable for dispatch
Suitable for Validation?
No
Yes
Yes
Home 999 AST
Suitable for Referral to CAS?
National Telephony
                                                 Receiving 999 AST
Route to available Trust
Record Demographics
Complete 999 Triage
Confirm Location
BT EISEC
Create case
Receive Call
Create case
Identify Home Trust
Transfer Case
BaRS Referral
Pre Triage Sieve
Reason for Call
Pre alert
Record Nature of Call
New Workflow
Existing BaRS Workflow
Close case
Continue Updates
No
Receive acknowledgment
Update MDT
Dispatch resource
Send for Validation
Refer to CAS
Existing Workflow
Pre alert
Business
Ack HTTP
Response
Pre alert
Home Trust available?
Yes
No
BAU workflow
Business Ack
- Action
Triggered
\ No newline at end of file diff --git a/CodeSystem/agency-types-bars.xml b/CodeSystem/agency-types-bars.xml new file mode 100644 index 00000000..97df43ca --- /dev/null +++ b/CodeSystem/agency-types-bars.xml @@ -0,0 +1,58 @@ + + + + + + + + + + + <status value="active" /> + <date value="2025-06-03" /> + <publisher value="NHS England" /> + <contact> + <name value="NHS England" /> + <telecom> + <system value="email" /> + <value value="england.interoperabilityteam@nhs.net" /> + <use value="work" /> + </telecom> + </contact> + <description value="Agency Types in BaRS" /> + <copyright value="Copyright © 2025 NHS England" /> + <caseSensitive value="true" /> + <content value="complete" /> + <concept> + <code value="CI" /> + <display value="Coastguard" /> + </concept> + <concept> + <code value="DI" /> + <display value="Doctor" /> + </concept> + <concept> + <code value="FI" /> + <display value="Fire service" /> + </concept> + <concept> + <code value="FHI" /> + <display value="Full Hazardous Area Response Team" /> + </concept> + <concept> + <code value="RI" /> + <display value="Hazardous Area Response Team" /> + </concept> + <concept> + <code value="HI" /> + <display value="Hospital" /> + </concept> + <concept> + <code value="PI" /> + <display value="Police" /> + </concept> + <concept> + <code value="OSI" /> + <display value="Other service" /> + </concept> +</CodeSystem> \ No newline at end of file diff --git a/Examples/REFRESP02- Referral Service Request Reponse Short - CAD Mutual Aid Rejection.xml b/Examples/REFRESP02- Referral Service Request Reponse Short - CAD Mutual Aid Rejection.xml index bd237259..6d7b325c 100644 --- a/Examples/REFRESP02- Referral Service Request Reponse Short - CAD Mutual Aid Rejection.xml +++ b/Examples/REFRESP02- Referral Service Request Reponse Short - CAD Mutual Aid Rejection.xml @@ -62,8 +62,8 @@ <code value="ok" /> </response> <focus> - <!-- ServiceRequest --> - <reference value="urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c" /> + <!-- Receiver Encounter --> + <reference value="urn:uuid:eba5ef44-5fdc-4d4f-b025-24db80e9b906" /> </focus> <definition value="https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-response-short" /> </MessageHeader> @@ -166,7 +166,7 @@ <profile value="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Encounter" /> </meta> <identifier> - <system value="https://sender.url/Id/case-number" /> + <system value="https://receiver.url/Id/case-number" /> <!-- Set by the receiver who is passing the business case number value --> <value value="reciever1234" /> </identifier> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/About-BaRS.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/About-BaRS.page.md index c80aa070..0ec91f08 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/About-BaRS.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/About-BaRS.page.md @@ -26,7 +26,7 @@ The workflow and payload elements can be predefined or completely dynamic, enabl The documentation for BaRS is separated into three groups (or "products"): -- {{pagelink:design-core-1.0.6}} is the foundation containing all the things *everyone* has to do regardless of what flows BaRS is being used to support +- {{pagelink:design-core-1.0.7}} is the foundation containing all the things *everyone* has to do regardless of what flows BaRS is being used to support - {{pagelink:Applications}}, *apply* the standard to a specific problem and build on this to support specific use cases diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/Quick-Start-Guide.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/Quick-Start-Guide.page.md index 6e0e5d7f..086e4033 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/Quick-Start-Guide.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/About-BaRS/Quick-Start-Guide.page.md @@ -6,7 +6,7 @@ Follow this **Quick Start Guide** to best understand how to approach BaRS: We recommend reading the following documentation as part of the discovery stage to inform planning: * {{pagelink:definitions_key_terms, text:Definition of key terms}} -* {{pagelink:design-core-1.0.6, text:BaRS Core}} +* {{pagelink:design-core-1.0.7, text:BaRS Core}} * {{pagelink:applications, text:BaRS Applications}} * [BaRS FHIR API specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) @@ -16,10 +16,10 @@ We recommend reading the following documentation as part of the discovery stage Full details of the security model adopted by the platform can be found under the [security](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) section. ### Design -The following sections provide the essential information needed to design and build a BaRS compliant solution. BaRS is devised in a way to support re-use of functionality across multiple uses cases, to this end the implementation guidance is split into {{pagelink:design-core-1.0.6, text:BaRS Core}} and {{pagelink:applications, text:BaRS Application}} sections. All solutions **must** build the Core and add the specific requirements of the Application to support the given use case. BaRS Core is not sufficient on its own, an Application will always be required. +The following sections provide the essential information needed to design and build a BaRS compliant solution. BaRS is devised in a way to support re-use of functionality across multiple uses cases, to this end the implementation guidance is split into {{pagelink:design-core-1.0.7, text:BaRS Core}} and {{pagelink:applications, text:BaRS Application}} sections. All solutions **must** build the Core and add the specific requirements of the Application to support the given use case. BaRS Core is not sufficient on its own, an Application will always be required. ### End-to-end workflow -When developing against the standard, understanding the {{pagelink:core-EndToEndWorkflow-1.0.6, text:end-to-end workflow}} is key. This section of the guide describes how a solution interacts with the BaRS API, along with the assumptions and expectations of Senders and Receivers. These are the roles suppliers will adopt when building a solution. This guide is written predominantly from the perspective of the request; the Sender and Receiver of the request. However, if the BaRS Application include a response workflow these roles swap, the Sender becoming the Receiver and vice versa. +When developing against the standard, understanding the {{pagelink:core-EndToEndWorkflow-1.0.7, text:end-to-end workflow}} is key. This section of the guide describes how a solution interacts with the BaRS API, along with the assumptions and expectations of Senders and Receivers. These are the roles suppliers will adopt when building a solution. This guide is written predominantly from the perspective of the request; the Sender and Receiver of the request. However, if the BaRS Application include a response workflow these roles swap, the Sender becoming the Receiver and vice versa. BaRS includes several {{pagelink:applications, text:BaRS Application (use cases)}}, each of which supports multiple use cases that share a common workflow and data model. @@ -28,15 +28,15 @@ BaRS includes several {{pagelink:applications, text:BaRS Application (use cases) The BaRS [API specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) provides detail of the structure of endpoints. The specification allows you to 'Try this API', calling endpoints to view anticipated responses. This is a purely technical document and must be read in conjunction with implementation guidance to build a compliant solution. ### Security -All {{pagelink:core-Security-1.0.6, text:security}} is provided through our platform. There are two methods for securing interactions via BaRS API: +All {{pagelink:core-Security-1.0.7, text:security}} is provided through our platform. There are two methods for securing interactions via BaRS API: * senders will [generate an access token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#how-this-pattern-works) from the platform and use this to authenticate with the BaRS API. Additionally, requests will include HTTP header values identifying the organisation, software and user, which are passed through the BaRS API to Receivers who apply their own access control to the request based on the headers content. * for Receivers accepting requests, the BaRS API secures the connection with the Receiver using Transport Layer Security Mutual Authentication (TLS MA), using an [NHS Root CA issued certificate](https://digital.nhs.uk/services/path-to-live-environments/live-environment#rootca-and-subca-certificates). The HTTP header values (as described above) are also passed through. This provides the Receiver with sufficient information to accept or reject the request without having to inspect the payload body. #### Error Handling -{{pagelink:core-ErrorHandling-1.0.6, text:Error handling}} is an important part of the standard for two key reasons: +{{pagelink:core-ErrorHandling-1.0.7, text:Error handling}} is an important part of the standard for two key reasons: * to ensure workflow is as smooth and seamless as possible, the error responses returned **must** be clear to allow the appropriate next action to take place, for example, to include a missing element of information (highlighted by the error response). -* there are several levels of interactions occurring from the Sender, through BaRS API to the Receiver and clearly identifying where the fault lies is important for swift resolution. All implementations **must** adhere to the {{pagelink:core-ErrorHandling-1.0.6, text:error handling guidance}} which is part of the {{pagelink:assure, text:assurance}} process. +* there are several levels of interactions occurring from the Sender, through BaRS API to the Receiver and clearly identifying where the fault lies is important for swift resolution. All implementations **must** adhere to the {{pagelink:core-ErrorHandling-1.0.7, text:error handling guidance}} which is part of the {{pagelink:assure, text:assurance}} process. ### Build #### Environments diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Current-Releases.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Current-Releases.page.md index ca675ca6..86179d39 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Current-Releases.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Current-Releases.page.md @@ -1,26 +1,26 @@ -## Current Release 1.8.2 +## Current Release 1.9.0 Product Link | Version | Handle | Phase | State | Release Date | Stability | Change Log Link -----------------------|---------|---------|----------|-----------------|--------------|------------|----------------- -Implementation Guide | 1.8.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-General}} +Implementation Guide | 1.9.0 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-General}} [FHIR Package](https://simplifier.net/packages/uk.nhsdigital.bars.r4/1.35.0) | 1.35.0| v1 | Live | Current Release | 01/04/2025 | Stable | -{{pagelink:design-core-1.1.6, text:BaRS Core}} | 1.1.6 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-core, text: BaRS Core Change Log}} -[API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0) | 1.1.0 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-api}} +{{pagelink:design-core-1.1.6, text:BaRS Core}} | 1.3.0 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-core, text: BaRS Core Change Log}} +[API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0) | 1.3.0 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-api}} {{pagelink: build-testing, text: TKW}} | 1.0.19 | v1 | Live | Current Release | 28/03/2025 | Stable |{{pagelink:trn-tkw}} -{{pagelink:application1, text:BaRS-APP1}} | 1.0.7 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app1,text:BaRS APP1 Change Log}} -{{pagelink:application2, text:BaRS-APP2}} | 1.0.7 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app2,text:BaRS APP2 Change Log}} -{{pagelink:application3, text:BaRS-APP3}} | 1.0.3 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app3,text:BaRS APP3 Change Log}} -{{pagelink:application4, text:BaRS-APP4}} | 1.2.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app4,text:BaRS APP4 Change Log}} -{{pagelink:application5, text:BaRS-APP5}} | 1.1.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app5,text:BaRS APP5 Change Log}} -{{pagelink:application6, text:BaRS-APP6}} | 1.0.0-beta.4 | beta | | Current Release | 01/04/2025 | Pre-Release |{{pagelink:trn-app6,text:BaRS APP6 Change Log}} -{{pagelink:application7, text:BaRS-APP7}} | 1.0.0-alpha.3 | alpha | | Current Release | 01/04/2025 | Pre-Release |{{pagelink:trn-app7,text:BaRS APP7 Change Log}} +{{pagelink:application1, text:BaRS-APP1}} | 1.0.8 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-app1,text:BaRS APP1 Change Log}} +{{pagelink:application2, text:BaRS-APP2}} | 1.0.8 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-app2,text:BaRS APP2 Change Log}} +{{pagelink:application3, text:BaRS-APP3}} | 1.0.4 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-app3,text:BaRS APP3 Change Log}} +{{pagelink:application4, text:BaRS-APP4}} | 1.2.3 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-app4,text:BaRS APP4 Change Log}} +{{pagelink:application5, text:BaRS-APP5}} | 1.1.3 | v1 | Live | Current Release | 02/07/2025 | Stable |{{pagelink:trn-app5,text:BaRS APP5 Change Log}} +{{pagelink:application6, text:BaRS-APP6}} | 1.0.0-beta.5 | beta | | Current Release | 02/07/2025 | Pre-Release |{{pagelink:trn-app6,text:BaRS APP6 Change Log}} +{{pagelink:application7, text:BaRS-APP7}} | 1.0.0-alpha.4 | alpha | | Current Release | 02/07/2025 | Pre-Release |{{pagelink:trn-app7,text:BaRS APP7 Change Log}} ### Overview of the release -Release 1.8.2 includes development of the {{pagelink:core-StandardPattern-appointment-1.1.6, text:Appointment Management Foundation}} guidance and supporting changes to the API specification. -There have been improvements to use-context HTTP header guidance and developer onboarding advice, alongside bug fixes and corrections throughout the guide. Application 5 TKW Receiver scenarios are now documented. +Release 1.9.0 includes development of the {{pagelink:, text:}} guidance and supporting changes to the cancellation workflows, introduces a search capability to the Implementation Guide and.... +There have been improvements Application 6 use-case descriptons alongside bug fixes and corrections throughout the guide. A clinical safety assessment of the scope of this release has determined that it has not significantly changed the clinical safety profile of the BaRS. No new hazards have been identified in this release. The latest version of the BaRS clinical safety case and hazard log can be downloaded from the <a href= "https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/onboarding-support-information#hazard-log-and-clinical-safety-case-report-cscr-" target="_blank"> BaRS FHIR API onboarding support information page </a>. @@ -63,6 +63,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 1 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 1 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 2 v1.0.1</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.1.0</a></td> @@ -83,6 +87,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 2 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 2 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 3 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -99,6 +107,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 3 v1.0.3</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 3 v1.0.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 4 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -115,6 +127,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 4 v1.2.2</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 4 v1.2.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 5 v1.0.0-beta.4</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -138,12 +154,16 @@ Table detailing active versions of the latest Applications in Production (or cur <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> <tr> - <td>Application 6 v1.0.0-beta.4</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 5 v1.1.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> </tr> <tr> - <td>Application 7 v1.0.0-alpha.3</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 6 v1.0.0-beta.5</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> + <tr> + <td>Application 7 v1.0.0-alpha.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">1.0.0</a></td> </tr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Previous-Releases.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Previous-Releases.page.md index 93288ce8..26c9c184 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Previous-Releases.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Previous-Releases.page.md @@ -1,5 +1,39 @@ ## {{page-title}} +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.8.2"> + +Product Link | Version | Handle | Phase | State | Release Date | Stability | Change Log Link +-----------------------|---------|---------|----------|-----------------|--------------|------------|----------------- +Implementation Guide | 1.8.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-General}} +[FHIR Package](https://simplifier.net/packages/uk.nhsdigital.bars.r4/1.35.0) | 1.35.0| v1 | Live | Current Release | 01/04/2025 | Stable | +{{pagelink:design-core-1.1.6, text:BaRS Core}} | 1.1.6 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-core, text: BaRS Core Change Log}} +[API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0) | 1.1.0 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-api}} +{{pagelink: build-testing, text: TKW}} | 1.0.19 | v1 | Live | Current Release | 28/03/2025 | Stable |{{pagelink:trn-tkw}} +{{pagelink:application1, text:BaRS-APP1}} | 1.0.7 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app1,text:BaRS APP1 Change Log}} +{{pagelink:application2, text:BaRS-APP2}} | 1.0.7 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app2,text:BaRS APP2 Change Log}} +{{pagelink:application3, text:BaRS-APP3}} | 1.0.3 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app3,text:BaRS APP3 Change Log}} +{{pagelink:application4, text:BaRS-APP4}} | 1.2.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app4,text:BaRS APP4 Change Log}} +{{pagelink:application5, text:BaRS-APP5}} | 1.1.2 | v1 | Live | Current Release | 01/04/2025 | Stable |{{pagelink:trn-app5,text:BaRS APP5 Change Log}} +{{pagelink:application6, text:BaRS-APP6}} | 1.0.0-beta.4 | beta | | Current Release | 01/04/2025 | Pre-Release |{{pagelink:trn-app6,text:BaRS APP6 Change Log}} +{{pagelink:application7, text:BaRS-APP7}} | 1.0.0-alpha.3 | alpha | | Current Release | 01/04/2025 | Pre-Release |{{pagelink:trn-app7,text:BaRS APP7 Change Log}} + + + +### Overview of the release + +Release 1.8.2 includes development of the {{pagelink:core-StandardPattern-appointment-1.1.6, text:Appointment Management Foundation}} guidance and supporting changes to the API specification. +There have been improvements to use-context HTTP header guidance and developer onboarding advice, alongside bug fixes and corrections throughout the guide. Application 5 TKW Receiver scenarios are now documented. + +A clinical safety assessment of the scope of this release has determined that it has not significantly changed the clinical safety profile of the BaRS. No new hazards have been identified in this release. The latest version of the BaRS clinical safety case and hazard log can be downloaded from the <a href= "https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/onboarding-support-information#hazard-log-and-clinical-safety-case-report-cscr-" target="_blank"> BaRS FHIR API onboarding support information page </a>. + +</div> +</div> + +<hr> + +<br> + <div class="bars-blg-expander"> <div class="bars-blg-expander-entry" id="v1.8.1"> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.6.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.6.page.md index 3d141d2c..1b092ffe 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.6.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.6.page.md @@ -2,13 +2,16 @@ topic: TRN-Core-1.0.6 --- +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.6"> + ## {{page-title}} | Change | Description | Impact | |------------------------------------------|----------------------------------------|---------------------------------| | Guidance on 'use-context' HTTP header updated | 'use-context' HTTP header is only require on write actions - POST, PUT and PATCH | <mark style="background-color: LightGreen">non-breaking</mark> | +</div> +</div> <br> <hr> - -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.7.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.7.page.md new file mode 100644 index 00000000..a00f36ea --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.0.7.page.md @@ -0,0 +1,14 @@ +--- +topic: TRN-Core-1.0.7 +--- + +## {{page-title}} + +| Change | Description | Impact | +|------------------------------------------|----------------------------------------|---------------------------------| +| ... | ...| <mark style="background-color: LightGreen">non-breaking</mark> | + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.1.6.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.1.6.page.md index 866c11b2..d387db31 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.1.6.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.1.6.page.md @@ -2,6 +2,9 @@ topic: TRN-Core-1.1.6 --- +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.1.6"> + ## {{page-title}} | Change | Description | Impact | @@ -9,5 +12,7 @@ topic: TRN-Core-1.1.6 | Guidance on 'use-context' HTTP header updated | 'use-context' HTTP header is only require on write actions - POST, PUT and PATCH | <mark style="background-color: LightGreen">non-breaking</mark> | | Standard Pattern - Appointments updated | Provided further guidance on how Appointments can be managed outside of BaRS Applications, in generic workflows. Added links to maintaining the Registry | <mark style="background-color: LightGreen">non-breaking</mark> | +</div> +</div> <br> <hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.2.2-alpha.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.2.2-alpha.page.md index 308d4a93..2242f590 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.2.2-alpha.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.2.2-alpha.page.md @@ -2,6 +2,10 @@ topic: TRN-Core-1.2.2 --- + +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.2.2-alpha"> + ## {{page-title}} | Change | Description | Impact | @@ -9,5 +13,7 @@ topic: TRN-Core-1.2.2 | Guidance on 'use-context' HTTP header updated | 'use-context' HTTP header is only require on write actions - POST, PUT and PATCH | <mark style="background-color: LightGreen">non-breaking</mark> | | Standard Pattern - Appointments updated | Provided further guidance on how Appointments can be managed outside of BaRS Applications, in generic workflows. Added links to maintaining the Registry | <mark style="background-color: LightGreen">non-breaking</mark> | +</div> +</div> <br> <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.3.0.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.3.0.page.md new file mode 100644 index 00000000..5d7fc13d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/1.3.0.page.md @@ -0,0 +1,15 @@ +--- +topic: TRN-Core-1.3.0 +--- + +## {{page-title}} + +| Change | Description | Impact | +|------------------------------------------|----------------------------------------|---------------------------------| +| ... | ... | <mark style="background-color: LightGreen">non-breaking</mark> | + + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/toc.yaml index b5da70f7..d081763b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/BaRS-Core/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.3.0 + filename: 1.3.0.page.md - name: 1.2.2-alpha filename: 1.2.2-alpha.page.md - name: 1.1.6 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.8.2.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.8.2.page.md index b8d60191..fb2fd592 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.8.2.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.8.2.page.md @@ -1,3 +1,5 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.8.2"> ### 1.8.2 ## Implementation Guide Changes @@ -11,7 +13,11 @@ | Remove references to CPCS | Remove references to CPCS and replaced with Primary Care to Community Pharmacy (Pharmacy First). The terminology changed from the Pharmacy First progamme. | | Updated DoS System references throughout | All reference to DoS System 'https://fhir.nhs.uk/CodeSystem/dos-id' in MessageDefinitions has been replaced with 'https://fhir.nhs.uk/Id/dos-service-id'. FHIR artefacts have also been updated. | +<p> +</div> +</div> + <br> <hr> -### Previous Releases + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.9.0.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.9.0.page.md new file mode 100644 index 00000000..a9d18c01 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/1.9.0.page.md @@ -0,0 +1,13 @@ +### 1.9.0 + +## Implementation Guide Changes + +| Change | Description | +|---------------------------------------|---------------------------------------------------------------------------------------------------------| +| Bug fixes and corrections |There have been several bug fixes and corrections in the guide, these includes typos, broken links or corrections.| + + +<br> +<hr> + +### Previous Releases diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/toc.yaml index d5acc0ed..e9d1f611 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/Implementation-Guide-Change-Log/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.9.0 + filename: 1.9.0.page.md - name: 1.8.2 filename: 1.8.2.page.md - name: 1.8.1 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.7.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.7.page.md index 2b75feeb..a46ae6e8 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.7.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.7.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.7"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.7. @@ -21,9 +24,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati |------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| | encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | - +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.8.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.8.page.md new file mode 100644 index 00000000..01d5aced --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/1.0.8.page.md @@ -0,0 +1,29 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.8. + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| Implementation Guidance updated | encounter.class.display value corrected from "Emergency" to "emergency" | <mark style="background-color: Yellow">correction</mark> | +|NHSD-Requesting-Practioner Examples updated | FHIRPractioner corrected to FHIRPractionerRole | <mark style="background-color: Yellow">correction</mark> | + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | + + + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/toc.yaml index d83e3c12..de7ce16d 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP1/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.0.8 + filename: 1.0.8.page.md - name: 1.0.7 filename: 1.0.7.page.md - name: 1.0.6 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.7.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.7.page.md index 2b75feeb..a46ae6e8 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.7.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.7.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.7"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.7. @@ -21,9 +24,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati |------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| | encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | - +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.8.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.8.page.md new file mode 100644 index 00000000..01d5aced --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/1.0.8.page.md @@ -0,0 +1,29 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.8. + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| Implementation Guidance updated | encounter.class.display value corrected from "Emergency" to "emergency" | <mark style="background-color: Yellow">correction</mark> | +|NHSD-Requesting-Practioner Examples updated | FHIRPractioner corrected to FHIRPractionerRole | <mark style="background-color: Yellow">correction</mark> | + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | + + + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/toc.yaml index d83e3c12..de7ce16d 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP2/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.0.8 + filename: 1.0.8.page.md - name: 1.0.7 filename: 1.0.7.page.md - name: 1.0.6 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.3.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.3.page.md index 4fce4dae..36c5ac0f 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.3.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.3.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.3"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.3. @@ -21,9 +24,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati |------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| | encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | - +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.4.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.4.page.md new file mode 100644 index 00000000..9332c743 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/1.0.4.page.md @@ -0,0 +1,26 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.4. + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| Implementation Guidance updated | patient.identifier.system Implementaton Guidance corrected | <mark style="background-color: Yellow">correction</mark> | + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| patient.identifier.system | | | Update | Referral Request |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/toc.yaml index 2e9b23dd..6bf30574 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP3/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.0.4 + filename: 1.0.4.page.md - name: 1.0.3 filename: 1.0.3.page.md - name: 1.0.2 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.2.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.2.page.md index b9723647..57de6092 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.2.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.2.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.2.2"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.2.2. @@ -23,8 +26,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati | encounter.class.display | | | Update | Interim Validation Response |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | | encounter.class.display | | | Update | Validation Response |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.3.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.3.page.md new file mode 100644 index 00000000..3c0083eb --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/1.2.3.page.md @@ -0,0 +1,30 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.2.3. + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| Implementation Guidance updated | patient.identifier.system Implementaton Guidance corrected | <mark style="background-color: Yellow">correction</mark> | + + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| patient.identifier.system | | | Update | Validation Request |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | +| patient.identifier.system | | | Update | Interim Validation Response |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | +| patient.identifier.system | | | Update | Validation Response |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | + + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/toc.yaml index 0fbc834b..7be019d6 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP4/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.2.3 + filename: 1.2.3.page.md - name: 1.2.2 filename: 1.2.2.page.md - name: 1.2.1 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.2.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.2.page.md index b3a03ee2..7facafb0 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.2.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.2.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.1.2"> + ## {{page-title}} <br> @@ -26,9 +29,11 @@ This stable release (v1.1.2) of Application 5 sees minor corrections. | Task.code.coding.display | Community Pharmacist Consultation Service for minor illness (procedure) | Referral to Community Pharmacy Pharmacy First Service (procedure) | Update | Referral Request |SNOMED Code changed | <mark style="background-color: LightGreen">non-breaking</mark> | | encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | +</div> +</div> <br> <hr> -### Previous Releases + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.3.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.3.page.md new file mode 100644 index 00000000..96e1ab04 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/1.1.3.page.md @@ -0,0 +1,34 @@ +## {{page-title}} + +<br> +This stable release (v1.1.3) of Application 5 sees minor corrections. +<br> + + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| SNOMED Code Updated | The SNOMED Code used to define a minor illness referral has been updated from '1577041000000100-Community Pharmacist Consultation Service for minor illness (procedure)' to '2140231000000104-Referral to Community Pharmacy Pharmacy First Service (procedure)', as requested by Pharmacy First Programme Clinical Lead | <mark style="background-color: Yellow">correction</mark> | +| Implementation Guidance updated | encounter.class.display value corrected from "Emergency" to "emergency" | <mark style="background-color: Yellow">correction</mark> | +|NHSD-Requesting-Practioner Examples updated | FHIRPractioner corrected to FHIRPractionerRole | <mark style="background-color: Yellow">correction</mark> | + + +### Payload Change Log + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| Task.code.coding.code | 1577041000000100 | 2140231000000104 | Update | Referral Request |SNOMED Code changed | <mark style="background-color: LightGreen">non-breaking</mark> | +| Task.code.coding.display | Community Pharmacist Consultation Service for minor illness (procedure) | Referral to Community Pharmacy Pharmacy First Service (procedure) | Update | Referral Request |SNOMED Code changed | <mark style="background-color: LightGreen">non-breaking</mark> | +| encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | + + +<br> +<hr> + +### Previous Releases + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/toc.yaml index deef9463..d0647b2d 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP5/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.1.3 + filename: 1.1.3.page.md - name: 1.1.2 filename: 1.1.2.page.md - name: 1.1.1 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.4.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.4.page.md index f5ed3303..832a55ee 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.4.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.4.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.0-beta.4"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.0-beta.4 @@ -21,8 +24,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati |------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| | encounter.class.display | | | Update | Referral Request |encounter.class.display value corrected from "Emergency" to "emergency" in Implementation Guidance | <mark style="background-color: Yellow">correction</mark> | +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.5.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.5.page.md new file mode 100644 index 00000000..5d768935 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/1.0.0-beta.5.page.md @@ -0,0 +1,28 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.0-beta.5 + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +| Implementation Guidance updated | patient.identifier.system Implementaton Guidance corrected | <mark style="background-color: Yellow">correction</mark> | + + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| patient.identifier.system | | | Update | Referral Request |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | +| patient.identifier.system | | | Update | Referral Response |patient.identifier.system Implementation Guidance value corrected from incorrect link text to This SHOULD be populated with the namespace for the Identifier | <mark style="background-color: Yellow">correction</mark> | + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/toc.yaml index f7c86099..e06e8918 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP6/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.0.0-beta.5 + filename: 1.0.0-beta.5.page.md - name: 1.0.0-beta.4 filename: 1.0.0-beta.4.page.md - name: 1.0.0-beta.3 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.3.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.3.page.md index 8d0fdfb5..8285327b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.3.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.3.page.md @@ -1,3 +1,6 @@ +<div class="bars-blg-expander"> +<div class="bars-blg-expander-entry" id="v1.0.0-alpha.3"> + ## {{page-title}} This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.0-alpha.3 @@ -20,9 +23,9 @@ This is a minor "patch" with clarifications to limited areas of the Implementati |------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| | | | | | | | | - +</div> +</div> <br> <hr> -### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.4.page.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.4.page.md new file mode 100644 index 00000000..80da906b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/1.0.0-alpha.4.page.md @@ -0,0 +1,28 @@ +## {{page-title}} +This is a minor "patch" with clarifications to limited areas of the Implementation Guidance and examples for v1.0.0-alpha.4 + +### Application Change Log + + +<br> + + +| Change | Description | Impact | +|-------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------| +|NHSD-Requesting-Practioner Examples updated | FHIRPractioner corrected to FHIRPractionerRole | <mark style="background-color: Yellow">correction</mark> | + + + +### Payload Change Log + + +| FHIR Element | Previous | Current | Other | Referral/Booking | Rationale | Impact | +|------------------------------------------------------|----------|------------|---------|------------------|-------------------------------------------------------------------------------------------------|----------| +| | | | | | | | + + + +<br> +<hr> + +### Previous Releases \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/toc.yaml index 4e7fc43e..c4747adc 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Releases/Technical-Release-Notes/TRN-APP7/toc.yaml @@ -1,5 +1,7 @@ - name: Index filename: Index.page.md +- name: 1.0.0-alpha.4 + filename: 1.0.0-alpha.4.page.md - name: 1.0.0-alpha.3 filename: 1.0.0-alpha.3.page.md - name: 1.0.0-alpha.2 diff --git a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Versioning.guide.md b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Versioning.guide.md index 57b62f67..088ab449 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Versioning.guide.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/About-BaRS/Versioning.guide.md @@ -24,7 +24,7 @@ The extensions ALPHA, BETA or RC (Release Candidate) will be used to indicate th An appreciation of the components involved in a released version must be understood when building solutions. These separate components come together under the umbrella of a given overall version but the components themselves are also versioned. This published implementation guide denotes the 'overall version' referenced. Components involved in an overall version:- -* **{{pagelink:design-core-1.0.6, text:Core}}**: BaRS Core components - API Spec, Endpoint Catalogue etc. +* **{{pagelink:design-core-1.0.7, text:Core}}**: BaRS Core components - API Spec, Endpoint Catalogue etc. * **[Package](https://simplifier.net/NHSBookingandReferrals/~packages)**: FHIR package * **{{pagelink:applications, text:Application}}**: the use cases i.e. '111 to ED' * **{{pagelink:fhir_assets, text:FHIR Assets}}**: MessageDefinitions and profiles diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Booking-Request-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Booking-Request-Payload.page.md index 1ff47ad3..f26c0deb 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Booking-Request-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Booking-Request-Payload.page.md @@ -29,6 +29,7 @@ This payload is used to support a booking workflow and contains all the required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -115,11 +116,11 @@ This payload is used to support a booking workflow and contains all the required | Appointment.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment | | Appointment.meta.lastupdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Appointment.status | This MUST be populated with 'booked' or 'cancelled' | MUST | 1..1 | booked | -| Appointent.serviceCategory | | | | | -| Appointent.serviceCategory.coding | BaRS Use Case | MUST | 0..* | | -| Appointent.serviceCategory.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/usecases-categories-bars | -| Appointent.serviceCategory.coding.code | This MUST be populated with Code for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | A1T1 | -| Appointent.serviceCategory.coding.display | This MUST be populated with Display for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | 111 - ED | +| Appointment.serviceCategory | | | | | +| Appointment.serviceCategory.coding | BaRS Use Case | MUST | 0..* | | +| Appointment.serviceCategory.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/usecases-categories-bars | +| Appointment.serviceCategory.coding.code | This MUST be populated with Code for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | A1T1 | +| Appointment.serviceCategory.coding.display | This MUST be populated with Display for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | 111 - ED | | Appointment.description | This SHOULD be populated. It is the human readable description of the booking | SHOULD | 0..1 | Reason for calling | | Appointment.start | This MUST be populated with the Start time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | | Appointment.end | This MUST be populated with the End time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/How-does-it-work.page.md index 1ba8ac30..f516e179 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/How-does-it-work.page.md @@ -13,7 +13,7 @@ To support the workflows for this Application of the standard the operations tha ### Make a Referral -Making a referral for this Application follows the {{pagelink:core-SPComposites-1.1.6, text:standard pattern for BaRS composite operations}}. +Making a referral for this Application follows the {{pagelink:core-SPComposites-1.3.0, text:standard pattern for BaRS composite operations}}. The message definition that defines this payload for this Application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}} @@ -86,9 +86,9 @@ X-Correlation-Id = <GUID_000002> ### Cancel a Referral -To cancel a referral this Application follows the {{pagelink:core-SPComposites-1.1.6, text:standard pattern for BaRS composite operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the referral from the **receiver** as it may have changed locally. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a referral this Application follows the {{pagelink:core-SPComposites-1.3.0, text:standard pattern for BaRS composite operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the referral from the **receiver** as it may have changed locally. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this Application is: {{link:messagedefinition-barsmessagedefinitionservicerequestrequestcancelled}} @@ -249,7 +249,7 @@ X-Correlation-Id = <GUID_00002> ### Make a booking -Making a booking for this Application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a booking for this Application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this Application is: [BARS Message Definition - Booking Request](https://simplifier.net/nhsbookingandreferrals/messagedefinition-bars-messagedefinition-booking-request) @@ -310,9 +310,9 @@ X-Correlation-Id = <GUID_00002> ``` ### Cancel a Booking -To cancel a booking this Application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the booking from the **receiver** as it may have changed locally. This is done by performing a "GET Appointment by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a booking this Application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the booking from the **receiver** as it may have changed locally. This is done by performing a "GET Appointment by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested Appointment resource which should be checked for its current status to ensure it does not already have a status of "cancelled". If not, this version of the Appointment should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested Appointment resource which should be checked for its current status to ensure it does not already have a status of "cancelled". If not, this version of the Appointment should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this Application is: [BARS Message Definition - Cancel Booking Request](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionbookingrequestcancelled) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Index.page.md index 589ee750..c8c6ac65 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Index.page.md @@ -19,9 +19,9 @@ topic: Application1 </thead> <tbody> <tr> - <td>Application 1 v1.0.7</td> + <td>Application 1 v1.0.8</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.0.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a></td> </tr> </tbody> @@ -53,7 +53,7 @@ This Application supports the use of the following use cases: ### Overview -This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.6, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. +This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.7, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. ### Data model endorsements diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Payloads.page.md index a4085a26..88987dcf 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Payloads.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Payloads.page.md @@ -6,7 +6,7 @@ topic: APP1-Payloads The specific guidance around the use of key FHIR resources is described below. ### MessageHeader Resource -{{pagelink:core-SPMessageHeader-1.1.6, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. The MessageHeader resource for the Booking Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'booking-request' @@ -27,7 +27,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars -). e.g. 111 - ED. 999 - UTC, CAS - SEDEC. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.6, text:use-case categories}} +). e.g. 111 - ED. 999 - UTC, CAS - SEDEC. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} An important function of the ServiceRequest resource is to link the booking and referral when they are related in a workflow. If the booking is successfully made before the referral, the Sender will have the *Appointment.Id* value (from the synchronous HTTP response) and this **must** be included as a relative reference, under *ServiceRequest.supportingInfo*, in the referral request. The element *ServiceRequest.supportingInfo* **may** also be used to provide reference to other resources in the request i.e. Rejected Services. This is outlined in the element guidance below. @@ -77,7 +77,7 @@ The extension *questionnaireresponse-reason* **must** be populated to indicate w Using a nested set of *questionnaireResponse.item*, *questionnaireResponse.linkId* and *questionnaireResponse.answer* complex structured data can be generated and processed, by the Sender and Receiver, respectively. The element guidance for this resource below goes into detail but, essentially, the *item* and *linkId* can be continually nested to convey various types of information. The *item* indicates a new element, *linkId* provide the number of elements (within the *item*) and *answer* contains any the value, supported by many different data types. ### Consent -In the BaRS UEC Applications the level of consent is stipulated to be for 'Direct Care' only. A referral **must** contain a Consent resource and it **must** adhere to the [example](https://simplifier.net/nhsbookingandreferrals/consent-example) provided under the BaRS FHIR assets. +In the BaRS UEC Applications the level of consent is stipulated to be for 'Direct Care' only. A referral **must** contain a Consent resource and it **must** adhere to the [example](https://simplifier.net/NHSBookingandReferrals/8fc39b95-89a6-45fb-914f-1458a10e9e14/~json) provided under the BaRS FHIR assets. <hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Payload.page.md index 87bec4ca..db06533b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Payload.page.md @@ -25,6 +25,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Response-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Response-Payload.page.md index d79a94fd..505d44f0 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Response-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Referral-Response-Payload.page.md @@ -25,6 +25,7 @@ Here is some placeholder text for the service request payload for this Applicati | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Scope-and-Requirements.page.md index 302d3737..fface84b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP1/Scope-and-Requirements.page.md @@ -87,8 +87,8 @@ The payloads and workflow have been designed to support these services. Other {{ * The booking Receiver **must** accept the booking request regardless of whether the patient is known to the service provider * The booking Receiver **must** accept potential patients who do **<ins>not</ins>** have a national validated identifier e.g. NHS Number. * Where a national identifier is included, it **must** be 'traced and verified', otherwise, the referral Sender **must <ins>not</ins>** include the national indentifier in the request -* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * If included in the synchronous HTTP response, the booking Sender **must** make available the human readable identifier for the booking to the end user * The booking Sender **must** send accompanying clinical information in a BaRS referral request * The booking Sender **must** reference the booking in the BaRS referral request (where the booking is made first in the workflow) @@ -131,8 +131,8 @@ The payloads and workflow have been designed to support these services. Other {{ * The referral Receiver **must** clearly identify any included safeguarding concern to the end user * The referral Receiver **must** accurately represent information made by the Sender to the end user * The referral Sender **must** make available the human readable identifier for the referral, included in the HTTP synchronous response, to the end user -* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Sender **must** include reference to any accompanying BaRS booking related to the referral * The referral Sender's request **must** be referenced in the BaRS booking request (where the referral is made first in the workflow) * The referral Receiver **must** link the explicitly related booking and referral requests @@ -173,11 +173,11 @@ The payloads and workflow have been designed to support these services. Other {{ <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Booking-Request-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Booking-Request-Payload.page.md index c41c4c3e..78d225f7 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Booking-Request-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Booking-Request-Payload.page.md @@ -29,6 +29,7 @@ This payload is used to support a booking workflow and contains all the required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -115,11 +116,11 @@ This payload is used to support a booking workflow and contains all the required | Appointment.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment | | Appointment.meta.lastupdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Appointment.status | This MUST be populated with 'booked' or 'cancelled' | MUST | 1..1 | booked | -| Appointent.serviceCategory | | | | | -| Appointent.serviceCategory.coding | BaRS Use Case | MUST | 0..* | | -| Appointent.serviceCategory.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/usecases-categories-bars | -| Appointent.serviceCategory.coding.code | This MUST be populated with Code for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | A1T1 | -| Appointent.serviceCategory.coding.display | This MUST be populated with Display for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | 111 - ED | +| Appointment.serviceCategory | | | | | +| Appointment.serviceCategory.coding | BaRS Use Case | MUST | 0..* | | +| Appointment.serviceCategory.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/usecases-categories-bars | +| Appointment.serviceCategory.coding.code | This MUST be populated with Code for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | A1T1 | +| Appointment.serviceCategory.coding.display | This MUST be populated with Display for the use-case. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/usecases-categories-bars' | MUST | 0..1 | 111 - ED | | Appointment.description | This SHOULD be populated. It is the human readable description of the booking | SHOULD | 0..1 | Reason for calling | | Appointment.start | This MUST be populated with the Start time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | | Appointment.end | This MUST be populated with the End time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/How-does-it-work.page.md index 06302aae..cf62bc52 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/How-does-it-work.page.md @@ -13,7 +13,7 @@ To support the workflows for this Application of the standard the operations tha ### Make a Referral -Making a referral for this Application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a referral for this Application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this Application is: {{link:https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-referral}} @@ -140,7 +140,7 @@ X-Correlation-Id = <GUID_00002> ### Make a booking -Making a booking for this Application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a booking for this Application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this Application is: {{link:https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-referral}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Index.page.md index c59e75a4..cfddb2d5 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Index.page.md @@ -20,9 +20,9 @@ topic: Application2 </thead> <tbody> <tr> - <td>Application 2 v1.0.7</td> + <td>Application 2 v1.0.8</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.0.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a></td> </tr> </tbody> @@ -51,7 +51,7 @@ This Application supports the use of the following use cases: ### Overview -This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.6, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. +This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.7, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. ### Data model endorsements diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Payloads.page.md index cbaa9c6f..5c445028 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Payloads.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Payloads.page.md @@ -6,7 +6,7 @@ topic: APP2-Payloads The specific guidance around the use of key FHIR resources is described below. ### MessageHeader Resource -{{pagelink:core-SPMessageHeader-1.1.6, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. The MessageHeader resource for the Booking Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'booking-request' @@ -27,7 +27,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars -). e.g. 111 Online - ED, S&R - UTC. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.6, text:use-case categories}} +). e.g. 111 Online - ED, S&R - UTC. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} An important function of the ServiceRequest resource is to link the booking and referral when they are related in a workflow. If the booking is successfully made before the referral, the Sender will have the *Appointment.Id* value and this **must** be included as a relative reference, under *ServiceRequest.supportingInfo*, in the referral request. The element *ServiceRequest.supportingInfo* **may** also be used to provide referrence to other resources in the request i.e. Rejected Services. This is outlined in the element guidance below. @@ -76,7 +76,7 @@ The extension *questionnaireresponse-reason* **must** be populated to indicate w Using a nested set of *questionnaireResponse.item*, *questionnaireResponse.linkId* and *questionnaireResponse.answer* complex structured data can be generated and processed, by the Sender and Receiver, respectively. The element guidance for this resource below goes into detail but, essentially, the *item* and *linkId* can be continually nested to convey various types of information. The *item* indicates a new element, *linkId* provide the number of elements (within the *item*) and *answer* contains any the value, supported by many different data types. ### Consent -In the BaRS UEC Applications the level of consent is stipulated to be for 'Direct Care' only. A referral **must** contain a Consent resource and it **must** adhere to the [example](https://simplifier.net/nhsbookingandreferrals/consent-example) provided under the BaRS FHIR assets. +In the BaRS UEC Applications the level of consent is stipulated to be for 'Direct Care' only. A referral **must** contain a Consent resource and it **must** adhere to the [example](https://simplifier.net/NHSBookingandReferrals/8fc39b95-89a6-45fb-914f-1458a10e9e14/~json) provided under the BaRS FHIR assets. <hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Referral-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Referral-Payload.page.md index f89e712f..da178b06 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Referral-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Referral-Payload.page.md @@ -26,6 +26,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | |1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Scope-and-Requirements.page.md index e3534c37..f6b7a1f5 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP2/Scope-and-Requirements.page.md @@ -80,8 +80,8 @@ The payloads and workflow have been designed to support these services. Other {{ * The booking Receiver **must** accept the booking request regardless of whether the patient is not known to the service provider * The booking Receiver **must** accept potential patients who do <ins>not</ins> have a national validated identifier e.g. NHS Number. * Where a national indentifier is included, it **must** be 'traced and verified', otherwise, the referral Sender **must** <ins>not</ins> include the national indentifer in the request -* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The booking Sender **must** send accompanying clinical information in a BaRS referral request * The booking Sender's request **must** be referenced in the BaRS referral request (where the booking is made first in the workflow) * The booking Receiver **must** link the explicitly related booking and referral requests @@ -108,8 +108,8 @@ The payloads and workflow have been designed to support these services. Other {{ * Any new or existing safeguarding concern, recorded as part of the assessment, **must** be included in the referral Sender's request * The referral Receiver **must** clearly identify any included safeguarding concern to the end user * The referral Receiver **must** accurately represent information made by the Sender to the end user -* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Sender **must** include reference to any accompanying BaRS booking related to the referral * The referral Sender's request **must** be referenced in the BaRS booking request (where the referral is made first in the workflow) * The referral Receiver **must** link the explicitly related booking and referral requests @@ -130,11 +130,11 @@ The payloads and workflow have been designed to support these services. Other {{ <br> <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/How-does-it-work.page.md index deddab1a..15d3ec80 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/How-does-it-work.page.md @@ -30,7 +30,7 @@ To support the workflows for this application of the standard the operations tha ### Make a Referral -Making a referral for this application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a referral for this application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}} <p> @@ -102,9 +102,9 @@ X-Correlation-Id = <GUID_000002> ### Cancel a Referral -To cancel a referral this application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a referral this application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this application is: {{link:messagedefinition-barsmessagedefinitionservicerequestrequestcancelled}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Index.page.md index ddd9b727..e740464d 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Index.page.md @@ -19,9 +19,9 @@ topic: Application3 </thead> <tbody> <tr> - <td>Application 3 v1.0.3</td> + <td>Application 3 v1.0.4</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.0.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a></td> </tr> </tbody> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Payloads.page.md index 81c0f98b..70a30933 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Payloads.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Payloads.page.md @@ -5,7 +5,7 @@ topic: APP3-Payloads ## {{page-title}} ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern Message Header}}. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern Message Header}}. The MessageHeader resource for the Referral Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-request' @@ -22,7 +22,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars -). e.g. 999-CAS Referral. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.6, text:use-case categories}} +). e.g. 999-CAS Referral. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} Additionally, the *ServiceRequest.occurrencePeriod* **must** be populated with the time that the receiving service must call the patient by (call back time) @@ -91,7 +91,7 @@ The level of consent currently supported by BaRS is for 'Direct Care' only. In e ## Referral Cancellation Payload -The ability to cancel a Referral Request is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.1.6, text:Standard Patterns - Cancellation}}. +The ability to cancel a Referral Request is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.3.0, text:Standard Patterns - Cancellation}}. <br> <hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Referral-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Referral-Payload.page.md index 2ca7c1cb..7c062b49 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Referral-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Referral-Payload.page.md @@ -4,7 +4,7 @@ topic: APP3-ReferralPayload ## {{page-title}} -### Payload for a Validation Request, using Service Request +### Payload for a Referral Request, using Service Request This payload is used to transmit all the necessary information that is required for a CAS to accept a patient referred into their service. @@ -31,6 +31,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -209,7 +210,7 @@ This payload is used to transmit all the necessary information that is required | CarePlan.encounter | | MUST | 0..1 | | | CarePlan.encounter.reference | This MUST be populated with a reference to the senders Encounter | MUST | 1..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4413 | | CarePlan.period | | MUST | 0..1 | | -| CarePlan.period.start | This MUST be populated with the datetime of the identification of the dispatch code (T5). | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| CarePlan.period.start | This MUST be populated with the dateTime of the identification of the dispatch code (T5). | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | CarePlan.activity | | MUST | 0..* | | | CarePlan.activity.outcomeCodeableConcept | | MUST | 0..* | | | CarePlan.activity.outcomeCodeableConcept.text | This SHOULD be populated with the clinical narrative. | SHOULD | 0..1 | CONSULTATION SUMMARY<br>PRINTED ON 18/03/2022 11:58:33<br>CASE ID: 6febefed-a5c9-43ed-9bd9-df14cbfb7d82<br>NHS PATHWAYS R26.2.1<br><br>PATIENT: Julie Jones<br>TELEPHONE:<br>AGE GROUP: Adult<br>GENDER: Female<br>PARTY: 1<br>POSTCODE: DH1 2HP<br>NOTES:<br><br>SKILLSET: 999 Call Handler<br>CALL HANDLER USER ID: julie.harris37@nhs.net<br>PATHWAY: PW1512 - Ankle or Foot Injury, Blunt<br>SYMPTOM GROUP: SG1011 - Ankle or Foot Injury, Blunt<br>SYMPTOM DISCRIMINATOR: SD4501 - ED Ischaemia, post trauma<br>DISPOSITION: Dx335 - A clinician from our service will call the individual back immediately to assess the problem.<br>SELECTED CARE SERVICE: No care service selected<br>CONSULTATION SUMMARY:<br><br>Injury - Leg pain<br>Warm to touch<br>Injury preceded by illness<br>Able to weight-bear<br>Cold/pale/blue foot<br>New swelling to injured limb<br>Access to transport<br>Transferred for clinician assessment<br>Local policy requires call to be transferred to a clinician<br>Local policy requires the call to be transferred to a clinician for a reason other than ambulance or treatment centre validation - Referral to CAS for callback<br>[...] | @@ -238,7 +239,7 @@ This payload is used to transmit all the necessary information that is required | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available. If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Scope-and-Requirements.page.md index 8250bad2..c1900b02 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP3/Scope-and-Requirements.page.md @@ -55,15 +55,15 @@ The payloads and workflow have been designed to support these services. Other {{ * The referral Receiver **must** clearly identify any included safeguarding concern to the end user * The referral Receiver **must** accurately represent information made by the Sender to the end user * The referral Sender **must** make available the human readable identifier for the referral, included in the HTTP synchronous response, to the end user -* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. **Update referral** * The referral Sender **must** be capable of updating any referral made by them, within the current consultation or after the consultation event * The referral Sender **must** retrieve the referral to be updated from the referral Receiver prior to update to ensure they are working with the most up-to date version and it has not already been completed * The referral Sender **must** provide visible confirmation to the end user of the status returned by the referral Receiver, i.e. whether the original referral was successfully updated or not -* Where the update was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the update was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the update was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the update was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Receiver **must** store all previous versions of the referral * The referral Receiver **must <ins>not</ins>** be required to inform the patient of the updating of the referral.  Business/clinical responsibility for informing the patient must remain with the referral Sender @@ -72,8 +72,8 @@ The payloads and workflow have been designed to support these services. Other {{ * The referral Sender **must** be capable of cancelling any referral made by them, within the current consultation or after the consultation event * The referral Sender **must** retrieve the referral to be cancelled from the referral Receiver prior to cancellation to ensure they are working with the most up-to date version and it has not already been completed * The referral Sender **must** provide visible confirmation to the end user of the status returned by the referral Receiver, i.e. whether the original referral was successfully cancelled or not -* Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Receiver **must** store all previous versions of the referral * The referral Receiver **must <ins>not</ins>** be required to inform the patient of the cancellation of the referral.  Business/clinical responsibility for informing the patient must remain with the referral Sender @@ -105,11 +105,11 @@ The payloads and workflow have been designed to support these services. Other {{ <br> <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/How-does-it-work.page.md index c4c19756..37fd5a2e 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/How-does-it-work.page.md @@ -68,7 +68,7 @@ To support the workflows for this application of the standard the operations tha ## Make a Validation Request -Making a Validation Request for this application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a Validation Request for this application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Validation}} <p> @@ -142,9 +142,9 @@ X-Correlation-Id = <GUID_000002> ## Cancel Validation Request -To cancel a Validation Request this application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as described on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned or completed. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a Validation Request this application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as described on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned or completed. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this application is: {{link:messagedefinition-barsmessagedefinitionservicerequestrequestcancelled}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Index.page.md index 8203f085..22744dcb 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Index.page.md @@ -17,9 +17,9 @@ topic: Application4 </thead> <tbody> <tr> - <td>Application 4 v1.2.2</td> + <td>Application 4 v1.2.3</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.0.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a></td> </tr> </tbody> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Interim-Validation-Response-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Interim-Validation-Response-Payload.page.md index 509f56b4..9a3d0355 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Interim-Validation-Response-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Interim-Validation-Response-Payload.page.md @@ -33,6 +33,7 @@ This payload is used to inform the Requester that the validation assessment has | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -206,7 +207,7 @@ This payload is used to inform the Requester that the validation assessment has | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Requestors.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Requestors.page.md index d3ae76f8..53c42366 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Requestors.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Requestors.page.md @@ -16,7 +16,7 @@ For Example Validation Request bundles see: * For additional example bundles please check [BaRS Example Bundles](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=Bundle&sortBy=LastUpdateDate_desc) ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern Message Header}}. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern Message Header}}. The MessageHeader resource for the Validation Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-request' @@ -30,7 +30,7 @@ The 'focus' resource in a Validation Request is the ServiceRequest resource. Whe There are two *coding* entries within *ServiceRequest.category* which are key to driving workflow: 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( -https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). e.g. 999- CAS Validation. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.6, text:use-case categories}} +https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). e.g. 999- CAS Validation. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} Additionally, the *ServiceRequest.occurrencePeriod* **must** be populated with the time by which the receiving service must complete the validation (validation breach time). @@ -102,7 +102,7 @@ The level of consent currently supported by BaRS is for 'Direct Care' only. In e ## Validation Cancellation Payload -The ability to cancel a Validation Request is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.1.6, text:Standard Patterns - Cancellation}}. +The ability to cancel a Validation Request is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.3.0, text:Standard Patterns - Cancellation}}. <br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Responders.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Responders.page.md index bbe440d0..671eb527 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Responders.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Payloads-for-Responders.page.md @@ -11,13 +11,13 @@ _Note that Responders will also have to build the capability to receive and proc For Interim Validation Response example bundles see: * [Interim Validation Response - CAS to 999 In-progress](https://simplifier.net/nhsbookingandreferrals/b8465a28-89ce-4530-8234-6fbe4aef6001) -* [Interim Validation Response - CAS to 999 Rejected](https://simplifier.net/nhsbookingandreferrals/b8465a28-89ce-4530-8234-6fbe4aef6002) +* [Interim Validation Response - CAS to 999 Rejected](https://simplifier.net/NHSBookingandReferrals/b8465a28-89ce-4530-8234-6fbe4aef6001-duplicate-2/~json) * For additional example bundles please check [BaRS Example Bundles](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=Bundle&sortBy=LastUpdateDate_desc) <br> ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern - Message Header}}. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern - Message Header}}. The MessageHeader resource in the Interim Validation Response should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-response' @@ -32,7 +32,7 @@ The *ServiceRequest* reflects that sent by the Requester, and maintains the acti There are two *coding* entries within *ServiceRequest.category* which are key to driving workflow: 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( -https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.6, text:use-case categories}} +https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} ### Encounter Resource @@ -66,7 +66,7 @@ example bundles see: * For additional example bundles please check [BaRS Example Bundles](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=Bundle&sortBy=LastUpdateDate_desc) ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern - Message Header}} for more information. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern - Message Header}} for more information. The MessageHeader resource in the Interim Validation Response should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-response' @@ -125,7 +125,7 @@ The *careplan.activity* holds the assessment information, whether it be coded or * The Ambulance Response Programme (ARP) priority code * Response outcome codes can also be included under additional instances of *careplan.activity.outcomeCodeableConcept.coding* -The *CarePlan.period.start* is used to calculate the clock start time for dispatch and **must** be populated populated with the datetime of the identification of the dispatch code. +The *CarePlan.period.start* is used to calculate the clock start time for dispatch and **must** be populated populated with the dateTime of the identification of the dispatch code. * If the Validation ARP code is the same or downgraded from the original 999 triage, this **must* be populated with the Requester's Clock start date/Time Definition as per the AmbSys specification. * If the Validation ARP code is upgraded from the original 999 triage this **must** be populated with the Dispatch/Disposition code identification date/time determined by the CAS diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Scope-and-Requirements.page.md index a6ccbf4e..85a68611 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Scope-and-Requirements.page.md @@ -78,14 +78,14 @@ For this application we will be referring to the actors as 'Requester' and the ' * The Responder **must** clearly identify any included safeguarding concern to the end user * The Responder **must** accurately represent information made by the Sender to the end user * The Requester **must** make available the human readable identifier for the referral, included in the HTTP synchronous response, to the end user -* Where the Validation Request was <ins>not</ins> successful, the Responder **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail -* Where the Validation Request was <ins>not</ins> successful, the Requester **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail +* Where the Validation Request was <ins>not</ins> successful, the Responder **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail +* Where the Validation Request was <ins>not</ins> successful, the Requester **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail **Update Validation Request** * The Requester **must** be capable of updating any Validation Request made by them, within the current consultation or after the consultation event * The Requester **must** retrieve the Validation Request to be updated from the Responder prior to update, to ensure they are working with the most up-to date version and the validation request has not already been completed, or is at a point in the workflow where it must not be updated * The Requester **must** provide visible confirmation of the status returned by the Responder to the end-user, i.e. whether the original Validation Request was successfully updated or not -* If the update fails, the Responder **must** respond with the most appropriately aligned error. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail +* If the update fails, the Responder **must** respond with the most appropriately aligned error. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail * The Responder **must** store all previous versions of the Validation Request * The Requester **must <ins>not</ins>** be required to inform the patient of the updating of the Validation Request.  Business/clinical responsibility for informing the patient must remain with the Requester * The Requester **should not** send updates after receiving an Interim Response @@ -119,7 +119,7 @@ For this application we will be referring to the actors as 'Requester' and the ' **Timings** * The Requester **must** send the Clock start date/Time (T5). Definition as per AmbSys specification * The Requester **must** send the validation breach time -* The Responder **must** send the dispatch (or disposition) code identification datetime in the **Validation Response**: +* The Responder **must** send the dispatch (or disposition) code identification dateTime in the **Validation Response**: - If the Validation ARP code is the same or downgraded from the original 999 triage, this **must** be populated with the original 999 Clock start date/Time (T5). - If the Validation ARP code is upgraded from the original 999 triage this **must** be populated with the Dispatch/Disposition code identification date/time determined by the CAS @@ -146,11 +146,11 @@ For this application we will be referring to the actors as 'Requester' and the ' <br> <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Request-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Request-Payload.page.md index 3bc0af96..e73dae8b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Request-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Request-Payload.page.md @@ -30,6 +30,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -235,7 +236,7 @@ This payload is used to transmit all the necessary information that is required | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Response-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Response-Payload.page.md index adaf03ed..2a3a6db5 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Response-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP4/Validation-Response-Payload.page.md @@ -30,6 +30,7 @@ This payload is used to transmit the outcome of the validation assessment back t | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -217,7 +218,7 @@ This payload is used to transmit the outcome of the validation assessment back t | CarePlan.encounter | | MUST | 0..1 | | | CarePlan.encounter.reference | This MUST be populated with a reference to the senders Encounter | MUST | 1..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4413 | | CarePlan.period | | MUST | 0..1 | | -| CarePlan.period.start | Disposition date/Time. This MUST be populated with the datetime of the identification of the dispatch code.<br><br>If the Validation ARP code is the same or downgraded from the original 999 triage, this MUST be populated with the original 999 Dispatch/Disposition code identification date/time.<br><br>If the Validation ARP code is upgraded from the original 999 triage this MUST be populated with the Dispatch/Disposition code identification date/time determined by the CAS | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| CarePlan.period.start | Disposition date/Time. This MUST be populated with the dateTime of the identification of the dispatch code.<br><br>If the Validation ARP code is the same or downgraded from the original 999 triage, this MUST be populated with the original 999 Dispatch/Disposition code identification date/time.<br><br>If the Validation ARP code is upgraded from the original 999 triage this MUST be populated with the Dispatch/Disposition code identification date/time determined by the CAS | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | CarePlan.activity | | MUST | 0..* | | | CarePlan.activity.outcomeCodeableConcept | | MUST | 0..* | | | CarePlan.activity.outcomeCodeableConcept.text | This SHOULD be populated with the clinical narrative. | SHOULD | 0..1 | CONSULTATION SUMMARY<br>PRINTED ON 30/03/2022 16:57:48<br>CASE ID: 91bcfff6-5220-48c4-8861-3bf6e69e8748<br>NHS PATHWAYS R25.2.1<br><br>PATIENT: Julie Jones<br>TELEPHONE:<br>AGE GROUP: Adult<br>GENDER: Female<br>PARTY: 1<br>POSTCODE: DH1 2HP<br>NOTES:<br><br>SKILLSET: PaCCS<br>CLINICIAN USER ID: julie.harris@nhs.net<br>PATHWAY: PW1848 - PaCCS Ambulance Dispatch<br>SYMPTOM GROUP: SG1137 - Palpitations<br>SYMPTOM DISCRIMINATOR: SD4118 - AMB ambulance dispatch<br>DISPOSITION: Dx016 - Non-emergency Ambulance Response (Category 4)<br>SELECTED CARE SERVICE: No care service selected<br>CONSULTATION SUMMARY:<br><br>Palpitations<br>Non-emergency ambulance response<br>Someone staying with individual<br>No indication scene unsafe<br>[...] | @@ -246,7 +247,7 @@ This payload is used to transmit the outcome of the validation assessment back t | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/How-does-it-work.page.md index 225459f8..9de967c0 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/How-does-it-work.page.md @@ -162,7 +162,7 @@ When a service is chosen, the "Service ID" field in the DOS data will be used as ### Make a Referral -Making a referral for this application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a referral for this application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}} <p> @@ -236,9 +236,9 @@ X-Correlation-Id = <GUID_000002> ### Cancel a Referral -To cancel a referral this application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a referral this application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, the referral **sender** must perform a read of the referral to be cancelled, from the referral **receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this application is: {{link:messagedefinition-barsmessagedefinitionservicerequestrequestcancelled}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md index 47564ec9..42131a45 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Index.page.md @@ -17,9 +17,9 @@ topic: Application5 </thead> <tbody> <tr> - <td>Application 5 v1.1.2</td> + <td>Application 5 v1.1.3</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.1.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0" target="_blank">v1.1.0</a></td> </tr> </tbody> @@ -47,7 +47,7 @@ NB - 'Primary Care' currently includes GP Practice and Online Consultation, as d ### Overview -This page provides guidance for implementing the Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.6, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. +This page provides guidance for implementing the Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.7, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. ### Data model endorsements diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Payloads.page.md index f56c9135..d4358e1a 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Payloads.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Payloads.page.md @@ -5,7 +5,7 @@ topic: APP5-Payloads ## {{page-title}} ### MessageHeader Resource -{{pagelink:core-SPMessageHeader-1.1.6, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. The MessageHeader resource for the Referral Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-request' @@ -20,7 +20,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars -). e.g. Primary Care to Community Pharmacy. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.1.6, text:use-case categories}} +). e.g. Primary Care to Community Pharmacy. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.3.0, text:use-case categories}} *Please note that the use-case category 'referraltopharmacy' is now deprecated to allow for more granular use cases.* diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Referral-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Referral-Payload.page.md index 034a1c1c..e7fc88fe 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Referral-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Referral-Payload.page.md @@ -28,6 +28,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.meta.versionId | This MUST be populated with the version of the Application the bundle complies with. The Receiver will read this to know whether they are capable of processing. | MUST | 0..1 | 1.0.0-beta | @@ -199,7 +200,7 @@ This payload is used to transmit all the necessary information that is required | CarePlan.encounter | | MUST | 0..1 | | | CarePlan.encounter.reference | This MUST be populated with a reference to the senders Encounter | MUST | 1..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4413 | | CarePlan.period | | MUST | 0..1 | | -| CarePlan.period.start | Disposition date/Time. This MUST be populated with the datetime of the identification of the dispatch/disposition code. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| CarePlan.period.start | Disposition date/Time. This MUST be populated with the dateTime of the identification of the dispatch/disposition code. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | CarePlan.addresses | | MUST | 0..* | | | CarePlan.addresses.reference | This MUST reference a Condition resource. This identifies which 'presenting complaint or issue' (as defined in the Information model) precipitated the generation of the CarePlan | MUST | 0..* | urn:uuid:8d12c664-0b6c-4e9b-8b70-10ccc81dbd89 | | CarePlan.activity | | MUST | 0..* | | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Scope-and-Requirements.page.md index 59d20c51..8687f898 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP5/Scope-and-Requirements.page.md @@ -64,15 +64,15 @@ The payload and workflow have been designed to support this service. Other {{pag - The referral Sender **should** include the service type when requesting a Blood Pressure service e.g. single check or monitoring over a period (ABPM) - The referral Sender **should** include the current oral contraception medication a patient is prescribed when requesting a Oral Contraception service, if requesting ongoing (repeat) supply - The referral Sender **must** make available the human readable identifier for the referral, included in the HTTP synchronous response, to the end user so they can share with the patient/third party -- Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -- Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +- Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +- Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. - Update to amend a referral request is <ins>not</ins> supported. If a referral Sender wishes to change information in a request they **must** follow the re-refer workflow **Cancel referral** - The referral Sender **must** be capable of cancelling any referral made by them, within the current consultation or after the consultation event - The referral Sender **must** perform a read of the referral to be cancelled, from the referral Receiver, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned -- Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -- Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +- Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +- Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. - The referral Receiver **must** store all previous versions of the referral - The referral Receiver **must <ins>not</ins>** be required to inform the patient of the cancellation of the referral.  Business/clinical responsibility for informing the patient remains with the referral Sender @@ -80,8 +80,8 @@ The payload and workflow have been designed to support this service. Other {{pag - The referral Sender **must** be capable of re-referring within the current consultation or after the consultation event - If the patient recontacts the sending service after the sender's consultation has been completed, the patient **should** be reassessed prior to attempting to re-refer - The referral Sender **should** revoke the original referral prior to making a re-referral, whether within the current consultation or after the consultation event -- Where the re-referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -- Where the re-referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +- Where the re-referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +- Where the re-referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. - The referral Receiver **must <ins>not</ins>** be required to inform the patient of the cancellation, incurred as part of the re-refer process.  Business/clinical responsibility for informing the patient remains with the referral Sender **Contacts** @@ -99,9 +99,9 @@ The payload and workflow have been designed to support this service. Other {{pag ### Error Handling -- Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +- Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} ### Non Functional -- Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +- Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/How-does-it-work.page.md index 61bc007a..ba9fcd3a 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/How-does-it-work.page.md @@ -10,16 +10,16 @@ This section describes how the primary operations used in this application work. * CAD to CAD Mutual Aid Request <br> -<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADOutOfArea-1.0.1.svg" target="_blank>"> -<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADOutOfArea-1.0.1.svg" width="1200"></img></a> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADOutOfArea-1.0.2.svg" target="_blank>"> +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADOutOfArea-1.0.2.svg" width="1200"></img></a> <br> -<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADCallAssist-1.0.1.svg" target="_blank>"> -<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADCallAssist-1.0.1.svg" width="1200"></img></a> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADCallAssist-1.0.2.svg" target="_blank>"> +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADCallAssist-1.0.2.svg" width="1200"></img></a> <br> -<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADMutualAid-1.0.1.svg" target="_blank>"> -<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADMutualAid-1.0.1.svg" width="1200"></img></a> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADMutualAid-1.0.2.svg" target="_blank>"> +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CADMutualAid-1.0.2.svg" width="1200"></img></a> ### Actors @@ -32,14 +32,12 @@ This section describes how the primary operations used in this application work. ### Out of area calls Calls may be re-routed by the BT Emergency Call Service to an Ambulance Service Trust (AST) outside of the geographic area of the incident (the Call Receiving AST) for the following reasons: -* The BT Intelligent Routing Platform (IRP) re-routes the call if the AST in the geographic area of the incident (the Home AST) has insufficient Call Handlers available to answer the call within a given time frame - * The Home AST has a 'buddying' arrangement with an out-of-area AST to take their calls under defined circumstances (e.g. system downtime, periods of surge) - * A third party caller calls about a patient in another area - * Calls where the incident is on the boundary between two ASTs +- The Home AST has arrangements with out of area ASTs to take their calls when needed +- A third party caller calls about a patient in another area +- Calls where the incident is on the boundary between two ASTs ### Call Assist Requests -- A Home AST may request support from a Supporting AST when they cannot send a resource to an incident within their geographic boundary of responsibility -- The Supporting AST may accept or reject this request +A Home AST may request support from a Supporting AST when they cannot send a resource to an incident within their geographic boundary of responsibility. The Supporting AST may accept or reject this request. - If the Supporting AST rejects the request, the Home AST will make alternative arrangements - If the Supporting AST accepts the request: - the Supporting AST is responsible for dispatching an appropriate resource within the time frame specified by the ARP Priority code @@ -47,14 +45,13 @@ Calls may be re-routed by the BT Emergency Call Service to an Ambulance Service ### Mutual Aid Requests -- A Home AST may request support from a Supporting AST when they cannot meet all of the resource requirements for an incident within their geographic boundary of responsibility. -- The Supporting AST may accept or reject this request +A Home AST may request support from a Supporting AST when they cannot meet all of the resource requirements for an incident within their geographic boundary of responsibility. The Supporting AST may accept or reject this request. - If the Supporting AST rejects the request, the Home AST will make alternative arrangements - If the Supporting AST accepts the request: - the Supporting AST is responsible for dispatching the requested resource within the time frame specified in the request - The Home AST remains responsible for the case and for dispatching the resources not specified in the request - Note: The BaRS Referral may be used to support single patient Mutual aid requests. It is not intended to replace processes relating to Mutual Aid Requests to support Major Incidents with multiple patients. +Note: The BaRS Referral may be used to support single patient Mutual aid requests. It is not intended to replace processes relating to Mutual Aid Requests to support Major Incidents with multiple patients. </br> @@ -95,7 +92,7 @@ Calls may be re-routed by the BT Emergency Call Service to an Ambulance Service - The referral Receiver's CAD will create a new case (Encounter) on receipt of the BaRS Referral and populate it with the patient and clinical details provided in the referral ### Acknowledge Receipt -- The referral Receiver will send an acknowledgement back to the referral Sender, when it has successfully processed the payload. If it fails to do this it will send a BaRS error code. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +- The referral Receiver will send an acknowledgement back to the referral Sender, when it has successfully processed the payload. If it fails to do this it will send a BaRS error code. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. ### Status Update (Referral Response) - The referral Receiver will send a series of status updates back to the referral Sender, to support tracking the progress of the case. @@ -103,7 +100,7 @@ Calls may be re-routed by the BT Emergency Call Service to an Ambulance Service ### Continue updates - If additional or changed information about the case is captured by the referral Sender, subsequent to sending the BaRS Referral, they may send a BaRS Referral Update to ensure that the referral Receiver has the most up to date information. - If the referral Sender needs to cancel a Referral, for example the patient calls back and says they do not require an ambulance, they need to send a Cancellation. -- On receipt of a Referral Update, the referral Receiver will send an acknowledgement back to the Sending AST on when it has successfully processed the payload. If it fails to do this it will send a BaRS error code. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +- On receipt of a Referral Update, the referral Receiver will send an acknowledgement back to the Sending AST on when it has successfully processed the payload. If it fails to do this it will send a BaRS error code. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. ### Manage Stack - The referral Receiver will manage the case in accordance with the Ambulance Response Programme (ARP) Priority Level. This may include: @@ -121,7 +118,7 @@ To support the workflows for this application of the standard the operations tha ## Make a Referral -Making a referral for this application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a referral for this application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}} <p> @@ -193,9 +190,9 @@ X-Correlation-Id = <GUID_000002> ### Cancel a Referral -To cancel a referral this application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as described on the linked section, the referral **Sender** must perform a read of the referral to be cancelled, from the referral **Receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **Receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a referral this application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as described on the linked section, the referral **Sender** must perform a read of the referral to be cancelled, from the referral **Receiver**, prior to cancellation to ensure they are working with the most up-to date information and it has not already been actioned. This is done by performing a "GET ServiceRequest by ID" call to the **Receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested ServiceRequest resource which should be checked for its current status to ensure it does not already have a status of "revoked" or "completed". If not, this version of the ServiceRequest should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:core-standardpattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this application is: {{link:messagedefinition-barsmessagedefinitionservicerequestrequestcancelled}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Index.page.md index a4100fdd..b557a89e 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Index.page.md @@ -22,9 +22,9 @@ topic: Application6 </thead> <tbody> <tr> - <td>Application 6 v1.0.0-beta.4</td> + <td>Application 6 v1.0.0-beta.5</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.1.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0" target="_blank">v1.1.0</a></td> </tr> </tbody> @@ -52,7 +52,7 @@ This application supports the use of the following use cases: ### Overview -This page provides guidance for implementing the Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.6, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. +This page provides guidance for implementing the Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.7, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. </br> </br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Referrals.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Referrals.page.md index f194e32b..4f3e6362 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Referrals.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Referrals.page.md @@ -17,7 +17,7 @@ For example Referral bundles please see: * For additional example bundles please check [BaRS Example Bundles](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=Bundle&sortBy=LastUpdateDate_desc) ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern Message Header}}. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern Message Header}}. The MessageHeader resource for the Referral Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-request' @@ -32,7 +32,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars -). e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.1.6, text:use-case categories}} +). e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.3.0, text:use-case categories}} Additionally, the *ServiceRequest.category.text* **must** be populated with details about the service request when the request is to support the Call Assist or Mutual Aid use cases. @@ -251,7 +251,7 @@ In this application it is used to transfer Call Log information and Crew Notes. ## Referral Cancellation Payload -The ability to cancel a referral is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.1.6, text:Standard Patterns - Cancellation}}. +The ability to cancel a referral is a core workflow in BaRS. For details on the use of the standard pattern for cancellation please see the following {{pagelink:core-SPCancellation-1.3.0, text:Standard Patterns - Cancellation}}. <br> <hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Responses.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Responses.page.md index a4cff1dc..ce8c9d3c 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Responses.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Payloads-for-Responses.page.md @@ -18,7 +18,7 @@ For Referral Response example bundles see: <br> ### MessageHeader Resource -For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.1.6, text:Standard Pattern - Message Header}}. +For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.3.0, text:Standard Pattern - Message Header}}. The MessageHeader resource in the Referral Response should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'servicerequest-response' @@ -34,7 +34,7 @@ There are two *coding* entries within *ServiceRequest.category* which are key to 1. Denotes the type of referral e.g. Transfer of care 2. Denotes the use case and must be populated with the relevant use case from [use-case CodeSystem]( -https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars) e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.1.6, text:use-case categories}} +https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars) e.g. Out of area, Mutual Aid or Call Assist. Please refer to the guidance in {{pagelink:core-SPUseCaseCategories-1.3.0, text:use-case categories}} ### Encounter Resource The Responder's current *Encounter* is the focus resource in the Referral Response. This was originally the 'planned' Encounter created by the Receiver in the synchronous response to the Referral Request. diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Referral-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Referral-Payload.page.md index d3d3d35d..699633e4 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Referral-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Referral-Payload.page.md @@ -30,6 +30,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -236,7 +237,7 @@ This payload is used to transmit all the necessary information that is required | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available. If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Response-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Response-Payload.page.md index b86b2f8c..0e0464ab 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Response-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Response-Payload.page.md @@ -36,6 +36,7 @@ ONLY) | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | @@ -198,7 +199,7 @@ ONLY) | Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | | Patient.meta.LastUpdate | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | -| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.system | This SHOULD be populated with namespace for the Identifier | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | | Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available. If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | | Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | | Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Scope-and-Requirements.page.md index 61dd2db0..15da2050 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Scope-and-Requirements.page.md @@ -76,16 +76,16 @@ The payloads and workflow have been designed to support these services. Other {{ * The referral Sender **must** make available the human readable identifier for the referral, included in the HTTP synchronous response, to the end user * The referral Receiver **must** clearly identify any included safeguarding concern to the end user * The referral Receiver **must** accurately represent information made by the Sender to the end user -* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail +* Where the referral was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the referral was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail **Update referral** * The referral Sender **must** be capable of updating any referral made by them, within the current consultation or after the consultation event * The referral Sender **must** send a referral update each time critical information is added to the case * The referral Sender **must** retrieve the referral to be updated from the referral Receiver prior to update to ensure they are working with the most up-to date version and the referral has not already been been completed, or is at a point in the workflow where it it must not be updated * The referral Sender **must** provide visible confirmation to the end user of the status returned by the referral Receiver, i.e. whether the original referral was successfully updated or not -* Where the update was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the update was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the update was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the update was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Receiver **must** store all previous versions of the referral * The referral Receiver **must <ins>not</ins>** be required to inform the patient of the updating of the referral.  Business/clinical responsibility for informing the patient must remain with the referral Sender @@ -94,8 +94,8 @@ The payloads and workflow have been designed to support these services. Other {{ * The referral Sender **must** be capable of cancelling any referral made by them, within the current consultation or after the consultation event * The referral Sender **must** retrieve the referral to be cancelled from the referral Receiver prior to cancellation to ensure they are working with the most up-to date version and it has not already been completed * The referral Sender **must** provide visible confirmation to the end user of the status returned by the referral Receiver, i.e. whether the original referral was successfully cancelled or not -* Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the cancellation was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the cancellation was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * The referral Receiver **must** store all previous versions of the referral * The referral Receiver **must <ins>not</ins>** be required to inform the patient of the cancellation of the referral.  Business/clinical responsibility for informing the patient must remain with the referral Sender @@ -154,11 +154,11 @@ The payloads and workflow have been designed to support these services. Other {{ <br> <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Booking-Request-Payload.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Booking-Request-Payload.page.md index 557f5ef3..2af8e443 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Booking-Request-Payload.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Booking-Request-Payload.page.md @@ -29,6 +29,7 @@ This payload is used to support a booking workflow and contains all the required | Bundle | https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This MUST be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/How-does-it-work.page.md index 6dcc8307..25d3e2d6 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/How-does-it-work.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/How-does-it-work.page.md @@ -78,7 +78,7 @@ X-Correlation-Id = <GUID_00002> ### Make a booking -Making a booking for this Application follows the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern for BaRS operations}}. +Making a booking for this Application follows the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern for BaRS operations}}. The message definition that defines this payload for this Application is: [BARS Message Definition - Booking Request](https://simplifier.net/nhsbookingandreferrals/messagedefinition-bars-messagedefinition-booking-request) @@ -146,9 +146,9 @@ This diagram illustrates the workflow and interactions of a booking cancellation <img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/BookingCancel-APP7-MVP-1.0.0-alpha.svg" width="1000"></img></a> -To cancel a booking this Application follows the {{pagelink:core-standardpattern-1.1.6, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the booking from the **receiver** as it may have changed locally. This is done by performing a "GET Appointment by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). +To cancel a booking this Application follows the {{pagelink:core-standardpattern-1.3.0, text:standard pattern for BaRS operations}} with an additional step. Before beginning the standard pattern as descbribed on the linked section, it is first necessary to retrieve the latest version of the booking from the **receiver** as it may have changed locally. This is done by performing a "GET Appointment by ID" call to the **receiving** system's corresponding API endpoint (via the BaRS proxy). -The response to this request will be the requested Appointment resource which should be checked for its current status to ensure it does not already have a status of "cancelled". If not, this version of the Appointment should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.1.6, text:standard pattern}}. +The response to this request will be the requested Appointment resource which should be checked for its current status to ensure it does not already have a status of "cancelled". If not, this version of the Appointment should be used when re-submitting the modified resource in the POST bundle as described in the {{pagelink:Core-StandardPattern-1.3.0, text:standard pattern}}. The message definition that defines this payload for this Application is: [BARS Message Definition - Cancel Booking Request](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionbookingrequestcancelled) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Index.page.md index 440e9d02..85257baf 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Index.page.md @@ -21,9 +21,9 @@ topic: Application7 </thead> <tbody> <tr> - <td>Application 7 v1.0.0-alpha.3</td> + <td>Application 7 v1.0.0-alpha.4</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core?version=1.8.2" target="_blank">v1.0.x</a></td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</td> <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a></td> </tr> </tbody> @@ -46,7 +46,7 @@ This Application supports the use of the following use case: ### Overview -This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.6, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. +This page provides guidance for implementing the Booking and Referral Standard (BaRS) specifically for the use cases listed above. It should be used alongside the {{pagelink:design-core-1.0.7, text:BaRS Core implementation guide}} and Payload Definitions when developing to the standard. For more information see {{pagelink: application7, text:Bookings and Referrals into GP (Application 7}} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Payloads.page.md index 1988f180..6942fc6b 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Payloads.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Payloads.page.md @@ -6,7 +6,7 @@ topic: APP7-Payloads The specific guidance around the use of key FHIR resources is described below. ### MessageHeader Resource -{{pagelink:core-SPMessageHeader-1.1.6, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. The MessageHeader resource for the Booking Request should have the following resource elements set as follows: * **MessageHeader.eventCoding** - **must** be populated with 'booking-request' diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Scope-and-Requirements.page.md index 82396002..6f806169 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Scope-and-Requirements.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Scope-and-Requirements.page.md @@ -61,8 +61,8 @@ The payloads and workflow have been designed to support these services. Other {{ **Booking** * Where a national identifier is included, it **must** have a [verification status](https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-nhsnumberverificationstatus) of 'Number present and verified' or 'Number present but not traced', otherwise, the referral Sender **must <ins>not</ins>** include it in the request -* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. -* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.1.6, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. +* Where the booking was <ins>not</ins> successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.3.0, text:failure scenarios}} for more detail. * If included in the synchronous HTTP response, the booking Sender **must** make available the human readable identifier for the booking to the end user * Update to amend a booking request is **<ins>not</ins>** supported. If a booking Sender wishes to change information in a request they **must** follow the re-book workflow @@ -100,11 +100,11 @@ The payloads and workflow have been designed to support these services. Other {{ <br> ### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.1.6, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.3.0, text:error handling guidance}} <br> <br> ### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.1.6, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.3.0, text:non functional requirements}} <br> <br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/Index.page.md index 5b2c9d8c..f65b2fb7 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/Index.page.md @@ -13,7 +13,7 @@ This page provides a catalogue of implementation guides that have been developed -These guides are designed to be used in conjunction with the documentation for {{pagelink:design-core-1.0.6}}. +These guides are designed to be used in conjunction with the documentation for {{pagelink:design-core-1.0.7}}. @@ -23,7 +23,7 @@ These guides are designed to be used in conjunction with the documentation for { | {{pagelink:application2, text: Booking and Referrals into UEC (Application 2)}} | <p>111 Online - ED <br>111 Online - UTC <br> S&R - ED <br> S&R - UTC <br> <p> | 1.0.7 | <a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a> | <a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a> | | {{pagelink:application3, text: Referral into UEC (Application 3)}} | <p>999-CAS Referral<br> | 1.0.3 | <a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a> | <a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a> | | {{pagelink:application4, text: Referral into UEC for Validation (Application 4)}} | <p>999-CAS Validation<br> <p>999 AST to Falls Lifting Service<br> <p>999 AST to Community Services <br> | 1.2.2 | <a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.0.0</a> | <a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a> | -| {{pagelink:application5, text: Referrals into Pharmacy (Application 5)}} | <p>Primary Care to Community Pharmacy (Pharmacy First)<br> <p>Primary Care to Pharmacy Contraception (Oral Contraception) <br> <p>Primary Care to Pharmacy Blood Pressure Check Service<br> | 1.1.2 | <a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0" target="_blank">v1.1.0</a> | {{pagelink:design-core-1.1.6, text:v1.1.0}} | +| {{pagelink:application5, text: Referrals into Pharmacy (Application 5)}} | <p>Primary Care to Community Pharmacy (Pharmacy First)<br> <p>Primary Care to Pharmacy Contraception (Oral Contraception) <br> <p>Primary Care to Pharmacy Blood Pressure Check Service<br> | 1.1.2 | <a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_1_0" target="_blank">v1.1.0</a> | {{pagelink:design-core-1.3.0, text:v1.1.0}} | <hr> @@ -43,7 +43,7 @@ Table detailing active versions of the latest Applications in Production (or cur </thead> <tbody> <tr> - <td>Application 1 v1.0.1</td> + <td>Application 1 v1.0.1</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.1.0</a></td> <td rowspan=14 style="text-align: center; vertical-align: middle;"><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a></td> <td rowspan=14 style="text-align: center; vertical-align: middle;"><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">1.0.0</a></td> @@ -64,6 +64,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 1 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 1 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 2 v1.0.1</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.1.0</a></td> @@ -84,6 +88,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 2 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 2 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 3 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -100,6 +108,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 3 v1.0.3</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 3 v1.0.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 4 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -116,6 +128,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 4 v1.2.2</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 4 v1.2.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 5 v1.0.0-beta.4</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -139,12 +155,16 @@ Table detailing active versions of the latest Applications in Production (or cur <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> <tr> - <td>Application 6 v1.0.0-beta.4</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 5 v1.1.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> </tr> <tr> - <td>Application 7 v1.0.0-alpha.3</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 6 v1.0.0-beta.5</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> + <tr> + <td>Application 7 v1.0.0-alpha.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">1.0.0</a></td> </tr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Pre-releases/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Pre-releases/Index.page.md index 794eebc6..9c93c1f2 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Pre-releases/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Pre-releases/Index.page.md @@ -40,7 +40,7 @@ Table detailing active versions of the latest Applications in Production (or cur </thead> <tbody> <tr> - <td>Application 1 v1.0.1</td> + <td>Application 1 v1.0.1</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.1.0</a></td> <td rowspan=14 style="text-align: center; vertical-align: middle;"><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a></td> <td rowspan=14 style="text-align: center; vertical-align: middle;"><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">1.0.0</a></td> @@ -61,6 +61,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 1 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 1 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 2 v1.0.1</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.1.0</a></td> @@ -81,6 +85,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 2 v1.0.7</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 2 v1.0.8</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 3 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -97,6 +105,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 3 v1.0.3</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 3 v1.0.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 4 v1.0.0</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -113,6 +125,10 @@ Table detailing active versions of the latest Applications in Production (or cur <td>Application 4 v1.2.2</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> + <tr> + <td>Application 4 v1.2.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> <tr> <td>Application 5 v1.0.0-beta.4</td> <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.4.0" target="_blank">v1.4.0</a></td> @@ -136,12 +152,16 @@ Table detailing active versions of the latest Applications in Production (or cur <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> </tr> <tr> - <td>Application 6 v1.0.0-beta.4</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 5 v1.1.3</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> </tr> <tr> - <td>Application 7 v1.0.0-alpha.3</td> - <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</a></td> + <td>Application 6 v1.0.0-beta.5</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> + </tr> + <tr> + <td>Application 7 v1.0.0-alpha.4</td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.9.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.0.0</a></td> <td rowspan=1 style="text-align: center; vertical-align: middle;"><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">1.0.0</a></td> </tr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Assure/Assure/SCAL.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Assure/Assure/SCAL.page.md index 28702599..7fcc86a1 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Assure/Assure/SCAL.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Assure/Assure/SCAL.page.md @@ -20,6 +20,6 @@ When planning a project to build a BaRS solution, the inclusion of assurance mus The process of being assured via the SCAL can take between 2-4 weeks (average), from the point of the first complete submission. This allows some time in any plan for resubmissions after review by the Solution Assurance team. -It is advised the SCAL requirements are reviewed after reading the implementation guidance. The two combined will help build a backlog of requirements for the anticipated solution. For example, there is implementation guidance for {{pagelink:core-EHFailureScenarios-1.1.6, text:error handling}} while the SCAL highlights the expectation for logging and auditing of errors. +It is advised the SCAL requirements are reviewed after reading the implementation guidance. The two combined will help build a backlog of requirements for the anticipated solution. For example, there is implementation guidance for {{pagelink:core-EHFailureScenarios-1.3.0, text:error handling}} while the SCAL highlights the expectation for logging and auditing of errors. Evidence, supporting the completion of the SCAL, can be gathered during testing with other supplier solutions or {{pagelink:Home/Build/Testing-and-Environments/TKW.page.md, text:Toolkit Workbench (TKW)}}. An ideal time to collect is during the end-to-end demonstration of the solution, a necessary part of assurance. The validation reports from TKW must also be submitted as part of the SCAL. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/TKW.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/TKW.page.md index 03685d22..09aa2b5e 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/TKW.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Build/Testing-and-Environments/TKW.page.md @@ -68,7 +68,7 @@ NB: the endpoints for TKW are case sensitive eg use the following #### Headers -The follow is a list of headers needed for the requests, these follow the pattern needed by BARS as follows {{pagelink:core-EndToEndWorkflow-HTTPHeader-1.1.6, text:Headers}} +The follow is a list of headers needed for the requests, these follow the pattern needed by BARS as follows {{pagelink:core-EndToEndWorkflow-HTTPHeader-1.3.0, text:Headers}} | Name | Value | example | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.6/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.6/Standard-Pattern-Composite-Messages/Cancellation.page.md index bb3d9948..6e9a88e2 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.6/Standard-Pattern-Composite-Messages/Cancellation.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.6/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -57,6 +57,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Bundle.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Bundle.page.md new file mode 100644 index 00000000..f20df435 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Bundle.page.md @@ -0,0 +1,14 @@ +--- +topic: core-FHIRUsage-bundle-1.0.7 +--- + +## Bundle + +The use of the FHIR bundle in BaRS primarily supports the use of $process-message. It is also used as follows: + +- When $process-message is initiated, a sender packages up numerous FHIR resources (MessageHeader, Patient, ServiceRequest etc.), the bundle will include everything needed by a receiver to process the request being made. +- The $process-message endpoint is capable of receiving different types of request. The sender indicates the the action required by specifying in the MessageHeader resource, for example: booking or servicerequest, the operation, whether it be 'new' or 'update' and central FHIR resource from which to make sense of the bundle, the 'focus'. +- A bundle type of 'searchset' is also used in BaRS when a receiver responds to a senders request for available slots, in the booking workflow. A receiver responds by bundling FHIR resources (HealthcareService, Schedule, Slot(s) etc.) related to particular HealthcareService which a sender will unpack and process to display service availability to a user. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md new file mode 100644 index 00000000..7393ab4c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md @@ -0,0 +1,13 @@ +--- +topic: core-FHIRUsage-FHIR-Operations-1.0.7 +--- + +## FHIR Operations framework + +Performing the required steps in workflow using simple CRUD operations on single resources can be complex and relies on prior knowledge or dictates explicit rules around workflow in any given system, for example: a patient must exist before a service request can be made. In order to support complex workflows that utilise composites of resources, simple CRUD operations on sinlge resources would breach some core principles of ReST (e.g. inabililty to maintain stateless communication for example). Therefore BaRS utilises the FHIR operations framework which: + +- offers a degree of autonomy to the receiver of the communication in how they process for their system +- is designed to support events, triggering activity between systems, supporting the response workflow requirements identified by many of the BaRS use cases, for example: 999 to CAS Validation Request/Response. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Frameworks.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Frameworks.page.md new file mode 100644 index 00000000..8362b8b7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Frameworks.page.md @@ -0,0 +1,10 @@ +--- +topic: core-FHIRUsage-Framework-1.0.7 +--- + +## Frameworks + +A mix of data exchange frameworks are employed by BaRS to support different workflows. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/How-to-handle-times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/How-to-handle-times.page.md new file mode 100644 index 00000000..eafe0f06 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/How-to-handle-times.page.md @@ -0,0 +1,18 @@ +--- +topic: core-FHIRUsage-Time-1.0.7 +--- + +## {{page-title}} + +* All times MUST be in FHIR Instant format (```YYYY-MM-DDThh:mm:ss.sssssss+zz:zz```) + * e.g. ```Year-Month-DayTHours:Minutes:Seconds.milliseconds+OffsetFromUTC``` + * e.g. ```2015-02-07T13:28:17.2398742+02:00``` + * *except* where specifically defined otherwise +* All times can have up to seven digits resolution for milliseconds +* All times SHOULD be converted to UTC from local times (if not stored locally in UTC) before being included in any messages, this means the offset should be zero +* When receiving a time in a message a system MUST expect and handle a non UTC time (e.g. with a non-zero offset) + * Therefore if a time is received that is not UTC, the receiver should convert the time back to UTC using the offset given (or to their local time, if storing times in a local time) + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important:</b> +This means both Sender and Receiver systems MUST be able to handle a time provided with an offset from UTC that differs from your local server time. As an illustration, if you store all times in UTC and someone uses a time specifying an offset, you will need to convert it to UTC when you store it. +</div> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Index.page.md new file mode 100644 index 00000000..182b6910 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-FHIRUsage-1.0.7 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Introduction.page.md new file mode 100644 index 00000000..3bb8d2b6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-FHIRUsage-introduction-1.0.7 +--- + +# BaRS FHIR Usage + +BaRS uses [FHIR](https://digital.nhs.uk/services/fhir-uk-core) to achieve interoperability between healthcare IT systems. This section explains how BaRS makes use of some key FHIR concepts which need to be understood by developers implementing the standard. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Journey-ID.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Journey-ID.page.md new file mode 100644 index 00000000..68a9e2fe --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/Journey-ID.page.md @@ -0,0 +1,25 @@ +--- +topic: core-FHIRUsage-JourneyID-1.0.7 +--- + +## {{page-title}} + +The Journey ID uses the episodeOfCare resource. + +Each Encounter between systems can reference the same originating episodeOfCare, allowing grouping of all the Encounters to one flow. + +The FHIR episodeOfCare resource would be created at the beginning of the patient journey when the Encounter is created and leads onto a ServiceRequest or other appropriate flow. + +{{render:Encounter-episodeOfCare-screenshot}} + +This snippet of coding shows the episodeOfCare within the Encounter referencing a GUID that will be used throughout the patients journey. + +```xml +<episodeOfCare> + <!-- Resource reference to an EpisodeOfCare Journey ID --> + <reference value="d877b820-e72b-44d1-a627-195f54bfc606" /> +</episodeOfCare> +``` + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/LastUpdatedDate.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/LastUpdatedDate.page.md new file mode 100644 index 00000000..9eedef8b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/LastUpdatedDate.page.md @@ -0,0 +1,18 @@ +--- +topic: core-FHIRUsage-LastUpdated-1.0.7 +--- + +## {{page-title}} + +Every resource will include a lastUpdated date in the meta tag. This is to be used for tracking and updating. + +```xml +<meta> + <versionId value="1.0.0-alpha" /> + <lastUpdated value="2021-11-26T15:00:00+00:00" /> + <profile value="https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage" /> +</meta> +``` + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/REST.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/REST.page.md new file mode 100644 index 00000000..46814e2b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/REST.page.md @@ -0,0 +1,16 @@ +--- +topic: core-FHIRUsage-REST-1.0.7 +--- + +## REST + +FHIR is often associated with REST (REpresentational State Transfer) as a primary method of exchange. BaRS uses REST for many of the benefits it offers - + +- allows independent modular development of client and server APIs (they don't need to know about each other before exchanges) +- easy to integrate because of common agreed standards +- scalability in developing and performance + +In BaRS, simple CRUD operations on single resources is used for discrete atomic functions, such as retrieving a known booking or referral entity. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/process-message.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/process-message.page.md new file mode 100644 index 00000000..930a68a4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/process-message.page.md @@ -0,0 +1,20 @@ +--- +topic: core-FHIRUsage-Process-Message-1.0.7 +--- + +## $process-message + +This specific FHIR operation enables the exchange of complex composites whilst maintaining the principles of REST. The $process-message endpoint will be called at various stages in any of the workflows outlined to fulfil requests such as: + +- 'create a booking' +- 'process a referral for validation' +- 'validation outcome response' + +The endpoint receives only POST requests of bundle type 'message', with the required MessageHeader resource dictating how to process and what is deemed the 'focus' (key Resource) of the request. The sender packages up this content, POSTs to the receiver and lets them decide how to consume and process the bundle. + +You must implement a $process-message endpoint to be compliant with BaRS because it is used for initial requests (booking, service request etc.) but also for responses (validation outcome response etc.). + +Please see the {{pagelink:Core-StandardPattern-1.0.7, text: Standard Patterns}} for generic guidance for processing messages. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/toc.yaml new file mode 100644 index 00000000..cb7ee837 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/BaRS-FHIR-Usage/toc.yaml @@ -0,0 +1,20 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Frameworks + filename: Frameworks.page.md +- name: REST + filename: REST.page.md +- name: FHIR Operations Framework + filename: FHIR-Operations-Framework.page.md +- name: $process-message + filename: process-message.page.md +- name: Bundle + filename: Bundle.page.md +- name: Journey ID + filename: Journey-ID.page.md +- name: LastUpdatedDate + filename: LastUpdatedDate.page.md +- name: How to handle times + filename: How-to-handle-times.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/All.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/All.page.md new file mode 100644 index 00000000..988afce4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/All.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-All-1.0.7 +--- + +### All + +- Provide Capability Statement +- Read and interpret Capability State +- Provide Message Definition(s) for a specific service +- Read and interpret Message Definition(s) for a specific service + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Receiver.page.md new file mode 100644 index 00000000..93a2827d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Receiver.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingReceiver-1.0.7 +--- + +### Booking Receiver + +- Provide Slots for a specific service +- Create Booking +- Cancel Booking +- Accept Rebook request (two open Bookings during this routine) + +<br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Sender.page.md new file mode 100644 index 00000000..58bb9dee --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Booking-Sender.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingSender-1.0.7 +--- + +### Booking Sender + +- Request Slots for a specific service +- Make Booking request +- Cancel Booking request +- Make Rebook request (two open Bookings during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Caching.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Caching.page.md new file mode 100644 index 00000000..ab433175 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Caching.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-Caching-1.0.7 +--- + +### Caching + +- The local caching of retrieved metadata (Capability Statements and Message Definitions) requests is permitted to improve performance +- Caching of responses **must <ins>not</ins>** exceed 24 hours (12 hours is recommended) +- There **must** be a mechanism to manually clear the cache + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Index.page.md new file mode 100644 index 00000000..82b70aa7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-FunctionalityRequirements-1.0.7 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Introduction.page.md new file mode 100644 index 00000000..b9e50c00 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Introduction.page.md @@ -0,0 +1,17 @@ +--- +topic: core-FunctionalityRequirements-introduction-1.0.7 +--- + +# Core Functionality Requirements + +BaRS should provide different functionality depending on: + +- its {{pagelink:applications, text:Application or use case}} +- whether it acts as a sender or receiver + + +This list of functionality will expand in later versions of BaRS. + +There are requirements in each of the central areas of functionality which every BaRS Application must adopt: + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Receiver.page.md new file mode 100644 index 00000000..e2a05c20 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Receiver.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralReceiver-1.0.7 +--- + +### Referral Receiver + +- Create Referral +- Cancel Referral +- Accept re-request Service Request (revoke current open Referral prior to sending new. Only one active/open Service Request during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Sender.page.md new file mode 100644 index 00000000..e34b6041 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/Referral-Sender.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralSender-1.0.7 +--- + +### Referral Sender + +- Make Referral request +- Cancel Referral request +- Re-request Service Request (revoke current open Referral prior to sending new. Only one active/open Service Request during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/toc.yaml new file mode 100644 index 00000000..31db240a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Core-Functionality-Requirements/toc.yaml @@ -0,0 +1,16 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: All + filename: All.page.md +- name: Caching + filename: Caching.page.md +- name: Booking Sender + filename: Booking-Sender.page.md +- name: Booking Receiver + filename: Booking-Receiver.page.md +- name: Referral Sender + filename: Referral-Sender.page.md +- name: Referral Receiver + filename: Referral-Receiver.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Asynchronous-Workflow.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Asynchronous-Workflow.page.md new file mode 100644 index 00000000..18f9574d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Asynchronous-Workflow.page.md @@ -0,0 +1,9 @@ +--- +topic: core-EndToEndWorkflow-AsyncWorkflow-1.0.7 +--- + +## {{page-title}} + +The FHIR $process-message function supports 'async' parameter but BaRS does not employ this, all $process-message requests are synchronous. + +However, BaRS does support request-response loops which are asynchronous. An example of this is the Safeguarding DNA response workflow; the sender (NHS 111 Telephony service) sends a referral with a safeguarding concern flag to an Emergency Department, the patient subsequently doesn't attend (DNAs). The Emergency Department receiver is now responsible for sending a response back to the original sender (the NHS 111 Telephony service) to inform them of the DNA. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authenticate-with-BaRS.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authenticate-with-BaRS.page.md new file mode 100644 index 00000000..24116fa1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authenticate-with-BaRS.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-BaRSAuth-1.0.7 +--- + +## Authenticate with BaRS + +The sender must have already [connected with our platform](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) in order to generate an access token to make a request of the BaRS API. The sender generates and signs a JWT and sends this request to the BaRS token endpoint which provides an access token to be used to interact with the BaRS API. +A receiver will follow the same process to interact with BaRS API when providing feedback to an original sender, for example. The sender and receiver switch roles in the workflow for referral in both the current first-of-type use cases. This is only relevant to some Applications and will be detailed in the specific {{pagelink:Applications , text:application guide.}} + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authentication-and-Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authentication-and-Authorisation.page.md new file mode 100644 index 00000000..b1debb41 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Authentication-and-Authorisation.page.md @@ -0,0 +1,15 @@ +--- +topic: core-EndToEndWorkflow-Auth-1.0.7 +--- + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| Authorisation | Required by the sender and not forwarded to the receiver | Will contain a token obtained from the relevant OAuth endpoint for the BaRS API being called. This token facilitates authentication with the API. | String representing a token | +| NHSD-End-User- Organisation | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the organisation making the request. Can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR Organization resource | +| NHSD-Requesting-Practitioner | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the healthcare professional making the request. Can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR PractitionerRole resource | +| NHSD-Requesting-Software | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the application making the request. This can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR Device resource | + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/BaRS-FHIR-API.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/BaRS-FHIR-API.page.md new file mode 100644 index 00000000..075dc114 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/BaRS-FHIR-API.page.md @@ -0,0 +1,14 @@ +--- +topic: core-EndToEndWorkflow-API-1.0.7 +--- + +## BaRS FHIR API + +The [BaRS FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) supports all functionality with receiver APIs for both booking and referrals. Once an access token has been obtained, the sender can start making requests of the API. + +Note: With every API request the sender must include the HTTP header parameter 'NHSD-Target Identifier'. + +You can find details for each endpoint in the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Header.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Header.page.md new file mode 100644 index 00000000..74de5983 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Header.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-HTTPHeader-1.0.7 +--- + +## {{page-title}} + +The BaRS API specifies several additional headers, many of which are items described in a standard Base64 encoded object (JSON). Their purpose and usage are described below. Examples can be found in the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Response-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Response-Headers.page.md new file mode 100644 index 00000000..6b7ffc79 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/HTTP-Response-Headers.page.md @@ -0,0 +1,12 @@ +--- +topic: core-EndToEndWorkflow-HTTPResponseHeader-1.0.7 +--- + +## {{page-title}} + +Responses to requests in the BaRS standard need not include anymore than Headers required by the HTTP protocol and the Transaction Integrity Headers listed above. Senders should not expect or require anymore than this in a synchronous HTTP response. + +For secure usage of HTTP headers, guidance can be found in the OWASP Secure headers project regarding the [security headers](https://owasp.org/www-project-secure-headers/#div-headers) and [prevention of information disclosure](https://owasp.org/www-project-secure-headers/#div-bestpractices) which can be leveraged. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Index.page.md new file mode 100644 index 00000000..a2890504 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-EndToEndWorkflow-1.0.7 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Introduction.page.md new file mode 100644 index 00000000..caa2c3a2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Introduction.page.md @@ -0,0 +1,22 @@ +--- +topic: core-EndToEndWorkflow-introduction-1.0.7 +--- + +# End-to-end Workflow + +This section covers the core elements of workflow outlined within the Booking and Referral Standard. There are two caveats when reading this: + +- Workflow is dependent on its Application or use case, for example in 999 - CAS validation, there is no step to perform a booking. See the relevant use case page in the +{{pagelink:applications, text:BaRS Applications}} section. + + +- The order of workflow is interchangeable. It is possible to: + - make a referral before a booking + - refer without booking + - book without referring + + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CoreWorkflowBaRS-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CoreWorkflowBaRS-1.0.0.svg" width="1200"></img></a> + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Logging.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Logging.page.md new file mode 100644 index 00000000..f82ac3f8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Logging.page.md @@ -0,0 +1,55 @@ +--- +topic: core-EndToEndWorkflow-Logging-1.0.7 +--- + +## {{page-title}} + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important: Versioning information - Preview</b> </div> +<p> + +| Header | Requirement | Description | Value | +|------------------------|------------------------|--------------------------------------------------------------|----------------------------| +| use-context | Required by the sender | Allows BaRS to route the message to the appropriate endpoint | Formatted string | + +This header is for usage statistics for the BaRS Proxy for NHS England. It consists of a composite of 4 values from within the payload, in order. The sender MUST include this information. The receiver MUST ignore this header. The elements are: + +The elements for a ServiceRequest are: + +* ServiceRequest.category.coding.code (usecases-categories-bars) +* ServiceRequest.category.coding.code (message-category-servicerequest) +* MessageHeader.eventCoding.code (message-event-bars) +* MessageHeader.reason.coding.code (message-reason-bars) + +The elements for an Appointment are: + +* Appointent.serviceCategory.coding (usecases-categories-bars) +* Appointment.status +* MessageHeader.eventCoding.code (message-event-bars) +* MessageHeader.reason.coding.code (message-reason-bars) + +These MUST be present in the use-context header, separated by a pipe, in the defined order. + +### Referral + +``` +ServiceRequest.category.coding.code[usecases-categories-bars] | ServiceRequest.category.coding.code[message-category-servicerequest] | MessageHeader.eventCoding.code | MessageHeader.reason.coding.code +``` +Example: +``` +--header 'use-context: a4t2|validation|servicerequest-response|new' +``` + +### Booking + +``` + Appointent.serviceCategory.coding[usecases-categories-bars] | Appointment.status | MessageHeader.eventCoding.code | MessageHeader.reason.coding.code +``` +Example: +``` +--header 'use-context: a1t1|booked|booking-request|new' +``` + +This header is applicable to the following endpoints: + * POST /$process-message +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Processing-Requests.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Processing-Requests.page.md new file mode 100644 index 00000000..6096944a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Processing-Requests.page.md @@ -0,0 +1,23 @@ +--- +topic: core-EndToEndWorkflow-Processing-1.0.7 +--- + +## {{page-title}} + +For GET requests (reads) the Receiver honours what is being asked for by generating and synchronously sending a response, for example the server Capability Statement on a GET /metadata request. Any failure during processing must initiate an error response back to the Sender. + +The $process-message endpoint on the implemented API supports a mix of RESTful and Messaging exchanges, as required by BaRS. The main benefit of introducing messaging is to allow a Sender to package up the information a Receiver needs, to process a particular request, but letting them handle it as necessitated by their system, rather than a Sender having to make numerous requests to REST endpoints to perform the same action. + +When a request is received against the $process-message endpoint, the MessageHeader resource must be examined to determine what process the Sender is expecting the Receiver to perform. There are three key elements to determine this - + +- .eventCoding - primary function being asked to perform, for example: booking-request or servicerequest-request +- .reason - operation, for example:. New or Update +- .focus - the key resource in the bundle, to be read first to make sense of other related resources + +The Receiver interprets the request, engages the processing and synchronously feeds back a response. + +When processing the body (the FHIR bundle or payload) of the request, the Receiver can implement business logic, determining the type of payload and whether a request is valid or not, by using the guidance under the payload sections of each Application. This guidance stiplates the business requirement of each element of the payload, allowing a Receiver to determine elements which are mandated, required, optional or forbidden. The 'Necessity' column, of the tables within each Application payload section, indicates these buisness level requirements and aligns with defintions under [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +Please see the {{pagelink:Core-StandardPattern-1.0.7, text: Standard Patterns}} for generic guidance for processing messages. + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Responses.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Responses.page.md new file mode 100644 index 00000000..31d81003 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Responses.page.md @@ -0,0 +1,9 @@ +--- +topic: core-EndToEndWorkflow-Responses-1.0.7 +--- + +### {{page-title}} + +In the BaRS workflows responses are an important step and likely to become more so as use cases offer up increasingly complex requirements, for example: negotiated referrals. + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Reversing-Roles.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Reversing-Roles.page.md new file mode 100644 index 00000000..72d8e6c7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Reversing-Roles.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-ReversingRoles-1.0.7 +--- + +### {{page-title}} + +When responding the sender and receiver roles are reversed. Here you are essentially building a sender, and still need to implement a $process-message endpoint. Similarly, a receiver needs the ability to send the response to the BaRS API and will need to [register with our platform](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Routing.page.md new file mode 100644 index 00000000..00262102 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Routing.page.md @@ -0,0 +1,12 @@ +--- +topic: core-EndToEndWorkflow-Routing-1.0.7 +--- + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------------|------------------------|--------------------------------------------------------------|----------------------------| +| NHSD-Target-Identifier | Required by the sender | Allows BaRS to route the message to the appropriate endpoint | Base64 encoded JSON object | + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Service-Discovery.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Service-Discovery.page.md new file mode 100644 index 00000000..b76514de --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/Service-Discovery.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-ServiceDiscovery-1.0.7 +--- + +## Service discovery + +For a sender making a booking or referral, the first step is to establish a service (including the identifier) to send to. This can be achieved by using national or local service directories or preconfigured services, where a sender only ever sends to a handful of endpoints. The service identifier is all the sender requires to engage with a service which supports BaRS. {{pagelink:Home/Helpandsupport, text:Contact us}} if you need further information about service discovery. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/toc.yaml new file mode 100644 index 00000000..7b6ddaf8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/toc.yaml @@ -0,0 +1,30 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Service Discovery + filename: Service-Discovery.page.md +- name: Authenticate with BaRS + filename: Authenticate-with-BaRS.page.md +- name: BaRS FHIR API + filename: BaRS-FHIR-API.page.md +- name: HTTP Header + filename: HTTP-Header.page.md +- name: Routing + filename: Routing.page.md +- name: Logging + filename: Logging.page.md +- name: Authentication and Authorisation + filename: Authentication-and-Authorisation.page.md +- name: Transactional Integrity + filename: transactional-Integrity.page.md +- name: HTTP Response Headers + filename: HTTP-Response-Headers.page.md +- name: Processing Requests + filename: Processing-Requests.page.md +- name: Responses + filename: Responses.page.md +- name: Reversing Roles + filename: Reversing-Roles.page.md +- name: Asynchronous Workflow + filename: Asynchronous-Workflow.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/transactional-Integrity.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/transactional-Integrity.page.md new file mode 100644 index 00000000..a3afca52 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/End-to-end-workflow/transactional-Integrity.page.md @@ -0,0 +1,21 @@ +--- +topic: core-EndToEndWorkflow-Transactional-Integrity-1.0.7 +--- + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------|--------| +| X-Request-ID | Required for sending of any request and forwarded to the receiver | Will facilitate transactional integrity and the ability to audit messages | UUID | +| X-Correlation-Id | Required for sending of any request and forwarded to the receiver | Will facilitate transactional integrity and the ability to audit messages | UUID | + +We expect receivers to use and store the header values in the following ways: + +- to ensure the message maintains transactional integrity and hasn't been received previously +- to check who has sent the request and apply access control if desired +- to ensure all interactions are auditable + +If at any point the request fails, the receiver must send an appropriate error response (see Error handling) back to the sender to inform them why the request cannot be fulfilled. It is important to return as accurate information in the response as possible so the sender knows what is happening and can act accordingly. Transparency in the workflow is essential to enable senders and receivers to work together to provide the best patient experience possible. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--receiving.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--receiving.page.md new file mode 100644 index 00000000..1f1e417d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--receiving.page.md @@ -0,0 +1,8 @@ +--- +topic: core-ErrorHandling-IntR-1.0.7 +--- + +## {{page-title}} + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--sending.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--sending.page.md new file mode 100644 index 00000000..0bcdf3ff --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/BaRS-interactions--sending.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-IntS-1.0.7 +--- + +## {{page-title}} + +In the event of an error; the BaRS API always responds with an HTTP response code (issue.code) and an OperationOutcome code (issue.details.code) within an OperationOutcome FHIR Resource - conditioned on it being reached successfully. Assuming the sender's access token (obtained from the Oauth 2 endpoint) is accepted and the request is valid, the BaRS API processes the request. Depending on the operation, BaRS proxies the request to the receiver. Depending on where in this flow the error occurs, the OperationOutcome codes is prefixed with one of the following three items, indicating where the cause of the error resides: + +- SEND - The sending application is the cause of the error + - These items are only be generated by the API to indicate there was an issue with the senders request +- PROXY - The BaRS Service is the source of the error + - These items generally generated to indicate there was an error internal to BaRS + - The information within the response will help identify the cause +- REC - The receiver is the source of the error + - These are generated by the receiver, however if there is a scenario where the receiver cannot respond, these are generated by the proxy to clarify the source of the problem + - The information within the response helps identify the cause + +These OperationOutcome codes are part of a value set to be used within a OperationOutcome FHIR Resource (issue.details.code) which forms the body of the response. Below is an example of an error response: + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Diagnostics-Text.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Diagnostics-Text.page.md new file mode 100644 index 00000000..765fa5fc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Diagnostics-Text.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-Diag-1.0.7 +--- + +### Diagnostics text + +The purpose of the two code values are to give high level information as to the nature and source of an error response. The diagnostics text is to contain clear and concise information regarding the exact cause of the problem encountered, where possible. This should include information on the problem encountered, internal debug details such as error message and texts are encouraged, exposing stack traces is not. The diagnostics field does not include any patient identifiable information at any time. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Example-Errors.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Example-Errors.page.md new file mode 100644 index 00000000..87aadd8d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Example-Errors.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-Examples-1.0.7 +--- + +### Example errors + +The table below contains some further examples of error codes, their associated Operation Outcomes codes and and potential diagnostics texts. + +| HTTP Code | Code Value | Description | Example diagnostics text | +|-----------|-----------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| 400 | SEND_BAD_REQUEST | The API was unable to process the request. | "The API was unable to process the request: <further diagnostics information, error message/error text>" | +| | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | "<Receiver Identifier (ODS)> was unable to process the request: <further diagnostics information, error message/error text>" | +| | PROXY_BAD_REQUEST | Though Unlikely, BaRS, having accepted the message; has received a 400 response from an internal component. | "BaRS was unable to process the request: <further diagnostics information, error message/error text>" | +| 404 | PROXY_NOT_FOUND | The resource was not found within BaRS. | "The resource was not found within BaRS: <further diagnostics information, error message/error text>" | +| | REC_NOT_FOUND | The resource was not found at the Receiver. | "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>" | +| 409 | REC_CONFLICT | Example: Sender is trying to Book an appointment in a slot that doesn't allow booking. | "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>" | +| 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | "The Request was not recognized by the API: <further diagnostics information, error message/error text>" | +| | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | "The Request was not recognised by the Receiver - <Receiver identifier (ODS)>: <further diagnostics information, error message/error text>" | +| | PROXY_NOT_IMPLEMENTED | BaRS did not recognize the request. | "This Request was not recognized by the proxy: <further diagnostics information, error message/error text>" | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Bundle-Processing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Bundle-Processing.page.md new file mode 100644 index 00000000..8721a472 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Bundle-Processing.page.md @@ -0,0 +1,490 @@ +## Bundle processing POST /$process-message + +This section defines unhappy path scenarios for when a receiver processes a message. This includes a reiteration of Transaction Integrity, workflow variable validations and data conflicts. + + +### HTTP Headers +Below is a simplified example of how how to handle the Transaction Integrity HTTP headers. +**Logic** +``` c# +{ + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 +} +``` +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/HTTP-Header-logic-1.0.0.svg) + + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | +|------------------|-----------------|------------|-------------------------------------------------------------------| +| 400 | REC_BAD_REQUEST | invalid | The request headers are not valid. | +| 400 | REC_BAD_REQUEST | required | The request headers are not present. | +| 409 | REC_CONFLICT | duplicate | The message has been identified as having already been processed. | + +**400 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "invalid", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_BAD_REQUEST" +          } +        ] +      }, +      "diagnostics": "Transaction Integrity headers were not present" +    } +  ] +} +``` + +**409 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "duplicate", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_CONFLICT" +          } +        ] +      }, +      "diagnostics": "This message has been recognised as having already been successfully processed." +    } +  ] +} +``` + +### Message workflow variable validations + +Many scenarios are covered by this one example, the full pseudo code can be located at the end of this page. + +**logic** +```c# +{ + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } +``` + +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/WorkflowVariable-FailureScenarios-1.0.0.svg) + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | +|------------------|-----------------|------------|-------------------------------------------------------------------------------------| +| 400 | REC_BAD_REQUEST | invariant | A combination of workflow variables has lead to a non-standard or unknown workflow. | + +**400 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "invariant", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_BAD_REQUEST" +          } +        ] +      }, +      "diagnostics": "A content validation rule failed, Validation message requires a Careplan.satus of 'active'" +    } +  ] +} +``` + +### Data Conflicts + +Receiving an update can present complications under certain conditions if data has been updated locally - for example, If you have updated a record locally prior to an update message being received and a conflict is then encountered. + +**Logic** +``` c# +if (Message == "update") +{ + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } +``` +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/DataConflict-FailureScenarios-1.0.0.svg) + + + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | +|------------------|-----------------|------------|--------------------------------------------------------------| +| 409 | REC_CONFLICT | conflict | local data updates conflict with the updates in the message. | + +**409 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "conflict", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_CONFLICT" +          } +        ] +      }, +      "diagnostics": "Information received has been updated locally and may cause loss, or presents a conflict, of data" +    } +  ] +} +``` + +## Full Pseudo Code example +Below is the Full Pseudo Code example of the details seen in the workflow variables section. + + +<details><summary>> <b class="barslink">Click here to show example</b></summary> + +```c# +Receive_Request +{ + initialise_variable "messageType" + initialise_variable "MessageReason" + initialise_variable "RequestType" + + //HTTP_Headers + { + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + //Bundle + { + if(Bundle.meta.versionID is null) + OperationOutcome.issue.code = "invariant" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if!(Bundle.meta.versionID in versionID.supported) + OperationOutcome.issue.code = "not-supported" + throw exception with "REC_UNPROCESSABLE_ENTITY" + then return with HTTP.ResponseCode 422 + } + //Contents; + { + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + else if(Encounter.Status.In("triaged","in-progress") + {RequestType = "Im Receiving a new Validation Request";} + else + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + break; + case "Referral": + if (Careplan.status != "completed") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + else if(Encounter.Status.In("triaged","finished")) + RequestType = "Im Receiving a new Referral" + else + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if (MessageHeader.reason.code == "update") + { + switch(ServiceRequest.category) + { + case "Validation": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled validation request";} + else if(ServiceRequest.status.In("active","on-hold")) + {RequestType = "im receiving an update to a validation request";} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + case "Referral": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled referral"} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + + } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400} + break; + case "servicerequest-response": + if (MessageHeader.Response is null ) + { + RequestType = "Invalid servicerequest-response" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + else if ( !Message.Response.identifier.existsLocally()) + { + RequestType = "none or invalid response ID" + OperationOutcome.issue.code = "not-found"//A content validation rule failed + throw exception with "REC_NOT_FOUND" + then return HTTP.ResponseCode 404; + } + switch (ServiceRequest.Category) + { + case "Referral": + if (ServiceRequest.status == "revoked" && MessageHeader.reason.code == "new") + { RequestType = "im receiving a Safeguarding DNA response (noshow)" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + break; + case "Validation": + if(!AnyEncounter.Originates.Local && Encount.Count()<=3) + { + if (MessageHeader.Reason.code == "new" && ServiceRequest.status == "active" && MessageHeader.FocusEncounter.status=="in-progress") + {Request Type = "im receiving a Validation Response interim update" } + else if (MessageHeader.Reason.code.In ("new","update") && ServiceRequest.status == "completed" && MessageHeader.FocusEncounter.status.In("triaged","complete") + {Request Type = "im receiving a final Validation Response" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if(MessageHeader.FocusEncounter.status = "triaged" && ServiceRequest.status == "revoked" && MessageHeader.Reason.code.In("new","update")) + { RequestType = "im receiving a Rejected validation response" } // a new encounter here is an edge case. + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + case "booking-request": + if (MessageHeader.Reason.code== "new" && Appointment.Status == "booked") + if(slot.IsFree()) + {RequestType = "Im Receiving a new booking.";} + else + { + OperationOutcome.issue.code = "conflict" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + else if (MessageHeader.Reason.code == "update") + MessageHeaderIsUpdate = true; + switch (Appointment.Status) + { + case "cancelled": + RequestType = "Im Receiving a booking cancellation." + break + case "entered-in-error": + RequestType = "Im Receiving a booking cancellation." + break + case "booked": + RequestType = "Im Receiving an update to a booking." + break + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + break; + } + else + { + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + } + break; + case "booking-response": + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + } + + } + //Submit //rework this + { + + if (Message == "update") + { + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + foreach (Entry in Bundle) + { + if (currentLocalData.Item.exists) + { + if (currentLocalData.LastUpdated > originaRequest.Received) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + if(Entry.LastUpdated > currentLocalData.Item.meta.LastUpdated && Entry.fullUrl = currentLocalData.Item.fullUrl) + currentLocalData.Item = Entry.Item + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + else + ignore + } + else + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + } + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + else + { + foreach(Entry in Bundle) + { + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + } + } +} +``` + +</details> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Capability-Statement.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Capability-Statement.page.md new file mode 100644 index 00000000..9afe6fc5 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Capability-Statement.page.md @@ -0,0 +1,9 @@ +## Check Capabilities GET /metadata + +Foreseen failure scenarios are limited for this interaction, in the scope of the receiver. The majority of failures for this stage of workflow is mainly going to be at the sender ascertaining the capabilities of the Receiver and whether they can interact. This is considered the purpose of this endpoint and therefore is not considered a failure. + +GET /metadata is the only Endpoint which does not need a Target identifier. Not providing a Target Identifier will result in the Capability Statement of the BaRS Proxy itself. Providing one will expose potential failure scenarios defined in {{pagelink:Core-ErrorHandling-MessageRouting-1.1.3}} . There are also no query or path parameters required meaning the potential failure scenarios are fewer however Transaction Integrity headers are still required. + +### interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/metadata-FailureScenarios-1.0.0.svg) \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Appointment.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Appointment.page.md new file mode 100644 index 00000000..7a0d4690 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Appointment.page.md @@ -0,0 +1,34 @@ +## GET /Appointment +This section defines the failure scenarios for GET /Appointment. There are two ways to call this endpoint. Either with a query parameter, or a path parameter. This section covers both of those methods. + +### Rules + +**GET /Appointment** +* query parameter identifier patient.identifier MUST be included. +* query parameter identifier patient.identifier MUST be a system:value. example: https://fhir.nhs.uk/Id/nhs-number|4857773456 + +**GET /Appointment/{id}** +* id in path MUST be a valid GUID/UUID + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/Appt-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**path id in GET /Appointment{id}** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | REC_BAD_REQUEST | value | The identifier was in the incorrect format. | Receiver | +| 404 | REC_NOT_FOUND | not-found | The resource requested was not found. | Receiver | + +**patient:identifier parameter identifier in GET /Appointment** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | SEND_BAD_REQUEST | value | the identifier was in the incorrect format. | API | +| 400 | REC_BAD_REQUEST | value | the identifier was in the incorrect format. | Receiver | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--MessageDefinition.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--MessageDefinition.page.md new file mode 100644 index 00000000..f0451263 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--MessageDefinition.page.md @@ -0,0 +1,33 @@ +## GET /MessageDefinition +Message definition includes only one additional parameter and therefore there are less scenarios to cover. + +### Rules +* The context query parameter must be present. + * For current use cases this will always match the value in the NHSD-Target-Identifier header. This could could not always be the case in future. + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/MessageDefinition-FailureScenarios-1.0.0.svg) + +### Errors by parameter + +**context** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|--------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | no context parameter was given. | API | +| 400 | REC_BAD_REQUEST | required | no context parameter was given. | Receiver | +| 400 | REC_BAD_REQUEST | invalid | the context parameter value was invalid (format) | Receiver | +| 400 | REC_BAD_REQUEST | value | the context parameter value was invalid (format) | Receiver | +| 404 | REC_NOT_FOUND | not-found | the context parameter given returned no results. | Receiver | + +### Standard errors +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| 400 | REC_BAD_REQUEST | invalid | Although this should be caught at the proxy/API, should a request be received with no X-Request-Id or X-Correlation-Id be received this check should be in place. (BaRS without the Proxy) | Receiver | +| 400 | REC_BAD_REQUEST | value | As above, but the value is not a GUID/UUID. | Receiver | +| 401 | REC_UNAUTHORIZED | security | Access Control issue. | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | exception | an unhandled exception has been encountered. | Receiver / API Injected | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The service(s) is unavailable but is able to respond as such, otherwise injected. | Receiver / API Injected | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--ServiceRequest.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--ServiceRequest.page.md new file mode 100644 index 00000000..3c680a59 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--ServiceRequest.page.md @@ -0,0 +1,34 @@ +### GET /ServiceRequest +This section defines the failure scenarios for GET /ServiceRequest. As with GET /Appointment, there are two ways to call this endpoint. Either with a query parameter, or a path parameter. This section covers both of those methods. + +### Rules + +**GET /ServiceRequest** +* query parameter identifier patient.identifier MUST be included. +* query parameter identifier patient.identifier MUST be a system:value. example: https://fhir.nhs.uk/Id/nhs-number|4857773456 + +**GET /ServiceRequest/{id}** +* id in path MUST be a valid GUID/UUID + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/SR-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**path id in GET /ServiceRequest{id}** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | REC_BAD_REQUEST | value | The identifier was in the incorrect format. | Receiver | +| 404 | REC_NOT_FOUND | not-found | The resource requested was not found. | Receiver | + +**patient:identifier parameter identifier in GET /ServiceRequest** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | SEND_BAD_REQUEST | value | the identifier was in the incorrect format. | API | +| 400 | REC_BAD_REQUEST | value | the identifier was in the incorrect format. | Receiver | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Slots.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Slots.page.md new file mode 100644 index 00000000..487b918e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/GET--Slots.page.md @@ -0,0 +1,66 @@ +## GET /Slots +Get /Slots has added complexity compared to previous endpoints in this section. With a myriad of available and required parameters there is a potential for many scenarios. + +### Rules +* Schedule:actor:HealthcareService - Must be included. + * For current use cases this will likely match the value in the NHSD-Target-Identifier header. This may not always be the case in future. +* _include - There is a minimum of the following 2 _includes required for current Applications. + * Slot:schedule + * Schedule:actor:HealthcareService +* start - The start parameter must be used twice, and adds the need for handling problematic requests with its use (too wide a time frame, as an example). + * Must use the [FHIR dateTime](https://www.hl7.org/fhir/datatypes.html#primitive) format which includes an offset. + * Must be UTC + * Must have a greater than and a less than. +* status - The status parameter must be used. + * multiple statuses must be comma separated. + * FOT allows free or busy. + +### Interaction + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/Slot-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**Schedule:actor:HealthcareService** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST? | required | The parameter value was not included in the request. (This parameter is not currently marked as required. ) | API and Receiver | +| 400 | REC_BAD_REQUEST | value / invariant | The parameter value was incorrect or wrong. | Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | +| 404 | REC_NOT_FOUND | not-found | This service does not exist. | Receiver | + +**_include** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-------------------------------------------------------------------------------------------------------------|------------------| +| 400 | REC_BAD_REQUEST | required | the minimum required includes are not present. | API and Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | + +**start** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------------------------|------------|-------------------------------------------------------------------------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | required | Date range was not present. | API and Receiver | +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | value | DateTimes in the requested start time range requested was invalid. | API and Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | +| 422 | REC_UNPROCESSABLE_ENTITY | too-costly | The start time range requested is too wide. | Receiver | + + +**status** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------------------------|------------|------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | required | status not present. | API and Receiver | +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | value | status value requested is invalid. | API and Receiver | + +**Common Failures** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| 400 | REC_BAD_REQUEST | invalid | Although this should be caught at the proxy/API, should a request be received with no X-Request-Id or X-Correlation-Id be received this check should be in place. | Receiver | +| 400 | REC_BAD_REQUEST | value | As above, but the value is not a GUID/UUID. | Receiver | +| 401 | REC_UNAUTHORIZED | security | Access Control issue. | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | exception | an unhandled exception has been encountered. | Receiver / API Injected | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The service is unavailable but is able to respond as such. | Receiver / API Injected | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/General-Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/General-Failure-Scenarios.page.md new file mode 100644 index 00000000..4e3683c6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/General-Failure-Scenarios.page.md @@ -0,0 +1,22 @@ +## General Failure Scenarios +This section will define errors that could be seen in any given step and shared from function to function without context. All interactions MUST follow these rules as such they may be listed in different sections. + + +| HTTP Status Code | HTTP Error Code | issue.Code | Scenario | Source | +|------------------|-----------------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| 400 | SEND_BAD_REQUEST | required | Content invalid against the specification or a profile. For example a required parameter or header is not provided. | API | +| 400 | REC_BAD_REQUEST | value | a header value or parameter is invalid. (these are defined in each specific scenario) | Receiver | +| 400 | REC_BAD_REQUEST | not-supported | in FOT for when a function or feature in the standard is not yet supported. | Receiver | +| 400 | PROXY_BAD_REQUEST | structure | When Base-64 decoding of the NHSD-Target-Identifier header fails. | API | +| 400 | PROXY_BAD_REQUEST | structure | The NHSD-Target-Identifier header doesn't adhere to the schema | API | +| 401 | SEND_UNAUTHORIZED | login / expired | The sender has not provided a token or it has expired or is otherwise invalid. | API | +| 405 | SEND_METHOD_NOT_ALLOWED | not-supported | using the wrong http verb. For example GET instead of POST | API | +| 406 | SEND_NOT_ACCEPTABLE | processing | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. Versions in Accept or content.<br><br>Version is not present in FOT and should be ignored in FOT if presented. Post FOT it MUST be evaluated. | API | +| 406 | REC_NOT_ACCEPTABLE | processing | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. Versions in Accept or content.<br><br>Version is not present in FOT and should be ignored in FOT if presented. Post FOT it MUST be evaluated. | Receiver | +| 429 | SEND_TOO_MANY_REQUESTS | throttled | when rate limiting is applied. | API | +| 409 | REC_TIMEOUT | timeout | Injected when a 504 is generated in the proxy due to a receiver timing out on a response. | API Injected | +| 500 | REC_SERVER_ERROR | transient | An unexpected exception has occurred during processing at the receiver. | Receiver/ API Injected | +| 500 | PROXY_SERVER_ERROR / SERVER ERROR | transient | An unexpected exception has occurred during processing internally. | API | +| 501 | REC_NOT_IMPLEMENTED | not-supported | The receiver has not yet implemented that endpoint or functionality. | Receiver | + +<a href="#" onclick="history.back()">back</a> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Index.page.md new file mode 100644 index 00000000..17d48319 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-failure_scenarios-1.0.7 +--- \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Introduction.page.md new file mode 100644 index 00000000..dd6beb45 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Introduction.page.md @@ -0,0 +1,11 @@ +<a href="#" onclick="history.back()">back</a> + +## Failure Scenarios + +This page defines the foreseen failure scenarios within the BaRS standard and its implementations. The scenarios are broken down by endpoint and describe which HTTP Status Code, BaRS HTTP Error Code and FHIR issue.code to use for each eventuality. In any case, the diagnostics text should reflect the scenarios given and not necessarily be used verbatim where examples are given. + +The rationale, described in the {{pagelink:core-failure_scenarios-1.0.7, text:error handling}} section is that as much information on the nature of the failure as possible is provided in a standard way. + +Each scenario has a Source to state whether it is the BaRS Proxy or the Receiver which is generating the error. In scenarios where a SEND prefix is used, the sender is not adhering to the API specification in one way or another. These codes are held within OperationOoutcome.issue.details.code and use the http-error-codes value set. + +Note: in future, the PROXY prefix will no longer be used, and all errors from the Proxy will use a code with no prefix. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Message-Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Message-Routing.page.md new file mode 100644 index 00000000..34628c7d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/Message-Routing.page.md @@ -0,0 +1,63 @@ +--- +topic: Core-ErrorHandling-MessageRouting-1.0.7 +--- + +## Endpoint Catalogue - Message routing. + +<div id="message_routing"></div> + +Below is a diagram of error locations coupled with scenarios with regards to the routing of messages by the proxy using the Endpoint Catalogue. The below diagram is generic and not specific to any particular API endpoint. Most requests will be subject to the errors that can be encountered during message routing. + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/EndpointCatalogue-FailureScenarios-1.0.0.svg) + +### SEND at the API +The SEND prefix indicates an issue caught before any internal routing or processing occurs, it communicates a problem with the format of the request, not adhering to the API Spec as an example. + +These scenarios can be found in other areas however if more required headers are added for endpoints this may be expanded. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-----------------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 400 | SEND_BAD_REQUEST | required | The X-Request-Id or the X-Correlation-Id was not included or the NHSD-Target-Identifier was not included (depending on the endpoint being called). | API | +| 401 | SEND_UNAUTHORIZED | security | The user or system was not able to be authenticated, either the access token was invalid, or not provided. | API | +| 401 | SEND_UNAUTHORIZED | unknown | No Access token was provided. | API | +| 403 | SEND_FORBIDDEN | forbidden | The access token was provided, but BaRS is not enabled. | API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | not-found | Endpoint on the API does not exist. This would be a Proxy or non-prefixed response. there is no SEND code for 404 in the value set. | API | +| 500 | PROXY_SERVER_ERROR / SERVER_ ERROR | exception | Unexpected error, would expect this to happen internally so this is likely never going to be needed for a SEND and thus unprefixed or PROXY is used here. | API | +| 503 | PROXY_UNAVAILABLE / SERVICE_UNAVAILABLE | transient | unlikely to get a OperationOutcome here. | API | + +### PROXY/NONE within the BaRS proxy + + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-----------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | invalid | The X-Request-Id or the X-Correlation-Id was invalid. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | invalid | When Base-64 decoding of the NHSD-Target-Identifier header fails. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | structure | The NHSD-Target-Identifier header doesn't adhere to the schema | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | required | A required item is missing. depending on the request/scenario this may be caught by the SEND details above. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | structure | A structural issue in the content such as wrong namespace, unable to parse the content completely - for example the Target identifier is malformed.| API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | not-found | The resource requested does not exist. For example; the target endpoint does not exist in the Endpoint Catalogue. | API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | multiple-matches | The Target Identifier found two endpoints, this would be an issue with the management of the Endpoint catalogue. | API | +| 500 | PROXY_SERVER_ERROR / SERVER_ERROR | exception | A sub-service encountered an unhandled exception. | API | +| 503 | PROXY_UNAVAILABLE / SERVICE_UNAVAILABLE | transient | A sub-service was unavailable. | API | + +### REC injected at the proxy +When a failure response is received when attempting to forward the request to the desired receiver but no OperationOutcome is included during a failure scenario. For example, a Timeout. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| 408 | REC_TIMEOUT | timeout | The connection to the Receiver timed out. | Receiver/ Injected at API | +| 500 | REC_SERVER_ERROR | exception | Generic should a 500 response be received but no operation outcome included. | Receiver / Injected at API | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The response from the receiver was a 503, with no detail. Also useful if there is a connection failure such as the endpoint not being found, or failing to resolve. | Receiver / Injected at API | + +### REC at the receiver. +Failure responses generated by the receiver. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|--------------------------------------------------------------|----------------------------| +| 401 | REC_UNAUTHORIZED | security | Access Control | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | too costly | The request was deemed to costly to process by the receiver. | Receiver | +| 500 | REC_SERVER_ERROR | exception | unhandled exception. | Receiver / Injected at API | +| 500 | REC_SERVER_ERROR | no-store | internal data storage issue. | Receiver / Injected at API | + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/toc.yaml new file mode 100644 index 00000000..116448ef --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios-1.0.x/toc.yaml @@ -0,0 +1,20 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Message Routing + filename: Message-Routing.page.md +- name: Capability Statement + filename: Capability-Statement.page.md +- name: GET /MessageDefinition + filename: GET--MessageDefinition.page.md +- name: GET /Slots + filename: GET--Slots.page.md +- name: GET /Appointment + filename: GET--Appointment.page.md +- name: GET /ServiceRequest + filename: GET--ServiceRequest.page.md +- name: Bundle Processing + filename: Bundle-Processing.page.md +- name: General Failure Scenarios + filename: General-Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios.page.md new file mode 100644 index 00000000..445446a3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Failure-Scenarios.page.md @@ -0,0 +1,7 @@ +--- +topic: core-EHFailureScenarios-1.0.7 +--- + +## Failure Scenarios + +For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.0.7, text: Failure Scenarios}} section. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Index.page.md new file mode 100644 index 00000000..29461e46 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-ErrorHandling-1.0.7 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Introduction.page.md new file mode 100644 index 00000000..422546c7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-introduction-1.0.7 +--- + +# Error Handling + +There are multiple points where an error may occur to prevent booking and referral operations from completing successfully. This section provides error handling guidance for BaRS and its associated API. For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.0.7}} section in addition to information included on this page. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/OperationOutcome-Example.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/OperationOutcome-Example.page.md new file mode 100644 index 00000000..b73bbf17 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/OperationOutcome-Example.page.md @@ -0,0 +1,61 @@ +--- +topic: core-ErrorHandling-OpOut-1.0.7 +--- + +### OperationOutcome Example + +<json> + + { + + "resourceType": "OperationOutcome", + + "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + + "meta": { + + "profile": [ + + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + + ] + + }, + + "issue": [ + + { + + "severity": "error", + + "code": "invalid", + + "details": { + + "coding": [ + + { + + "system": "https://fhir.nhs.uk/CodeSystem/http-error-codes", + + "code": "PROXY_BAD_REQUEST", + + "display": "400 - PROXY_BAD_REQUEST" + + } + + ] + + }, + + "diagnostics": "BaRS encountered a conflict: <further diagnostics information, error message/error text>" + + } + + ] + + } +</json> + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Overview.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Overview.page.md new file mode 100644 index 00000000..486058bd --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Overview.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-Overview-1.0.7 +--- + +### Overview + +Error codes (HTTP Response codes) can be caused by any of the three parties involved in a transaction using the Booking and Referral API. Error codes will be accompanied by a OperationOutcome FHIR resource where possible. Error codes and their relative operation outcome codes are meant for developer use only - they should not be presented to end-users. Instead, sending applications should interpret the two codes and provide user-friendly resolution steps on failure. Sender and receiver systems should record the detailed error codes in local logs in order to support service incident investigation. There are scenarios where an operation outcome may not be applicable or available. A HTTP Response code should always be returned. + +Operation Outcome Codes are prefixed with an indicator of the source of the error help identify where a problem may be. + +The following table provides a high-level overview of each stage in the booking and referral process from the perspective of a sending application. + +| Interaction | Error Handling Overview | Operation Outcome Prefix | +|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| +| Sender querying a Service Discovery tool | As an existing solution, the DOS APIs return a number of significant errors specific to the actual API failing. These are all self-contained in that process. These are documented in a link below and will not affect the ongoing activity unless the data returned in the query is erroneous and then cause the next stages of the process to either fail or not be possible. | N/A | +| Sender interactions with the BaRS API | Interactions with the BaRS API may fail due to, but not limited to, the following reasons: The service being unavailable to the sender, the Sender being unauthenticated, the Sender reaching or exceeding a rate limit, or badly formed requests being sent. | SEND | +| BaRS Service internal interactions | Depending on the operation requested, internal interactions may fail within the proxy due to non-existent resources, service failures or data related issues within the Senders payload. | PROXY | +| BaRS interaction with the Receiver | In the event BaRS successfully proxies a request through to a Receiver, the Receiver may still respond with an error due to authentication, authorization or data related issues within the Senders payload, assuming the endpoint is available. | REC | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Receiver-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Receiver-Responsibilities.page.md new file mode 100644 index 00000000..f429d6e8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Receiver-Responsibilities.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-RecResp-1.0.7 +--- + +### Receiver responsibilities + +- Receiving APIs should adhere to the HTTP Response code and Operational Outcome code paradigm described above in the event that an error response needs to be returned +- The sender should be able to ascertain what went wrong and why in the event of an error +- Receiving endpoints should use the REC prefixed Operation Outcome codes and provide clear and concise diagnostics texts +- There should be no need to omit or use a different prefix when responding to requests +- There will be times where it is not possible to generate a response in the above format +- In the event this occurs, a relevant HTTP response code should be the minimum +- Log errors locally for incident investigation by IT support staff +- If the request is problematic, this should be logged specifically as a sender system issue +- Details of the sender system should be logged to support investigation +- As a minimum, the Operation Outcome must include: + - The HTTP Response code + - The Operation Outcome code + - Clear and concise diagnostics information + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Sender-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Sender-Responsibilities.page.md new file mode 100644 index 00000000..87303f86 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/Sender-Responsibilities.page.md @@ -0,0 +1,14 @@ +--- +topic: core-ErrorHandling-SendResp-1.0.7 +--- + +### Sender responsibilities + +- Log errors returned for incident investigation by IT support staff +- Ensure sufficient information for appropriate local incident management is captured +- Communicate with receivers should an unexpected error be received consistently (REC) +- Communicate with NHS Digital should a persistent error state be encountered from BaRS (PROXY) +- Inform end-user with a suitable message appropriate to the business flow, for example: critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/toc.yaml new file mode 100644 index 00000000..cd1e4b7a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Error-Handling/toc.yaml @@ -0,0 +1,26 @@ +- name: + filename: Failure-Scenarios-1.0.x +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Overview + filename: Overview.page.md +- name: BaRS interactions (sending) + filename: BaRS-interactions--sending.page.md +- name: OperationOutcome Example + filename: OperationOutcome-Example.page.md +- name: Diagnostics Text + filename: Diagnostics-Text.page.md +- name: Example Errors + filename: Example-Errors.page.md +- name: Sender Responsibilities + filename: Sender-Responsibilities.page.md +- name: BaRS interactions (receiving) + filename: BaRS-interactions--receiving.page.md +- name: Receiver Responsibilities + filename: Receiver-Responsibilities.page.md +- name: OperationOutcome Example + filename: OperationOutcome-Example-duplicate-2.page.md +- name: Failure Scenarios + filename: Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Index.page.md new file mode 100644 index 00000000..f5de480d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Index.page.md @@ -0,0 +1,176 @@ +--- +topic: design-core-1.0.7 +--- + +# BaRS Core 1.0.6 + +BaRS consists of BaRS Core that provides a core set of functionality and BaRS Applications that provide distinct functionality for each use case. + +You will find here a set of documentation, specifications and services that describe and support all the fundamental components of the standard that are always the same for all use cases or care journeys. Examples include the underlying capabilities and patterns and transport layer elements such as security, authorisation and access control. + +<details> +<summary>> <b class="barslink">Expand for full Core directory</b></summary> + +• {{pagelink:design-core-1.0.7 , text: Core 1.0.6}}</br> +  • {{pagelink:core-EndToEndWorkflow-1.0.7 , text:End to end workflow}}</br> +    • {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.0.7 , text:Service Discovery}}</br> +    • {{pagelink:core-EndToEndWorkflow-BaRSAuth-1.0.7 , text:Authenticate with BaRS}}</br> +    • {{pagelink:core-EndToEndWorkflow-API-1.0.7 , text:BaRS FHIR API}}</br> +    • {{pagelink:core-EndToEndWorkflow-HTTPHeader-1.0.7 , text:HTTP Header}}</br> +    • {{pagelink:core-EndToEndWorkflow-Routing-1.0.7 , text:Routing}}</br> +    • {{pagelink:core-EndToEndWorkflow-Auth-1.0.7 , text:Authentication and Authorisation}}</br> +    • {{pagelink:core-EndToEndWorkflow-Transactional-Integrity-1.0.7 , text:Transactional Integrity}}</br> +    • {{pagelink:core-EndToEndWorkflow-HTTPResponseHeader-1.0.7 , text:HTTP Response Headers}}</br> +    • {{pagelink:core-EndToEndWorkflow-Processing-1.0.7 , text:Processing Requests}}</br> +    • {{pagelink:core-EndToEndWorkflow-Responses-1.0.7 , text:Responses}}</br> +    • {{pagelink:core-EndToEndWorkflow-ReversingRoles-1.0.7 , text:Reversing Roles}}</br> +    • {{pagelink:core-EndToEndWorkflow-AsyncWorkflow-1.0.7 , text:Asynchronous Workflow}}</br> +  • {{pagelink:core-FunctionalityRequirements-1.0.7 , text:Core Functionality Requirements.}}</br> +    • {{pagelink:core-FunctionalityRequirements-All-1.0.7 , text:All}}</br> +    • {{pagelink:core-FunctionalityRequirements-Caching-1.0.7 , text:Caching}}</br> +    • {{pagelink:core-FunctionalityRequirements-BookingSender-1.0.7 , text:Booking Sender}}</br> +    • {{pagelink:core-FunctionalityRequirements-BookingReceiver-1.0.7 , text:Booking Receiver}}</br> +    • {{pagelink:core-FunctionalityRequirements-ReferralSender-1.0.7 , text:Referral Sender}}</br> +    • {{pagelink:core-FunctionalityRequirements-ReferralReceiver-1.0.7 , text:Referral Receiver}}</br> +  • {{pagelink:core-FHIRUsage-1.0.7 , text:BaRS FHIR Usage}}</br> +    • {{pagelink:core-FHIRUsage-Framework-1.0.7 , text:Frameworks}}</br> +    • {{pagelink:core-FHIRUsage-REST-1.0.7 , text:REST}}</br> +    • {{pagelink:core-FHIRUsage-FHIR-Operations-1.0.7 , text:FHIR Operations}}</br> +    • {{pagelink:core-FHIRUsage-Process-Message-1.0.7 , text:$process-message}}</br> +    • {{pagelink:core-FHIRUsage-bundle-1.0.7 , text:Bundle}}</br> +    • {{pagelink:core-FHIRUsage-JourneyID-1.0.7 , text:Journey ID}}</br> +    • {{pagelink:core-FHIRUsage-Time-1.0.7 , text:How to handle times}}</br> +    • {{pagelink:core-FHIRUsage-LastUpdated-1.0.7 , text:LastUpdatedDate}}</br> +  • {{pagelink:core-Security-1.0.7 , text:Security and Authorisation}}</br> +    • {{pagelink:core-Security-Sender-1.0.7 , text:Sender}}</br> +    • {{pagelink:core-Security-Oauth-1.0.7 , text:OAuth Endpoints}}</br> +    • {{pagelink:core-Security-Receiver-1.0.7 , text:Receiver}}</br> +    • {{pagelink:core-Security-Auth-1.0.7 , text:Authorisation}}</br> +  • {{pagelink:core-ErrorHandling-1.0.7 , text:Error Handling}}</br> +    • {{pagelink:core-ErrorHandling-Overview-1.0.7 , text:Overview}}</br> +    • {{pagelink:core-ErrorHandling-IntS-1.0.7 , text:BaRS interactions(sending)}}</br> +    • {{pagelink:core-ErrorHandling-OpOut-1.0.7 , text:OperationOutcome Example}}</br> +    • {{pagelink:core-ErrorHandling-Diag-1.0.7 , text:Diagnostic Text}}</br> +    • {{pagelink:core-ErrorHandling-Examples-1.0.7 , text:Example Errors}}</br> +    • {{pagelink:core-ErrorHandling-SendResp-1.0.7 , text:Sender Responsibilities}}</br> +    • {{pagelink:core-ErrorHandling-IntR-1.0.7 , text:BaRs interactions(receiving)}}</br> +    • {{pagelink:core-ErrorHandling-RecResp-1.0.7 , text:Receiver responsibilities}}</br> +    • {{pagelink:core-failure_scenarios-1.0.7 , text:Failure Scenarios}} </br> +  • {{pagelink:Core-TransactionalIntegrity-1.0.7 , text:Transactional Integrity}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Initial-1.0.7 , text:Initial Request}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Update-1.0.7 , text:Sending an update}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Feedback-1.0.7 , text:Feedback (response) requests}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Retry-1.0.7 , text:Retry Scenario}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Onward-1.0.7 , text:Onwards Referrals}}</br> +    • {{pagelink:Core-TransactionalIntegrity-retry-1.0.7 , text:Definition of a Retry}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Receiver-1.0.7 , text:Receiver responsibilities}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Sender-1.0.7 , text:Sender responsibilities}}</br> +    • {{pagelink:core-TIFailureScenarios-1.0.7 , text:Failure Scenarios}}</br> +  • {{pagelink:core-NFR-1.0.7 , text:Non functional Requirements}}</br> +    • {{pagelink:core-NFR-Requirements-1.0.7 , text:Requirements}}</br> +    • {{pagelink:core-NFR-Processing-Time-1.0.7 , text:Processing Times}}</br> +  • {{pagelink:Core-StandardPattern-1.0.7 , text:Standard Pattern - Composite Messages}}</br> +    • {{pagelink:core-SPComposites-1.0.7 , text:Standard Pattern for Composites}}</br> +    • {{pagelink:core-SPMessageHeader-1.0.7 , text:Message Headers}}</br> +    • {{pagelink:core-SPCancellation-1.0.7 , text:Cancellation}}</br> +    • {{pagelink:core-SPUseCaseCategories-1.0.7 , text:Use Case Categories}}</br> + +</details> + +<hr> + + + + +# End to end workflow +This section covers the core elements of workflow outlined within the Booking and Referral Standard. There are two caveats when reading this: + +- Workflow is dependent on its Application or use case, for example in 999 - CAS validation, there is no step to perform a booking. See the relevant use case page in the +{{pagelink:applications, text:BaRS Applications}} section. + + +- The order of workflow is interchangeable. It is possible to: + - make a referral before a booking + - refer without booking + - book without referring + +For more detail please visit the {{pagelink:core-EndToEndWorkflow-1.0.7, text: End to End Workflow}} section. + +<hr> +<br> + + +# Core Functionality Requirements +BaRS should provide different functionality depending on: + +- its {{pagelink:applications, text:Application or use case}} +- whether it acts as a sender or receiver + + +This list of functionality will expand in later versions of BaRS. + +There are requirements in each of the central areas of functionality which every BaRS Application must adopt: + +For more detail please visit the {{pagelink:core-FunctionalityRequirements-1.0.7, text: Core Functionality Requirements}} section. + +<hr> +<br> + +# Content Negotiation + +Content Negotiation within BaRS leverages multiple variables within the CapabilityStatement and MessageDefinition to ensure that a Sender and a Receiver are Compatible. Though some of this is possible due to the Versioning Negotiation, Content Negotiation further builds on that concept with the capabilities published by the server and the identification of message definitions and use cases therein to ensure a workflow can be completed. + +For more detail please visit the {{pagelink:core-content-negotiation, text: Content Negotiation}} section. + +<hr> +<br> + +# BaRS FHIR usage +BaRS uses [FHIR](https://digital.nhs.uk/services/fhir-uk-core) to achieve interoperability between healthcare IT systems. This section explains how BaRS makes use of some key FHIR concepts which need to be understood by developers implementing the standard. + +For more detail please visit the {{pagelink:core-FHIRUsage-1.0.7, text: BaRS FHIR usage}} section. + +<hr> +<br> + +# Security and Authorisation + +For more detail on Security and Authorisation, please visit the {{pagelink:core-Security-1.0.7, text: Security and Authorisation}} section. + +<hr> +<br> + +# Error Handling +There are multiple points where an error may occur to prevent booking and referral operations from completing successfully. This section provides error handling guidance for BaRS and its associated API. For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.0.7}} section in addition to information included on this page. + +For more detail please visit the {{pagelink:core-ErrorHandling-1.0.7, text: Error Handling}} section. + +<hr> +<br> + +# Transactional Integrity +Transactional integrity is employed to ensure data integrity is maintained between two parties. It helps ensure that the success or failure of a message is known and can be confirmed. + +For more detail please visit the {{pagelink:Core-TransactionalIntegrity-1.0.7, text:Transactional Integrity}} section. + +<hr> +<br> + +# Non Functional Requirements + +The non functional requirements apply to all APIs designed to receive requests from BaRS. This includes sender systems receiving asynchronous responses and feedback, as well as receiving systems. All items detailed will be adhered to. + +For more detail please visit the {{pagelink:core-NFR-1.0.7, text: Non Functional Requirements}} section. + +<hr> +<br> + +# Standard Pattern - Composite Messages +Most implementations of the BaRS that are applying the standard to support a particular use case or operational workflow will follow the same basic set of foundational operations with little deviation. + +In order to establish a guarantee of compatibility between different solutions compliant with the standard, **all** implementations **must** support all the underlying foundational operations and patterns. + +For more detail please visit the {{pagelink:Core-StandardPattern-1.0.7, text: Standard Pattern - Composite Messages}} section. + +<hr> +<br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Index.page.md new file mode 100644 index 00000000..2ebcebfe --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-NFR-1.0.7 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Introduction.page.md new file mode 100644 index 00000000..40040917 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-NFR-introduction-1.0.7 +--- + +# Non-Functional Requirements + +The following non functional requirements apply to all APIs designed to receive requests from BaRS. This includes sender systems receiving asynchronous responses and feedback, as well as receiving systems. All items listed below will be adhered to. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Processing-Times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Processing-Times.page.md new file mode 100644 index 00000000..bec8b920 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Processing-Times.page.md @@ -0,0 +1,14 @@ +--- +topic: core-NFR-Processing-Time-1.0.7 +--- + +## {{page-title}} + +The following Processing time SLAs describe the need for APIs to respond to a request within an acceptable time frame. This time frame should be measured from when a request is received and does not include the transport time. +These times are guide for average response time. + +| item | Requirement. | +|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1 | 90% of requests SHOULD take less than 2100ms to process. (Allowing for response time depending on measurement point). $process-message independently measured. | +| 2 | All requests MUST take less than 5000ms to process. | +| 3 | Any requests not processed within 5000ms should be timed out with "408 - REC_TIMEOUT - timeout" \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Requirements.page.md new file mode 100644 index 00000000..e574d116 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/Requirements.page.md @@ -0,0 +1,19 @@ +--- +topic: core-NFR-Requirements-1.0.7 +--- + +## {{page-title}} + +| Name | Description | +|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Conformance | The solution conforms with the BaRS standards where applicable, within any Application | +| Safety | The solution complies with NHS Digital [Clinical Risk Management Standards](https://digital.nhs.uk/services/clinical-safety/clinical-risk-management-standards), in particular 0129 (IT Supplier) and 0160 (Trust/Provider) | +| Security | The solution resists unauthorised, accidental or unintended usage and provides access only to legitimate requests | +| Scalable and capacity | The solution is designed to accommodate increased volumes, workloads and users | +| Availability and reliability | The solution meets a service level agreement that includes a 99.9% uptime guarantee and a high Mean Time Between Failures (MTBF) The solution has adequate disaster recovery and fault tolerance enabling continued operation in the event of a failure | +| Auditability | All of the solutions interactions are fully auditable for both sending and receiving | +| Data retention | The Solution audits all API access attempts and actions, retaining all pertinent data therein | +| Deployment | Solution providers release a new major version of their Booking and Referral APIs alongside a previous major version, until such time as consumers have migrated to the new major version. Alternatively, there is support for backward compatibility of requests to support consumers. Solution providers release a new minor or patch version, replacing the previous minor or patch version The Booking and Referral endpoints are independently deployable against unique Fully Qualified Domain Names (FDQN). This ensures support for limitations around sending and receiving messages between path-to-live and production environments. To increase availability, during upgrades and maintenance, the Booking and Referral APIs are load balanced across multiple servers In multi tenanted deployments, the activity of individual tenants are readily distinguishable | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/toc.yaml new file mode 100644 index 00000000..5e962e98 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Non-Functional-Requirements/toc.yaml @@ -0,0 +1,8 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Requirements + filename: Requirements.page.md +- name: Processing Times + filename: Processing-Times.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Authorisation.page.md new file mode 100644 index 00000000..f89a7b00 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Authorisation.page.md @@ -0,0 +1,17 @@ +--- +topic: core-Security-Auth-1.0.7 +--- + +## Authorisation + +BaRS will use several HTTP headers to facilitate authorisation. Although optional, receivers can expect these to be present for each request (excluding /metadata and /MessageDefinition), where applicable, to enforce access control. These will be in addition to the X-Request-ID and the X-Correlation-ID headers. If the information in these headers is available in the sending system, they'll be included in the request. + +Each of these HTTP headers are objects and will therefore need to be added in the form of a standard Base64 encoded string. + +Examples of each HTTP header item can be found within the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir). + +| HTTP Header | Purpose | +|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| NHSD-End-User-Organisation | This will represent the organisation making the request. It Shall include the ODS code and the human readable name of the organisation making the request. The object is based on a FHIR Organisation resource. | | +| NHSD-Requesting-Practitioner | This entry will represent the Practitioner role associated to the request. It shall include their sds role id and a SNOMED code related to their role where applicable. The object is based on a FHIR PractitionerRole resource. | +| NHSD-Requesting-Software | This entry will represent the Software or application making the request. It shall include an identifier for the instance, the product name and its version. The object is based on a FHIR Device resource. | \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Index.page.md new file mode 100644 index 00000000..9c9a79f6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-Security-1.0.7 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Introduction.page.md new file mode 100644 index 00000000..f8e4ce84 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Introduction.page.md @@ -0,0 +1,4 @@ +# Security and Authorisation + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/OAuth-Endpoints.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/OAuth-Endpoints.page.md new file mode 100644 index 00000000..6895a346 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/OAuth-Endpoints.page.md @@ -0,0 +1,15 @@ +--- +topic: core-Security-Oauth-1.0.7 +--- + +## OAuth Endpoints + +| Environment | Endpoint | Usage/Availability | +|------------------|-------------------------------------------|------------------------------------------------------------| +| Sandbox | https://sandbox.api.service.nhs.uk/oauth2 | Authentication is not required in the Sandbox environment. | +| Development | https://dev.api.service.nhs.uk/oauth2 | Limited to specific APIs | +| Integration test | https://int.api.service.nhs.uk/oauth2 | All APIs | +| Production | https://api.service.nhs.uk/oauth2 | All APIs | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Receiver.page.md new file mode 100644 index 00000000..c8e76f5b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Receiver.page.md @@ -0,0 +1,40 @@ +--- +topic: core-Security-Receiver-1.0.7 +--- + +## Receiver + +BaRS will utilise TLS-MA (Mutual Authentication) to communicate with receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA. + +- The receiver will need to request a certificate under the NHS Root CA + - There are two different certificate chains for INT and Prod + - INT Certificate chains, which are superceded from 4/06/2024, can be found [here](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) + - Prod Certificate chains,which expire from 4/06/2024, can be found [here](https://digital.nhs.uk/services/path-to-live-environments/live-environment) + - **Current** INT Certificate chains can be found [here](https://pki.nhs.uk/G2Transition/) + - **Current** Prod Certificate chains can be found [here](https://pki.nhs.uk/G2Transition/) + + +- The receiving endpoint will present the certificate obtained for TLS-MA +- The receiving endpoint will need to trust the Root CAs and SubCAs for their respective environments +- The receiving endpoint will only accept requests presented with certificates from their respective chains + +As the certificates are using the NHS Root CA, fully qualified domain name (FQDN) must be an nhs.uk address, this is the case for both INT and Prod + +You need to [apply for your domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications), ensuring that you complete 'Section 5: For website or application records visible on public internet'. + +In production there is a naming convention that must be adhered to. In INT the naming convention should be adhered where possible. In the context of BaRS an example will be: + +- ==BaRS-< ODSCode >.< OrganisationName >.nhs.uk== , BaRS is always the application name. + +Once you have you have your domain registered you can then begin the process to obtain your certificate by generating a certificate request. + +Certificate requests will need to be signed for your endpoint. Note that the FQDN is equal to the certificate name (CN) by convention. + +At this point you should have a .key and a .csr files. The next step will be to send the .csr file to be signed by the NHS and get the client certificate. + +- If your client certificate will be implemented in any PTL environment then you should send the .csr file to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) and they will reply with the certificate (.crt file) + +- If your client certificate will be implemented in the PROD environment then the .csr file needs to be send to the DIR team at [dir@nhs.net](mailto:dir@nhs.net) and they will take care of issuing the certificate after validating your request with the Live Services Pipeline at [liveservices.gate@nhs.net](mailto:liveservices.gate@nhs.net) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Sender.page.md new file mode 100644 index 00000000..14c6582e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/Sender.page.md @@ -0,0 +1,18 @@ +--- +topic: core-Security-Sender-1.0.7 +--- + +## Sender + +The BaRS standard uses an [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) security model and [security pattern](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#how-this-pattern-works) as opposed to a [user-restricted security](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) model. This means the application is authenticated as opposed to the end-user using it. The high level steps for a sending application are defined below: + +1. The end user launches the calling application +2. Time passes, until the user needs to interact with BaRS +3. The calling application generates and signs a JWT, using its own private key +4. The calling application calls our OAuth 2.0 token endpoint with the signed JWT. In particular, this uses the OAuth 2.0 client credentials flow +5. We check the signature against the application's public key and, if valid, return an access token to the calling application +6. The calling application calls the BaRS API, including the access token +7. The BaRS API allows the interaction should the access token be valid + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/toc.yaml new file mode 100644 index 00000000..3949edb7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Security-and-Authorisation/toc.yaml @@ -0,0 +1,12 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Sender + filename: Sender.page.md +- name: OAuth Endpoints + filename: OAuth-Endpoints.page.md +- name: Receiver + filename: Receiver.page.md +- name: Authorisation + filename: Authorisation.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Cancellation.page.md new file mode 100644 index 00000000..0277191c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -0,0 +1,538 @@ +--- +topic: core-SPCancellation-1.0.7 +--- + + +## {{page-title}} + +The ability to reverse a digital request, by performing a cancellation, whether booking or referral, is a core workflow within BaRS. It completes the digital workflow, supports genuine interoperability and removes the need for manual intervention by service providers. + +Cancellation, for any referral type or booking, is a stripped back request, containing only the specific resources a Receiver requires to the fulfil the request. There are separate MessageDefinitions involved when engaged in [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. + +A prerequisite when performing a cancellation of any request is to perform a read (GET) of either the booking or referral to be cancelled. The Sender **must** only make a cancellation request if the entity has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the entity they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.0.7, text:error}} response. + +## Cancellation Referral Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.0.7, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. + +When cancelling a referral, in conjunction with the guidance provided under the Standard Patterns, the four important elements which drive workflow **must** be used as follows: +* **eventCoding** - this **must** be the same code as used in the request. +* **reasonCode** - a cancellation follows an initial request, therefore, this **must** always be 'update' for cancellation. +* **definition** - cancellation has a unique [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the request **must** adhere to. +* **focus** - **must** point to the *ServiceRequest* resource. + +<br> + +### ServiceRequest Resource +The 'focus' resource in a cancellation referral request is the ServiceRequest resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail. + +When a Receiver processes the cancellation referral request, the two key elements used are the *ServiceRequest.id* and *ServiceRequest.status*. The *.id* **must** already exist as an 'active' (status) ServiceRequest on the Receiver system (this **must** have been confirmed by a prior read (GET) by the Sender) and the *.status*, in the request, **must** either be 'revoked' or 'entered-in-error'. There is a distinct difference between these two *ServiceRequest.status(es)*. 'Revoked' **should** be used to denote the original request was intentional but, due to a change in circumstances, is no longer valid, whereas, 'entered-in-error' **should** be used when original request was in error. The purpose of this differentiation is to allow service providers to accurately report the reason for cancellations. + +### Patient Resource +Key patient demographics **should** be cross-referenced between the current 'active' referral and incoming cancellation referral request to ensure validity. + +## Payload for Referral Cancellation Request + +This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Referral. + +<br> + <div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> + <b>Please expand each resource below to view implementation guidance.</b> + </div> +<br> + +<details> + <summary>> <b class="barslink">Bundle</b></summary> + <p> + + <p>The Bundle resource is the container for the event message.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | +| Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | +| Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | +| Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | +| Bundle.timestamp | the date that the content of the message was assembled. This date is not changed by middleware engines unless they add additional data that changes the meaning of the time of the message | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.entry(s) | Follow BaRS profile guidance for populating this element | MUST | 1..* | | +| Bundle.entry.fullUrl | unique identifier for the resource entry. Transient id relative to the bundle | MUST | 0..1 | urn:uuid:1cbdfb97-5859-48a4-8301-d54eab818d68 | +| Bundle.entry.resourceType | Resources detailed in the message definition. | MUST | 0..1 | MessageHeader,Patient, Encounter | + + + +</details> +<p> +<details> + <summary>> <b class="barslink">Message Header</b></summary> + + <p> + + <p>A resource that describes the BaRS message being exchanged between two systems.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-servicerequest-request, hybrid}} + <p> + + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| MessageHeader | A resource that describes the BaRS message being exchanged between two systems https://simplifier.net/nhsbookingandreferrals/barsmessageheaderservicerequestrequest | | 1..1 | | +| MessageHeader.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| MessageHeader.meta.profile | This MUST be populated with the structure definition for BaRSMessageHeader-servicerequest-request. | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSMEssageHeader-servicerequest-request | +| MessageHeader.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| MessageHeader.extension | This MUST be populated with details of the Clinical Decision Support System used | MUST | 0..* | | +| MessageHeader.extension.url | This MUST be populated with 'https://fhir.nhs.uk/StructureDefinition/CDSSExtension' - FIXED VALUE | MUST | 1..1 | https://fhir.nhs.uk/StructureDefinition/CDSSExtension | +| MessageHeader.extension.extension | | MUST | 0..* | | +| MessageHeader.extension.extension.url | This MUST be populated with the pre-defined Clinical Decision Support System software URL - FIXED VALUE | MUST | 1..1 | requesterCDSSSoftware | +| MessageHeader.extension.extension.valueString | This MUST be populated with the Clinical Decision Support System software name e.g. Pathways | MUST | 0..1 | Pathways | +| MessageHeader.extension.extension | | MUST | 0..* | | +| MessageHeader.extension.extension.url | This MUST be populated with the pre-defined Clinical Decision Support System software Version URL - FIXED VALUE | MUST | 1..1 | requesterCDSSVersion | +| MessageHeader.extension.extension.valueString | This MUST be populated with the Clinical Decision Support System software Version name e.g. 30.2.0 | MUST | 0..1 | 30.2.0 | +| MessageHeader.eventcoding | | MUST | 1..1 | | +| MessageHeader.eventcoding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-events-bars | +| MessageHeader.eventcoding.code | The status MUST be populated with 'servicerequest-request'. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | servicerequest-request | +| MessageHeader.destination | | MUST | 0..1 | | +| MessageHeader.destination.receiver | | MUST | 0..1 | | +| MessageHeader.destination.receiver.reference | This MUST be populated with the full URL to the Receiving Organisation resource. | MUST | 0..1 | urn:uuid:10397afd-479c-42ea-9d5d-e4024481e0f8 | +| MessageHeader.destination.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows the intended destination. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|1122334455 | +| MessageHeader.sender | | MUST | 0..1 | | +| MessageHeader.sender.reference | This MUST be populated. Follow BaRS profile guidance for populating this element | MUST | 0..1 | urn:uuid:07939a0c-2854-46ff-9282-ad906bc93679 | +| MessageHeader.source | | MUST | 1..1 | | +| MessageHeader.source.name | This MUST be populated with the sending system supplier name | MUST | 0..1 | NHS Trust | +| MessageHeader.source.software | This SHOULD be populated with the sending software application name | SHOULD | 0..1 | Supplier Software | +| MessageHeader.source.version | This SHOULD be populated with the sending software version | SHOULD | 0..1 | V1.0.0 | +| MessageHeader.source.contact | | SHOULD | 0..1 | | +| MessageHeader.source.contact.system | This SHOULD be populated with the Contact Type - phone \| fax \| email \| pager \| url \| sms \| other | SHOULD | 0..1 | phone | +| MessageHeader.source.contact.value | This SHOULD be populated with the Contact Type value | SHOULD | 0..1 | +44 (0123) 123 4567 | +| MessageHeader.source.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows where any response messages SHOULD be addressed. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|5566778899 | +| MessageHeader.reason | | MUST | 0..1 | | +| MessageHeader.reason.coding | | MUST | 0..1 | | +| MessageHeader.reason.coding.system | This MUST be populated with 'https://fhir.nhs.uk/CodeSystem/message-reason-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-reason-bars | +| MessageHeader.reason.coding.code | This MUST be populated with "delete" for an cancellation. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' | MUST | 0..1 | delete | +| MessageHeader.reason.coding.display | This MUST be populated with 'Delete' when cancelling a Service Request. | SHOULD | 0..1 | Delete | +| MessageHeader.focus | | MUST | 0..* | | +| MessageHeader.focus.reference | This MUST be populated with a reference to the ServiceRequest | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| MessageHeader.definition | This MUST be populated with the MessageDefinition the bundle is based on. This will be used for validation. Value - https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-cancelled | MUST | 0..1 | https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-cancelled | + + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Service Request</b></summary> + <p> + <p> A resource to carry a request for a service to be performed, in this case a Validation. This Resource is the focus of the Validation Request interaction.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-referral , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| ServiceRequest | A resource to carry a request for a service to be performed, in this case a Validation. This Resource is the focus of the Validation Request interaction https://simplifier.net/nhsbookingandreferrals/barsservicerequest-request-validation | | 1..1 | | +| ServiceRequest.id | MUST only be generated by the Receiver as the id for the resource in the synchronous HTTP response. | MUST | 0..1 | 236bb75d-90ef-461f-b71e-fde7f899802c | +| ServiceRequest.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| ServiceRequest.meta.profile | https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-validation | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-validation | +| ServiceRequest.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.basedOn | | MUST | 0..* | | +| ServiceRequest.basedOnreference | This MUST be populated with a reference to the CarePlan resource | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| ServiceRequest.status | Only use the following 2 values, as appropriate: revoked is used when a SR is legitimately cancelled, entered-in-error is used when sent to the by mistake and needs to be removed. | MUST | 1..1 | entered-in-error | +| ServiceRequest.intent | This MUST be populated with 'plan' - Fixed Value | MUST | 1..1 | plan | +| ServiceRequest.category | | MUST | 0..1 | | +| ServiceRequest.category.coding | | MUST | 0..* | | +| ServiceRequest.category.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-category-servicerequest' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-category-servicerequest | +| ServiceRequest.category.coding.code | This MUST be populated with code value appropriate for the Application employed. | MUST | 0..1 | validation | +| ServiceRequest.category.coding.display | This MUST be populated with display value appropriate for the Application employed. | MUST | 0..1 | For Validation | +| ServiceRequest.subject | Follow BaRS profile guidance for populating this element | MUST | 1..1 | | +| ServiceRequest.subjectreference | This MUST be populated with a Reference to the Patient resource | MUST | 0..1 | urn:uuid:9589fb37-87a2-48d8-968f-b371429208a8 | +| ServiceRequest.encounter | | MUST | 0..1 | | +| ServiceRequest.encounter.reference | This MUST be populated with a Reference to the Encounter | MUST | 0..1 | urn:uuid:8c63d621-4d86-4f57-8699-e8e22d49935d | +| ServiceRequest.occurrencePeriod | Validation Breach time | MUST | 0..1 | | +| ServiceRequest.occurrencePeriod.start | The start of the period must be ‘now’. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.occurrencePeriod.end | The time by which the validation must be complete (validation breach time) | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.reasonCode | This will ONLY be populated in a cancellation message with the reason for cancellation | SHOULD | 0..* | | +| ServiceRequest.reasonCode.text | This SHOULD be populated. This will ONLY be populated in a cancellation message with the reason for cancellation and SHOULD only be used in conjunction with a corresponding status - revoked or entered-in-error | SHOULD | 0..1 | Revoked as patient has been dealt with. | + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Patient</b></summary> + <p>This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Patient | This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.<br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-patient | | 1..1 | | +| Patient.id | If this value was included in the synchronous response to the original request, it MUST be populated in subsequent requests. | MUST | 0..1 | 9589fb37-87a2-48d8-968f-b371429208a8 | +| Patient.meta | https://simplifier.net/hl7fhirukcorer4/ukcore-patient | MUST | 1..1 | | +| Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | +| Patient.meta.LastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | +| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | +| Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | +| Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding.system | https://simplifier.net/hl7fhirukcorer4/extensionukcorenhsnumberverificationstatus | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept.coding.code | Follow UK Core guidance for populating this element | SHOULD | 0..1 | number-present-and-verified | +| Patient.identifier.extension.valueCodeableConcept.coding.display | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Number present and verified | +| Patient.name | | SHOULD | 0..* | | +| Patient.name.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | official | +| Patient.name.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs Julie Jones | +| Patient.name.family | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jones | +| Patient.name.given | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Julie | +| Patient.name.prefix | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs | +| Patient.gender | Follow UK Core guidance for populating this element | SHOULD | 0..1 | female | +| Patient.birthDate | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 1959-05-04 | +| Patient.address | Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.address.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | home | +| Patient.address.type | Follow UK Core guidance for populating this element | SHOULD | 0..1 | both | +| Patient.address.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 22 Brightside Crescent, Overtown, West Yorkshire, LS10 4YU | +| Patient.address.line | Follow UK Core guidance for populating this element | SHOULD | 0..* | 22 Brightside Crescent | +| Patient.address.city | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Overtown | +| Patient.address.district | Follow UK Core guidance for populating this element | SHOULD | 0..1 | West Yorkshire | +| Patient.address.postalCode | Follow UK Core guidance for populating this element | SHOULD | 0..1 | LS10 4YU | +| Patient.contact | This should be used to record telecom information for the patient and/or the patient's representative for the encounter | MUST | 0..* | | +| Patient.contact.extension | | MUST | 0..* | | +| Patient.contact.extension.url | This MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactRank' - FIXED VALUE | MUST | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference | +| Patient.contact.extension.urlvaluePositiveInt | This MUST be populated with the rank of the whole contact and MUST be populated with the value '1' for the primary person to contact for referral. There MUST be at least one contact for the referral. | MUST | 0..1 | 1 | +| Patient.contact.relationship | | MUST | 0..* | | +| Patient.contact.relationship.coding | | MUST | 0..* | | +| Patient.contact.relationship.coding.system | This MUST be populated with the CodeSystem from the ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'.<br>Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.<br>Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.<br>If the relationship is not known this SHOULD be populated with the value 'Unknown' | MUST | 0..1 | http://terminology.hl7.org/CodeSystem/v2-0131 | +| Patient.contact.relationship.coding.code | This MUST be populated with Code of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.relationship.coding.display | This MUST be populated with Display of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.name | | SHOULD | 0..1 | | +| Patient.contact.name.family | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Grayson | +| Patient.contact.name.given | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jack | +| Patient.contact.telecom | | MUST | 0..* | | +| Patient.contact.telecom.system | This MUST be populated for the rank 1 contact. There MUST be at least one contact phone number for the referral | MUST | 0..1 | phone | +| Patient.contact.telecom.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | 0789 1234567 | +| Patient.contact.gender | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | male | +| Patient.Communication | | SHOULD | 0..* | | +| Patient.Communication.Language | | MUST | 1..1 | | +| Patient.Communication.Language.coding | | MUST | 1..1 | | +| Patient.Communication.Language.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | en | +| Patient.Communication.Language.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage | +| Patient.Communication.Language.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | English | +| Patient.Communication.Language.preferred | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | TRUE | +| Patient.extension | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.extension.url | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | A | +| Patient.extension.url.valueCodeableConcept.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | British, Mixed British | +| Patient.generalPractitioner | This SHOULD be populated with a reference to the GP Surgery ONLY rather than a specific practitioner | SHOULD | 0..* | | +| Patient.generalPractitioner.reference | This SHOULD be populated. Where populated this MUST reference to an Organisation resource | SHOULD | 0..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4411 | + + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Organization</b></summary> + <p>This resource is used to communicate details about the sender and receiver organisations.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Organization | This resource is used to communicate details about the sender organisations. <br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-organization | | 2..* | | +| Organization.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 5d897313-c62d-4e7e-92b7-b2199804fed3 | +| Organization.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Organization.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +| Organization.meta.lastUpdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Organization.identifier | This MUST be populated with an organisation identifier e.g. ODS code | MUST | 0..* | | +| Organization.identifier.system | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | https://fhir.nhs.uk/id/ods-organization-code | +| Organization.identifier.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | ABD01 | +| Organization.name | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | Organisation name | + + + +</details> +<p> +<br> + +### Entity Relationship Diagram - Cancellation Referral Request + +<br> +<br> +The below diagram details the Cancellation Referral Request +<br> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMap9sToCASCancellationRequest-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapCancellationReferralRequest-1.1.0.svg" width="1200"></img></a> +<br> +<br> +<hr> + +## Cancellation Booking Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.0.7, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. + +When cancelling a booking, in conjunction with the guidance provided under the Standard Patterns, the three important elements which drive workflow **must** be used as follows: +* **eventCoding** - this **must** be the same code as used in the request. +* **reasonCode** - a cancellation follows an initial request, therefore, this **must** always be 'update' for cancellation. +* **definition** - cancellation has a unique [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the request **must** adhere to. +* **focus** - **must** point to the *Appointment* resource. + +### Appointment Resource +The 'focus' resource in a cancellation booking request is the Appointment resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail. + +When a Receiver processes the cancellation booking request, the two key elements used are the *Appointment.id* and *Appointment.status*. The *.id* **must** already exist as a 'booked' (status) booking on the Receiver system (this **must** have been confirmed by a prior read (GET) by the Sender) and the *.status*, in the request, **must** be 'cancelled'. No other status is valid in the cancellation booking request. + +### Patient Resource +Key patient demographics **should** be cross-referenced between the current 'booked' (status) booking and incoming cancellation booking request to ensure validity. + +## Payload for Booking Cancellation Request + +This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Booking. + +<br> + <div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> + <b>Please expand each resource below to view implementation guidance.</b> + </div> +<br> + +<details> + <summary>> <b class="barslink">Bundle</b></summary> + <p> + + <p>The Bundle resource is the container for the event message.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | +| Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | +| Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | +| Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | +| Bundle.timestamp | the date that the content of the message was assembled. This date is not changed by middleware engines unless they add additional data that changes the meaning of the time of the message | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.entry(s) | Follow BaRS profile guidance for populating this element | MUST | 1..* | | +| Bundle.entry.fullUrl | unique identifier for the resource entry. Transient id relative to the bundle | MUST | 0..1 | urn:uuid:1cbdfb97-5859-48a4-8301-d54eab818d68 | +| Bundle.entry.resourceType | Resources detailed in the message definition. | MUST | 0..1 | MessageHeader,Patient, Encounter | + +</details> +<p> +<details> + <summary>> <b class="barslink">Message Header</b></summary> + + <p> + + <p>A resource that describes the BaRS message being exchanged between two systems.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-servicerequest-request, hybrid}} + <p> + + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| MessageHeader | A resource that describes the BaRS message being exchanged between two systems https://simplifier.net/nhsbookingandreferrals/barsmessageheaderservicerequestrequest | | 1..1 | | +| MessageHeader.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| MessageHeader.meta.profile | This MUST be populated with the structure definition for BARSMessageHeader-booking-request | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-booking-request | +| MessageHeader.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| MessageHeader.eventcoding | | MUST | 1..1 | | +| MessageHeader.eventcoding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-events-bars | +| MessageHeader.eventcoding.code | The status MUST be populated with 'booking-request'. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | booking-request | +| MessageHeader.destination | | MUST | 0..1 | | +| MessageHeader.destination.receiver | | MUST | 0..1 | | +| MessageHeader.destination.receiver.reference | This MUST be populated with the full URL to the Receiving Organisation resource. | MUST | 0..1 | urn:uuid:10397afd-479c-42ea-9d5d-e4024481e0f8 | +| MessageHeader.destination.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows the intended destination. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|1122334455 | +| MessageHeader.sender | | MUST | 0..1 | | +| MessageHeader.sender.reference | This MUST be populated. Follow BaRS profile guidance for populating this element | MUST | 0..1 | urn:uuid:07939a0c-2854-46ff-9282-ad906bc93679 | +| MessageHeader.source | | MUST | 1..1 | | +| MessageHeader.source.name | This MUST be populated with the sending system supplier name | MUST | 0..1 | NHS Trust | +| MessageHeader.source.software | This SHOULD be populated with the sending software application name | SHOULD | 0..1 | Supplier Software | +| MessageHeader.source.version | This SHOULD be populated with the sending software version | SHOULD | 0..1 | V1.0.0 | +| MessageHeader.source.contact | | SHOULD | 0..1 | | +| MessageHeader.source.contact.system | This SHOULD be populated with the Contact Type - phone \| fax \| email \| pager \| url \| sms \| other | SHOULD | 0..1 | phone | +| MessageHeader.source.contact.value | This SHOULD be populated with the Contact Type value | SHOULD | 0..1 | +44 (0123) 123 4567 | +| MessageHeader.source.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows where any response messages SHOULD be addressed. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|5566778899 | +| MessageHeader.reason | | MUST | 0..1 | | +| MessageHeader.reason.coding | | MUST | 0..1 | | +| MessageHeader.reason.coding.system | This MUST be populated with 'https://fhir.nhs.uk/CodeSystem/message-reason-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-reason-bars | +| MessageHeader.reason.coding.code | This MUST be populated with "delete" for an cancellation. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' | MUST | 0..1 | delete | +| MessageHeader.reason.coding.display | This MUST be populated with 'Delete' when cancelling a Booking. | SHOULD | 0..1 | Delete | +| MessageHeader.focus | | MUST | 0..* | | +| MessageHeader.focus.reference | This MUST be populated with a reference to the ServiceRequest | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| MessageHeader.definition | This MUST be populated with the MessageDefinition the bundle is based on. This will be used for validation. Value - hhttps://fhir.nhs.uk/MessageDefinition/bars-message-booking-request-cancelled | MUST | 0..1 | https://fhir.nhs.uk/MessageDefinition/bars-message-booking-request-cancelled | + + +</details> +<p> +<details> + <summary>> <b class="barslink">Appointment</b></summary> + + + + <p> + + <p>This resource will be used to communicate information about an Appointment and is the focus of the Booking interation.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Appointment | https://simplifier.net/hl7fhirukcorer4/ukcore-appointment <br><br>This resource will be used to communicate information about an appointment. | | 1..1 | | +| Appointment.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 3713c8fc-dbcf-4f90-bacf-89d99e434e9b | +| Appointment.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Appointment.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment | +| Appointment.meta.lastupdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Appointment.status | This MUST be populated with 'booked' | MUST | 1..1 | cencelled | +| Appointment.description | This SHOULD be populated. It is the human readable description of the booking | SHOULD | 0..1 | Reason for calling | +| Appointment.start | This MUST be populated with the Start time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | +| Appointment.end | This MUST be populated with the End time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | +| Appointment.slot | | MUST | 0..* | | +| Appointment.slot.reference | This MUST be populated with the local logical bundle reference to the Slot resource | MUST | 0..1 | urn:uuid:c3f6145e-1a26-4345-b3f2-dccbcba62049 | +| Appointment.created | This MUST only be populated with the date/time the booking was generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 2021-10-11T15:01:30+00:00" | +| Appointment.basedOn | This MAY be populated. When the Service Request is made before the booking in the workflow this MUST be populated. | MAY | 0..* | | +| Appointment.basedOn.reference | This MAY be populated. This is MUST be the relative reference to the Service Request when referral is made before booking in the workflow | MAY | 0..1 | ServiceRequest/236bb75d-90ef-461f-b71e-fde7f899802c | +| Appointment.participant | | MUST | 1..1 | | +| Appointment.participant.actor | This MUST be populated with reference to the patient | MUST | 0..1 | | +| Appointment.participant.actor.reference | This MUST be populated with the local logical bundle reference to the Patient resource | MUST | 0..1 | urn:uuid:3a62607b-df65-4932-940c-14262787f62d | +| Appointment.participant.actor.status | This MUST be populated with 'accepted' - FIXED VALUE | MUST | 1..1 | accepted | +</details> +<p> +<details> + <summary>> <b class="barslink">Patient</b></summary> + <p>This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Patient | This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.<br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-patient | | 1..1 | | +| Patient.id | If this value was included in the synchronous response to the original request, it MUST be populated in subsequent requests. | MUST | 0..1 | 9589fb37-87a2-48d8-968f-b371429208a8 | +| Patient.meta | https://simplifier.net/hl7fhirukcorer4/ukcore-patient | MUST | 1..1 | | +| Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | +| Patient.meta.LastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | +| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | +| Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | +| Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding.system | https://simplifier.net/hl7fhirukcorer4/extensionukcorenhsnumberverificationstatus | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept.coding.code | Follow UK Core guidance for populating this element | SHOULD | 0..1 | number-present-and-verified | +| Patient.identifier.extension.valueCodeableConcept.coding.display | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Number present and verified | +| Patient.name | | SHOULD | 0..* | | +| Patient.name.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | official | +| Patient.name.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs Julie Jones | +| Patient.name.family | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jones | +| Patient.name.given | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Julie | +| Patient.name.prefix | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs | +| Patient.gender | Follow UK Core guidance for populating this element | SHOULD | 0..1 | female | +| Patient.birthDate | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 1959-05-04 | +| Patient.address | Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.address.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | home | +| Patient.address.type | Follow UK Core guidance for populating this element | SHOULD | 0..1 | both | +| Patient.address.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 22 Brightside Crescent, Overtown, West Yorkshire, LS10 4YU | +| Patient.address.line | Follow UK Core guidance for populating this element | SHOULD | 0..* | 22 Brightside Crescent | +| Patient.address.city | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Overtown | +| Patient.address.district | Follow UK Core guidance for populating this element | SHOULD | 0..1 | West Yorkshire | +| Patient.address.postalCode | Follow UK Core guidance for populating this element | SHOULD | 0..1 | LS10 4YU | +| Patient.contact | This should be used to record telecom information for the patient and/or the patient's representative for the encounter | MUST | 0..* | | +| Patient.contact.extension | | MUST | 0..* | | +| Patient.contact.extension.url | This MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactRank' - FIXED VALUE | MUST | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference | +| Patient.contact.extension.urlvaluePositiveInt | This MUST be populated with the rank of the whole contact and MUST be populated with the value '1' for the primary person to contact for referral. There MUST be at least one contact for the referral. | MUST | 0..1 | 1 | +| Patient.contact.relationship | | MUST | 0..* | | +| Patient.contact.relationship.coding | | MUST | 0..* | | +| Patient.contact.relationship.coding.system | This MUST be populated with the CodeSystem from the ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'.<br>Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.<br>Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.<br>If the relationship is not known this SHOULD be populated with the value 'Unknown' | MUST | 0..1 | http://terminology.hl7.org/CodeSystem/v2-0131 | +| Patient.contact.relationship.coding.code | This MUST be populated with Code of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.relationship.coding.display | This MUST be populated with Display of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.name | | SHOULD | 0..1 | | +| Patient.contact.name.family | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Grayson | +| Patient.contact.name.given | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jack | +| Patient.contact.telecom | | MUST | 0..* | | +| Patient.contact.telecom.system | This MUST be populated for the rank 1 contact. There MUST be at least one contact phone number for the referral | MUST | 0..1 | phone | +| Patient.contact.telecom.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | 0789 1234567 | +| Patient.contact.gender | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | male | +| Patient.Communication | | SHOULD | 0..* | | +| Patient.Communication.Language | | MUST | 1..1 | | +| Patient.Communication.Language.coding | | MUST | 1..1 | | +| Patient.Communication.Language.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | en | +| Patient.Communication.Language.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage | +| Patient.Communication.Language.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | English | +| Patient.Communication.Language.preferred | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | TRUE | +| Patient.extension | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.extension.url | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | A | +| Patient.extension.url.valueCodeableConcept.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | British, Mixed British | +| Patient.generalPractitioner | This SHOULD be populated with a reference to the GP Surgery ONLY rather than a specific practitioner | SHOULD | 0..* | | +| Patient.generalPractitioner.reference | This SHOULD be populated. Where populated this MUST reference to an Organisation resource | SHOULD | 0..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4411 | + + + +</details> +<p> +<details> + <summary>> <b class="barslink">Organization</b></summary> + <p> This resource is used to communicate details about the sender and receiver organisations.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Organization | This resource is used to communicate details about the sender organisations. <br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-organization | | 2..* | | +| Organization.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 5d897313-c62d-4e7e-92b7-b2199804fed3 | +| Organization.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Organization.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +| Organization.meta.lastUpdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Organization.identifier | This MUST be populated with an organisation identifier e.g. ODS code | MUST | 0..* | | +| Organization.identifier.system | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | https://fhir.nhs.uk/id/ods-organization-code | +| Organization.identifier.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | ABD01 | +| Organization.name | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | Organisation name | + +</details> +<p> + +<br> + +## Entity Relationship Diagram - Cancellation Booking Request + +<br> +<br> +The below diagram details the Cancellation Booking Request +<br> +<br> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMap9sToCASCancellationRequest-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapCancellationBookingRequest-1.1.0.svg" width="1200"></img></a> +<br> +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Introduction.page.md new file mode 100644 index 00000000..e1e17e8f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Introduction.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-StandardPattern-Introduction-1.0.7 +--- + +# Standard Pattern - Composite Messages + +Most implementations of the BaRS that are applying the standard to support a particular use case or operational workflow will follow the same basic set of foundational operations with little deviation. + +In order to establish a guarantee of compatibility between different solutions compliant with the standard, **all** implementations **must** support all the underlying foundational operations and patterns. + + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Message-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Message-Headers.page.md new file mode 100644 index 00000000..5314d4a9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Message-Headers.page.md @@ -0,0 +1,47 @@ +--- +topic: core-SPMessageHeader-1.0.7 +--- + +# {{page-title}} + +## MessageHeader Resource +BaRS payloads (FHIR message bundles) require a **MessageHeader** FHIR resource which provides key information to drive workflow and start interpreting the data contained within. This resource is central to making a request or asynchronous response and **must** be present in all payloads. + +The **MessageHeader** resource contains the following element which **must** be used as outlined: +* **MessageHeader.source** - stipulates where the payload originated. The Sender **must**, under **MessageHeader.source.endpoint**, include a valid URI which could be used as a NHSD-Target-Identifier (their reference on the Endpoint Catalogue) for the Receiver to send an asynchronous response. +* **MessageHeader.destination** - designates who the payload is intended for, including reference to an Organisation resource and a valid URI (*MessageHeader.destination.endpoint*) which is the NHSD-Target-Identifier (their reference on the Endpoint Catalogue) the payload is being sent to. +* **MessageHeader.eventCoding** - determines the 'type' of payload, whether booking, referral, request or asynchronousus response. The value **must** be populated from this [CodeSystem](https://simplifier.net/NHSBookingandReferrals/message-events-bars). In referrals, this value, combined with the *ServiceRequest.category* element, allows supports for different styles of referral to support various use-cases. The value **must** be populated from CodeSystems for [specific type](https://simplifier.net/NHSDigital/message-category-servicerequest) and [use-case](https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). +* **MessageHeader.reason.code** - indicates whether the message is '**new**' or an '**update**' to something the Receiver is already aware of. The value **must** be populated from this [CodeSystem](https://simplifier.net/NHSBookingandReferrals/message-reason-bars). +* **MessageHeader.focus** - specifies the root resource through which to start interpreting the payload. +* **MessageHeader.definition** - cites the [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the payload **must** adhere to and **must** be rejected by the Receiver if it fails to do so. Note: payload conformance to MessageDefinitions is not checked as part of FHIR validation. + +When a Receiver begins to process the payload, they **must** initially ensure it is for them and they know who it is from: +* check the **MessageHeader.destination** and verify the **MessageHeader.destination.receiver.reference** refers to their Organisation. +* check the **MessageHeader.destination.endpoint** is the Service ID they are expected to be processing the request on behalf of. +* Store **MessageHeader.source.endpoint** as NHSD-Target-Identifier to enable an asynchronous response back to the Sender. Not all workflows will require this type of response but this data must be stored for audit purposes. + +Certain elements in MessageHeader explicitly drive workflow, check **MessageHeader.eventCoding** to determine whether a booking or referral payload is being sent, and whether this is an initial or update request or an asynchronous response to a pre-existing request. There are various styles of referral too, a request could be made for a simple 'transfer of care' or, currently, something termed a 'validation', where one service requests another to validate the assessment outcome they have reached. The intention of supporting gradation of referral is to provide BaRS the malleability to support further subtlety of referrals for future use cases. Combining the **MessageHeader.eventCoding** with the **ServiceRequest.cateory** provides this functionality and, with the addition of {{pagelink:core-SPUseCaseCategories-1.0.7, text:use-case categories}} (again populated under **ServiceRequest.category**) specific services are pinpointed through every BaRS workflow. + +Once the above checks have been made, the detail of the payload can start to be unpacked and processed. The structure of the payload **must** be checked first to ensure it adheres to the **MessageHeader.definition** it claims to. The [MessageDefinitions](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) will principally be defined by BaRS, at a national level (although bespoke definitions can be used through BaRS), and the Receiver is checking to ensure all mandatory FHIR resources are present and meet their assigned cardinality. This is a manual, business logic, check and not something which is supported through standard FHIR validation of the payload (bundle). +Next, **MessageHeader.focus** is the root resource through which the payload is intended to be understood. In an initial referral request, this will typically be the **ServiceRequest** FHIR resource. This root will link to other resources to build a narrative for the payload, for example, the **ServiceRequest** will link to the **Encounter** which led to the referral being made and the **Careplan** detailing next actions. The Entity Relationship Diagrams (included in each {{pagelink:Home/Applications/BaRS-Applications/Applications, text:Application}}) are used as a visual representation of the FHIR resource links in the payloads. + +<br> +<br> + + +### Asynchronous Response Workflows + +For certain {{pagelink:Home/Applications/BaRS-Applications/Applications, text:Applications}}, an initial request by a Sender expects an asynchronous response (as opposed to an HTTP synchronous response (200) message). These responses are defined by the workflow of the Application and may be consistently returned or conditional. When an asynchronous response is initiated, the original Sender and Receiver roles are switched, the Sender becoming the Receiver and vice versa. This allows BaRS to support complex workflows through support for multiple requests (initial and update) and, potentially, multiple asynchronous responses, for example, an initial status update followed by a more detailed final outcome (as defined in {{pagelink:Home/Applications/BaRS-Applications/Applications/BaRS-APP4, text:Application 4}}). +The asynchronous response should be thought of as merely another payload, adhering to all the same rules as an initial request or update. Similarly, Sender and Receiver roles are intended to be interchangeable in BaRS and, in most BaRS Applications a supplier is expected to build both Sender and Receiver functionality, something which is reflected in the {{pagelink:Home/Assure/Assure, text:assurance process}}, especially {{pagelink:Home/Core, text:BaRS Core}}. + +Where the workflow dictates an asynchronous response is to be sent, the Sender (originally the Receiver) **must** populate: +* **MessageHeader.response.identifier** with the **Bundle.Id** of the original request payload and set the **MessageHeader.response.code** value to 'ok'. +* Additionally, they **must** follow the above guidance on populating the **MessageHeader**. + + + + + + + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md new file mode 100644 index 00000000..c4d9e6e3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md @@ -0,0 +1,312 @@ +--- +topic: core-SPComposites-1.0.7 +--- + +## {{page-title}} + +The majority of BaRS operations utilise a single standard approach. Since most BaRS operations involve composites of FHIR resources supporting a particular workflow they all utilise a single type of endpoint designed for processing and consuming of composite resources. This is the $process-message endpoint from the FHIR operations framework. The resource being transmitted in the body of the http request is a FHIR "Bundle" resource. This request payload needs to support two purposes, both the transmission of information as well as an indicator to direct the recieving system to how this particular bundle of resources is to be processed and what workflow should be triggered as a result of its consumption. + +These core functions are: + +* making a referral +* cancelling/amending a referral +* making a booking +* cancelling/amending a booking +* providing a response/feedback communication + +At the highest level this pattern follows the following key steps: + +* **Sender** GET the message definition for the payload/workflow being attempted +* **Sender** composes the bundle (as defined by the message definition) ready for POST-ing. +* **Sender** does a POST request to the **receiver**s' /$process-message endpoint. +* **Receiver** inspects the request header and the bundle MessageHeader resource for the *core workflow variables* indicating how to process and consume the bundle. +* **Receiver** send http response message back to the **sender**. + +Below is a pseudo code example, showing the above process in detail, illustrating how a message could be interpreted using core workflow variables for a message sent to POST /$process-message. + +Each Application will have a tailored example of the below pseudo code. + +<details><summary>> <b class="barslink">Click here to show example</b></summary> + +```c# +Receive_Request +{ + initialise_variable "messageType" + initialise_variable "MessageReason" + initialise_variable "RequestType" + + //HTTP_Headers + { + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + //Bundle + { + if(Bundle.meta.versionID is null) + OperationOutcome.issue.code = "invariant" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if!(Bundle.meta.versionID in versionID.supported) + OperationOutcome.issue.code = "not-supported" + throw exception with "REC_UNPROCESSABLE_ENTITY" + then return with HTTP.ResponseCode 422 + } + //Contents; + { + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + else if(Encounter.Status.In("triaged","in-progress") + {RequestType = "Im Receiving a new Validation Request";} + else + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + break; + case "Referral": + if (Careplan.status != "completed") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + else if(Encounter.Status.In("triaged","finished")) + RequestType = "Im Receiving a new Referral" + else + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if (MessageHeader.reason.code == "update") + { + switch(ServiceRequest.category) + { + case "Validation": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled validation request";} + else if(ServiceRequest.status.In("active","on-hold")) + {RequestType = "im receiving an update to a validation request";} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + case "Referral": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled referral"} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + + } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400} + break; + case "servicerequest-response": + if (MessageHeader.Response is null ) + { + RequestType = "Invalid servicerequest-response" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + else if ( !Message.Response.identifier.existsLocally()) + { + RequestType = "none or invalid response ID" + OperationOutcome.issue.code = "not-found"//A content validation rule failed + throw exception with "REC_NOT_FOUND" + then return HTTP.ResponseCode 404; + } + switch (ServiceRequest.Category) + { + case "Referral": + if (ServiceRequest.status == "revoked" && MessageHeader.reason.code == "new") + { RequestType = "im receiving a Safeguarding DNA response (noshow)" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + break; + case "Validation": + if(!AnyEncounter.Originates.Local && Encount.Count()<=3) + { + if (MessageHeader.Reason.code == "new" && ServiceRequest.status == "active" && MessageHeader.FocusEncounter.status=="in-progress") + {Request Type = "im receiving a Validation Response interim update" } + else if (MessageHeader.Reason.code.In ("new","update") && ServiceRequest.status == "completed" && MessageHeader.FocusEncounter.status.In("triaged","complete") + {Request Type = "im receiving a final Validation Response" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if(MessageHeader.FocusEncounter.status = "triaged" && ServiceRequest.status == "revoked" && MessageHeader.Reason.code.In("new","update")) + { RequestType = "im receiving a Rejected validation response" } // a new encounter here is an edge case. + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + case "booking-request": + if (MessageHeader.Reason.code== "new" && Appointment.Status == "booked") + if(slot.IsFree()) + {RequestType = "Im Receiving a new booking.";} + else + { + OperationOutcome.issue.code = "conflict" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + else if (MessageHeader.Reason.code == "update") + MessageHeaderIsUpdate = true; + switch (Appointment.Status) + { + case "cancelled": + RequestType = "Im Receiving a booking cancellation." + break + case "entered-in-error": + RequestType = "Im Receiving a booking cancellation." + break + case "booked": + RequestType = "Im Receiving an update to a booking." + break + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + break; + } + else + { + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + } + break; + case "booking-response": + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + } + + } + //Submit + { + + if (Message == "update") + { + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + foreach (Entry in Bundle) + { + if (currentLocalData.Item.exists) + { + if (currentLocalData.LastUpdated > originaRequest.Received) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + if(Entry.LastUpdated > currentLocalData.Item.meta.LastUpdated && Entry.fullUrl = currentLocalData.Item.fullUrl) + currentLocalData.Item = Entry.Item + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + else + ignore + } + else + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + } + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + else + { + foreach(Entry in Bundle) + { + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + } + } +} +``` + +</details> + + +<br> +<hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md new file mode 100644 index 00000000..b5442064 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md @@ -0,0 +1,34 @@ +--- +topic: core-SPUseCaseCategories-1.0.7 +--- + +# {{page-title}} + +## What are use case categories? + +Use case categories define the specific type of referral being requested. The type is categorised at the service level. A BaRS Application can support multiple use cases; a use case can only ever belong to one BaRS Application. For instance, in Application 6 there are three defined use cases: Out of Area, Mutual Aid and Call Assist. All of these use cases relate to referrals between Ambulance Service Trusts but the workflow, timeframes and responses are not universal across all three scenarios. + +The BaRS use case categories are defined in the BARS CodeSystem (https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). All BaRS compliant solutions must adopt use case categories. + +## How to use BaRS use case categories + +The use case category is used in the initial content negotiation phase: +* when a Sender makes a request for MessageDefinitions and the Receiver responds +* when the Sender makes a referral request to the Receiver + + +When a Sender makes a request for MessageDefinitions, the MessageDefinitions returned by the Receiver will contain a use case category code (from the use case categories code system) under Message.Definition.useContext.code. The Sender **must** read this field to verify the Receiver supports the use case workflow they require. The use case category code will also be included in: +* the Sender's service request under ServiceRequest.category +* the Sender’s booking request under Appointment.ServiceCategory + +If this is not a use case supported by the Receiver, they will respond with an error (Operation Outcome). + +The sequence of events occurs as follows: +* the Sender requests the MessageDefinitions +* the Receiver indicates the use-case categories they support +* the Sender reads and only engages in the use-case workflows supported +* the Sender's request includes the use-case category code (the same code they read from the MessageDefinition), under ServiceRequest.category (referral) or Appointment.ServiceCategory (booking) +* the Receiver processes accordingly + + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/index.page.md new file mode 100644 index 00000000..7cdacf90 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/index.page.md @@ -0,0 +1,3 @@ +--- +topic: Core-StandardPattern-1.0.7 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/toc.yaml new file mode 100644 index 00000000..66f49100 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Standard-Pattern-Composite-Messages/toc.yaml @@ -0,0 +1,12 @@ +- name: index + filename: index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Standard Pattern For Composites + filename: Standard-Pattern-For-Composites.page.md +- name: Message Headers + filename: Message-Headers.page.md +- name: Cancellation + filename: Cancellation.page.md +- name: Use Case Categories + filename: Use-Case-Categories.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Definition-of-a-retry.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Definition-of-a-retry.page.md new file mode 100644 index 00000000..d4f6f1cc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Definition-of-a-retry.page.md @@ -0,0 +1,14 @@ +--- +topic: Core-TransactionalIntegrity-RetryDefinition-1.0.7 +--- + +## Definition of a retry + +In this context a retry is an attempt to send the same message, without any changes following a failure. This means: + +- the Message body is the same +- the X-Request-ID and X-Correlation-ID are unchanged +- no other header items have changed. (with the potential exemption of the Access Token) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Failure-Scenarios.page.md new file mode 100644 index 00000000..8968ba6c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Failure-Scenarios.page.md @@ -0,0 +1,422 @@ +--- +topic: core-TIFailureScenarios-1.0.7 +--- + +## Failure Scenarios + +When a message is received, the X-Request-ID and X-Correlation-ID header values are stored appropriately. In this example, this occurs ahead of the message being processed but after any access control is applied by means of the other available headers. + +If a message fails due to a message with the same header ids having already been processed, the response must be a 409, REC_CONFLICT with an OperationOutcome.issue.code of 'duplicate' as seen below. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-1.0.0.svg) + +<br> + +### 401 Outcome + +<json> + +      { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "security", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_UNAUTHORIZED" + +             "display": "401 - REC_UNAUTHORIZED"         + +           } + +         ] + +       }, + +       "diagnostics": "Details of the Exact problem" + +     } + +   ] + + }    + +</json> + +### 409 Outcome + +<json> + +         { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + }     + +</json> + +In the event of a timeout, a retry attempt is made after a suitable amount of time to ensure the message was received. The same X-Request-ID and X-Correlation-ID must be used. Should a 409 REC_CONFLICT response be received with a OperationOutcome.issue.code of "duplicate", then this can be used as confirmation that the message was received. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Timeout-Failure-Scenario-1.0.0.svg) + + +### 408 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "timeout", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TIMEOUT" + +             "display": "408 - REC_TIMEOUT"         + +           } + +         ] + +       }, + +       "diagnostics": "The connection for this request has timed out." + +     } + +   ] + + } + +</json> + +### 409 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + } + +</json> + +If the processing of a message is not completed prior to the initial retry, the receiver must respond with a 425 REC_TOO_EARLY response, to indicate the initial message is still processing. The receipt is then unconfirmed and the sender can retry after a suitable amount of time until they receive a desired response. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-solution-1.0.0.svg) + + +### 408 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "timeout", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TIMEOUT" + +             "display": "408 - REC_TIMEOUT"         + +           } + +         ] + +       }, + +       "diagnostics": "The connection for this request has timed out." + +     } + +   ] + + } + +</json> + +### 425 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "98ae13af-3bc7-8cc5-4ac7-ea4f14d47dc9", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TOO_EARLY" + +             "display": "425 - REC_TOO_EARLY"         + +           } + +         ] + +       }, + +       "diagnostics": "The Server has not finished processing the previous attempted request." + +     } + +   ] + + } + +</json> + +### 409 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + } + +</json> + +The scenarios above describe the response where a message is successful. If a message is not successfully processed following a timeout, the receiver should respond with the response that that failure would have generated. In the diagram below the final response inherits its response from the message that has failed after the timeout. + +The relevant 4xx or 5xx response is what the sender receives as a response, ensuring the correct reason for a failure is communicated. + + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Feedback--response--requests.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Feedback--response--requests.page.md new file mode 100644 index 00000000..fb677dd0 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Feedback--response--requests.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Feedback-1.0.7 +--- + +## Feedback (response) requests + +In the event of feedback (a response), for example, a Safeguarding/DNA message; the receiver (becoming the sender effectively) sends a request to the initial sender with a new X-Request-ID and the same X-Correlation-ID as the original request. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Feedback-Request-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Index.page.md new file mode 100644 index 00000000..af6bd0b5 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: Core-TransactionalIntegrity-1.0.7 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Initial-Request.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Initial-Request.page.md new file mode 100644 index 00000000..9d90d5d4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Initial-Request.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Initial-1.0.7 +--- + +## Initial Request + +The X-Correlation-ID is a conversation ID for this Encounter or Case. In our initial request both IDs are supplied by the original sender. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-Request-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Introduction.page.md new file mode 100644 index 00000000..38d69107 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Introduction.page.md @@ -0,0 +1,26 @@ +--- +topic: Core-TransactionalIntegrity-introduction-1.0.7 +--- + +# Transactional Integrity + +Transactional integrity is employed to ensure data integrity is maintained between two parties. It helps ensure that the success or failure of a message is known and can be confirmed. + +There are two existing header items for requests currently available to allow BaRS to meet transactional integrity requirements. They are listed below with their intended uses. The [BaRS API specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) contains example values for these entries. + +| Header | Requirement | Description | Value | +|------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| X-Correlation-ID | Required | A globally unique identifier for the request that can be used to track related transactions across multiple systems. | string representing a GUID | +| X-Request-ID | Required | A globally unique identifier for the request, used to de-duplicate repeated requests and to trace the request for support purposes if needed. | string representing a GUID | + +Transactional integrity is based on guidance in the [FHIR standard](https://www.hl7.org/fhir/http.html#custom). The header items are used as outlined below: + +- the sender will generate both IDs at the beginning of a request for a message. +- the receiver will respond to this initial message, echoing back both IDs. The receiving server does not need to generate a new ID. +- any feedback requests from receiver to the initial sender shall use a new X-Request-ID but retain the X-Correlation-ID. This will be as a new message of the same conversation. +- any subsequent updates from the sender to the receiver shall use a X-Request-ID but will retain the original X-Correlation-ID. This will be as a new message of the same conversation. +- any onward referrals of a message will use a new X-Request-ID but retain the X-Correlation-ID +- a receiver of any message will not accept two messages with the same request and X-Correlation-IDs + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Onwards-Referrals.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Onwards-Referrals.page.md new file mode 100644 index 00000000..a4cfc297 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Onwards-Referrals.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Onward-1.0.7 +--- + +## Onward Referrals + +The X-Correlation-ID is retained in all interactions. This is beneficial for logging and auditing as using the X-Correlation-ID you can see all interactions for this encounter. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Onward-Referral-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Receiver-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Receiver-responsibilities.page.md new file mode 100644 index 00000000..17ea6930 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Receiver-responsibilities.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-TransactionalIntegrity-Receiver-1.0.7 +--- + +## Receiver responsibilities + +- return the X-Request-ID and X-Correlation-ID in responses at ALL times, where possible +- reject any message with no X-Request-ID and X-Correlation-ID, without exception with REC_BAD_REQUEST (400) +- in the event that a duplicate message that has already been correctly processed is received, return a response with REC_CONFLICT (409) and an operationOutcome.issue.code of "duplicate" +- this combination of codes can only be used in a duplicate message scenario + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Retry-Scenario.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Retry-Scenario.page.md new file mode 100644 index 00000000..eba75086 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Retry-Scenario.page.md @@ -0,0 +1,20 @@ +--- +topic: Core-TransactionalIntegrity-RetryScenario-1.0.7 +--- + +## Retry scenario + +Should a request fail for any reason and the sender not receive a response (in any of the above scenarios) the sender is to retry the request, retaining the same X-Request-ID and X-Correlation-ID as the initial attempt. This allows the receiver to identify whether it has already processed this message or not. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Retry-Scenario-1.0.0.svg) + + +This satisfies the need to be able to handle transaction integrity, and for the most part auditing/logging. There are two more scenarios that need to be clarified: + +- onwards referrals +- sending a booking and referral + +The proposal is to retain the X-Correlation-ID for two separate and distinct messages concerning the same encounter or case. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sender-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sender-responsibilities.page.md new file mode 100644 index 00000000..77dfd760 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sender-responsibilities.page.md @@ -0,0 +1,30 @@ +--- +topic: Core-TransactionalIntegrity-Sender-1.0.7 +--- + +## Sender responsibilities + +The frequency of retries and the duration of a retry period depends on the scenario and should not disrupt workflow. Exponential backoff is considered best practice however it is at the discretion of the sender to define how many times a retry is attempted. + +- retry in the event X-Request-ID and X-Correlation-ID is not in the response +- retry in the event no OperationOutcome is in the body of the response +- retry when an OperationOutcome from a receiver contains one of the following values and response codes: + - REC_TIMEOUT (408) + - REC_TOO_MANY_REQUESTS (429) + - REC_UNAVAILABLE (503) +-retry when an OperationOutcome from BaRS itself contains one of the following: + - PROXY_TIMEOUT / TIMEOUT (504 indicating 408 internally) + - PROXY_TOO_MANY_REQUESTS / TOO_MANY_REQUESTS (500 indicating a 408 internally) + - PROXY_UNAVAILABLE / UNAVAILABLE (503) +- retry when an OperationOutcome from the BaRS API contains one of the following: + - SEND_TOO_MANY_REQUESTS (429) + - SEND_FORBIDDEN (403), on the assumption the access token issue is resolved +- it is then at the senders discretion as to whether they update other properties of the message accordingly +- do not retry a request again if a response with the following attributes is received, this indicates the message was successfully sent + - REC_CONFLICT (409) + - an operationOutcome.issue.code of "duplicate" + +Any intermediary network device responding 'on behalf or in lieu' of the API or the receiver is not likely to respond with an OperationalOutcome or the required X-Request-ID and X-Correlation-ID. Any response not having either one of these properties can be safely deemed a communications failure, a temporary interruption to connectivity or could potentially indicate a service outage. Any of these scenarios could, but not always, warrant an retry. This would be at the discretion of the suppliers however these failed interactions should be logged with as much detail as possible. Errors outside of the HTTP standard should also be logged locally with as much detail as possible, for example; Transport-Layer error messages. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sending-an-update.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sending-an-update.page.md new file mode 100644 index 00000000..798c25bd --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/Sending-an-update.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Update-1.0.7 +--- + +## Sending an update + +For an update or subsequent message, a new X-Request-ID is generated, therefore allowing the receiver to accept the new message. The X-Correlation-ID remains unchanged to indicate it is part of the same conversation. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Sending-An-Update-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/toc.yaml new file mode 100644 index 00000000..b7f619a8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/Transactional-integrity/toc.yaml @@ -0,0 +1,20 @@ +- name: Index + filename: Index.page.md +- name: Initial Request + filename: Initial-Request.page.md +- name: Sending an update + filename: Sending-an-update.page.md +- name: Feedback (response) requests + filename: Feedback--response--requests.page.md +- name: Retry Scenario + filename: Retry-Scenario.page.md +- name: Onwards Referrals + filename: Onwards-Referrals.page.md +- name: Definition of a retry + filename: Definition-of-a-retry.page.md +- name: Receiver responsibilities + filename: Receiver-responsibilities.page.md +- name: Sender responsibilities + filename: Sender-responsibilities.page.md +- name: Failure Scenarios + filename: Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/toc.yaml new file mode 100644 index 00000000..1228533d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.0.7/toc.yaml @@ -0,0 +1,38 @@ +- name: Index + filename: Index.page.md +- name: + filename: End-to-end-workflow +- name: + filename: Core-Functionality-Requirements +- name: + filename: BaRS-FHIR-Usage +- name: + filename: Security-and-Authorisation +- name: + filename: Error-Handling +- name: + filename: Transactional-integrity +- name: + filename: Non-Functional-Requirements +- name: + filename: Standard-Pattern-Composite-Messages +- name: Core functionality requirements + filename: Core-functionality-requirements.page.md +- name: BaRS FHIR usage + filename: BaRS-FHIR-usage.page.md +- name: Journey ID + filename: Journey-ID.page.md +- name: LastUpdatedDate + filename: LastUpdatedDate.page.md +- name: How to handle times + filename: How-to-handle-times.page.md +- name: Security and authorisation + filename: Security-and-authorisation.page.md +- name: Error handling + filename: Error-Handling.page.md +- name: Transactional integrity + filename: Transactional-integrity.page.md +- name: Non functional requirements + filename: Non-functional-requirements.page.md +- name: Standard Pattern for BaRS Operations + filename: Standard-Pattern-for-BaRS-Operations.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.1.6/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.1.6/Standard-Pattern-Composite-Messages/Cancellation.page.md index d1bb32c3..3a224027 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.1.6/Standard-Pattern-Composite-Messages/Cancellation.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.1.6/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -57,6 +57,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.2.2/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.2.2/Standard-Pattern-Composite-Messages/Cancellation.page.md index 6fbe23e7..e79cc470 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.2.2/Standard-Pattern-Composite-Messages/Cancellation.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.2.2/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -57,6 +57,7 @@ This payload is used to transmit all the necessary information that is required | Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | | Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | | Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.versionId | | MUST | 1..1 | | | Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | | Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | | Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md new file mode 100644 index 00000000..79da1ce1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md @@ -0,0 +1,112 @@ +--- +topic: core-StandardPattern-appointment-cancel-1.3.0 +--- + +### Cancel + +To cancel an appointment: + +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Set the Appointment.status value to "cancelled" +* Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} + +resource returned: +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T15:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "booked", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` + +Request body: +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T16:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "cancelled", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` +OR if the appointment was entered in error + +Request body: +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T16:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "entered-in-error", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` + +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_Foundation_Cancel.drawio.svg" ></img> + +Once the appointment is cancelled, the Receiver is responsible for managing the pointer in the central Registry, as described {{pagelink:core-StandardPattern-document-reference-1.3.0, text: here}}. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Index.page.md new file mode 100644 index 00000000..43388d9d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-StandardPattern-appointment-1.3.0 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Initial-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Initial-Booking.page.md new file mode 100644 index 00000000..3b1ad0e8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Initial-Booking.page.md @@ -0,0 +1,57 @@ +--- +topic: core-StandardPattern-appointment-booking-1.3.0 +--- + +## Appointment Resource + +Below are examples of each of the described interactions. The appointment resource adheres to the [UKCore-Appointment](https://simplifier.net/HL7FHIRUKCoreR4/UKCore-Appointment) definition. + +Any operations that modify an existing resource must perform a read before a write. GET /Appointment/\{id\} + +### Book +The method for the initial booking of an appointment depends on the {{pagelink:Home/Applications/BaRS-Applications, text:Application}} specific guidance within BaRS. Within BaRS Applications, making a booking will involve building a FHIR bundle and making a POST to the [$process-message](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/$process-message) endpoint. Alternatively, booking an appointment can be used outside of use-cases supported by a BaRS Application, to fulfil a generic Appointment Management Foundation workflow against the discete [booking endpoints](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/Appointment), either way, the typical sequence of events is: + +* {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.3.0, text:Select the service}} to book an appointment with. +* Confirm BaRS [Capabilities](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/metadata). +* [Request Available slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot). +* Select a slot. +* Send a Request to [book an appointment](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/Appointment) in that slot + +Request Body + +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T15:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "booked", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` + +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_Foundation_Book.drawio.svg" ></img> + +Once the appointment is created, the Receiver is responsible for managing the pointer in the central Registry, as described {{pagelink:core-StandardPattern-document-reference-1.3.0, text: here}}. + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Introduction.page.md new file mode 100644 index 00000000..1ef58ef6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Introduction.page.md @@ -0,0 +1,46 @@ +--- +topic: core-StandardPattern-appointment-Introduction-1.3.0 +--- + +# Standard Pattern - Appointments + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b>Important: Release information</b> +<p>This Section of the Implementation Guide is currently a preview, in an Alpha state and subject to change.</p> +</div> + +## Introduction + +The [BaRS API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir) suite can be used where there is no specific use-case supported by the {{pagelink:Home/Applications/BaRS-Applications, text:Applications}} to fulfil generic Appointment workflows, referred to as Appointment Management Foundation. This section outlines the functionality supported, workflows involved and how these correspond with the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0). + +This includes using {{pagelink:core-StandardPattern-document-reference-1.3.0, text: DocumentReference Standard Pattern}} to write pointers for Appointments to a central respository, commonly referred to as the Registry. + +The Appointment Management Foundation is based on {{pagelink:design-core-1.3.0, text:BaRS Core}} and an understanding of the central tenets is essential before beginning. This includes: - +* {{pagelink:core-EndToEndWorkflow-1.3.0, text:End to end workflow }} - how Senders and Receivers, interacting through the central Proxy, negotiate compatibility and engage +* {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.3.0, text:Service Discovery }} - every workflow must include the resolution of a receiving Service Identifier +* {{pagelink:core-Security-1.3.0, text:Authentication and Authorisation }} - the central Proxy will handle Authentication but Authorisation is handled by Receivers +* {{pagelink:onboarding, text:Onboarding to environments }} - getting access to the central Proxy. This differs for Senders (OAuth) and Receivers (mTLS) + +There are four functions that are required surrounding appointments. This section will provide information on how to meet them using the Appointment Resource. + +* The ability to book an appointment. +* The ability to cancel an appointment. +* The ability to update an appointment. +* The ability to rebook an appointment. + +## Interface + +The following table describes how the BaRS API accomodates these four capabilities using the [/Appointment](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/Appointment) endpoint and the [/Appointment/\{id\}](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) endpoint + +| Capability | Endpoint | VERB | Description | +|------------|-----------|-----|--------------| +| [List](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/DocumentReference) | /DocumentReference | GET | Using the {{pagelink:core-StandardPattern-document-reference-Introduction-1.3.0, text:DocumentReference}} pattern, a list of existing appointments for a patient can be viewed with the central Registry. | +| [View](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) | /Appointment/\{id\} | GET | This action, using the id from the List capability, will allow that specific Appointment Resource to be [retrieved](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) from the healthcare service who owns it. | +| [View (Search)](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment) | /Appointment | GET | If the Appointment.id is not known, the Sender can perform a look up based the patient national identifier (NHS No.) or demographics (Name (as defined by [FHIR](https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/2834389 )), Date of Birth, Home Address Postcode). This returns a (FHIR) bundle of resources for the specific Appointment Resource to be [retrieved](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment) from the healthcare service who owns it. See {{pagelink:core-SPCancellation-1.3.0, text:Cancellation}} for further detail.| +| [Get Slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot) | /Slots | GET | Obtain a list of available booking slots from a specified receiving system using the [GET /Slots endpoint](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot) | +| [Book](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/Appointment) | /Appointment or /$process-message | POST | This will be a POST operation, with a BaRS Application /$process-message is typically used, outside of supported use cases /Appointment is adopted.| +| [Cancel](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) | /Appointment/\{id\} | PUT| The cancel of a booking will be setting the status of the appointment to "cancelled". Cancel is also possible using /$process-message | +| [Update](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) | /Appointment/\{id\} | PUT / PATCH| An update to an appointment will be a direct update to the existing resource | +| [Rebook](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#post-/Appointment) | Composite of Cancel and then Book | Composite | Requesting a new booking and then cancelling the existing one will constitute a rebook | + + +In line with the BaRS standard all operations used to modify a resource must be preceded by a read of the resource by means of a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation. diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md new file mode 100644 index 00000000..8074e2c6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md @@ -0,0 +1,108 @@ +--- +topic: core-StandardPattern-appointment-rebook-1.3.0 +--- + +### Rebook + +Notes on Rebook from https://hl7.org/fhir/R4/appointment.html + +#### Waitlisting the Appointment (optional) + +This optional step permits creating a waitlisted appointment. This could occur if an appointment needs to be booked into a time that is not ideal for the patient due to lack of available time slots. In this workflow, there would be two appointments, the booked appointment in the time slot that is currently available, and the waitlisted appointment with a requestedPeriod spanning the time that the patient would prefer if new slots become available. + +If new time slots become available during the requestedPeriod, the scheduling system, or staff at the scheduling organization, can notify the patient that a new time slot is available. If the patient chooses, the waitlisted appointment would then be booked into that specific slot, and the previously booked appointment would be cancelled. The specific business process for notifying patients of new availability is not specified, and is up to the implementing system to determine. + +under section 12.10.4.5 Flow for a patient waitlist: + +| Activity Description | Appointment (inconvenient) | Appointment (preferred) | +|--------------------------------------------------------------------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------| +| An appointment is booked for an inconvenient time using a typical status flow | status = bookedparticipant.status = accepted | | +| Waitlist appointment created | status = bookedparticipant.status = accepted | status = waitlistrequestedPeriod = (more convenient time period) | +| Patient notified of availability of a better slot | status = booked | status = proposedparticipant.status = needs-action | +| Patient accepts better slot | status = cancelled | status = bookedparticipant.status = accepted | + +The FHIR guidance indicates that the Appointment that is no longer needed should be updated with a PUT status=cancelled + +A new Appointment can then be created as needed using the same existing workflow, whether this is using the Slot/Schedule or a POST Appointment resource. +Use the cancel method described above. + +#### Process for rebook +The method for the subsequent booking of an appointment depends on the Application specific guidance within BaRS. The only difference would be the Appointment Resource would include Appointment.replaces referencing the previous appointment for provenance. +Alternatively, rebooking an appointment can be used outside of use-cases supported by a BaRS Application, to fulfil a generic Appointment workflow, either way, the typical sequence of events using PUT or POST is: + +* {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.3.0, text:Select the service}} to book an appointment with. +* Confirm BaRS [Capabilities](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/metadata). +* [Request Available slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot). +* Select a slot. +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Set the Appointment.status value to "cancelled" +* Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} + +Request Body + +```json +{ + "resourceType": "Appointment", + "id":"1ed510f2-df15-45b7-8852-8adfb0fcf4f3" + "meta": { + "lastUpdated": "2024-01-11T15:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "booked", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ], + "replaces": [ + { + "reference": "Appointment/aca94bdb-2e38-4399-9ece-2ba083ce65b5" + } + ] +} +``` + +Using PATCH: + +* {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.3.0, text:Select the service}} to book an appointment with. +* Confirm BaRS [Capabilities](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/metadata). +* [Request Available slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot). +* Select a slot. +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} +* Set the Appointment.status value to "cancelled" +* Perform a [PATCH](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#patch-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} + +```json +{ + "resourceType": "Appointment", + "id":"1ed510f2-df15-45b7-8852-8adfb0fcf4f3", + "status": "booked", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", +} +``` + +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_Foundation_ReBook.drawio.svg" ></img> + +Once the appointment is rebooked, the Receiver is responsible for managing the pointer in the central Registry, as described {{pagelink:core-StandardPattern-document-reference-1.3.0, text: here}}. diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md new file mode 100644 index 00000000..11cd8cdc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md @@ -0,0 +1,74 @@ +--- +topic: core-StandardPattern-appointment-update-1.3.0 +--- + +### Update + +To update an appointment: + +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Amend or append the resource as required. +* Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} + +In this example a placeholder was created, and updated when the slot is selected. This is a hypothetical scenario. + +resource returned: +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T15:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "waitlist", + "description": "Reason for calling", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` + +Request Body + +```json +{ + "resourceType": "Appointment", + "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5" + "meta": { + "lastUpdated": "2024-01-11T15:01:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment" + ] + }, + "status": "booked", + "slot": [ + { + "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda" + } + ], + "description": "Reason for calling", + "start": "2024-02-12T12:30:30+00:00", + "end": "2024-02-12T12:40:30+00:00", + "created": "2024-10-08T15:01:30+00:00", + "participant": [ + { + "actor": { + "reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2" + }, + "status": "accepted" + } + ] +} +``` +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_Foundation_Update.drawio.svg" ></img> + +Once the appointment is updated, the Receiver is responsible for managing the pointer in the central Registry, as described {{pagelink:core-StandardPattern-document-reference-1.3.0, text: here}}. diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/toc.yaml new file mode 100644 index 00000000..368719f9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/toc.yaml @@ -0,0 +1,13 @@ +- name: Index + filename: index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Initial Booking + filename: Initial-Booking.page.md +- name: Update a Booking + filename: Update-Existing-Booking.page.md +- name: Cancel a Booking + filename: Cancel-Booking.page.md +- name: Rebook Methods + filename: Rebook-Methods.page.md + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Bundle.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Bundle.page.md new file mode 100644 index 00000000..cf054ebc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Bundle.page.md @@ -0,0 +1,14 @@ +--- +topic: core-FHIRUsage-bundle-1.3.0 +--- + +## Bundle + +The use of the FHIR bundle in BaRS primarily supports the use of $process-message. It is also used as follows: + +- When $process-message is initiated, a sender packages up numerous FHIR resources (MessageHeader, Patient, ServiceRequest etc.), the bundle will include everything needed by a receiver to process the request being made. +- The $process-message endpoint is capable of receiving different types of request. The sender indicates the the action required by specifying in the MessageHeader resource, for example: booking or servicerequest, the operation, whether it be 'new' or 'update' and central FHIR resource from which to make sense of the bundle, the 'focus'. +- A bundle type of 'searchset' is also used in BaRS when a receiver responds to a senders request for available slots, in the booking workflow. A receiver responds by bundling FHIR resources (HealthcareService, Schedule, Slot(s) etc.) related to particular HealthcareService which a sender will unpack and process to display service availability to a user. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md new file mode 100644 index 00000000..e2b7fd49 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md @@ -0,0 +1,13 @@ +--- +topic: core-FHIRUsage-FHIR-Operations-1.3.0 +--- + +## FHIR Operations framework + +Performing the required steps in workflow using simple CRUD operations on single resources can be complex and relies on prior knowledge or dictates explicit rules around workflow in any given system, for example: a patient must exist before a service request can be made. In order to support complex workflows that utilise composites of resources, simple CRUD operations on sinlge resources would breach some core principles of ReST (e.g. inabililty to maintain stateless communication for example). Therefore BaRS utilises the FHIR operations framework which: + +- offers a degree of autonomy to the receiver of the communication in how they process for their system +- is designed to support events, triggering activity between systems, supporting the response workflow requirements identified by many of the BaRS use cases, for example: 999 to CAS Validation Request/Response. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Frameworks.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Frameworks.page.md new file mode 100644 index 00000000..76a6603e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Frameworks.page.md @@ -0,0 +1,10 @@ +--- +topic: core-FHIRUsage-Framework-1.3.0 +--- + +## Frameworks + +A mix of data exchange frameworks are employed by BaRS to support different workflows. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/How-to-handle-times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/How-to-handle-times.page.md new file mode 100644 index 00000000..833cf549 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/How-to-handle-times.page.md @@ -0,0 +1,18 @@ +--- +topic: core-FHIRUsage-Time-1.3.0 +--- + +## {{page-title}} + +* All times MUST be in FHIR Instant format (```YYYY-MM-DDThh:mm:ss.sssssss+zz:zz```) + * e.g. ```Year-Month-DayTHours:Minutes:Seconds.milliseconds+OffsetFromUTC``` + * e.g. ```2015-02-07T13:28:17.2398742+02:00``` + * *except* where specifically defined otherwise +* All times can have up to seven digits resolution for milliseconds +* All times SHOULD be converted to UTC from local times (if not stored locally in UTC) before being included in any messages, this means the offset should be zero +* When receiving a time in a message a system MUST expect and handle a non UTC time (e.g. with a non-zero offset) + * Therefore if a time is received that is not UTC, the receiver should convert the time back to UTC using the offset given (or to their local time, if storing times in a local time) + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important:</b> +This means both Sender and Receiver systems MUST be able to handle a time provided with an offset from UTC that differs from your local server time. As an illustration, if you store all times in UTC and someone uses a time specifying an offset, you will need to convert it to UTC when you store it. +</div> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Index.page.md new file mode 100644 index 00000000..89390c27 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-FHIRUsage-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Introduction.page.md new file mode 100644 index 00000000..e96a162a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-FHIRUsage-Introduction-1.3.0 +--- + +# BaRS FHIR Usage + +BaRS uses [FHIR](https://digital.nhs.uk/services/fhir-uk-core) to achieve interoperability between healthcare IT systems. This section explains how BaRS makes use of some key FHIR concepts which need to be understood by developers implementing the standard. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Journey-ID.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Journey-ID.page.md new file mode 100644 index 00000000..728b831b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/Journey-ID.page.md @@ -0,0 +1,25 @@ +--- +topic: core-FHIRUsage-JourneyID-1.3.0 +--- + +## {{page-title}} + +The Journey ID uses the episodeOfCare resource. + +Each Encounter between systems can reference the same originating episodeOfCare, allowing grouping of all the Encounters to one flow. + +The FHIR episodeOfCare resource would be created at the beginning of the patient journey when the Encounter is created and leads onto a ServiceRequest or other appropriate flow. + +{{render:Encounter-episodeOfCare-screenshot}} + +This snippet of coding shows the episodeOfCare within the Encounter referencing a GUID that will be used throughout the patients journey. + +```xml +<episodeOfCare> + <!-- Resource reference to an EpisodeOfCare Journey ID --> + <reference value="d877b820-e72b-44d1-a627-195f54bfc606" /> +</episodeOfCare> +``` + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/LastUpdatedDate.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/LastUpdatedDate.page.md new file mode 100644 index 00000000..6eaf6ca9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/LastUpdatedDate.page.md @@ -0,0 +1,17 @@ +--- +topic: core-FHIRUsage-LastUpdated-1.3.0 +--- +## {{page-title}} + +Every resource will include a lastUpdated date in the meta tag. This is to be used for tracking and updating. + +```xml +<meta> + <versionId value="1.0.0-alpha" /> + <lastUpdated value="2021-11-26T15:00:00+00:00" /> + <profile value="https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage" /> +</meta> +``` + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/REST.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/REST.page.md new file mode 100644 index 00000000..88a7f579 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/REST.page.md @@ -0,0 +1,16 @@ +--- +topic: core-FHIRUsage-REST-1.3.0 +--- + +## REST + +FHIR is often associated with REST (REpresentational State Transfer) as a primary method of exchange. BaRS uses REST for many of the benefits it offers - + +- allows independent modular development of client and server APIs (they don't need to know about each other before exchanges) +- easy to integrate because of common agreed standards +- scalability in developing and performance + +In BaRS, simple CRUD operations on single resources is used for discrete atomic functions, such as retrieving a known booking or referral entity. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/process-message.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/process-message.page.md new file mode 100644 index 00000000..737380a0 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/process-message.page.md @@ -0,0 +1,20 @@ +--- +topic: core-FHIRUsage-Process-Message-1.3.0 +--- + +## $process-message + +This specific FHIR operation enables the exchange of complex composites whilst maintaining the principles of REST. The $process-message endpoint will be called at various stages in any of the workflows outlined to fulfil requests such as: + +- 'create a booking' +- 'process a referral for validation' +- 'validation outcome response' + +The endpoint receives only POST requests of bundle type 'message', with the required MessageHeader resource dictating how to process and what is deemed the 'focus' (key Resource) of the request. The sender packages up this content, POSTs to the receiver and lets them decide how to consume and process the bundle. + +You must implement a $process-message endpoint to be compliant with BaRS because it is used for initial requests (booking, service request etc.) but also for responses (validation outcome response etc.). + +Please see the {{pagelink:Core-StandardPattern-1.3.0, text: Standard Patterns}} for generic guidance for processing messages. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/toc.yaml new file mode 100644 index 00000000..cb7ee837 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/BaRS-FHIR-Usage/toc.yaml @@ -0,0 +1,20 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Frameworks + filename: Frameworks.page.md +- name: REST + filename: REST.page.md +- name: FHIR Operations Framework + filename: FHIR-Operations-Framework.page.md +- name: $process-message + filename: process-message.page.md +- name: Bundle + filename: Bundle.page.md +- name: Journey ID + filename: Journey-ID.page.md +- name: LastUpdatedDate + filename: LastUpdatedDate.page.md +- name: How to handle times + filename: How-to-handle-times.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/All.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/All.page.md new file mode 100644 index 00000000..3a5e6973 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/All.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-All-1.3.0 +--- + +### All + +- Provide Capability Statement +- Read and interpret Capability State +- Provide Message Definition(s) for a specific service +- Read and interpret Message Definition(s) for a specific service + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Receiver.page.md new file mode 100644 index 00000000..ec7e6c5f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Receiver.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingReceiver-1.3.0 +--- + +### Booking Receiver + +- Provide Slots for a specific service +- Create Booking +- Cancel Booking +- Accept Rebook request (two open Bookings during this routine) + +<br> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Sender.page.md new file mode 100644 index 00000000..2fac6805 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Booking-Sender.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingSender-1.3.0 +--- + +### Booking Sender + +- Request Slots for a specific service +- Make Booking request +- Cancel Booking request +- Make Rebook request (two open Bookings during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Caching.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Caching.page.md new file mode 100644 index 00000000..97ed32ca --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Caching.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-Caching-1.3.0 +--- + +### Caching + +- The local caching of retrieved metadata (Capability Statements and Message Definitions) requests is permitted to improve performance +- Caching of responses **must <ins>not</ins>** exceed 24 hours (12 hours is recommended) +- There **must** be a mechanism to manually clear the cache + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Index.page.md new file mode 100644 index 00000000..2e40a386 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-FunctionalityRequirements-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Introduction.page.md new file mode 100644 index 00000000..4436469a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Introduction.page.md @@ -0,0 +1,17 @@ +--- +topic: core-FunctionalityRequirements-Introduction-1.3.0 +--- + +# Core Functionality Requirements + +BaRS should provide different functionality depending on: + +- its {{pagelink:applications, text:Application or use case}} +- whether it acts as a sender or receiver + + +This list of functionality will expand in later versions of BaRS. + +There are requirements in each of the central areas of functionality which every BaRS Application must adopt: + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Receiver.page.md new file mode 100644 index 00000000..58a6b545 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Receiver.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralReceiver-1.3.0 +--- + +### Referral Receiver + +- Create Referral +- Cancel Referral +- Accept re-request Service Request (revoke current open Referral prior to sending new. Only one active/open Service Request during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Sender.page.md new file mode 100644 index 00000000..6b7cd0b7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/Referral-Sender.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralSender-1.3.0 +--- + +### Referral Sender + +- Make Referral request +- Cancel Referral request +- Re-request Service Request (revoke current open Referral prior to sending new. Only one active/open Service Request during this routine) + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/toc.yaml new file mode 100644 index 00000000..31db240a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Core-Functionality-Requirements/toc.yaml @@ -0,0 +1,16 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: All + filename: All.page.md +- name: Caching + filename: Caching.page.md +- name: Booking Sender + filename: Booking-Sender.page.md +- name: Booking Receiver + filename: Booking-Receiver.page.md +- name: Referral Sender + filename: Referral-Sender.page.md +- name: Referral Receiver + filename: Referral-Receiver.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md new file mode 100644 index 00000000..87f8d24c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md @@ -0,0 +1,45 @@ +--- +topic: core-StandardPattern-document-reference-interface-1.3.0 +--- + +## Interface + +### Introduction + +The BaRS API will facilitate the DocumentReference Endpoints for BaRS enabled systems. BaRS will forward the requests for DocumentReferences to the NRL API. Acting as a proxy the BaRS API will verify a producer is authorized. + + +| BaRS Path | Maps to NRLF Path | Purpose | +|--------------------------------|---------------------------------------------|-------------------------------------------| +| GET /DocumentReference | NRL Consumer GET /DocumentReference | Read Pointers (search) | +| GET /DocumentReference/[id] | NRL Producer GET /DocumentReference/[id] | Read specific pointer (read before write) | +| POST /DocumentReference | NRL Producer POST /DocumentReference | Add a pointer | +| PUT /DocumentReference/[id] | NRL Producer PUT /DocumentReference/[id] | Update pointer | +| Delete /DocumentReference/[id] | NRL Producer DELETE /DocumentReference/[id] | Remove/delete pointer. | + + +### Request and Response + +This table describes the two endpoints behaviours for the interaction From a BaRS enabled system through to NRLF. + +All Endpoints will use the exsiting Access Control Headers and Transaction Integrity Headers. + +| Behaviour | Initiator | VERB | API Path | Parameters | Payload | Reactor | Reactor Behaviour | Happy Response | Response Definition | +|-----------------|---------------|--------|-------------------------|---------------------------------------------------------------------------------------------|-------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------|------------------------------------------------------| +| Search Pointers | BaRS Sender | GET | /DocumentReference | Query: subject:identifier<br>Query: custodian:identifier<br>Query: next-page-token<br>Query:type | N/A | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Consumer Endpoint<br>NRLF: NRLF returns Bundle of DocumentReferences matching search critieria. | 200 | Search Bundle Response containing DocumentReferences | +| Get Pointer | BaRS Receiver | GET | /DocumentReference/[id] | Path: id | N/A | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Producer Endpoint<br>NRLF: NRLF returns Bundle of DocumentReference matching path param [id]. | 200 | DocumentReference | +| Add Pointer | BaRS Receiver | POST | /DocumentReference | N/A | DocumentReference | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Producer Endpoint<br>NRLF: returns a DocumentReference | 201 | OperationOutcome/DocumentReference | +| Update Pointer | BaRS Receiver | PUT | /DocumentReference/[id] | Path: id | DocumentReference | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Producer Endpoint<br>NRLF: NRLF updates the DocumentReference | 200 | OperationOutcome/DocumentReference | +| Delete Pointer | BaRS Receiver | DELETE | /DocumentReference/[id] | Path: id | DocumentReference | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Producer Endpoint <br>NRLF: NRLF removes the DocumentReference. | 200 | OperationOutcome/DocumentReference | + +### Parameters + +| API Path | Type | Parameter | Format | Purpose | Required? | +|-------------------------|-------|----------------------|-----------------------------------------------------|-----------------------------------------|-----------| +| /DocumentReference | query | subject:identifier | https://fhir.nhs.uk/Id/nhs-number|4409815415 | Filter by Patient | Y | +| /DocumentReference | query | custodian:identifier | https://fhir.nhs.uk/Id/ods-organization-code|Y05868 | Filter by custodian (ODS) | N | +| /DocumentReference | query | next-page-token | - | retrieve next set of 20 records | N | +| /DocumentReference | query | type | http://snomed.info/sct|736253002 | Filter by Appointment or ServiceRequesr | N | +| /DocumentReference/[id] | path | [ id ] | | Specific Document Reference Id. | Y | + +## Payload \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Index.page.md new file mode 100644 index 00000000..7e9e934a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-StandardPattern-document-reference-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Introduction.page.md new file mode 100644 index 00000000..80a8015e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Introduction.page.md @@ -0,0 +1,21 @@ +--- +topic: core-StandardPattern-document-reference-Introduction-1.3.0 +--- + +# Standard Pattern - DocumentReference + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b>Important: Release information</b> +<p>This Section of the Implementation Guide is currently a preview, in an Alpha state and subject to change.</p> +</div> + +## Introduction + +In version 1.1.0 of the BaRS API Specification, functionality was added to accommodate the use of pointers (DocumentReference resources), to locate existing bookings and referrals. + +The FHIR DocumentReference resource allows you to reference and locate clinical documents or resources. This section will walk you through the process of using a FHIR DocumentReference to find a resource's location and retrieve it. + +The BaRS API acts as a gateway to the National Record Locator FHIR API for BaRS enabled Services. In the image below the BaRS API is interacted with by Consumers and Producers. +* Consumer - Queries the API for existing DocumentReferences for use in finding existing Bookings and Referrals. This is usually a BaRS [Sender](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=current#Core-functionality-requirements). +* Producer - Posts and maintains DocumentReferences for Bookings and Referrals that they have received. This is invariably the BaRS [Receiver](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=current#Core-functionality-requirements). + +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/DocumentReference/NRLF Via BaRS-1.1.0.svg" width="1200"></img> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Receiver-DocumentReference.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Receiver-DocumentReference.md new file mode 100644 index 00000000..b4109a5c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Receiver-DocumentReference.md @@ -0,0 +1,107 @@ +--- +topic: core-StandardPattern-document-reference-Receiver-1.3.0 +--- + +# {{page-title}} + +## Creating a DocumentReference. + +The FHIR DocumentReference resource allows you to create a reference to a clinical document or resource. This section describes the process of creating a FHIR DocumentReference for a resource. A DocumentReference will be created when a Receiver accepts a Booking or a Referral. Each request will warrant a distinct Document Reference. + +### Step 1: Understand the Document Reference Resource +The Document Reference resource in FHIR represents a reference to a clinical document or resource. It contains metadata about the document, such as its type, author, and creation date, along with a reference to the actual document's location. Within BaRS the DocumentReference acts as a pointer towards ServiceRequests, or Appointment resources. + +### Step 2: Identify the Resource to Reference +Determine the resource that you want to create a Document Reference for. This will be any ServiceRequest or Appointment Resource that has been created in the Receiver system by means of a booking request or a service request. + +The resources themselves will have unique identifiers upon creation in the receiver system. + +### Step 3: Set the Metadata of the Document Reference +Create a new instance of the Document Reference resource and populate the relevant metadata fields. key fields to include are as follows: + +type: Specify the type of document or resource being referenced. For example, if you are referencing a referral you would use the value `https://snomed.info/ict|736253002` or if it is a booking `https://snomed.info/ict|749001000000101`. + +```json +"type": { + "coding": [ + { + "system": "https://snomed.info/ict", + "code": "736253002" + } + ] +} +``` + +subject: Specify the subject of the document reference, which is typically the patient associated with the Resource. +```json +"subject": { + "identifier": { + "system": "https://fhir.nhs.uk/Id/nhs-number", + "value": "9556274839" + } +}, +``` + +custodian: Set the author of the document reference, which will be the ODS code for the organisation writing the DocumentReference. +```json + "custodian": { + "identifier": { + "system": "https://fhir.nhs.uk/Id/ods-organization-code", + "value": "A1001" + } + } +``` + + +### Step 4: Set the Content Reference +The content element of the Document Reference resource contains the reference to the location of the actual resource. Create a new instance of the content element and set the attachment property. The attachment property has a URL field where you specify the location of the resource. + +Access the content element of the Document Reference. This element contains the reference to the location of the actual resource. The content element is typically an array, as a DocumentReference can reference multiple versions or representations of the same document. Each item in the array will have a URL element, which specifies the location of the resource. + +The content.attachment.URL element in this example is a URL friendly Target Identifier for the receiver endpoint, of which can be used to retrieve the resource via the BaRS proxy by a consumer/sender. This element can also contain a direct URL if appropriate. +The content.format element will contain the coding that describes the format of the resource in question. In this instance this is a [BaRS message event](https://simplifier.net/nhsbookingandreferrals/message-events-bars) of "servicerequest-request". ensure you set the creation date of the resource. + +```json +"content": [ + { + "attachment": { + "language": "en-UK", + "URL": "http://fhir.nhs.uk/Id/dos-service-id|111111111", + "title": "Physical", + "creation": "2005-12-24T09:35:00+11:00" + }, + "format": [ + { + "coding": [ + { + "system": "https://fhir.nhs.uk/CodeSystem/message-events-bars", + "code": "servicerequest-request" + } + ] + } + ] + } +] +``` +### Step 5: Save and Transmit the DocumentReference +Once you have populated all the necessary fields, you will need to perform a POST of the DocumentResource to the /DocumentReference endpoint on the BaRS proxy. This will create a DocumentReference in the NRL. + +After saving, the DocumentReference will be assigned a unique id (e.g., DocumentReference/12345). You can use this identifier to reference or retrieve the DocumentReference in the future. + +### Step 6: Verify the DocumentReference +To ensure that the DocumentReference was created successfully, you can retrieve it using its identifier or search for it using relevant parameters. Make sure to validate the returned DocumentReference to confirm that all the metadata and content references are accurate. + +### Updating a DocumentReference +A DocumentReference can be updated by performing a PUT request with the updated resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate id. A Read operation must be performed prior to this to ensure that the new DocumentReference is the most up to date. + +**Note**: You can only delete DocumentReference resources that you own and that you created. + +### Delete a DocumentReference +A DocumentReference can be updated by performing a DELETE request with the resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate id. A Read operation must be performed prior to this to ensure that the Action is appropriate. + +**Note**: You can only delete DocumentReference resources that you own and that you created. + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/DocumentReference/BaRS_NRL_Write_Sequence-1.1.0.svg" target="_blank"> +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/DocumentReference/BaRS_NRL_Write_Sequence-1.1.0.svg" ></img></a> + +. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Sender-DocumentReference.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Sender-DocumentReference.md new file mode 100644 index 00000000..66347bac --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/Sender-DocumentReference.md @@ -0,0 +1,115 @@ +--- +topic: core-StandardPattern-document-reference-Sender-1.3.0 +--- + +# {{page-title}} + +### Step 1: Understand the Document Reference Resource +The Document Reference resource in FHIR represents a reference to a clinical document or resource. It contains metadata about the document, such as its type, author, and creation date, subject (the patients NHS number), as well as a reference to the actual document's location (URL) and markers for how the method needed to retrieve it. + +### Step 2: Search for the Document Reference +To find a resource's location, you need to search for the appropriate DocumentReference resource. The most common way to search for Document References is by using search parameters. + +For example, if you are looking for a DocumentReference that represents a referral, you could use the following search query, where a snomed code is used to define the type of the document: + +GET [base-URL]/DocumentReference?type=https://snomed.info/ict|736253002 + +The Booking and Referrals API [v1.1.0 specification](google.com) has more information on search parameters available. + +### Step 3: Inspect the Document Reference +Once you retrieve the Document Reference(s) from the search, inspect the returned resources to identify the one you need. Look for relevant metadata like the document type, author, creation date or format to confirm it is the correct resource. + +identifier: The DocumentReference will have an identifier stating the id of the resource. +``` +"identifier": [ + { + "system": "https://fhir.nhs.uk/Id/BaRS-Identifier", + "value": "8c63d621-4d86-4f57-8699-e8e22d49935d" + } +``` + +type: Below you can see the type, within the DocumentReference Resource. Within BaRS there is currently only bookings (749001000000101) and Referrals (736253002), described using SNOMED codes. +```json +"type": { + "coding": [ + { + "system": "https://snomed.info/ict", + "code": "736253002" + } + ] +} +``` + +subject: The subject will describe the patient, by means of an NHS number. + +```json +"subject": { + "identifier": { + "system": "https://fhir.nhs.uk/Id/nhs-number", + "value": "9556274839" + } +``` + +custodian: The custodian element will describe the organization that owns the resource data. This will be a concatenation of ODS codes. + +```json + "custodian": { + "identifier": { + "system": "https://fhir.nhs.uk/Id/ods-organization-code", + "value": "A1001" + } + } +``` +### Step 4: Retrieve the Resource's Location +Access the content element of the Document Reference. This element contains the reference to the location of the actual resource. The content element is typically an array, as a Document Reference can reference multiple versions or representations of the same document. Each item in the array will have a URL element, which specifies the location of the resource. + +The content.attachment.URL element in this example is a URL friendly Target Identifier, of which can be used to retrieve the resource. This element can also contain a direct URL if appropriate. +The content.format element will contain the coding that describes the format of the resource in question. In this instance this is a [BaRS message event](https://simplifier.net/nhsbookingandreferrals/message-events-bars) of "servicerequest-request". + +```json +"content": [ + { + "attachment": { + "language": "en-UK", + "URL": "http://fhir.nhs.uk/Id/dos-service-id|111111111", + "title": "Physical", + "creation": "2005-12-24T09:35:00+11:00" + }, + "format": [ + { + "coding": [ + { + "system": "https://fhir.nhs.uk/CodeSystem/message-events-bars", + "code": "servicerequest-request" + } + ] + } + ] + } +] +``` +### Step 5: Retrieve the Resource +Retrieve the resource by making a GET request to the URL specified in the URL element of the Document Reference's content. Ensure that you have the necessary authorization and access privileges to retrieve the resource. + +For BaRS, a GET of the relevant resource type using the Target Identifiers. In this simplified example the URL above containing a TargetIdentifier is used in the NHSD-Target-Identifier header to instruct the BaRS proxy to route to the request to that target **note**: The header is not base64Encoded in this example: + +``` bash +cURL --location 'https://int.api.service.nhs.uk/booking-and-referral/FHIR/R4/ServiceRequest/8c63d621-4d86-4f57-8699-e8e22d49935d' \ +--header 'X-Request-ID: {{X-Request-ID}}' \ +--header 'X-Correlation-ID: {{X-Correlation-ID}}' \ +--header 'NHSD-Target-Identifier: {system:"http://fhir.nhs.uk/Id/dos-service-id", value:"111111111"}' \ +--header 'Accept: application/fhir+json' \ +``` + +Also, if the content element has a direct URL, this can be obtained using a direct GET request. + +### Step 6: Handle the Retrieved Resource +Once you have retrieved the resource, you can process it according to your requirements. The format and structure of the resource will depend on the specific resource type, such as Patient or ServiceRequest. Refer to the FHIR documentation or resource-specific or application-specific guides for further information on handling the retrieved resource. + +**Note**: It's important to consider the security and privacy aspects when working with clinical documents and resources. Ensure that you adhere to applicable regulations and best practices to protect patient data. + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/DocumentReference/BaRS_NRL_Search_Sequence-1.1.0.svg" target="_blank"> +<img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/DocumentReference/BaRS_NRL_Search_Sequence-1.1.0.svg" ></img></a> + +. + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/toc.yaml new file mode 100644 index 00000000..9ac19ca8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/DocumentReference-StandardPattern/toc.yaml @@ -0,0 +1,8 @@ +- name: Index + filename: index.page.md +- name: Introduction + filename: Introduction.page.md +- name: DocumentReferences for Senders + filename: Sender-DocumentReference.md +- name: DocumentReferences for Receivers + filename: Receiver-DocumentReference.md \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Asynchronous-Workflow.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Asynchronous-Workflow.page.md new file mode 100644 index 00000000..dc5bf40b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Asynchronous-Workflow.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-AsyncWorkflow-1.3.0 +--- + + +## {{page-title}} + +The FHIR $process-message function supports 'async' parameter but BaRS does not employ this, all $process-message requests are synchronous. + +However, BaRS does support request-response loops which are asynchronous. An example of this is the Safeguarding DNA response workflow; the sender (NHS 111 Telephony service) sends a referral with a safeguarding concern flag to an Emergency Department, the patient subsequently doesn't attend (DNAs). The Emergency Department receiver is now responsible for sending a response back to the original sender (the NHS 111 Telephony service) to inform them of the DNA. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authenticate-with-BaRS.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authenticate-with-BaRS.page.md new file mode 100644 index 00000000..e62be02c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authenticate-with-BaRS.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-BaRSAuth-1.3.0 +--- + +## Authenticate with BaRS + +The sender must have already [connected with our platform](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) in order to generate an access token to make a request of the BaRS API. The sender generates and signs a JWT and sends this request to the BaRS token endpoint which provides an access token to be used to interact with the BaRS API. +A receiver will follow the same process to interact with BaRS API when providing feedback to an original sender, for example. The sender and receiver switch roles in the workflow for referral in both the current first-of-type use cases. This is only relevant to some Applications and will be detailed in the specific {{pagelink:Applications , text:application guide.}} + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authentication-and-Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authentication-and-Authorisation.page.md new file mode 100644 index 00000000..90f073ec --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Authentication-and-Authorisation.page.md @@ -0,0 +1,15 @@ +--- +topic: core-EndToEndWorkflow-Auth-1.3.0 +--- + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------| +| Authorisation | Required by the sender and not forwarded to the receiver | Will contain a token obtained from the relevant OAuth endpoint for the BaRS API being called. This token facilitates authentication with the API. | String representing a token | +| NHSD-End-User- Organisation | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the organisation making the request. Can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR Organization resource | +| NHSD-Requesting-Practitioner | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the healthcare professional making the request. Can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR PractitionerRole resource | +| NHSD-Requesting-Software | Optional for the sender and forwarded to the receiver | For authorisation purposes this header contains information about the application making the request. This can be used by the receiver to impose access control limitations and should be retained for auditing purposes. | Base64 encoded object based on a FHIR Device resource | + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/BaRS-FHIR-API.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/BaRS-FHIR-API.page.md new file mode 100644 index 00000000..6e989944 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/BaRS-FHIR-API.page.md @@ -0,0 +1,14 @@ +--- +topic: core-EndToEndWorkflow-API-1.3.0 +--- + +## BaRS FHIR API + +The [BaRS FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) supports all functionality with receiver APIs for both booking and referrals. Once an access token has been obtained, the sender can start making requests of the API. + +Note: With every API request the sender must include the HTTP header parameter 'NHSD-Target Identifier'. + +You can find details for each endpoint in the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Header.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Header.page.md new file mode 100644 index 00000000..968b2a81 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Header.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-HTTPHeader-1.3.0 +--- + + +## {{page-title}} + +The BaRS API specifies several additional headers, many of which are items described in a standard Base64 encoded object (JSON). Their purpose and usage are described below. Examples can be found in the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Response-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Response-Headers.page.md new file mode 100644 index 00000000..2e2cd6d3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/HTTP-Response-Headers.page.md @@ -0,0 +1,13 @@ +--- +topic: core-EndToEndWorkflow-HTTPResponseHeader-1.3.0 +--- + + +## {{page-title}} + +Responses to requests in the BaRS standard need not include anymore than Headers required by the HTTP protocol and the Transaction Integrity Headers listed above. Senders should not expect or require anymore than this in a synchronous HTTP response. + +For secure usage of HTTP headers, guidance can be found in the OWASP Secure headers project regarding the [security headers](https://owasp.org/www-project-secure-headers/#div-headers) and [prevention of information disclosure](https://owasp.org/www-project-secure-headers/#div-bestpractices) which can be leveraged. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Index.page.md new file mode 100644 index 00000000..72eff32e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-EndToEndWorkflow-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Introduction.page.md new file mode 100644 index 00000000..7dd8e752 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Introduction.page.md @@ -0,0 +1,22 @@ +--- +topic: core-EndToEndWorkflow-Introduction-1.3.0 +--- + +# End-to-End Workflow + +This section covers the core elements of workflow outlined within the Booking and Referral Standard. There are two caveats when reading this: + +- Workflow is dependent on its Application or use case, for example in 999 - CAS validation, there is no step to perform a booking. See the relevant use case page in the +{{pagelink:applications, text:BaRS Applications}} section. + + +- The order of workflow is interchangeable. It is possible to: + - make a referral before a booking + - refer without booking + - book without referring + + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CoreWorkflowBaRS-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/WorkFlows/CoreWorkflowBaRS-1.0.0.svg" width="1200"></img></a> + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Logging.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Logging.page.md new file mode 100644 index 00000000..07074fbb --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Logging.page.md @@ -0,0 +1,62 @@ +--- +topic: core-EndToEndWorkflow-Logging-1.3.0 +--- + +## {{page-title}} + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important: Versioning information - Preview</b> </div> +<p> + +| Header | Requirement | Description | Value | +|------------------------|------------------------|--------------------------------------------------------------|----------------------------| +| use-context | Required by the sender | Allows BaRS to route the message to the appropriate endpoint | Formatted string | + +This header is for usage statistics for the BaRS Proxy for NHS England. It consists of a composite of 4 values from within the payload, in order. The sender MUST include this information. The receiver MUST ignore this header. The elements are: + +The elements for a ServiceRequest are: + +* ServiceRequest.category.coding.code (usecases-categories-bars) +* ServiceRequest.category.coding.code (message-category-servicerequest) +* MessageHeader.eventCoding.code (message-event-bars) +* MessageHeader.reason.coding.code (message-reason-bars) + +The elements for an Appointment are: + +* Appointent.serviceCategory.coding (usecases-categories-bars) +* Appointment.status +* MessageHeader.eventCoding.code (message-event-bars) +* MessageHeader.reason.coding.code (message-reason-bars) + +These MUST be present in the use-context header, separated by a pipe, in the defined order. + +### Referral + +``` +ServiceRequest.category.coding.code[usecases-categories-bars] | ServiceRequest.category.coding.code[message-category-servicerequest] | MessageHeader.eventCoding.code | MessageHeader.reason.coding.code +``` +Example: +``` +--header 'use-context: a4t2|validation|servicerequest-response|new' +``` + +### Booking + +``` + Appointent.serviceCategory.coding[usecases-categories-bars] | Appointment.status | MessageHeader.eventCoding.code | MessageHeader.reason.coding.code +``` +Example: +``` +--header 'use-context: a1t1|booked|booking-request|new' +``` + +This header is applicable to the following endpoints: + * POST /$process-message + * POST /Appointment + * PUT /Appointment/{id} + * PATCH /Appointment/{id} + * POST /ServiceRequest + * PUT /ServiceRequest/{id} + * PATCH /ServiceRequest/{id} + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Processing-Requests.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Processing-Requests.page.md new file mode 100644 index 00000000..3b239b64 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Processing-Requests.page.md @@ -0,0 +1,24 @@ +--- +topic: core-EndToEndWorkflow-Processing-1.3.0 +--- + + +## {{page-title}} + +For GET requests (reads) the Receiver honours what is being asked for by generating and synchronously sending a response, for example the server Capability Statement on a GET /metadata request. Any failure during processing must initiate an error response back to the Sender. + +The $process-message endpoint on the implemented API supports a mix of RESTful and Messaging exchanges, as required by BaRS. The main benefit of introducing messaging is to allow a Sender to package up the information a Receiver needs, to process a particular request, but letting them handle it as necessitated by their system, rather than a Sender having to make numerous requests to REST endpoints to perform the same action. + +When a request is received against the $process-message endpoint, the MessageHeader resource must be examined to determine what process the Sender is expecting the Receiver to perform. There are three key elements to determine this - + +- .eventCoding - primary function being asked to perform, for example: booking-request or servicerequest-request +- .reason - operation, for example:. New or Update +- .focus - the key resource in the bundle, to be read first to make sense of other related resources + +The Receiver interprets the request, engages the processing and synchronously feeds back a response. + +When processing the body (the FHIR bundle or payload) of the request, the Receiver can implement business logic, determining the type of payload and whether a request is valid or not, by using the guidance under the payload sections of each Application. This guidance stiplates the business requirement of each element of the payload, allowing a Receiver to determine elements which are mandated, required, optional or forbidden. The 'Necessity' column, of the tables within each Application payload section, indicates these buisness level requirements and aligns with defintions under [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + +Please see the {{pagelink:Core-StandardPattern-1.3.0, text: Standard Patterns}} for generic guidance for processing messages. + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Responses.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Responses.page.md new file mode 100644 index 00000000..e0a90bcf --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Responses.page.md @@ -0,0 +1,9 @@ +--- +topic: core-EndToEndWorkflow-Responses-1.3.0 +--- + +### {{page-title}} + +In the BaRS workflows responses are an important step and likely to become more so as use cases offer up increasingly complex requirements, for example: negotiated referrals. + +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Reversing-Roles.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Reversing-Roles.page.md new file mode 100644 index 00000000..41b6c915 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Reversing-Roles.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-ReversingRoles-1.3.0 +--- + +### {{page-title}} + +When responding the sender and receiver roles are reversed. Here you are essentially building a sender, and still need to implement a $process-message endpoint. Similarly, a receiver needs the ability to send the response to the BaRS API and will need to [register with our platform](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication). + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Routing.page.md new file mode 100644 index 00000000..7852e587 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Routing.page.md @@ -0,0 +1,13 @@ +--- +topic: core-EndToEndWorkflow-Routing-1.3.0 +--- + + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------------|------------------------|--------------------------------------------------------------|----------------------------| +| NHSD-Target-Identifier | Required by the sender | Allows BaRS to route the message to the appropriate endpoint | Base64 encoded JSON object | + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Service-Discovery.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Service-Discovery.page.md new file mode 100644 index 00000000..9b4cbe10 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/Service-Discovery.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-ServiceDiscovery-1.3.0 +--- + + +## Service discovery + +For a sender making a booking or referral, the first step is to establish a service (including the identifier) to send to. This can be achieved by using national or local service directories or preconfigured services, where a sender only ever sends to a handful of endpoints. The service identifier is all the sender requires to engage with a service which supports BaRS. {{pagelink:Home/Helpandsupport, text:Contact us}} if you need further information about service discovery. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/toc.yaml new file mode 100644 index 00000000..7b6ddaf8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/toc.yaml @@ -0,0 +1,30 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Service Discovery + filename: Service-Discovery.page.md +- name: Authenticate with BaRS + filename: Authenticate-with-BaRS.page.md +- name: BaRS FHIR API + filename: BaRS-FHIR-API.page.md +- name: HTTP Header + filename: HTTP-Header.page.md +- name: Routing + filename: Routing.page.md +- name: Logging + filename: Logging.page.md +- name: Authentication and Authorisation + filename: Authentication-and-Authorisation.page.md +- name: Transactional Integrity + filename: transactional-Integrity.page.md +- name: HTTP Response Headers + filename: HTTP-Response-Headers.page.md +- name: Processing Requests + filename: Processing-Requests.page.md +- name: Responses + filename: Responses.page.md +- name: Reversing Roles + filename: Reversing-Roles.page.md +- name: Asynchronous Workflow + filename: Asynchronous-Workflow.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/transactional-Integrity.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/transactional-Integrity.page.md new file mode 100644 index 00000000..a00de0c2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/End-to-end-workflow/transactional-Integrity.page.md @@ -0,0 +1,21 @@ +--- +topic: core-EndToEndWorkflow-Transactional-Integrity-1.3.0 +--- + +## {{page-title}} + +| Header | Requirement | Description | Value | +|------------------|-------------------------------------------------------------------|---------------------------------------------------------------------------|--------| +| X-Request-ID | Required for sending of any request and forwarded to the receiver | Will facilitate transactional integrity and the ability to audit messages | UUID | +| X-Correlation-Id | Required for sending of any request and forwarded to the receiver | Will facilitate transactional integrity and the ability to audit messages | UUID | + +We expect receivers to use and store the header values in the following ways: + +- to ensure the message maintains transactional integrity and hasn't been received previously +- to check who has sent the request and apply access control if desired +- to ensure all interactions are auditable + +If at any point the request fails, the receiver must send an appropriate error response (see Error handling) back to the sender to inform them why the request cannot be fulfilled. It is important to return as accurate information in the response as possible so the sender knows what is happening and can act accordingly. Transparency in the workflow is essential to enable senders and receivers to work together to provide the best patient experience possible. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Endpoint-Data.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Endpoint-Data.md new file mode 100644 index 00000000..0b9a9b59 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Endpoint-Data.md @@ -0,0 +1,255 @@ +--- +topic: core-StandardPattern-Endpoint-Data-1.3.0 +--- + +# Payloads for Creating or modifying an endpoint + +Describing Endpoints will be facilitated by the Organization, HealthcareService and Endpoint FHIR resources. Each of these are detailed in the below tables. Examples of each are also given. In this model + +* HealthcareServices Belong to an organization. +* An Organization can be a child Organization of a parent Organization, or Standalone. +* An Organization can describe a Provider or a Supplier. +* An Endpoint belongs to a HealthcareService. + * Multiple Endpoints of the same type are not permitted for a HealthcareService + +<details> + <summary>> <b class="barslink">Organization</b></summary> + <p> + <p>This resource will describe either the Organisation of the Provider or the Organisation of the Supplier managing an Endpoint</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization, hybrid}} + </p> + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example | Immutable | +|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|----------------------------------------------------------------------|-----------| +| Organization | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | | | | | +| Organization.id | This MUST only be populated with an id generated by the Endpoint Catalogue in the synchronous HTTP response upon creation. Its necessity is applicable to all VERBS  bar POST | MUST | 0.1 | 236bb75d-90ef-461f-b71e-fde7f899802c | Y | +| Organization.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | | | Y | +| Organization.meta.lastUpdated | This MUST be supplied by the client with the time the resource is requested to be created or updated. If it is before the timestamp on the resource on an update, the request will be rejected. This is not the case for a DELETE operation. | MUST | | 2021-11-26T15:00:00.8185338+00:00 | Y | +| Organization.meta.profile | This MUST be populated with the structure definition for the R4 Organization Resource | MUST | | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | Y | +| Organization.identifier[1] | | MUST | | | Y | +| Organization.identifier[0] | This MUST Contain the identifier for Organization ODS code | MUST | | | Y | +| Organization.identifier[0].system | This MUST be the ODS code system identifier https://fhir.nhs.uk/id/ods-organization-code | MUST | | https://fhir.nhs.uk/id/ods-organization-code | Y | +| Organization.identifier[0].value | The ODS code as a string. | MUST | | AA01 | Y | +| Organization.identifier[1] | this MUST contain the identifier for  Product ID | MUST | | | Y | +| Organization.identifier[1].system | this MUST be the Product ID system Identifier for  http://fhir.nhs.uk/Id/product-id | MUST | | http://fhir.nhs.uk/Id/product-id | Y | +| Organization.identifier[1].value | The hexadecimal Product ID as a string. | MUST | | AAA000 | Y | +| Organization.name | The name of the Organization | MUST | | "NHS Trust A" OR "Supplier A" | Y | +| Organization.partOf | If this Organization describes a child organisation, then the reference to the parent MUST be populated | SHOULD | | | N | +| Organization.partOf.reference | the reference to the parent organization. | SHOULD | | Organization/d5ffd0cd-ec7e-48a1-84f1-91f4c0eb8fc5 | N | +| Organization.type | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.type.ValueCodeableConcept | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.alias | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.telecom | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.address | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.contact | Follow UK Core guidance for populating this element. | COULD | | | N | +| Organization.endpoint | Not currently used in this implementation. | COULD | | | N | + + + +</details> +<p> +<details> + <summary>> <b class="barslink">HealthcareService</b></summary> + <p> + <p>This Resource describes the healthcare service that the endpoint is serving.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-HealthcareService , hybrid}} + </p> + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example | Immutable | +|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|----------------------------------------------------------------------|-----------| +| HealthcareService | https://fhir.hl7.org.uk/StructureDefinition/UKCore-HealthcareService | | | | | +| HealthcareService.id | This MUST only be populated with an id generated by the Endpoint Catalogue in the synchronous HTTP response upon creation. Its necessity is applicable to all VERBS  bar POST | MUST | 0.1 | 236bb75d-90ef-461f-b71e-fde7f899802c | Y | +| HealthcareService.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | | | Y | +| HealthcareService.meta.profile | This MUST be populated with the structure definition for the R4 HealthcareService Resource | MUST | | https://fhir.hl7.org.uk/StructureDefinition/UKCore-HealthcareService | Y | +| HealthcareService.meta.lastUpdated | This MUST be supplied by the client with the time the resource is requested to be created or updated. If it is before the timestamp on the resource on an update, the request will be rejected. This is not the case for a DELETE operation. | MUST | | 2021-11-26T15:00:00.8185338+00:00 | Y | +| HealthcareService.identifier[1] | | MUST | | | Y | +| HealthcareService.identifier[0] | This MUST Contain the identifier for HealthcareService service ID | MUST | | | Y | +| HealthcareService.identifier[0].system | This MUST be the system used for the Service ID, in this example, DoS ID | MUST | | http://fhir.nhs.uk/Id/dos-service-id | Y | +| HealthcareService.identifier[0].value | The Service ID code as a string. | MUST | | 1122334455 | Y | +| HealthcareService.identifier[1] | this MUST contain the identifier for  Product ID | MUST | | http://fhir.nhs.uk/Id/product-id | Y | +| HealthcareService.identifier[1].system | this MUST be the Product ID system Identifier for  http://fhir.nhs.uk/Id/product-id | MUST | | AAA000 | Y | +| HealthcareService.identifier[1].value | The hexadecimal Product ID as a string. | MUST | | | Y | +| HealthcareService.active | Whether this Service is Active and ready to accept requests. | MUST | | TRUE | Y | +| HealthcareService.providedBy | The provider Organization this HealthcareService is provided by. | MUST | | | Y | +| HealthcareService.providedBy.reference | A reference to the id of the Organization, this MUST exist. | MUST | | Organization/d5ffd0cd-ec7e-48a1-84f1-91f4c0eb8fc5 | Y | +| HealthcareService.name | The name of the HealthcareService | MUST | | Emergency Department A | Y | +| HealthcareService.endpoint | A reference to the Endpoint associated to this HealthcareService. This MUST be a reference to the BaRS endpoint. | MUST | | | N | +| HealthcareService.endpoint.reference | This MUST be a reference to the BaRS endpoint. | MUST | | Endpoint/d5ffd0cd-ec7e-48a1-84f1-91f4c0eb8fc5 | N | +| HealthcareService.category | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.type | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.specialty | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.location | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.name | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.comment | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.extraDetails | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.photo | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.telecom | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.coverageArea | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.eligibility | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.serviceProvisionCode | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.program | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.characteristic | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.communication | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.referralMethod | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.appoiuntmentRequired | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.availableTime | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.notAvailable | Follow UK Core guidance for populating this element. | COULD | | | N | +| HealthcareService.availabilityExceptions | Follow UK Core guidance for populating this element. | COULD | | | N | + + +</details> +<p> +<details> + <summary>> <b class="barslink">Endpoint</b></summary> + <p> + <p>This resource describes the endpoint itself including data around how to interact with it </p> + {{tree:http://hl7.org/fhir/structuredefinition/endpoint, hybrid}} + </p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example | Immutable | +|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|----------------------------------------------------------------------|-----------| +| Endpoint | http://hl7.org/fhir/structuredefinition/endpoint | | | | | +| Endpoint.id | This MUST only be populated with an id generated by the Endpoint Catalogue in the synchronous HTTP response upon creation. Its necessity is applicable to all VERBS  bar POST | MUST | 0.1 | 236bb75d-90ef-461f-b71e-fde7f899802c | Y | +| Endpoint.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | | | Y | +| Endpoint.meta.profile | This MUST be populated with the structure definition for the R4 Endpoint Resource | MUST | | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | Y | +| Endpoint.lastUpdated | This MUST be supplied by the client with the time the resource is requested to be created or updated. If it is before the timestamp on the resource on an update, the request will be rejected. This is not the case for a DELETE operation. | MUST | | 2021-11-26T15:00:00.8185338+00:00 | Y | +| Endpoint.identifier[0] | this MUST contain the identifier for  Product ID | MUST | | | Y | +| Endpoint.identifier[0].system | this MUST be the Product ID system Identifier for  http://fhir.nhs.uk/Id/product-id | MUST | | http://fhir.nhs.uk/Id/product-id | Y | +| Endpoint.identifier[0].value | The hexadecimal Product ID as a string. | MUST | | AAA000 | Y | +| Endpoint.status | Whether this Service is Active and ready to accept requests. This MUST be inline with  the HealthcareService.active value | MUST | | active | Y | +| Endpoint.managingOrganization | The Provider or Supplier Organization that manages this Endpoint. This DOES NOT need to match HealthcareService.providedBy. | MUST | | | Y | +| Endpoint.managingOrganization.reference | A reference to the id of the Organization, this MUST exist. | MUST | | Organization/51ab1d8b-72c3-4ca0-877c-b5f73faf36b5 | Y | +| Endpoint.connectionType | | MUST | | | Y | +| Endpoint.connectionType.valueCodeableConcept | | | | | Y | +| Endpoint.connectionType.valueCodeableConcept.coding[0] | This MUST define the type of connection this endpoint supports. In this Instance describing a BaRS endpoint. | MUST | | | Y | +| Endpoint.connectionType.valueCodeableConcept.coding[0].system | MUST be  https://fhir.nhs.uk/CodeSystem/ConnectionTypes | MUST | | https://fhir.nhs.uk/CodeSystem/ConnectionTypes | Y | +| Endpoint.connectionType.valueCodeableConcept.coding[0].code | MUST be "BARS" | MUST | | BARS | Y | +| Endpoint.connectionType.valueCodeableConcept.coding[0].display | MUST be  "Booking And Referrals Standard" | MUST | | Booking And Referrals Standard | Y | +| Endpoint.connectionType.valueCodeableConcept.text | MUST be "Booking and Referrals" | MUST | | Booking and Referrals | Y | +| Endpoint.address | This MUST be the receiving systems base URL for BARS. | MUST | | https://MyBaseServerAddress.nhs.uk/FHIR/R4 | Y | +| Endpoint.name | The name of this Endpoint, defined by the service | MUST | | Emergency Department B - BaRS Endpoint | Y | +| Endpoint.header | Defines whether this endpoint is public or private. | COULD | | public | N | +| Endpoint.Period | Interval the endpoint is expected to be operational | MUST | | | Y | +| Endpoint.Period.Start | Date from which the endpoint is active. | MUST | | 2024-11-26T15:00:00.8185338+00:00 | Y | +| Endpoint.Period.End | Date from the endpoint is inactive. | COULD | | 2028-11-26T15:00:00.8185338+00:00 | N | +| Endpoint.contact | Follow UK Core guidance for populating this element. | COULD | | | N | +| Endpoint.payloadType | Follow UK Core guidance for populating this element. | COULD | | | N | +| Endpoint.payloadMimeType | Follow UK Core guidance for populating this element. | COULD | | | N | + + + +</details> +<p> + +## Entity Relationship Diagram + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapEndpointCatalogue-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapEndpointCatalogue-1.0.0.svg" width="1200"></img></a> + +## Examples + +### Endpoint +```json +{ + "resourceType": "Organization", + "meta": { + "lastUpdated": "2021-10-11T15:23:30.8185338+00:00", + "profile": [ + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization" + ] + }, + "identifier": [ + { + "system": "https://fhir.nhs.uk/id/ods-organization-code", + "value": "RYE" + }, + { + "system": "http://fhir.nhs.uk/Id/product-id", + "value": "AAA000" + } + ], + "name": "NHS Trust A" +} +``` + +### HealthcareService +```json +{ + "resourceType": "HealthcareService", + "meta": { + "lastUpdated": "2021-11-26T15:00:00.8185338+00:00", + "profile": [ + "http://hl7.org/fhir/StructureDefinition/HealthcareService", + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-HealthcareService" + ] + }, + "identifier": [ + { + "system": "http://fhir.nhs.uk/Id/dos-service-id", + "value": "111111111" + }, + { + "system": "http://fhir.nhs.uk/Id/product-id", + "value": "AAA000" + } + ], + "active": true, + "providedBy": { + "reference": "Organization/d5ffd0cd-ec7e-48a1-84f1-91f4c0eb8fc5" + }, + "name": "Emergency Department A", + "endpoint":{ + "reference":"Endpoint/4e958d43-ad80-40c9-85ff-2be003d1ea86" + } +} +``` + +### Endpoint +```json +{ + "resourceType": "Endpoint", + "id": "0cb21027-a246-43e6-9c7a-35b17163eab1", + "meta": { + "lastUpdated": "2021-10-11T15:23:30+00:00", + "profile": [ + "http://hl7.org/fhir/StructureDefinition/Endpoint" + ] + }, + "identifier": [ + { + "system": "http://fhir.nhs.uk/Id/product-id", + "value": "AAA000" + } + ], + "status": "active", + "name": "Service Endpoint Name", + "connectionType": [ + { + "valueCodeableConcept": { + "coding": [ + { + "system": "https://fhir.nhs.uk/CodeSystem/ConnectionTypes", + "code": "BARS", + "display": "Booking And Referrals Standard" + } + ], + "text": "Booking and Referrals" + } + } + ], + "managingOrganization": [ + { + "reference": "3e96763f-7969-404f-afac-c415f47dff42" + } + ], + "address": "https://myService.nhs.uk/Base/Address", + "header": "public", + "Period": { + "Start": "2021-10-11T15:23:30+00:00", + "End": "2021-10-11T15:23:30+00:00" + } +} +``` \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Interface.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Interface.md new file mode 100644 index 00000000..5ace955e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Interface.md @@ -0,0 +1,329 @@ +--- +topic: core-StandardPattern-Endpoint-Interface-1.3.0 +--- + +# Interface + +The Interface for managing the 3 resources relating to an "endpoint" is detailed below and is part of the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0) for Core 1.2.0 and above. + +## Request and Response + +<table><thead> + <tr> + <th>Behaviour</th> + <th>Initiator</th> + <th>VERB</th> + <th>API Path</th> + <th>Parameters</th> + <th>Payload</th> + <th>Payload Definition</th> + <th>Reactor</th> + <th>Reactor Behaviour</th> + <th>Happy Response</th> + <th>Response Definition</th> + </tr></thead> +<tbody> + <tr> + <td>Get Capabilities</td> + <td>Sender</td> + <td>GET</td> + <td>/metadata</td> + <td>N/A</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a capability statement   describing capabilities.</td> + <td>200: CapabilityStatement</td> + <td><a href="https://www.hl7.org/fhir/capabilitystatement.html">https://www.hl7.org/fhir/capabilitystatement.html</a></td> + </tr> + <tr> + <td rowspan="2">Get   Endpoints</td> + <td rowspan="2">Sender / Receiver /   BaRS / Admin</td> + <td rowspan="2">GET</td> + <td rowspan="2">/Endpoint</td> + <td>query: _has</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a searchset of Endpoints   based on the properties of the parent given as a _has   HealthcareService.Identifier or Id</td> + <td>200: Search Bundle</td> + <td><a href="https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle">https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle   searchset</a></td> + </tr> + <tr> + <td><a href="https://www.hl7.org/fhir/organization.html">query:   Endpoint.identifier</a></td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a searchset of Endpoints   based on the identifier of the Endpoint itself. this should only be one item.</td> + <td>200:   Search Bundle</td> + <td><a href="https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle">https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle   searchset</a></td> + </tr> + <tr> + <td>Get   Endpoint</td> + <td>Sender / Receiver / BaRS / Admin</td> + <td>GET</td> + <td>/Endpoint/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return specific Endpoint based   on id given.</td> + <td>200: Endpoint</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint</a></td> + </tr> + <tr> + <td>Create   Endpoint</td> + <td>Receiver / Admin</td> + <td>POST</td> + <td>/Endpoint</td> + <td>path: id</td> + <td>Endpoint</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint</a></td> + <td>Endpoint Catalogue</td> + <td>Store a new Endpoint based on id   given.</td> + <td>201: Endpoint</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint</a></td> + </tr> + <tr> + <td>Update   Endpoint</td> + <td>Receiver / Admin</td> + <td>PUT</td> + <td>/Endpoint/{id}</td> + <td>path: id</td> + <td>Endpoint</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint</a></td> + <td>Endpoint Catalogue</td> + <td>Update an existing endpoint   based on id given.</td> + <td>200: Endpoint</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint</a></td> + </tr> + <tr> + <td>Delete   Endpoint</td> + <td>Receiver / Admin</td> + <td>DELETE</td> + <td>/Endpoint/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Remove an existing endpoint   based on id given</td> + <td>200: OperationOutcome</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome">https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome</a></td> + </tr> + <tr> + <td>Get Organisations</td> + <td>Sender / Receiver / BaRS / Admin</td> + <td>GET</td> + <td>/Organisation?</td> + <td><a href="https://www.hl7.org/fhir/organization.html">query:   Organization.identifier</a></td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a list of Organizations   based on the identifier given</td> + <td>200: Search Bundle</td> + <td><a href="https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle">https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle   searchset</a></td> + </tr> + <tr> + <td>Get   Organisation</td> + <td>Sender / Receiver / BaRS / Admin</td> + <td>GET</td> + <td>/Organisation/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a specific Endpoint based   on the id given.</td> + <td>200: Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Create   Organisation</td> + <td>Receiver / Admin</td> + <td>POST</td> + <td>/Organisation</td> + <td>path: id</td> + <td>Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + <td>Endpoint Catalogue</td> + <td>Store a new Organization based   on the id given.</td> + <td>201: Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Update   Organisation</td> + <td>Receiver / Admin</td> + <td>PUT</td> + <td>/Organisation/{id}</td> + <td>path: id</td> + <td>Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + <td>Endpoint Catalogue</td> + <td>Update an existing Organization   based on the id given.</td> + <td>200: Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Delete   Organisation</td> + <td>Receiver / Admin</td> + <td>DELETE</td> + <td>/Organisation/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Remove an existing Organization   based on the id given.</td> + <td>200: OperationOutcome</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome">https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome</a></td> + </tr> + <tr> + <td rowspan="2">Get HealthcareService</td> + <td rowspan="2">Sender / Receiver /   BaRS / Admin</td> + <td rowspan="2">GET</td> + <td rowspan="2">/HealthcareService</td> + <td>query:   HealthcareService.identifier</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a list of   HealthcareServices based on the identifier given</td> + <td>200: Search Bundle</td> + <td><a href="https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle">https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle   searchset</a></td> + </tr> + <tr> + <td>query:   HealthcareService.providedBy</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a list of   HealthcareServices based on the identifier given</td> + <td>200: Search Bundle</td> + <td><a href="https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle">https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle   searchset</a></td> + </tr> + <tr> + <td>Get   HealthcareService</td> + <td>Sender / Receiver / BaRS / Admin</td> + <td>GET</td> + <td>/HealthcareService/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Return a specific   HealthcareServicesbased on the id given.</td> + <td>200: HealthcareServices</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Create   HealthcareService</td> + <td>Receiver / Admin</td> + <td>POST</td> + <td>/HealthcareService</td> + <td>path: id</td> + <td>Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + <td>Endpoint Catalogue</td> + <td>Store a new   HealthcareServicesbased on the id given.</td> + <td>201: HealthcareServices</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Update   HealthcareService</td> + <td>Receiver / Admin</td> + <td>PUT</td> + <td>/HealthcareService/{id}</td> + <td>path: id</td> + <td>Organization</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + <td>Endpoint Catalogue</td> + <td>Update an existing   HealthcareServicesbased on the id given.</td> + <td>200: HealthcareServices</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization">https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization</a></td> + </tr> + <tr> + <td>Delete   HealthcareService</td> + <td>Receiver / Admin</td> + <td>DELETE</td> + <td>/HealthcareService/{id}</td> + <td>path: id</td> + <td>N/A</td> + <td>N/A</td> + <td>Endpoint Catalogue</td> + <td>Remove an existing   HealthcareServicesbased on the id given.</td> + <td>200: OperationOutcome</td> + <td><a href="https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome">https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome</a></td> + </tr> +</tbody></table> + +## Parameters + +This table describes the parameters currently defined for the Paths defined in the interface table above. + + +<table><thead> + <tr> + <th>API Path</th> + <th>Type</th> + <th>Parameter</th> + <th>Format</th> + <th>Purpose</th> + </tr></thead> +<tbody> + <tr> + <td rowspan="2">/Endpoint?</td> + <td rowspan="2">query</td> + <td rowspan="2">_has</td> + <td>_has:HealthcareService.Identifier=<a href="https://fhir.nhs.uk/Id/dos-service-id%7C1000099999">https://fhir.nhs.uk/Id/dos-service-id|1000099999</a></td> + <td rowspan="2">An identifier for the HealthcareService to which Endpoints belong. in this example an id or DoS id.</td> + </tr> + <tr> + <td rowspan="2">_has:HealthcareService.Id=95852b93-d1ab-4c51-8e7d-c24cf9b257a9</td> + </tr> + <tr> + <td>/Endpoint?</td> + <td>query</td> + <td><a href="https://www.hl7.org/fhir/organization.html">Endpoint.identifier</a></td> + <td>The identifier of the type of Endpoint. This would be used to say if you want a BaRS endpoint or otherwise.<br></td> + </tr> + <tr> + <td>/Endpoint/{}</td> + <td>path</td> + <td>id</td> + <td>GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91"</td> + <td>The identifier of the endpoint.</td> + </tr> + <tr> + <td>/HealthcareService/?</td> + <td>query</td> + <td>HealthcareService.identifier</td> + <td><a href="https://fhir.nhs.uk/Id/dos-service-id%7C1000099999">https://fhir.nhs.uk/Id/dos-service-id|1000099999</a></td> + <td>an identifier of the healthcareService, in this example, a DoS id.</td> + </tr> + <tr> + <td>/HealthcareService/?</td> + <td>query</td> + <td>HealthcareService.providedBy</td> + <td><a href="https://fhir.nhs.uk/Id/ods-organization-code%7CA001">https://fhir.nhs.uk/Id/ods-organization-code|A001</a></td> + <td>the owning organisations ODS code.</td> + </tr> + <tr> + <td>/HealthcareService/{id}</td> + <td>path</td> + <td>id</td> + <td>GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91"</td> + <td>specific resource id of an HealthcareService.</td> + </tr> + <tr> + <td rowspan="2">/Organisation?</td> + <td rowspan="2">query</td> + <td rowspan="2"><a href="https://www.hl7.org/fhir/organization.html">Organization.identifier</a></td> + <td>"A001"</td> + <td rowspan="2">An identifier for the organization. in this example an ODS code. </td> + </tr> + <tr> + <td><a href="https://fhir.nhs.uk/id/ods-organization-code">"https://fhir.nhs.uk/id/ods-organization-code</a>|A001"</td> + </tr> + <tr> + <td>/Organisation/{id}</td> + <td>path</td> + <td>id</td> + <td>GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91"</td> + <td>specific resource id of an organization. </td> + </tr> +</tbody></table> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Introduction.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Introduction.md new file mode 100644 index 00000000..31cba703 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Introduction.md @@ -0,0 +1,35 @@ +--- +topic: core-StandardPattern-Endpoint-Introduction-1.3.0 +--- + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important: Versioning information - Preview</b> +<p> + +This version of core is strictly a preview of what is currently in development for 1.2.0 and should <b>not be built against.</b> + +<table> +<thead> + <tr> + <th data-no-sort="">Core Version</th> + <th data-no-sort="">Minimum Guide Version</th> + <th data-no-sort="">Minimum API Spec Version</th> + </tr> +</thead> +<tbody> + <tr> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/BaRS-Core?version=1.0.0" target="_blank">v1.2.0-alpha</a></td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.1.0" target="_blank">v1.8.0</td> + <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0" target="_blank">v1.2.0</a></td> + </tr> +</tbody> +</table> +</div> + +# Standard Pattern - Endpoints + +BaRS employs an endpoint catalogue to match Target Identifiers with a stored endpoint. Target Identifiers are provided in a header which is descripted in the [API Spec](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0) The following pages will describe how these entries can be managed, outside of the onboarding process. + +The BaRS endpoints will utilise not only service ids and a physical endpoint, but data describing the healthcare service, the provider of that service and the organization which manages and/or supplies the endpoint in question. This information will be stored using 3 FHIR resources which appropriately describe [Endpoints](http://hl7.org/fhir/R4/endpoint.html), [HealthcareServices](http://hl7.org/fhir/R4/healthcareservice.html) and [Organizations](http://hl7.org/fhir/R4/organization.html). + +BaRS will expose an interface to manage this information for each of these resources. Each resource will have a corresponding endpoint on the Proxy to assist in managing these endpoints. + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Sequences.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Sequences.md new file mode 100644 index 00000000..98c3bcf2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/Sequences.md @@ -0,0 +1,29 @@ +--- +topic: core-StandardPattern-Endpoint-Sequences-1.3.0 +--- + +# Sequences + +The sequences to create, update or read an endpoint via BaRS are detailed below. Though the interaction for a sender to route to a receiver has not changed, the sequence is included. The Sequence is the same for all resources, that being said, due to constraints on the data, there are limits to certain scenarios depending on if a resource would result in being orphaned, or a duplicate entry is being created. + +## Sender + +Here a Sender is simply sending a request to a receiver using the NHSD-Target-Identifier header. + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Sender-Abstract.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Sender-Abstract.svg" width="1200"></img></a> + + +## Create + +Here a Receiving system is creating a resource related to an endpoint. + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Receiver-Create-Abstract.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Receiver-Create-Abstract.svg" width="1200"></img></a> + + +## Update + +Here a Receiving system is updating a resource related to an endpoint. + +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Receiver-Update-Abstract.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/EPC-Sequence-Receiver-Update-Abstract.svg" width="1200"></img></a> + +. diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/index.page.md new file mode 100644 index 00000000..f93a5277 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/index.page.md @@ -0,0 +1,6 @@ +--- +topic: core-StandardPattern-Endpoints-1.3.0 +--- + + +. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/toc.yaml new file mode 100644 index 00000000..82637464 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/EndpointCatalogue-StandardPattern/toc.yaml @@ -0,0 +1,10 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.md +- name: Interface + filename: Interface.md +- name: Endpoint Data + filename: Endpoint-Data.md +- name: Sequences + filename: Sequences.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--receiving.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--receiving.page.md new file mode 100644 index 00000000..9a8aa469 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--receiving.page.md @@ -0,0 +1,8 @@ +--- +topic: core-ErrorHandling-IntR-1.3.0 +--- + +## {{page-title}} + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--sending.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--sending.page.md new file mode 100644 index 00000000..78546dfd --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/BaRS-interactions--sending.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-IntS-1.3.0 +--- + +## {{page-title}} + +In the event of an error; the BaRS API always responds with an HTTP response code (issue.code) and an OperationOutcome code (issue.details.code) within an OperationOutcome FHIR Resource - conditioned on it being reached successfully. Assuming the sender's access token (obtained from the Oauth 2 endpoint) is accepted and the request is valid, the BaRS API processes the request. Depending on the operation, BaRS proxies the request to the receiver. Depending on where in this flow the error occurs, the OperationOutcome codes is prefixed with one of the following three items, indicating where the cause of the error resides: + +- SEND - The sending application is the cause of the error + - These items are only be generated by the API to indicate there was an issue with the senders request +- PROXY - The BaRS Service is the source of the error + - These items generally generated to indicate there was an error internal to BaRS + - The information within the response will help identify the cause +- REC - The receiver is the source of the error + - These are generated by the receiver, however if there is a scenario where the receiver cannot respond, these are generated by the proxy to clarify the source of the problem + - The information within the response helps identify the cause + +These OperationOutcome codes are part of a value set to be used within a OperationOutcome FHIR Resource (issue.details.code) which forms the body of the response. Below is an example of an error response: + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Diagnostics-Text.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Diagnostics-Text.page.md new file mode 100644 index 00000000..74865572 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Diagnostics-Text.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-Diag-1.3.0 +--- + +### Diagnostics text + +The purpose of the two code values are to give high level information as to the nature and source of an error response. The diagnostics text is to contain clear and concise information regarding the exact cause of the problem encountered, where possible. This should include information on the problem encountered, internal debug details such as error message and texts are encouraged, exposing stack traces is not. The diagnostics field does not include any patient identifiable information at any time. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Example-Errors.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Example-Errors.page.md new file mode 100644 index 00000000..1f5d6bc9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Example-Errors.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-Examples-1.3.0 +--- + +### Example errors + +The table below contains some further examples of error codes, their associated Operation Outcomes codes and and potential diagnostics texts. + +| HTTP Code | Code Value | Description | Example diagnostics text | +|-----------|-----------------------|-------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| 400 | SEND_BAD_REQUEST | The API was unable to process the request. | "The API was unable to process the request: <further diagnostics information, error message/error text>" | +| | REC_BAD_REQUEST | The Receiver has responded stating the message was malformed. | "<Receiver Identifier (ODS)> was unable to process the request: <further diagnostics information, error message/error text>" | +| | PROXY_BAD_REQUEST | Though Unlikely, BaRS, having accepted the message; has received a 400 response from an internal component. | "BaRS was unable to process the request: <further diagnostics information, error message/error text>" | +| 404 | PROXY_NOT_FOUND | The resource was not found within BaRS. | "The resource was not found within BaRS: <further diagnostics information, error message/error text>" | +| | REC_NOT_FOUND | The resource was not found at the Receiver. | "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>" | +| 409 | REC_CONFLICT | Example: Sender is trying to Book an appointment in a slot that doesn't allow booking. | "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>" | +| 501 | SEND_NOT_IMPLEMENTED | The Request was not recognized. | "The Request was not recognized by the API: <further diagnostics information, error message/error text>" | +| | REC_NOT_IMPLEMENTED | The Receiver did not recognize the request. | "The Request was not recognised by the Receiver - <Receiver identifier (ODS)>: <further diagnostics information, error message/error text>" | +| | PROXY_NOT_IMPLEMENTED | BaRS did not recognize the request. | "This Request was not recognized by the proxy: <further diagnostics information, error message/error text>" | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Bundle-Processing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Bundle-Processing.page.md new file mode 100644 index 00000000..26a4902b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Bundle-Processing.page.md @@ -0,0 +1,490 @@ +## Bundle processing POST /$process-message + +This section defines unhappy path scenarios for when a receiver processes a message. This includes a reiteration of Transaction Integrity, workflow variable validations and data conflicts. + + +### HTTP Headers +Below is a simplified example of how how to handle the Transaction Integrity HTTP headers. +**Logic** +``` c# +{ + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 +} +``` +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/HTTP-Header-logic-1.0.0.svg) + + +| HTTP Status Code | HTTP Error Code | Issue Code | Scenario | +|------------------|-----------------|------------|-------------------------------------------------------------------| +| 400 | REC_BAD_REQUEST | invalid | The request headers are not valid. | +| 400 | REC_BAD_REQUEST | required | The request headers are not present. | +| 409 | REC_CONFLICT | duplicate | The message has been identified as having already been processed. | + +**400 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "invalid", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_BAD_REQUEST" +          } +        ] +      }, +      "diagnostics": "Transaction Integrity headers were not present" +    } +  ] +} +``` + +**409 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "duplicate", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_CONFLICT" +          } +        ] +      }, +      "diagnostics": "This message has been recognised as having already been successfully processed." +    } +  ] +} +``` + +### Message workflow variable validations + +Many scenarios are covered by this one example, the full pseudo code can be located at the end of this page. + +**logic** +```c# +{ + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } +``` + +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/WorkflowVariable-FailureScenarios-1.0.0.svg) + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | +|------------------|-----------------|------------|-------------------------------------------------------------------------------------| +| 400 | REC_BAD_REQUEST | invariant | A combination of workflow variables has lead to a non-standard or unknown workflow. | + +**400 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "invariant", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_BAD_REQUEST" +          } +        ] +      }, +      "diagnostics": "A content validation rule failed, Validation message requires a Careplan.satus of 'active'" +    } +  ] +} +``` + +### Data Conflicts + +Receiving an update can present complications under certain conditions if data has been updated locally - for example, If you have updated a record locally prior to an update message being received and a conflict is then encountered. + +**Logic** +``` c# +if (Message == "update") +{ + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } +``` +**Visual** + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/DataConflict-FailureScenarios-1.0.0.svg) + + + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | +|------------------|-----------------|------------|--------------------------------------------------------------| +| 409 | REC_CONFLICT | conflict | local data updates conflict with the updates in the message. | + +**409 OperationOutcome** +```json +{ +  "resourceType": "OperationOutcome", +  "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", +  "meta": { +    "profile": [ +      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" +    ] +  }, +  "issue": [ +    { +      "severity": "error", +      "code": "conflict", +      "details": { +        "coding": [ +          { +            "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", +            "code": "REC_CONFLICT" +          } +        ] +      }, +      "diagnostics": "Information received has been updated locally and may cause loss, or presents a conflict, of data" +    } +  ] +} +``` + +## Full Pseudo Code example +Below is the Full Pseudo Code example of the details seen in the workflow variables section. + + +<details><summary>> <b class="barslink">Click here to show example</b></summary> + +```c# +Receive_Request +{ + initialise_variable "messageType" + initialise_variable "MessageReason" + initialise_variable "RequestType" + + //HTTP_Headers + { + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + //Bundle + { + if(Bundle.meta.versionID is null) + OperationOutcome.issue.code = "invariant" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if!(Bundle.meta.versionID in versionID.supported) + OperationOutcome.issue.code = "not-supported" + throw exception with "REC_UNPROCESSABLE_ENTITY" + then return with HTTP.ResponseCode 422 + } + //Contents; + { + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + else if(Encounter.Status.In("triaged","in-progress") + {RequestType = "Im Receiving a new Validation Request";} + else + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + break; + case "Referral": + if (Careplan.status != "completed") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + else if(Encounter.Status.In("triaged","finished")) + RequestType = "Im Receiving a new Referral" + else + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if (MessageHeader.reason.code == "update") + { + switch(ServiceRequest.category) + { + case "Validation": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled validation request";} + else if(ServiceRequest.status.In("active","on-hold")) + {RequestType = "im receiving an update to a validation request";} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + case "Referral": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled referral"} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + + } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400} + break; + case "servicerequest-response": + if (MessageHeader.Response is null ) + { + RequestType = "Invalid servicerequest-response" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + else if ( !Message.Response.identifier.existsLocally()) + { + RequestType = "none or invalid response ID" + OperationOutcome.issue.code = "not-found"//A content validation rule failed + throw exception with "REC_NOT_FOUND" + then return HTTP.ResponseCode 404; + } + switch (ServiceRequest.Category) + { + case "Referral": + if (ServiceRequest.status == "revoked" && MessageHeader.reason.code == "new") + { RequestType = "im receiving a Safeguarding DNA response (noshow)" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + break; + case "Validation": + if(!AnyEncounter.Originates.Local && Encount.Count()<=3) + { + if (MessageHeader.Reason.code == "new" && ServiceRequest.status == "active" && MessageHeader.FocusEncounter.status=="in-progress") + {Request Type = "im receiving a Validation Response interim update" } + else if (MessageHeader.Reason.code.In ("new","update") && ServiceRequest.status == "completed" && MessageHeader.FocusEncounter.status.In("triaged","complete") + {Request Type = "im receiving a final Validation Response" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if(MessageHeader.FocusEncounter.status = "triaged" && ServiceRequest.status == "revoked" && MessageHeader.Reason.code.In("new","update")) + { RequestType = "im receiving a Rejected validation response" } // a new encounter here is an edge case. + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + case "booking-request": + if (MessageHeader.Reason.code== "new" && Appointment.Status == "booked") + if(slot.IsFree()) + {RequestType = "Im Receiving a new booking.";} + else + { + OperationOutcome.issue.code = "conflict" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + else if (MessageHeader.Reason.code == "update") + MessageHeaderIsUpdate = true; + switch (Appointment.Status) + { + case "cancelled": + RequestType = "Im Receiving a booking cancellation." + break + case "entered-in-error": + RequestType = "Im Receiving a booking cancellation." + break + case "booked": + RequestType = "Im Receiving an update to a booking." + break + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + break; + } + else + { + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + } + break; + case "booking-response": + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + } + + } + //Submit //rework this + { + + if (Message == "update") + { + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + foreach (Entry in Bundle) + { + if (currentLocalData.Item.exists) + { + if (currentLocalData.LastUpdated > originaRequest.Received) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + if(Entry.LastUpdated > currentLocalData.Item.meta.LastUpdated && Entry.fullUrl = currentLocalData.Item.fullUrl) + currentLocalData.Item = Entry.Item + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + else + ignore + } + else + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + } + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + else + { + foreach(Entry in Bundle) + { + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + } + } +} +``` + +</details> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Capability-Statement.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Capability-Statement.page.md new file mode 100644 index 00000000..b4e3da7c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Capability-Statement.page.md @@ -0,0 +1,9 @@ +## Check Capabilities GET /metadata + +Foreseen failure scenarios are limited for this interaction, in the scope of the receiver. The majority of failures for this stage of workflow is mainly going to be at the sender ascertaining the capabilities of the Receiver and whether they can interact. This is considered the purpose of this endpoint and therefore is not considered a failure. + +GET /metadata is the only Endpoint which does not need a Target identifier. Not providing a Target Identifier will result in the Capability Statement of the BaRS Proxy itself. Providing one will expose potential failure scenarios defined in {{pagelink:Core-ErrorHandling-MessageRouting-1.3.0}} . There are also no query or path parameters required meaning the potential failure scenarios are fewer however Transaction Integrity headers are still required. + +### interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/metadata-FailureScenarios-1.0.0.svg) \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Appointment.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Appointment.page.md new file mode 100644 index 00000000..ea4e15df --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Appointment.page.md @@ -0,0 +1,34 @@ +## GET /Appointment +This section defines the failure scenarios for GET /Appointment. There are two ways to call this endpoint. Either with a query parameter, or a path parameter. This section covers both of those methods. + +### Rules + +**GET /Appointment** +* query parameter identifier patient.identifier MUST be included. +* query parameter identifier patient.identifier MUST be a system:value. example: https://fhir.nhs.uk/Id/nhs-number|4857773456 + +**GET /Appointment/{id}** +* id in path MUST be a valid GUID/UUID + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/Appt-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**path id in GET /Appointment{id}** + +| HTTP Status Code | HTTP Error Code | Issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | REC_BAD_REQUEST | value | The identifier was in the incorrect format. | Receiver | +| 404 | REC_NOT_FOUND | not-found | The resource requested was not found. | Receiver | + +**patient:identifier parameter identifier in GET /Appointment** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | SEND_BAD_REQUEST | value | the identifier was in the incorrect format. | API | +| 400 | REC_BAD_REQUEST | value | the identifier was in the incorrect format. | Receiver | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--MessageDefinition.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--MessageDefinition.page.md new file mode 100644 index 00000000..6b8432ad --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--MessageDefinition.page.md @@ -0,0 +1,33 @@ +## GET /MessageDefinition +Message definition includes only one additional parameter and therefore there are less scenarios to cover. + +### Rules +* The context query parameter must be present. + * For current use cases this will always match the value in the NHSD-Target-Identifier header. This could could not always be the case in future. + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/MessageDefinition-FailureScenarios-1.0.0.svg) + +### Errors by parameter + +**context** + +| HTTP Status Code | HTTP Error Code | Issue Code | Scenario | Source | +|------------------|------------------|------------|--------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | no context parameter was given. | API | +| 400 | REC_BAD_REQUEST | required | no context parameter was given. | Receiver | +| 400 | REC_BAD_REQUEST | invalid | the context parameter value was invalid (format) | Receiver | +| 400 | REC_BAD_REQUEST | value | the context parameter value was invalid (format) | Receiver | +| 404 | REC_NOT_FOUND | not-found | the context parameter given returned no results. | Receiver | + +### Standard errors +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| 400 | REC_BAD_REQUEST | invalid | Although this should be caught at the proxy/API, should a request be received with no X-Request-Id or X-Correlation-Id be received this check should be in place. (BaRS without the Proxy) | Receiver | +| 400 | REC_BAD_REQUEST | value | As above, but the value is not a GUID/UUID. | Receiver | +| 401 | REC_UNAUTHORIZED | security | Access Control issue. | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | exception | an unhandled exception has been encountered. | Receiver / API Injected | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The service(s) is unavailable but is able to respond as such, otherwise injected. | Receiver / API Injected | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--ServiceRequest.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--ServiceRequest.page.md new file mode 100644 index 00000000..0d49be8f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--ServiceRequest.page.md @@ -0,0 +1,34 @@ +### GET /ServiceRequest +This section defines the failure scenarios for GET /ServiceRequest. As with GET /Appointment, there are two ways to call this endpoint. Either with a query parameter, or a path parameter. This section covers both of those methods. + +### Rules + +**GET /ServiceRequest** +* query parameter identifier patient.identifier MUST be included. +* query parameter identifier patient.identifier MUST be a system:value. example: https://fhir.nhs.uk/Id/nhs-number|4857773456 + +**GET /ServiceRequest/{id}** +* id in path MUST be a valid GUID/UUID + +### Interactions + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/SR-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**path id in GET /ServiceRequest{id}** + +| HTTP Status Code | HTTP Error Code | Issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | REC_BAD_REQUEST | value | The identifier was in the incorrect format. | Receiver | +| 404 | REC_NOT_FOUND | not-found | The resource requested was not found. | Receiver | + +**patient:identifier parameter identifier in GET /ServiceRequest** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-----------------------------------------------------------------------------------------------|----------| +| 400 | SEND_BAD_REQUEST | required | The parameter value was not included in the request. | API | +| 400 | REC_BAD_REQUEST | required | The parameter value was not included in the request. | Receiver | +| 400 | SEND_BAD_REQUEST | value | the identifier was in the incorrect format. | API | +| 400 | REC_BAD_REQUEST | value | the identifier was in the incorrect format. | Receiver | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Slots.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Slots.page.md new file mode 100644 index 00000000..bcacdec6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/GET--Slots.page.md @@ -0,0 +1,66 @@ +## GET /Slots +Get /Slots has added complexity compared to previous endpoints in this section. With a myriad of available and required parameters there is a potential for many scenarios. + +### Rules +* Schedule:actor:HealthcareService - Must be included. + * For current use cases this will likely match the value in the NHSD-Target-Identifier header. This may not always be the case in future. +* _include - There is a minimum of the following 2 _includes required for current Applications. + * Slot:schedule + * Schedule:actor:HealthcareService +* start - The start parameter must be used twice, and adds the need for handling problematic requests with its use (too wide a time frame, as an example). + * Must use the [FHIR dateTime](https://www.hl7.org/fhir/datatypes.html#primitive) format which includes an offset. + * Must be UTC + * Must have a greater than and a less than. +* status - The status parameter must be used. + * multiple statuses must be comma separated. + * FOT allows free or busy. + +### Interaction + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/Slot-FailureScenarios-1.0.0.svg) + +### Errors by parameter +**Schedule:actor:HealthcareService** + +| HTTP Status Code | HTTP Error Code | Issue Code | Scenario | Source | +|------------------|-------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST? | required | The parameter value was not included in the request. (This parameter is not currently marked as required. ) | API and Receiver | +| 400 | REC_BAD_REQUEST | value / invariant | The parameter value was incorrect or wrong. | Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | +| 404 | REC_NOT_FOUND | not-found | This service does not exist. | Receiver | + +**_include** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|-------------------------------------------------------------------------------------------------------------|------------------| +| 400 | REC_BAD_REQUEST | required | the minimum required includes are not present. | API and Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | + +**start** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------------------------|------------|-------------------------------------------------------------------------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | required | Date range was not present. | API and Receiver | +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | value | DateTimes in the requested start time range requested was invalid. | API and Receiver | +| 401 | REC_UNAUTHORIZED | forbidden | The Sending organisation/ software/ practitioner Role does is not allowed to access this information, evaluated in their corresponding Access Control headers. | Receiver | +| 422 | REC_UNPROCESSABLE_ENTITY | too-costly | The start time range requested is too wide. | Receiver | + + +**status** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------------------------|------------|------------------------------------|------------------| +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | required | status not present. | API and Receiver | +| 400 | SEND_BAD_REQUEST / REC_BAD_REQUEST | value | status value requested is invalid. | API and Receiver | + +**Common Failures** + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------| +| 400 | REC_BAD_REQUEST | invalid | Although this should be caught at the proxy/API, should a request be received with no X-Request-Id or X-Correlation-Id be received this check should be in place. | Receiver | +| 400 | REC_BAD_REQUEST | value | As above, but the value is not a GUID/UUID. | Receiver | +| 401 | REC_UNAUTHORIZED | security | Access Control issue. | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | exception | an unhandled exception has been encountered. | Receiver / API Injected | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The service is unavailable but is able to respond as such. | Receiver / API Injected | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/General-Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/General-Failure-Scenarios.page.md new file mode 100644 index 00000000..bd03e6c7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/General-Failure-Scenarios.page.md @@ -0,0 +1,22 @@ +## General Failure Scenarios +This section will define errors that could be seen in any given step and shared from function to function without context. All interactions MUST follow these rules as such they may be listed in different sections. + + +| HTTP Status Code | HTTP Error Code | Issue.Code | Scenario | Source | +|------------------|-----------------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------| +| 400 | SEND_BAD_REQUEST | required | Content invalid against the specification or a profile. For example a required parameter or header is not provided. | API | +| 400 | REC_BAD_REQUEST | value | a header value or parameter is invalid. (these are defined in each specific scenario) | Receiver | +| 400 | REC_BAD_REQUEST | not-supported | in FOT for when a function or feature in the standard is not yet supported. | Receiver | +| 400 | PROXY_BAD_REQUEST | structure | When Base-64 decoding of the NHSD-Target-Identifier header fails. | API | +| 400 | PROXY_BAD_REQUEST | structure | The NHSD-Target-Identifier header doesn't adhere to the schema | API | +| 401 | SEND_UNAUTHORIZED | login / expired | The sender has not provided a token or it has expired or is otherwise invalid. | API | +| 405 | SEND_METHOD_NOT_ALLOWED | not-supported | using the wrong http verb. For example GET instead of POST | API | +| 406 | SEND_NOT_ACCEPTABLE | processing | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. Versions in Accept or content.<br><br>Version is not present in FOT and should be ignored in FOT if presented. Post FOT it MUST be evaluated. | API | +| 406 | REC_NOT_ACCEPTABLE | processing | The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. Versions in Accept or content.<br><br>Version is not present in FOT and should be ignored in FOT if presented. Post FOT it MUST be evaluated. | Receiver | +| 429 | SEND_TOO_MANY_REQUESTS | throttled | when rate limiting is applied. | API | +| 409 | REC_TIMEOUT | timeout | Injected when a 504 is generated in the proxy due to a receiver timing out on a response. | API Injected | +| 500 | REC_SERVER_ERROR | transient | An unexpected exception has occurred during processing at the receiver. | Receiver/ API Injected | +| 500 | PROXY_SERVER_ERROR / SERVER ERROR | transient | An unexpected exception has occurred during processing internally. | API | +| 501 | REC_NOT_IMPLEMENTED | not-supported | The receiver has not yet implemented that endpoint or functionality. | Receiver | + +<a href="#" onclick="history.back()">back</a> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Index.page.md new file mode 100644 index 00000000..8b9411a8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-failure_scenarios-1.3.0 +--- \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Introduction.page.md new file mode 100644 index 00000000..9184faa4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Introduction.page.md @@ -0,0 +1,11 @@ +<a href="#" onclick="history.back()">back</a> + +## Failure Scenarios + +This page defines the foreseen failure scenarios within the BaRS standard and its implementations. The scenarios are broken down by endpoint and describe which HTTP Status Code, BaRS HTTP Error Code and FHIR issue.code to use for each eventuality. In any case, the diagnostics text should reflect the scenarios given and not necessarily be used verbatim where examples are given. + +The rationale, described in the {{pagelink:core-failure_scenarios-1.3.0, text:error handling}} section is that as much information on the nature of the failure as possible is provided in a standard way. + +Each scenario has a Source to state whether it is the BaRS Proxy or the Receiver which is generating the error. In scenarios where a SEND prefix is used, the sender is not adhering to the API specification in one way or another. These codes are held within OperationOoutcome.issue.details.code and use the http-error-codes value set. + +Note: in future, the PROXY prefix will no longer be used, and all errors from the Proxy will use a code with no prefix. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Message-Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Message-Routing.page.md new file mode 100644 index 00000000..6af42976 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/Message-Routing.page.md @@ -0,0 +1,63 @@ +--- +topic: Core-ErrorHandling-MessageRouting-1.3.0 +--- + +## Endpoint Catalogue - Message routing. + +<div id="message_routing"></div> + +Below is a diagram of error locations coupled with scenarios with regards to the routing of messages by the proxy using the Endpoint Catalogue. The below diagram is generic and not specific to any particular API endpoint. Most requests will be subject to the errors that can be encountered during message routing. + + ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/FailureScenarios/EndpointCatalogue-FailureScenarios-1.0.0.svg) + +### SEND at the API +The SEND prefix indicates an issue caught before any internal routing or processing occurs, it communicates a problem with the format of the request, not adhering to the API Spec as an example. + +These scenarios can be found in other areas however if more required headers are added for endpoints this may be expanded. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-----------------------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 400 | SEND_BAD_REQUEST | required | The X-Request-Id or the X-Correlation-Id was not included or the NHSD-Target-Identifier was not included (depending on the endpoint being called). | API | +| 401 | SEND_UNAUTHORIZED | security | The user or system was not able to be authenticated, either the access token was invalid, or not provided. | API | +| 401 | SEND_UNAUTHORIZED | unknown | No Access token was provided. | API | +| 403 | SEND_FORBIDDEN | forbidden | The access token was provided, but BaRS is not enabled. | API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | not-found | Endpoint on the API does not exist. This would be a Proxy or non-prefixed response. there is no SEND code for 404 in the value set. | API | +| 500 | PROXY_SERVER_ERROR / SERVER_ ERROR | exception | Unexpected error, would expect this to happen internally so this is likely never going to be needed for a SEND and thus unprefixed or PROXY is used here. | API | +| 503 | PROXY_UNAVAILABLE / SERVICE_UNAVAILABLE | transient | unlikely to get a OperationOutcome here. | API | + +### PROXY/NONE within the BaRS proxy + + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-----------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | invalid | The X-Request-Id or the X-Correlation-Id was invalid. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | invalid | When Base-64 decoding of the NHSD-Target-Identifier header fails. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | structure | The NHSD-Target-Identifier header doesn't adhere to the schema | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | required | A required item is missing. depending on the request/scenario this may be caught by the SEND details above. | API | +| 400 | PROXY_BAD_REQUEST / BAD_REQUEST | structure | A structural issue in the content such as wrong namespace, unable to parse the content completely - for example the Target identifier is malformed.| API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | not-found | The resource requested does not exist. For example; the target endpoint does not exist in the Endpoint Catalogue. | API | +| 404 | PROXY_NOT_FOUND / NOT_FOUND | multiple-matches | The Target Identifier found two endpoints, this would be an issue with the management of the Endpoint catalogue. | API | +| 500 | PROXY_SERVER_ERROR / SERVER_ERROR | exception | A sub-service encountered an unhandled exception. | API | +| 503 | PROXY_UNAVAILABLE / SERVICE_UNAVAILABLE | transient | A sub-service was unavailable. | API | + +### REC injected at the proxy +When a failure response is received when attempting to forward the request to the desired receiver but no OperationOutcome is included during a failure scenario. For example, a Timeout. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|-------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| 408 | REC_TIMEOUT | timeout | The connection to the Receiver timed out. | Receiver/ Injected at API | +| 500 | REC_SERVER_ERROR | exception | Generic should a 500 response be received but no operation outcome included. | Receiver / Injected at API | +| 503 | REC_SERVICE_UNAVAILABLE | transient | The response from the receiver was a 503, with no detail. Also useful if there is a connection failure such as the endpoint not being found, or failing to resolve. | Receiver / Injected at API | + +### REC at the receiver. +Failure responses generated by the receiver. + +| HTTP Status Code | HTTP Error Code | issue Code | Scenario | Source | +|------------------|------------------|------------|--------------------------------------------------------------|----------------------------| +| 401 | REC_UNAUTHORIZED | security | Access Control | Receiver | +| 403 | REC_FORBIDDEN | forbidden | TLS-MA failure. | Receiver | +| 403 | REC_FORBIDDEN | security | TLS-MA failure. | Receiver | +| 500 | REC_SERVER_ERROR | too costly | The request was deemed to costly to process by the receiver. | Receiver | +| 500 | REC_SERVER_ERROR | exception | unhandled exception. | Receiver / Injected at API | +| 500 | REC_SERVER_ERROR | no-store | internal data storage issue. | Receiver / Injected at API | + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/toc.yaml new file mode 100644 index 00000000..116448ef --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios-1.1.x/toc.yaml @@ -0,0 +1,20 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Message Routing + filename: Message-Routing.page.md +- name: Capability Statement + filename: Capability-Statement.page.md +- name: GET /MessageDefinition + filename: GET--MessageDefinition.page.md +- name: GET /Slots + filename: GET--Slots.page.md +- name: GET /Appointment + filename: GET--Appointment.page.md +- name: GET /ServiceRequest + filename: GET--ServiceRequest.page.md +- name: Bundle Processing + filename: Bundle-Processing.page.md +- name: General Failure Scenarios + filename: General-Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios.page.md new file mode 100644 index 00000000..363ceddc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Failure-Scenarios.page.md @@ -0,0 +1,7 @@ +--- +topic: core-EHFailureScenarios-1.3.0 +--- + +## Failure Scenarios + +For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.3.0, text: Failure Scenarios}} section. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Index.page.md new file mode 100644 index 00000000..44a24205 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-ErrorHandling-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Introduction.page.md new file mode 100644 index 00000000..9c11f26c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-Introduction-1.3.0 +--- + +# Error Handling + +There are multiple points where an error may occur to prevent booking and referral operations from completing successfully. This section provides error handling guidance for BaRS and its associated API. For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.3.0}} section in addition to information included on this page. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/OperationOutcome-Example.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/OperationOutcome-Example.page.md new file mode 100644 index 00000000..b583a8ec --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/OperationOutcome-Example.page.md @@ -0,0 +1,61 @@ +--- +topic: core-ErrorHandling-OpOut-1.3.0 +--- + +### OperationOutcome Example + +<json> + + { + + "resourceType": "OperationOutcome", + + "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + + "meta": { + + "profile": [ + + "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + + ] + + }, + + "issue": [ + + { + + "severity": "error", + + "code": "invalid", + + "details": { + + "coding": [ + + { + + "system": "https://fhir.nhs.uk/CodeSystem/http-error-codes", + + "code": "PROXY_BAD_REQUEST", + + "display": "400 - PROXY_BAD_REQUEST" + + } + + ] + + }, + + "diagnostics": "BaRS encountered a conflict: <further diagnostics information, error message/error text>" + + } + + ] + + } +</json> + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Overview.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Overview.page.md new file mode 100644 index 00000000..decd9fb2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Overview.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-Overview-1.3.0 +--- + +### Overview + +Error codes (HTTP Response codes) can be caused by any of the three parties involved in a transaction using the Booking and Referral API. Error codes will be accompanied by a OperationOutcome FHIR resource where possible. Error codes and their relative operation outcome codes are meant for developer use only - they should not be presented to end-users. Instead, sending applications should interpret the two codes and provide user-friendly resolution steps on failure. Sender and receiver systems should record the detailed error codes in local logs in order to support service incident investigation. There are scenarios where an operation outcome may not be applicable or available. A HTTP Response code should always be returned. + +Operation Outcome Codes are prefixed with an indicator of the source of the error help identify where a problem may be. + +The following table provides a high-level overview of each stage in the booking and referral process from the perspective of a sending application. + +| Interaction | Error Handling Overview | Operation Outcome Prefix | +|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------| +| Sender querying a Service Discovery tool | As an existing solution, the DOS APIs return a number of significant errors specific to the actual API failing. These are all self-contained in that process. These are documented in a link below and will not affect the ongoing activity unless the data returned in the query is erroneous and then cause the next stages of the process to either fail or not be possible. | N/A | +| Sender interactions with the BaRS API | Interactions with the BaRS API may fail due to, but not limited to, the following reasons: The service being unavailable to the sender, the Sender being unauthenticated, the Sender reaching or exceeding a rate limit, or badly formed requests being sent. | SEND | +| BaRS Service internal interactions | Depending on the operation requested, internal interactions may fail within the proxy due to non-existent resources, service failures or data related issues within the Senders payload. | PROXY | +| BaRS interaction with the Receiver | In the event BaRS successfully proxies a request through to a Receiver, the Receiver may still respond with an error due to authentication, authorization or data related issues within the Senders payload, assuming the endpoint is available. | REC | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Receiver-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Receiver-Responsibilities.page.md new file mode 100644 index 00000000..a0040337 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Receiver-Responsibilities.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-RecResp-1.3.0 +--- + +### Receiver responsibilities + +- Receiving APIs should adhere to the HTTP Response code and Operational Outcome code paradigm described above in the event that an error response needs to be returned +- The sender should be able to ascertain what went wrong and why in the event of an error +- Receiving endpoints should use the REC prefixed Operation Outcome codes and provide clear and concise diagnostics texts +- There should be no need to omit or use a different prefix when responding to requests +- There will be times where it is not possible to generate a response in the above format +- In the event this occurs, a relevant HTTP response code should be the minimum +- Log errors locally for incident investigation by IT support staff +- If the request is problematic, this should be logged specifically as a sender system issue +- Details of the sender system should be logged to support investigation +- As a minimum, the Operation Outcome must include: + - The HTTP Response code + - The Operation Outcome code + - Clear and concise diagnostics information + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Sender-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Sender-Responsibilities.page.md new file mode 100644 index 00000000..27a9f6a3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/Sender-Responsibilities.page.md @@ -0,0 +1,14 @@ +--- +topic: core-ErrorHandling-SendResp-1.3.0 +--- + +### Sender responsibilities + +- Log errors returned for incident investigation by IT support staff +- Ensure sufficient information for appropriate local incident management is captured +- Communicate with receivers should an unexpected error be received consistently (REC) +- Communicate with NHS Digital should a persistent error state be encountered from BaRS (PROXY) +- Inform end-user with a suitable message appropriate to the business flow, for example: critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/toc.yaml new file mode 100644 index 00000000..cf1fff38 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Error-Handling/toc.yaml @@ -0,0 +1,26 @@ +- name: + filename: Failure-Scenarios-1.1.x +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Overview + filename: Overview.page.md +- name: BaRS interactions (sending) + filename: BaRS-interactions--sending.page.md +- name: OperationOutcome Example + filename: OperationOutcome-Example.page.md +- name: Diagnostics Text + filename: Diagnostics-Text.page.md +- name: Example Errors + filename: Example-Errors.page.md +- name: Sender Responsibilities + filename: Sender-Responsibilities.page.md +- name: BaRS interactions (receiving) + filename: BaRS-interactions--receiving.page.md +- name: Receiver Responsibilities + filename: Receiver-Responsibilities.page.md +- name: OperationOutcome Example + filename: OperationOutcome-Example-duplicate-2.page.md +- name: Failure Scenarios + filename: Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md new file mode 100644 index 00000000..4dd1d828 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md @@ -0,0 +1,259 @@ +--- +topic: design-core-1.3.0 +--- +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important: Versioning information</b> +<p> + +This version of core is strictly a preview of what is currently in development for 1.2.2-alpha and should not be built against. + +<table> +<thead> + <tr> + <th data-no-sort="">Core Version</th> + <th data-no-sort="">Minimum Guide Version</th> + <th data-no-sort="">Minimum API Spec Version</th> + </tr> +</thead> +<tbody> + <tr> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Core/1.2.2" target="_blank">v1.2.2-alpha</a></td> + <td><a href="https://simplifier.net/guide/nhsbookingandreferralstandard/home?version=1.8.2" target="_blank">v1.8.2</td> + <td><a href="https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0" target="_blank">v1.2.0</a></td> + </tr> +</tbody> +</table> +</div> + + +# BaRS Core 1.2.2-alpha + +BaRS consists of BaRS Core that provides a core set of functionality and BaRS Applications that provide distinct functionality for each use case. + +You will find here a set of documentation, specifications and services that describe and support all the fundamental components of the standard that are always the same for all use cases or care journeys. Examples include the underlying capabilities and patterns and transport layer elements such as security, authorisation and access control. + +<details> +<summary>> <b class="barslink">Expand for full Core directory</b></summary> + +• {{pagelink:design-core-1.3.0 , text: Core 1.2.2}}</br> +  • {{pagelink:core-EndToEndWorkflow-1.3.0 , text:End to end workflow}}</br> +    • {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.3.0 , text:Service Discovery}}</br> +    • {{pagelink:core-EndToEndWorkflow-BaRSAuth-1.3.0 , text:Authenticate with BaRS}}</br> +    • {{pagelink:core-EndToEndWorkflow-API-1.3.0 , text:BaRS FHIR API}}</br> +    • {{pagelink:core-EndToEndWorkflow-HTTPHeader-1.3.0 , text:HTTP Header}}</br> +    • {{pagelink:core-EndToEndWorkflow-Routing-1.3.0 , text:Routing}}</br> +    • {{pagelink:core-EndToEndWorkflow-Auth-1.3.0 , text:Authentication and Authorisation}}</br> +    • {{pagelink:core-EndToEndWorkflow-Transactional-Integrity-1.3.0 , text:Transactional Integrity}}</br> +    • {{pagelink:core-EndToEndWorkflow-HTTPResponseHeader-1.3.0 , text:HTTP Response Headers}}</br> +    • {{pagelink:core-EndToEndWorkflow-Processing-1.3.0 , text:Processing Requests}}</br> +    • {{pagelink:core-EndToEndWorkflow-Responses-1.3.0 , text:Responses}}</br> +    • {{pagelink:core-EndToEndWorkflow-ReversingRoles-1.3.0 , text:Reversing Roles}}</br> +    • {{pagelink:core-EndToEndWorkflow-AsyncWorkflow-1.3.0 , text:Asynchronous Workflow}}</br> +  • {{pagelink:core-FunctionalityRequirements-1.3.0 , text:Core Functionality Requirements.}}</br> +    • {{pagelink:core-FunctionalityRequirements-All-1.3.0 , text:All}}</br> +    • {{pagelink:core-FunctionalityRequirements-Caching-1.3.0 , text:Caching}}</br> +    • {{pagelink:core-FunctionalityRequirements-BookingSender-1.3.0 , text:Booking Sender}}</br> +    • {{pagelink:core-FunctionalityRequirements-BookingReceiver-1.3.0 , text:Booking Receiver}}</br> +    • {{pagelink:core-FunctionalityRequirements-ReferralSender-1.3.0 , text:Referral Sender}}</br> +    • {{pagelink:core-FunctionalityRequirements-ReferralReceiver-1.3.0 , text:Referral Receiver}}</br> +  • {{pagelink:core-FHIRUsage-1.3.0 , text:BaRS FHIR Usage}}</br> +    • {{pagelink:core-FHIRUsage-Framework-1.3.0 , text:Frameworks}}</br> +    • {{pagelink:core-FHIRUsage-REST-1.3.0 , text:REST}}</br> +    • {{pagelink:core-FHIRUsage-FHIR-Operations-1.3.0 , text:FHIR Operations}}</br> +    • {{pagelink:core-FHIRUsage-Process-Message-1.3.0 , text:$process-message}}</br> +    • {{pagelink:core-FHIRUsage-bundle-1.3.0 , text:Bundle}}</br> +    • {{pagelink:core-FHIRUsage-JourneyID-1.3.0 , text:Journey ID}}</br> +    • {{pagelink:core-FHIRUsage-Time-1.3.0 , text:How to handle times}}</br> +    • {{pagelink:core-FHIRUsage-LastUpdated-1.3.0 , text:LastUpdatedDate}}</br> +  • {{pagelink:core-Security-1.3.0 , text:Security and Authorisation}}</br> +    • {{pagelink:core-Security-Sender-1.3.0 , text:Sender}}</br> +    • {{pagelink:core-Security-Oauth-1.3.0 , text:OAuth Endpoints}}</br> +    • {{pagelink:core-Security-Receiver-1.3.0 , text:Receiver}}</br> +    • {{pagelink:core-Security-Auth-1.3.0 , text:Authorisation}}</br> +  • {{pagelink:core-ErrorHandling-1.3.0 , text:Error Handling}}</br> +    • {{pagelink:core-ErrorHandling-Overview-1.3.0 , text:Overview}}</br> +    • {{pagelink:core-ErrorHandling-IntS-1.3.0 , text:BaRS interactions(sending)}}</br> +    • {{pagelink:core-ErrorHandling-OpOut-1.3.0 , text:OperationOutcome Example}}</br> +    • {{pagelink:core-ErrorHandling-Diag-1.3.0 , text:Diagnostic Text}}</br> +    • {{pagelink:core-ErrorHandling-Examples-1.3.0 , text:Example Errors}}</br> +    • {{pagelink:core-ErrorHandling-SendResp-1.3.0 , text:Sender Responsibilities}}</br> +    • {{pagelink:core-ErrorHandling-IntR-1.3.0 , text:BaRs interactions(receiving)}}</br> +    • {{pagelink:core-ErrorHandling-RecResp-1.3.0 , text:Receiver responsibilities}}</br> +    • {{pagelink:core-failure_scenarios-1.3.0 , text:Failure Scenarios}} </br> +  • {{pagelink:Core-TransactionalIntegrity-1.3.0 , text:Transactional Integrity}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Initial-1.3.0 , text:Initial Request}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Update-1.3.0 , text:Sending an update}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Feedback-1.3.0 , text:Feedback (response) requests}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Retry-1.3.0 , text:Retry Scenario}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Onward-1.3.0 , text:Onwards Referrals}}</br> +    • {{pagelink:Core-TransactionalIntegrity-retry-1.3.0 , text:Definition of a Retry}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Receiver-1.3.0 , text:Receiver responsibilities}}</br> +    • {{pagelink:Core-TransactionalIntegrity-Sender-1.3.0 , text:Sender responsibilities}}</br> +    • {{pagelink:core-TIFailureScenarios-1.3.0 , text:Failure Scenarios}}</br> +  • {{pagelink:core-NFR-1.3.0 , text:Non functional Requirements}}</br> +    • {{pagelink:core-NFR-Requirements-1.3.0 , text:Requirements}}</br> +    • {{pagelink:core-NFR-Processing-Time-1.3.0 , text:Processing Times}}</br> +  • {{pagelink:Core-StandardPattern-1.3.0 , text:Standard Pattern - Composite Messages}}</br> +    • {{pagelink:core-SPComposites-1.3.0 , text:Standard Pattern for Composites}}</br> +    • {{pagelink:core-SPMessageHeader-1.3.0 , text:Message Headers}}</br> +    • {{pagelink:core-SPCancellation-1.3.0 , text:Cancellation}}</br> +    • {{pagelink:core-SPUseCaseCategories-1.3.0 , text:Use Case Categories}}</br> +  • {{pagelink:core-StandardPattern-appointment-1.3.0 , text:Standard Pattern - Appointments}}</br> +    • {{pagelink:core-StandardPattern-appointment-booking-1.3.0 , text:Booking}}</br> +    • {{pagelink:core-StandardPattern-appointment-update-1.3.0 , text:Updates}}</br> +    • {{pagelink:core-StandardPattern-appointment-cancel-1.3.0 , text:Cancellations}}</br> +    • {{pagelink:core-StandardPattern-appointment-rebook-1.3.0 , text:Rebook}}</br> +  • {{pagelink:core-StandardPattern-document-reference-1.3.0 , text:Standard Pattern - DocumentReference}}</br> +    • {{pagelink:core-StandardPattern-document-reference-Sender-1.3.0 , text:Sender}}</br> +    • {{pagelink:core-StandardPattern-document-reference-Receiver-1.3.0 , text:Receiver}}</br> +    • {{pagelink:core-StandardPattern-document-reference-interface-1.3.0 , text:Interface}}</br> +  • {{pagelink:core-StandardPattern-Endpoints-1.3.0 , text:Standard Pattern - Endpoints}}</br> +    • {{pagelink:core-StandardPattern-Endpoint-Introduction-1.3.0 , text:Introduction}}</br> +    • {{pagelink:core-StandardPattern-Endpoint-Interface-1.3.0 , text:Interface}}</br> +    • {{pagelink:core-StandardPattern-Endpoint-Data-1.3.0 , text:Data Model}}</br> +    • {{pagelink:core-StandardPattern-Endpoint-Sequences-1.3.0 , text:Sequences}}</br> + + + +</details> + +<hr> + +# End to end workflow +This section covers the core elements of workflow outlined within the Booking and Referral Standard. There are two caveats when reading this: + +- Workflow is dependent on its Application or use case, for example in 999 - CAS validation, there is no step to perform a booking. See the relevant use case page in the +{{pagelink:applications, text:BaRS Applications}} section. + + +- The order of workflow is interchangeable. It is possible to: + - make a referral before a booking + - refer without booking + - book without referring + +For more detail please visit the {{pagelink:core-EndToEndWorkflow-1.3.0, text: End to End Workflow}} section. + +<hr> +<br> + + +# Core Functionality Requirements +BaRS should provide different functionality depending on: + +- its {{pagelink:applications, text:Application or use case}} +- whether it acts as a sender or receiver + + +This list of functionality will expand in later versions of BaRS. + +There are requirements in each of the central areas of functionality which every BaRS Application must adopt: + +For more detail please visit the {{pagelink:core-FunctionalityRequirements-1.3.0, text: Core Functionality Requirements}} section. + +<hr> +<br> + +# Content Negotiation + +Content Negotiation within BaRS leverages multiple variables within the CapabilityStatement and MessageDefinition to ensure that a Sender and a Receiver are Compatible. Though some of this is possible due to the Versioning Negotiation, Content Negotiation further builds on that concept with the capabilities published by the server and the identification of message definitions and use cases therein to ensure a workflow can be completed. + +For more detail please visit the {{pagelink:core-content-negotiation, text: Content Negotiation}} section. + +<hr> +<br> + +# BaRS FHIR usage +BaRS uses [FHIR](https://digital.nhs.uk/services/fhir-uk-core) to achieve interoperability between healthcare IT systems. This section explains how BaRS makes use of some key FHIR concepts which need to be understood by developers implementing the standard. + +For more detail please visit the {{pagelink:core-FHIRUsage-1.3.0, text: BaRS FHIR usage}} section. + +<hr> +<br> + +# Security and Authorisation + +For more detail on Security and Authorisation, please visit the {{pagelink:core-Security-1.3.0, text: Security and Authorisation}} section. + +<hr> +<br> + +# Error Handling +There are multiple points where an error may occur to prevent booking and referral operations from completing successfully. This section provides error handling guidance for BaRS and its associated API. For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.3.0}} section in addition to information included on this page. + +For more detail please visit the {{pagelink:core-ErrorHandling-1.3.0, text: Error Handling}} section. + +<hr> +<br> + +# Transactional Integrity +Transactional integrity is employed to ensure data integrity is maintained between two parties. It helps ensure that the success or failure of a message is known and can be confirmed. + +For more detail please visit the {{pagelink:Core-TransactionalIntegrity-1.3.0, text:Transactional Integrity}} section. + +<hr> +<br> + +# Non Functional Requirements + +The non functional requirements apply to all APIs designed to receive requests from BaRS. This includes sender systems receiving asynchronous responses and feedback, as well as receiving systems. All items detailed will be adhered to. + +For more detail please visit the {{pagelink:core-NFR-1.3.0, text: Non Functional Requirements}} section. + +<hr> +<br> + +# Standard Pattern - Composite Messages +Most implementations of the BaRS that are applying the standard to support a particular use case or operational workflow will follow the same basic set of foundational operations with little deviation. + +In order to establish a guarantee of compatibility between different solutions compliant with the standard, **all** implementations **must** support all the underlying foundational operations and patterns. + +For more detail please visit the {{pagelink:Core-StandardPattern-1.3.0, text: Standard Pattern - Composite Messages}} section. + +<hr> +<br> + +# Standard Pattern - Appointment + +There are 4 capabilities that are required surrounding appointments. This section will provide information on how to meet them. + +* The ability to book an appointment. +* The ability to cancel an appointment. +* The ability to update an appointment. +* The ability to rebook an appointment. + +For more detail please visit the {{pagelink:core-StandardPattern-appointment-1.3.0, text: Appointment Standard Pattern}} section. + +<hr> +<br> + +# Standard Pattern - DocumentReference + +In version 1.1.0 of the BaRS API Specification, functionality was added to accommodate the use of pointers (DocumentReference resources), to locate existing bookings and referrals. + +The FHIR DocumentReference resource allows you to reference and locate clinical documents or resources. This section will walk you through the process of using a FHIR DocumentReference to find a resource's location and retrieve it. + +For more detail please visit the {{pagelink:core-StandardPattern-document-reference-1.3.0, text: DocumentReference Standard Pattern}} section. + +<hr> +<br> + + +# Standard Pattern - Endpoints + + +<div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i><b> Important: Versioning information - Preview</b> +<p> + +This version of core is strictly a preview of what is currently in development for 1.2.0 and should not be built against. + +</div> + +BaRS employs an endpoint catalogue to match Target Identifiers with a stored endpoint. Target Identifiers are provided in a header which is descripted in the [API Spec](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0) The following pages will describe how these entries can be managed, outside of the onboarding process. + +The BaRS endpoints will utilise not only service ids and a physical endpoint, but data describing the healthcare service, the provider of that service and the organization which manages and/or supplies the endpoint in question. + +BaRS will expose an interface to manage this information in the format of FHIR resources. Each resource will have a corresponding endpoint on the Proxy to assist in managing these endpoints. + +For more detail please visit the {{pagelink:core-StandardPattern-Endpoints-1.3.0, text: Endpoint Standard Pattern}} section. + +<hr> +<br> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Index.page.md new file mode 100644 index 00000000..e6155cc3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-NFR-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Introduction.page.md new file mode 100644 index 00000000..ab1e57ff --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-NFR-Introduction-1.3.0 +--- + +## Non-Functional Requirements + +The following non functional requirements apply to all APIs designed to receive requests from BaRS. This includes sender systems receiving asynchronous responses and feedback, as well as receiving systems. All items listed below will be adhered to. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Processing-Times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Processing-Times.page.md new file mode 100644 index 00000000..ee8b390b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Processing-Times.page.md @@ -0,0 +1,15 @@ +--- +topic: core-NFR-Processing-Time-1.3.0 +--- + + +## {{page-title}} + +The following Processing time SLAs describe the need for APIs to respond to a request within an acceptable time frame. This time frame should be measured from when a request is received and does not include the transport time. +These times are guide for average response time. + +| item | Requirement. | +|------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 1 | 90% of requests SHOULD take less than 2100ms to process. (Allowing for response time depending on measurement point). $process-message independently measured. | +| 2 | All requests MUST take less than 5000ms to process. | +| 3 | Any requests not processed within 5000ms should be timed out with "408 - REC_TIMEOUT - timeout" \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Requirements.page.md new file mode 100644 index 00000000..8895ad56 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/Requirements.page.md @@ -0,0 +1,19 @@ +--- +topic: core-NFR-Requirements-1.3.0 +--- + +## {{page-title}} + +| Name | Description | +|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Conformance | The solution conforms with the BaRS standards where applicable, within any Application | +| Safety | The solution complies with NHS Digital [Clinical Risk Management Standards](https://digital.nhs.uk/services/clinical-safety/clinical-risk-management-standards), in particular 0129 (IT Supplier) and 0160 (Trust/Provider) | +| Security | The solution resists unauthorised, accidental or unintended usage and provides access only to legitimate requests | +| Scalable and capacity | The solution is designed to accommodate increased volumes, workloads and users | +| Availability and reliability | The solution meets a service level agreement that includes a 99.9% uptime guarantee and a high Mean Time Between Failures (MTBF) The solution has adequate disaster recovery and fault tolerance enabling continued operation in the event of a failure | +| Auditability | All of the solutions interactions are fully auditable for both sending and receiving | +| Data retention | The Solution audits all API access attempts and actions, retaining all pertinent data therein | +| Deployment | Solution providers release a new major version of their Booking and Referral APIs alongside a previous major version, until such time as consumers have migrated to the new major version. Alternatively, there is support for backward compatibility of requests to support consumers. Solution providers release a new minor or patch version, replacing the previous minor or patch version The Booking and Referral endpoints are independently deployable against unique Fully Qualified Domain Names (FDQN). This ensures support for limitations around sending and receiving messages between path-to-live and production environments. To increase availability, during upgrades and maintenance, the Booking and Referral APIs are load balanced across multiple servers In multi tenanted deployments, the activity of individual tenants are readily distinguishable | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/toc.yaml new file mode 100644 index 00000000..5e962e98 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Non-Functional-Requirements/toc.yaml @@ -0,0 +1,8 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Requirements + filename: Requirements.page.md +- name: Processing Times + filename: Processing-Times.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Authorisation.page.md new file mode 100644 index 00000000..c5396575 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Authorisation.page.md @@ -0,0 +1,17 @@ +--- +topic: core-Security-Auth-1.3.0 +--- + +## Authorisation + +BaRS will use several HTTP headers to facilitate authorisation. Although optional, receivers can expect these to be present for each request (excluding /metadata and /MessageDefinition), where applicable, to enforce access control. These will be in addition to the X-Request-ID and the X-Correlation-ID headers. If the information in these headers is available in the sending system, they'll be included in the request. + +Each of these HTTP headers are objects and will therefore need to be added in the form of a standard Base64 encoded string. + +Examples of each HTTP header item can be found within the [API Specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir). + +| HTTP Header | Purpose | +|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| NHSD-End-User-Organisation | This will represent the organisation making the request. It Shall include the ODS code and the human readable name of the organisation making the request. The object is based on a FHIR Organisation resource. | | +| NHSD-Requesting-Practitioner | This entry will represent the Practitioner role associated to the request. It shall include their sds role id and a SNOMED code related to their role where applicable. The object is based on a FHIR PractitionerRole resource. | +| NHSD-Requesting-Software | This entry will represent the Software or application making the request. It shall include an identifier for the instance, the product name and its version. The object is based on a FHIR Device resource. | \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Index.page.md new file mode 100644 index 00000000..54225d30 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-Security-1.3.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Introduction.page.md new file mode 100644 index 00000000..69139bfa --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Introduction.page.md @@ -0,0 +1,8 @@ +--- +topic: core-Security-Introduction-1.3.0 +--- + +# Security and Authorisation + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/OAuth-Endpoints.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/OAuth-Endpoints.page.md new file mode 100644 index 00000000..d676c05b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/OAuth-Endpoints.page.md @@ -0,0 +1,15 @@ +--- +topic: core-Security-Oauth-1.3.0 +--- + +## OAuth Endpoints + +| Environment | Endpoint | Usage/Availability | +|------------------|-------------------------------------------|------------------------------------------------------------| +| Sandbox | https://sandbox.api.service.nhs.uk/oauth2 | Authentication is not required in the Sandbox environment. | +| Development | https://dev.api.service.nhs.uk/oauth2 | Limited to specific APIs | +| Integration test | https://int.api.service.nhs.uk/oauth2 | All APIs | +| Production | https://api.service.nhs.uk/oauth2 | All APIs | + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Receiver.page.md new file mode 100644 index 00000000..b31f2920 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Receiver.page.md @@ -0,0 +1,39 @@ +--- +topic: core-Security-Receiver-1.3.0 +--- + +## Receiver + +BaRS will utilise TLS-MA (Mutual Authentication) to communicate with receiving endpoints. Receiving endpoints will require a certificate under the NHS Root CA to facilitate TLS-MA. + +- The receiver will need to request a certificate under the NHS Root CA + - There are two different certificate chains for INT and Prod + - INT Certificate chains, which are superceded from 4/06/2024, can be found [here](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates) + - Prod Certificate chains,which expire from 4/06/2024, can be found [here](https://digital.nhs.uk/services/path-to-live-environments/live-environment) + - **Current** INT Certificate chains can be found [here](https://pki.nhs.uk/G2Transition/) + - **Current** Prod Certificate chains can be found [here](https://pki.nhs.uk/G2Transition/) + +- The receiving endpoint will present the certificate obtained for TLS-MA +- The receiving endpoint will need to trust the Root CAs and SubCAs for their respective environments +- The receiving endpoint will only accept requests presented with certificates from their respective chains + +As the certificates are using the NHS Root CA, fully qualified domain name (FQDN) must be an nhs.uk address, this is the case for both INT and Prod + +You need to [apply for your domain](https://digital.nhs.uk/services/networking-addressing/apply-for-an-nhs.uk-domain-for-websites-and-web-applications), ensuring that you complete 'Section 5: For website or application records visible on public internet'. + +In production there is a naming convention that must be adhered to. In INT the naming convention should be adhered where possible. In the context of BaRS an example will be: + +- ==BaRS-< ODSCode >.< OrganisationName >.nhs.uk== , BaRS is always the application name. + +Once you have you have your domain registered you can then begin the process to obtain your certificate by generating a certificate request. + +Certificate requests will need to be signed for your endpoint. Note that the FQDN is equal to the certificate name (CN) by convention. + +At this point you should have a .key and a .csr files. The next step will be to send the .csr file to be signed by the NHS and get the client certificate. + +- If your client certificate will be implemented in any PTL environment then you should send the .csr file to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) and they will reply with the certificate (.crt file) + +- If your client certificate will be implemented in the PROD environment then the .csr file needs to be send to the DIR team at [dir@nhs.net](mailto:dir@nhs.net) and they will take care of issuing the certificate after validating your request with the Live Services Pipeline at [liveservices.gate@nhs.net](mailto:liveservices.gate@nhs.net) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Sender.page.md new file mode 100644 index 00000000..69b4ec40 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/Sender.page.md @@ -0,0 +1,18 @@ +--- +topic: core-Security-Sender-1.3.0 +--- + +## Sender + +The BaRS standard uses an [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis) security model and [security pattern](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication#how-this-pattern-works) as opposed to a [user-restricted security](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) model. This means the application is authenticated as opposed to the end-user using it. The high level steps for a sending application are defined below: + +1. The end user launches the calling application +2. Time passes, until the user needs to interact with BaRS +3. The calling application generates and signs a JWT, using its own private key +4. The calling application calls our OAuth 2.0 token endpoint with the signed JWT. In particular, this uses the OAuth 2.0 client credentials flow +5. We check the signature against the application's public key and, if valid, return an access token to the calling application +6. The calling application calls the BaRS API, including the access token +7. The BaRS API allows the interaction should the access token be valid + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/toc.yaml new file mode 100644 index 00000000..3949edb7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Security-and-Authorisation/toc.yaml @@ -0,0 +1,12 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Sender + filename: Sender.page.md +- name: OAuth Endpoints + filename: OAuth-Endpoints.page.md +- name: Receiver + filename: Receiver.page.md +- name: Authorisation + filename: Authorisation.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md new file mode 100644 index 00000000..fc24caa7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -0,0 +1,551 @@ +--- +topic: core-SPCancellation-1.3.0 +--- + + +## {{page-title}} + +The ability to reverse a digital request, by performing a cancellation, whether booking or referral, is a core workflow within BaRS. It completes the digital workflow, supports genuine interoperability and removes the need for manual intervention by service providers. + +Cancellation, for any referral type or booking, is a stripped back request, containing only the specific resources a Receiver requires to the fulfil the request. There are separate MessageDefinitions involved when engaged in [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. + +A prerequisite when performing a cancellation of any request is to perform a read (GET) of either the booking or referral to be cancelled. The Sender **must** only make a cancellation request if the entity has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the entity they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.3.0, text:error}} response. + +The Sender **must** obtain the (resource).id value of the booking (Appintment) or referral (ServiceRequest) to be able to generate the cancellation request. If the Sender made the original request, they will know this and can directly request the specific resource to check the status, using the GET (read) by Id request. Alternatively, if they did not generate the original request or there was a problem with the synchronous response being received, the booking or referral can be obtained by searching for active entities for the patient, either by using the national identifier (NHS No.) or patient demographics (Name (as defined by [FHIR](https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/2834389 )), Date of Birth, Home Address Postcode) (See diagram under 'Options for obtaining booking or referral' for detailed workflows). This will return a (FHIR) bundle of responses (typically, containing only one resource) which the Sender can match based on dateTime (elements dependent of resource) and use-case category values to identify the resource of interest. If the Sender cannot match the resource they should advise the user the cancellation cannot be performed and to revert to manual cancellation options instead. + +#### Options for obtaining booking or referral + +<br> +<br> +The below diagram details the options for obtaining the booking (Appointment) or referral (ServiceRequest) resource, prior to cancellation. The Sender **must** know the (resource).status and (resource).id values, as minimum, to build a valid cancellation request. +<br> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_StandardPattern_Cancellation_Find_Id.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/SequenceDiagrams/BaRS_StandardPattern_Cancellation_Find_Id.svg" width="1200"></img></a> +<br> +<br> +<hr> + +## Cancellation Referral Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. + +When cancelling a referral, in conjunction with the guidance provided under the Standard Patterns, the four important elements which drive workflow **must** be used as follows: +* **eventCoding** - this **must** be the same code as used in the request. +* **reasonCode** - a cancellation follows an initial request, therefore, this **must** always be 'update' for cancellation. +* **definition** - cancellation has a unique [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the request **must** adhere to. +* **focus** - **must** point to the *ServiceRequest* resource. + +<br> + +### ServiceRequest Resource +The 'focus' resource in a cancellation referral request is the ServiceRequest resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail. + +When a Receiver processes the cancellation referral request, the two key elements used are the *ServiceRequest.id* and *ServiceRequest.status*. The *.id* **must** already exist as an 'active' (status) ServiceRequest on the Receiver system (this **must** have been confirmed by a prior read (GET) by the Sender) and the *.status*, in the request, **must** either be 'revoked' or 'entered-in-error'. There is a distinct difference between these two *ServiceRequest.status(es)*. 'Revoked' **should** be used to denote the original request was intentional but, due to a change in circumstances, is no longer valid, whereas, 'entered-in-error' **should** be used when original request was in error. The purpose of this differentiation is to allow service providers to accurately report the reason for cancellations. + +### Patient Resource +Key patient demographics **should** be cross-referenced between the current 'active' referral and incoming cancellation referral request to ensure validity. + +## Payload for Referral Cancellation Request + +This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Referral. + +<br> + <div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> + <b>Please expand each resource below to view implementation guidance.</b> + </div> +<br> + +<details> + <summary>> <b class="barslink">Bundle</b></summary> + <p> + + <p>The Bundle resource is the container for the event message.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | +| Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | +| Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | +| Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | +| Bundle.timestamp | the date that the content of the message was assembled. This date is not changed by middleware engines unless they add additional data that changes the meaning of the time of the message | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.entry(s) | Follow BaRS profile guidance for populating this element | MUST | 1..* | | +| Bundle.entry.fullUrl | unique identifier for the resource entry. Transient id relative to the bundle | MUST | 0..1 | urn:uuid:1cbdfb97-5859-48a4-8301-d54eab818d68 | +| Bundle.entry.resourceType | Resources detailed in the message definition. | MUST | 0..1 | MessageHeader,Patient, Encounter | + + + +</details> +<p> +<details> + <summary>> <b class="barslink">Message Header</b></summary> + + <p> + + <p>A resource that describes the BaRS message being exchanged between two systems.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-servicerequest-request, hybrid}} + <p> + + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| MessageHeader | A resource that describes the BaRS message being exchanged between two systems https://simplifier.net/nhsbookingandreferrals/barsmessageheaderservicerequestrequest | | 1..1 | | +| MessageHeader.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| MessageHeader.meta.profile | This MUST be populated with the structure definition for BaRSMessageHeader-servicerequest-request. | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSMEssageHeader-servicerequest-request | +| MessageHeader.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| MessageHeader.extension | This MUST be populated with details of the Clinical Decision Support System used | MUST | 0..* | | +| MessageHeader.extension.url | This MUST be populated with 'https://fhir.nhs.uk/StructureDefinition/CDSSExtension' - FIXED VALUE | MUST | 1..1 | https://fhir.nhs.uk/StructureDefinition/CDSSExtension | +| MessageHeader.extension.extension | | MUST | 0..* | | +| MessageHeader.extension.extension.url | This MUST be populated with the pre-defined Clinical Decision Support System software URL - FIXED VALUE | MUST | 1..1 | requesterCDSSSoftware | +| MessageHeader.extension.extension.valueString | This MUST be populated with the Clinical Decision Support System software name e.g. Pathways | MUST | 0..1 | Pathways | +| MessageHeader.extension.extension | | MUST | 0..* | | +| MessageHeader.extension.extension.url | This MUST be populated with the pre-defined Clinical Decision Support System software Version URL - FIXED VALUE | MUST | 1..1 | requesterCDSSVersion | +| MessageHeader.extension.extension.valueString | This MUST be populated with the Clinical Decision Support System software Version name e.g. 30.2.0 | MUST | 0..1 | 30.2.0 | +| MessageHeader.eventcoding | | MUST | 1..1 | | +| MessageHeader.eventcoding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-events-bars | +| MessageHeader.eventcoding.code | The status MUST be populated with 'servicerequest-request'. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | servicerequest-request | +| MessageHeader.destination | | MUST | 0..1 | | +| MessageHeader.destination.receiver | | MUST | 0..1 | | +| MessageHeader.destination.receiver.reference | This MUST be populated with the full URL to the Receiving Organisation resource. | MUST | 0..1 | urn:uuid:10397afd-479c-42ea-9d5d-e4024481e0f8 | +| MessageHeader.destination.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows the intended destination. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|1122334455 | +| MessageHeader.sender | | MUST | 0..1 | | +| MessageHeader.sender.reference | This MUST be populated. Follow BaRS profile guidance for populating this element | MUST | 0..1 | urn:uuid:07939a0c-2854-46ff-9282-ad906bc93679 | +| MessageHeader.source | | MUST | 1..1 | | +| MessageHeader.source.name | This MUST be populated with the sending system supplier name | MUST | 0..1 | NHS Trust | +| MessageHeader.source.software | This SHOULD be populated with the sending software application name | SHOULD | 0..1 | Supplier Software | +| MessageHeader.source.version | This SHOULD be populated with the sending software version | SHOULD | 0..1 | V1.0.0 | +| MessageHeader.source.contact | | SHOULD | 0..1 | | +| MessageHeader.source.contact.system | This SHOULD be populated with the Contact Type - phone \| fax \| email \| pager \| url \| sms \| other | SHOULD | 0..1 | phone | +| MessageHeader.source.contact.value | This SHOULD be populated with the Contact Type value | SHOULD | 0..1 | +44 (0123) 123 4567 | +| MessageHeader.source.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows where any response messages SHOULD be addressed. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|5566778899 | +| MessageHeader.reason | | MUST | 0..1 | | +| MessageHeader.reason.coding | | MUST | 0..1 | | +| MessageHeader.reason.coding.system | This MUST be populated with 'https://fhir.nhs.uk/CodeSystem/message-reason-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-reason-bars | +| MessageHeader.reason.coding.code | This MUST be populated with "delete" for an cancellation. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' | MUST | 0..1 | delete | +| MessageHeader.reason.coding.display | This MUST be populated with 'Delete' when cancelling a Service Request. | SHOULD | 0..1 | Delete | +| MessageHeader.focus | | MUST | 0..* | | +| MessageHeader.focus.reference | This MUST be populated with a reference to the ServiceRequest | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| MessageHeader.definition | This MUST be populated with the MessageDefinition the bundle is based on. This will be used for validation. Value - https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-cancelled | MUST | 0..1 | https://fhir.nhs.uk/MessageDefinition/bars-message-servicerequest-request-cancelled | + + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Service Request</b></summary> + <p> + <p> A resource to carry a request for a service to be performed, in this case a Validation. This Resource is the focus of the Validation Request interaction.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-referral , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| ServiceRequest | A resource to carry a request for a service to be performed, in this case a Validation. This Resource is the focus of the Validation Request interaction https://simplifier.net/nhsbookingandreferrals/barsservicerequest-request-validation | | 1..1 | | +| ServiceRequest.id | MUST only be generated by the Receiver as the id for the resource in the synchronous HTTP response. | MUST | 0..1 | 236bb75d-90ef-461f-b71e-fde7f899802c | +| ServiceRequest.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| ServiceRequest.meta.profile | https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-validation | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSServiceRequest-request-validation | +| ServiceRequest.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.basedOn | | MUST | 0..* | | +| ServiceRequest.basedOnreference | This MUST be populated with a reference to the CarePlan resource | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| ServiceRequest.status | Only use the following 2 values, as appropriate: revoked is used when a SR is legitimately cancelled, entered-in-error is used when sent to the by mistake and needs to be removed. | MUST | 1..1 | entered-in-error | +| ServiceRequest.intent | This MUST be populated with 'plan' - Fixed Value | MUST | 1..1 | plan | +| ServiceRequest.category | | MUST | 0..1 | | +| ServiceRequest.category.coding | | MUST | 0..* | | +| ServiceRequest.category.coding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-category-servicerequest' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-category-servicerequest | +| ServiceRequest.category.coding.code | This MUST be populated with code value appropriate for the Application employed. | MUST | 0..1 | validation | +| ServiceRequest.category.coding.display | This MUST be populated with display value appropriate for the Application employed. | MUST | 0..1 | For Validation | +| ServiceRequest.subject | Follow BaRS profile guidance for populating this element | MUST | 1..1 | | +| ServiceRequest.subjectreference | This MUST be populated with a Reference to the Patient resource | MUST | 0..1 | urn:uuid:9589fb37-87a2-48d8-968f-b371429208a8 | +| ServiceRequest.encounter | | MUST | 0..1 | | +| ServiceRequest.encounter.reference | This MUST be populated with a Reference to the Encounter | MUST | 0..1 | urn:uuid:8c63d621-4d86-4f57-8699-e8e22d49935d | +| ServiceRequest.occurrencePeriod | Validation Breach time | MUST | 0..1 | | +| ServiceRequest.occurrencePeriod.start | The start of the period must be ‘now’. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.occurrencePeriod.end | The time by which the validation must be complete (validation breach time) | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| ServiceRequest.reasonCode | This will ONLY be populated in a cancellation message with the reason for cancellation | SHOULD | 0..* | | +| ServiceRequest.reasonCode.text | This SHOULD be populated. This will ONLY be populated in a cancellation message with the reason for cancellation and SHOULD only be used in conjunction with a corresponding status - revoked or entered-in-error | SHOULD | 0..1 | Revoked as patient has been dealt with. | + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Patient</b></summary> + <p>This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Patient | This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.<br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-patient | | 1..1 | | +| Patient.id | If this value was included in the synchronous response to the original request, it MUST be populated in subsequent requests. | MUST | 0..1 | 9589fb37-87a2-48d8-968f-b371429208a8 | +| Patient.meta | https://simplifier.net/hl7fhirukcorer4/ukcore-patient | MUST | 1..1 | | +| Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | +| Patient.meta.LastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | +| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | +| Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | +| Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding.system | https://simplifier.net/hl7fhirukcorer4/extensionukcorenhsnumberverificationstatus | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept.coding.code | Follow UK Core guidance for populating this element | SHOULD | 0..1 | number-present-and-verified | +| Patient.identifier.extension.valueCodeableConcept.coding.display | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Number present and verified | +| Patient.name | | SHOULD | 0..* | | +| Patient.name.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | official | +| Patient.name.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs Julie Jones | +| Patient.name.family | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jones | +| Patient.name.given | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Julie | +| Patient.name.prefix | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs | +| Patient.gender | Follow UK Core guidance for populating this element | SHOULD | 0..1 | female | +| Patient.birthDate | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 1959-05-04 | +| Patient.address | Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.address.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | home | +| Patient.address.type | Follow UK Core guidance for populating this element | SHOULD | 0..1 | both | +| Patient.address.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 22 Brightside Crescent, Overtown, West Yorkshire, LS10 4YU | +| Patient.address.line | Follow UK Core guidance for populating this element | SHOULD | 0..* | 22 Brightside Crescent | +| Patient.address.city | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Overtown | +| Patient.address.district | Follow UK Core guidance for populating this element | SHOULD | 0..1 | West Yorkshire | +| Patient.address.postalCode | Follow UK Core guidance for populating this element | SHOULD | 0..1 | LS10 4YU | +| Patient.contact | This should be used to record telecom information for the patient and/or the patient's representative for the encounter | MUST | 0..* | | +| Patient.contact.extension | | MUST | 0..* | | +| Patient.contact.extension.url | This MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactRank' - FIXED VALUE | MUST | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference | +| Patient.contact.extension.urlvaluePositiveInt | This MUST be populated with the rank of the whole contact and MUST be populated with the value '1' for the primary person to contact for referral. There MUST be at least one contact for the referral. | MUST | 0..1 | 1 | +| Patient.contact.relationship | | MUST | 0..* | | +| Patient.contact.relationship.coding | | MUST | 0..* | | +| Patient.contact.relationship.coding.system | This MUST be populated with the CodeSystem from the ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'.<br>Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.<br>Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.<br>If the relationship is not known this SHOULD be populated with the value 'Unknown' | MUST | 0..1 | http://terminology.hl7.org/CodeSystem/v2-0131 | +| Patient.contact.relationship.coding.code | This MUST be populated with Code of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.relationship.coding.display | This MUST be populated with Display of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.name | | SHOULD | 0..1 | | +| Patient.contact.name.family | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Grayson | +| Patient.contact.name.given | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jack | +| Patient.contact.telecom | | MUST | 0..* | | +| Patient.contact.telecom.system | This MUST be populated for the rank 1 contact. There MUST be at least one contact phone number for the referral | MUST | 0..1 | phone | +| Patient.contact.telecom.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | 0789 1234567 | +| Patient.contact.gender | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | male | +| Patient.Communication | | SHOULD | 0..* | | +| Patient.Communication.Language | | MUST | 1..1 | | +| Patient.Communication.Language.coding | | MUST | 1..1 | | +| Patient.Communication.Language.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | en | +| Patient.Communication.Language.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage | +| Patient.Communication.Language.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | English | +| Patient.Communication.Language.preferred | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | TRUE | +| Patient.extension | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.extension.url | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | A | +| Patient.extension.url.valueCodeableConcept.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | British, Mixed British | +| Patient.generalPractitioner | This SHOULD be populated with a reference to the GP Surgery ONLY rather than a specific practitioner | SHOULD | 0..* | | +| Patient.generalPractitioner.reference | This SHOULD be populated. Where populated this MUST reference to an Organisation resource | SHOULD | 0..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4411 | + + + +</details> +<p> + +<details> + <summary>> <b class="barslink">Organization</b></summary> + <p>This resource is used to communicate details about the sender and receiver organisations.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Organization | This resource is used to communicate details about the sender organisations. <br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-organization | | 2..* | | +| Organization.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 5d897313-c62d-4e7e-92b7-b2199804fed3 | +| Organization.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Organization.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +| Organization.meta.lastUpdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Organization.identifier | This MUST be populated with an organisation identifier e.g. ODS code | MUST | 0..* | | +| Organization.identifier.system | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | https://fhir.nhs.uk/id/ods-organization-code | +| Organization.identifier.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | ABD01 | +| Organization.name | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | Organisation name | + + + +</details> +<p> +<br> + +### Entity Relationship Diagram - Cancellation Referral Request + +<br> +<br> +The below diagram details the Cancellation Referral Request +<br> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMap9sToCASCancellationRequest-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapCancellationReferralRequest-1.1.0.svg" width="1200"></img></a> +<br> +<br> +<hr> + +## Cancellation Booking Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.3.0, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used. + +When cancelling a booking, in conjunction with the guidance provided under the Standard Patterns, the three important elements which drive workflow **must** be used as follows: +* **eventCoding** - this **must** be the same code as used in the request. +* **reasonCode** - a cancellation follows an initial request, therefore, this **must** always be 'update' for cancellation. +* **definition** - cancellation has a unique [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the request **must** adhere to. +* **focus** - **must** point to the *Appointment* resource. + +### Appointment Resource +The 'focus' resource in a cancellation booking request is the Appointment resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail. + +When a Receiver processes the cancellation booking request, the two key elements used are the *Appointment.id* and *Appointment.status*. The *.id* **must** already exist as a 'booked' (status) booking on the Receiver system (this **must** have been confirmed by a prior read (GET) by the Sender) and the *.status*, in the request, **must** be 'cancelled'. No other status is valid in the cancellation booking request. + +### Patient Resource +Key patient demographics **should** be cross-referenced between the current 'booked' (status) booking and incoming cancellation booking request to ensure validity. + +## Payload for Booking Cancellation Request + +This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Booking. + +<br> + <div markdown="span" class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> + <b>Please expand each resource below to view implementation guidance.</b> + </div> +<br> + +<details> + <summary>> <b class="barslink">Bundle</b></summary> + <p> + + <p>The Bundle resource is the container for the event message.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Bundle | The Bundle resource is the container for the event message  https://simplifier.net/nhsbookingandreferrals/barsbundlemessage | | 1..1 | | +| Bundle.id | This id is generated by the originating sender of the message, retained in subsequent messages.. | MUST | 1..1 | 79120f41-a431-4f08-bcc5-1e67006fcae0 | +| Bundle.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| Bundle.meta.profile | This MUST be populated with the structure definition for BaRSBundleMessage : 'https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage | +| Bundle.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.type | This must be populated with 'message' - FIXED VALUE | MUST | 1..1 | message | +| Bundle.timestamp | the date that the content of the message was assembled. This date is not changed by middleware engines unless they add additional data that changes the meaning of the time of the message | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Bundle.entry(s) | Follow BaRS profile guidance for populating this element | MUST | 1..* | | +| Bundle.entry.fullUrl | unique identifier for the resource entry. Transient id relative to the bundle | MUST | 0..1 | urn:uuid:1cbdfb97-5859-48a4-8301-d54eab818d68 | +| Bundle.entry.resourceType | Resources detailed in the message definition. | MUST | 0..1 | MessageHeader,Patient, Encounter | + +</details> +<p> +<details> + <summary>> <b class="barslink">Message Header</b></summary> + + <p> + + <p>A resource that describes the BaRS message being exchanged between two systems.</p> + {{tree:https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-servicerequest-request, hybrid}} + <p> + + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| MessageHeader | A resource that describes the BaRS message being exchanged between two systems https://simplifier.net/nhsbookingandreferrals/barsmessageheaderservicerequestrequest | | 1..1 | | +| MessageHeader.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 0..1 | | +| MessageHeader.meta.profile | This MUST be populated with the structure definition for BARSMessageHeader-booking-request | MUST | 0..1 | https://fhir.nhs.uk/StructureDefinition/BARSMessageHeader-booking-request | +| MessageHeader.meta.lastUpdated | All resources MUST include 'lastUpdated' value, under the meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates to resources, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 0..1 | 2023-03-08T12:01:08.4677672+00:00 | +| MessageHeader.eventcoding | | MUST | 1..1 | | +| MessageHeader.eventcoding.system | This MUST be populated with CodeSystem 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-events-bars | +| MessageHeader.eventcoding.code | The status MUST be populated with 'booking-request'. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' - FIXED VALUE | MUST | 0..1 | booking-request | +| MessageHeader.destination | | MUST | 0..1 | | +| MessageHeader.destination.receiver | | MUST | 0..1 | | +| MessageHeader.destination.receiver.reference | This MUST be populated with the full URL to the Receiving Organisation resource. | MUST | 0..1 | urn:uuid:10397afd-479c-42ea-9d5d-e4024481e0f8 | +| MessageHeader.destination.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows the intended destination. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|1122334455 | +| MessageHeader.sender | | MUST | 0..1 | | +| MessageHeader.sender.reference | This MUST be populated. Follow BaRS profile guidance for populating this element | MUST | 0..1 | urn:uuid:07939a0c-2854-46ff-9282-ad906bc93679 | +| MessageHeader.source | | MUST | 1..1 | | +| MessageHeader.source.name | This MUST be populated with the sending system supplier name | MUST | 0..1 | NHS Trust | +| MessageHeader.source.software | This SHOULD be populated with the sending software application name | SHOULD | 0..1 | Supplier Software | +| MessageHeader.source.version | This SHOULD be populated with the sending software version | SHOULD | 0..1 | V1.0.0 | +| MessageHeader.source.contact | | SHOULD | 0..1 | | +| MessageHeader.source.contact.system | This SHOULD be populated with the Contact Type - phone \| fax \| email \| pager \| url \| sms \| other | SHOULD | 0..1 | phone | +| MessageHeader.source.contact.value | This SHOULD be populated with the Contact Type value | SHOULD | 0..1 | +44 (0123) 123 4567 | +| MessageHeader.source.endpoint | This MUST be populated with the system and Service ID separated by a pipe. for example https://fhir.nhs.uk/id/dos-service-id\|11111111, this is to ensure the receiver knows where any response messages SHOULD be addressed. | MUST | 1..1 | https://fhir.nhs.uk/id/dos-service-id\|5566778899 | +| MessageHeader.reason | | MUST | 0..1 | | +| MessageHeader.reason.coding | | MUST | 0..1 | | +| MessageHeader.reason.coding.system | This MUST be populated with 'https://fhir.nhs.uk/CodeSystem/message-reason-bars' - FIXED VALUE | MUST | 0..1 | https://fhir.nhs.uk/CodeSystem/message-reason-bars | +| MessageHeader.reason.coding.code | This MUST be populated with "delete" for an cancellation. See CodeSystem: 'https://fhir.nhs.uk/CodeSystem/message-events-bars' | MUST | 0..1 | delete | +| MessageHeader.reason.coding.display | This MUST be populated with 'Delete' when cancelling a Booking. | SHOULD | 0..1 | Delete | +| MessageHeader.focus | | MUST | 0..* | | +| MessageHeader.focus.reference | This MUST be populated with a reference to the ServiceRequest | MUST | 0..1 | urn:uuid:236bb75d-90ef-461f-b71e-fde7f899802c | +| MessageHeader.definition | This MUST be populated with the MessageDefinition the bundle is based on. This will be used for validation. Value - hhttps://fhir.nhs.uk/MessageDefinition/bars-message-booking-request-cancelled | MUST | 0..1 | https://fhir.nhs.uk/MessageDefinition/bars-message-booking-request-cancelled | + + +</details> +<p> +<details> + <summary>> <b class="barslink">Appointment</b></summary> + + + + <p> + + <p>This resource will be used to communicate information about an Appointment and is the focus of the Booking interation.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Appointment | https://simplifier.net/hl7fhirukcorer4/ukcore-appointment <br><br>This resource will be used to communicate information about an appointment. | | 1..1 | | +| Appointment.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 3713c8fc-dbcf-4f90-bacf-89d99e434e9b | +| Appointment.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Appointment.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment | +| Appointment.meta.lastupdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Appointment.status | This MUST be populated with 'booked' | MUST | 1..1 | cencelled | +| Appointment.description | This SHOULD be populated. It is the human readable description of the booking | SHOULD | 0..1 | Reason for calling | +| Appointment.start | This MUST be populated with the Start time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | +| Appointment.end | This MUST be populated with the End time of the booking | MUST | 0..1 | 2021-10-12T12:30:00+00:00 | +| Appointment.slot | | MUST | 0..* | | +| Appointment.slot.reference | This MUST be populated with the local logical bundle reference to the Slot resource | MUST | 0..1 | urn:uuid:c3f6145e-1a26-4345-b3f2-dccbcba62049 | +| Appointment.created | This MUST only be populated with the date/time the booking was generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 2021-10-11T15:01:30+00:00" | +| Appointment.basedOn | This MAY be populated. When the Service Request is made before the booking in the workflow this MUST be populated. | MAY | 0..* | | +| Appointment.basedOn.reference | This MAY be populated. This is MUST be the relative reference to the Service Request when referral is made before booking in the workflow | MAY | 0..1 | ServiceRequest/236bb75d-90ef-461f-b71e-fde7f899802c | +| Appointment.participant | | MUST | 1..1 | | +| Appointment.participant.actor | This MUST be populated with reference to the patient | MUST | 0..1 | | +| Appointment.participant.actor.reference | This MUST be populated with the local logical bundle reference to the Patient resource | MUST | 0..1 | urn:uuid:3a62607b-df65-4932-940c-14262787f62d | +| Appointment.participant.actor.status | This MUST be populated with 'accepted' - FIXED VALUE | MUST | 1..1 | accepted | +</details> +<p> +<details> + <summary>> <b class="barslink">Patient</b></summary> + <p>This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient , hybrid}} + <p> + + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Patient | This resource is used to communicate details about the patient who is the subject of the referral.<br>It also includes contact information for third parties when required.<br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-patient | | 1..1 | | +| Patient.id | If this value was included in the synchronous response to the original request, it MUST be populated in subsequent requests. | MUST | 0..1 | 9589fb37-87a2-48d8-968f-b371429208a8 | +| Patient.meta | https://simplifier.net/hl7fhirukcorer4/ukcore-patient | MUST | 1..1 | | +| Patient.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Patient | +| Patient.meta.LastUpdated | All resources MUST include 'lastUpdated' value, under meta section which must be the same timestamp for each resource when created from new, but must be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Patient.identifier | This is a human readable patient identifier. This MUST be populated with the NHS number when available. Additionally a Local Patient Identifier Should be populated where available. If no NHS number is available this Should be populated with the Local patient identifier. | SHOULD | 0..* | | +| Patient.identifier.system | https://simplifier.net/hl7-fhir--uk-core-r4-stu1-sequence/ukcore-nhsnumberverificationstatus | SHOULD | 1..1 | https://fhir.nhs.uk/Id/nhs-number | +| Patient.identifier.value | This SHOULD be populated with a human readable patient identifier. When used this MUST be populated with the NHS number when available.If no NHS number is available this SHOULD be populated with the Local patient identifier. | SHOULD | 1..1 | 3478526985 | +| Patient.identifier.extension | This extension is used to record the NHS number Verification status | SHOULD | 0..* | | +| Patient.identifier.extension.url | This SHOULD be populated. Where used this MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus' - FIXED VALUE | SHOULD | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding | | SHOULD | 0..1 | | +| Patient.identifier.extension.valueCodeableConcept.coding.system | https://simplifier.net/hl7fhirukcorer4/extensionukcorenhsnumberverificationstatus | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus | +| Patient.identifier.extension.valueCodeableConcept.coding.code | Follow UK Core guidance for populating this element | SHOULD | 0..1 | number-present-and-verified | +| Patient.identifier.extension.valueCodeableConcept.coding.display | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Number present and verified | +| Patient.name | | SHOULD | 0..* | | +| Patient.name.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | official | +| Patient.name.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs Julie Jones | +| Patient.name.family | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jones | +| Patient.name.given | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Julie | +| Patient.name.prefix | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Mrs | +| Patient.gender | Follow UK Core guidance for populating this element | SHOULD | 0..1 | female | +| Patient.birthDate | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 1959-05-04 | +| Patient.address | Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.address.use | Follow UK Core guidance for populating this element | SHOULD | 0..1 | home | +| Patient.address.type | Follow UK Core guidance for populating this element | SHOULD | 0..1 | both | +| Patient.address.text | Follow UK Core guidance for populating this element | SHOULD | 0..1 | 22 Brightside Crescent, Overtown, West Yorkshire, LS10 4YU | +| Patient.address.line | Follow UK Core guidance for populating this element | SHOULD | 0..* | 22 Brightside Crescent | +| Patient.address.city | Follow UK Core guidance for populating this element | SHOULD | 0..1 | Overtown | +| Patient.address.district | Follow UK Core guidance for populating this element | SHOULD | 0..1 | West Yorkshire | +| Patient.address.postalCode | Follow UK Core guidance for populating this element | SHOULD | 0..1 | LS10 4YU | +| Patient.contact | This should be used to record telecom information for the patient and/or the patient's representative for the encounter | MUST | 0..* | | +| Patient.contact.extension | | MUST | 0..* | | +| Patient.contact.extension.url | This MUST be populated with Structure Definition 'https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactRank' - FIXED VALUE | MUST | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference | +| Patient.contact.extension.urlvaluePositiveInt | This MUST be populated with the rank of the whole contact and MUST be populated with the value '1' for the primary person to contact for referral. There MUST be at least one contact for the referral. | MUST | 0..1 | 1 | +| Patient.contact.relationship | | MUST | 0..* | | +| Patient.contact.relationship.coding | | MUST | 0..* | | +| Patient.contact.relationship.coding.system | This MUST be populated with the CodeSystem from the ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'.<br>Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.<br>Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.<br>If the relationship is not known this SHOULD be populated with the value 'Unknown' | MUST | 0..1 | http://terminology.hl7.org/CodeSystem/v2-0131 | +| Patient.contact.relationship.coding.code | This MUST be populated with Code of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.relationship.coding.display | This MUST be populated with Display of CodeSystem value. See ValueSet 'https://simplifier.net/hl7fhirukcorer4/valueset-ukcore-personrelationshiptype'. | MUST | 0..1 | EP | +| Patient.contact.name | | SHOULD | 0..1 | | +| Patient.contact.name.family | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Grayson | +| Patient.contact.name.given | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | Jack | +| Patient.contact.telecom | | MUST | 0..* | | +| Patient.contact.telecom.system | This MUST be populated for the rank 1 contact. There MUST be at least one contact phone number for the referral | MUST | 0..1 | phone | +| Patient.contact.telecom.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | 0789 1234567 | +| Patient.contact.gender | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | male | +| Patient.Communication | | SHOULD | 0..* | | +| Patient.Communication.Language | | MUST | 1..1 | | +| Patient.Communication.Language.coding | | MUST | 1..1 | | +| Patient.Communication.Language.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | en | +| Patient.Communication.Language.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage | +| Patient.Communication.Language.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | English | +| Patient.Communication.Language.preferred | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | TRUE | +| Patient.extension | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..* | | +| Patient.extension.url | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | | +| Patient.extension.url.valueCodeableConcept.coding.system | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | https://fhir.hl7.org.uk/CodeSystem/UKCore-EthnicCategory | +| Patient.extension.url.valueCodeableConcept.coding.code | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | A | +| Patient.extension.url.valueCodeableConcept.coding.display | This SHOULD be populated. Follow UK Core guidance for populating this element | SHOULD | 0..1 | British, Mixed British | +| Patient.generalPractitioner | This SHOULD be populated with a reference to the GP Surgery ONLY rather than a specific practitioner | SHOULD | 0..* | | +| Patient.generalPractitioner.reference | This SHOULD be populated. Where populated this MUST reference to an Organisation resource | SHOULD | 0..1 | urn:uuid:b83d13e2-8c2e-422c-88ac-63b8e86a4411 | + + + +</details> +<p> +<details> + <summary>> <b class="barslink">Organization</b></summary> + <p> This resource is used to communicate details about the sender and receiver organisations.</p> + {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization , hybrid}} + <p> + + + +| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) | +|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------| +| Organization | This resource is used to communicate details about the sender organisations. <br><br>https://simplifier.net/hl7fhirukcorer4/ukcore-organization | | 2..* | | +| Organization.id | This MUST only be populated with an id generated by the Receiver in the synchronous HTTP response. | MUST | 0..1 | 5d897313-c62d-4e7e-92b7-b2199804fed3 | +| Organization.meta | https://www.hl7.org/fhir/resource.html#Meta | MUST | 1..1 | | +| Organization.meta.profile | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 1..1 | https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +| Organization.meta.lastUpdated | This MUST be populated. All resources MUST include 'lastUpdated' value, under meta section which MUST be the same timestamp for each resource when created from new, but MUST be a later timestamp on updates, if the content of a particular resource contains updated info for subsequent updates. Otherwise, maintain the timestamp originally sent. | MUST | 1..1 | 2023-03-08T12:01:08.4677672+00:00 | +| Organization.identifier | This MUST be populated with an organisation identifier e.g. ODS code | MUST | 0..* | | +| Organization.identifier.system | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | https://fhir.nhs.uk/id/ods-organization-code | +| Organization.identifier.value | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | ABD01 | +| Organization.name | This MUST be populated. Follow UK Core guidance for populating this element | MUST | 0..1 | Organisation name | + +</details> +<p> + +<br> + +## Entity Relationship Diagram - Cancellation Booking Request + +<br> +<br> +The below diagram details the Cancellation Booking Request +<br> +<br> +<a href="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMap9sToCASCancellationRequest-1.0.0.svg" target="_blank"><img src="https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/EntityMaps/EntityMapCancellationBookingRequest-1.1.0.svg" width="1200"></img></a> +<br> +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Introduction.page.md new file mode 100644 index 00000000..8397b6a4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Introduction.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-StandardPattern-Introduction-1.3.0 +--- + +## Standard Pattern - Composite Messages + +Most implementations of the BaRS that are applying the standard to support a particular use case or operational workflow will follow the same basic set of foundational operations with little deviation. + +In order to establish a guarantee of compatibility between different solutions compliant with the standard, **all** implementations **must** support all the underlying foundational operations and patterns. + + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Message-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Message-Headers.page.md new file mode 100644 index 00000000..f5539cd5 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Message-Headers.page.md @@ -0,0 +1,47 @@ +--- +topic: core-SPMessageHeader-1.3.0 +--- + +# {{page-title}} + +## MessageHeader Resource +BaRS payloads (FHIR message bundles) require a **MessageHeader** FHIR resource which provides key information to drive workflow and start interpreting the data contained within. This resource is central to making a request or asynchronous response and **must** be present in all payloads. + +The **MessageHeader** resource contains the following element which **must** be used as outlined: +* **MessageHeader.source** - stipulates where the payload originated. The Sender **must**, under **MessageHeader.source.endpoint**, include a valid URI which could be used as a NHSD-Target-Identifier (their reference on the Endpoint Catalogue) for the Receiver to send an asynchronous response. +* **MessageHeader.destination** - designates who the payload is intended for, including reference to an Organisation resource and a valid URI (*MessageHeader.destination.endpoint*) which is the NHSD-Target-Identifier (their reference on the Endpoint Catalogue) the payload is being sent to. +* **MessageHeader.eventCoding** - determines the 'type' of payload, whether booking, referral, request or asynchronousus response. The value **must** be populated from this [CodeSystem](https://simplifier.net/NHSBookingandReferrals/message-events-bars). In referrals, this value, combined with the *ServiceRequest.category* element, allows supports for different styles of referral to support various use-cases. The value **must** be populated from CodeSystems for [specific type](https://simplifier.net/NHSDigital/message-category-servicerequest) and [use-case](https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). +* **MessageHeader.reason.code** - indicates whether the message is '**new**' or an '**update**' to something the Receiver is already aware of. The value **must** be populated from this [CodeSystem](https://simplifier.net/NHSBookingandReferrals/message-reason-bars). +* **MessageHeader.focus** - specifies the root resource through which to start interpreting the payload. +* **MessageHeader.definition** - cites the [MessageDefinition](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) the payload **must** adhere to and **must** be rejected by the Receiver if it fails to do so. Note: payload conformance to MessageDefinitions is not checked as part of FHIR validation. + +When a Receiver begins to process the payload, they **must** initially ensure it is for them and they know who it is from: +* check the **MessageHeader.destination** and verify the **MessageHeader.destination.receiver.reference** refers to their Organisation. +* check the **MessageHeader.destination.endpoint** is the Service ID they are expected to be processing the request on behalf of. +* Store **MessageHeader.source.endpoint** as NHSD-Target-Identifier to enable an asynchronous response back to the Sender. Not all workflows will require this type of response but this data must be stored for audit purposes. + +Certain elements in MessageHeader explicitly drive workflow, check **MessageHeader.eventCoding** to determine whether a booking or referral payload is being sent, and whether this is an initial or update request or an asynchronous response to a pre-existing request. There are various styles of referral too, a request could be made for a simple 'transfer of care' or, currently, something termed a 'validation', where one service requests another to validate the assessment outcome they have reached. The intention of supporting gradation of referral is to provide BaRS the malleability to support further subtlety of referrals for future use cases. Combining the **MessageHeader.eventCoding** with the **ServiceRequest.cateory** provides this functionality and, with the addition of {{pagelink:core-SPUseCaseCategories-1.3.0, text:use-case categories}} (again populated under **ServiceRequest.category**) specific services are pinpointed through every BaRS workflow. + +Once the above checks have been made, the detail of the payload can start to be unpacked and processed. The structure of the payload **must** be checked first to ensure it adheres to the **MessageHeader.definition** it claims to. The [MessageDefinitions](https://simplifier.net/nhsbookingandreferrals/~resources?category=Example&exampletype=MessageDefinition&sortBy=DisplayName) will principally be defined by BaRS, at a national level (although bespoke definitions can be used through BaRS), and the Receiver is checking to ensure all mandatory FHIR resources are present and meet their assigned cardinality. This is a manual, business logic, check and not something which is supported through standard FHIR validation of the payload (bundle). +Next, **MessageHeader.focus** is the root resource through which the payload is intended to be understood. In an initial referral request, this will typically be the **ServiceRequest** FHIR resource. This root will link to other resources to build a narrative for the payload, for example, the **ServiceRequest** will link to the **Encounter** which led to the referral being made and the **Careplan** detailing next actions. The Entity Relationship Diagrams (included in each {{pagelink:Home/Applications/BaRS-Applications/Applications, text:Application}}) are used as a visual representation of the FHIR resource links in the payloads. + +<br> +<br> + + +### Asynchronous Response Workflows + +For certain {{pagelink:Home/Applications/BaRS-Applications/Applications, text:Applications}}, an initial request by a Sender expects an asynchronous response (as opposed to an HTTP synchronous response (200) message). These responses are defined by the workflow of the Application and may be consistently returned or conditional. When an asynchronous response is initiated, the original Sender and Receiver roles are switched, the Sender becoming the Receiver and vice versa. This allows BaRS to support complex workflows through support for multiple requests (initial and update) and, potentially, multiple asynchronous responses, for example, an initial status update followed by a more detailed final outcome (as defined in {{pagelink:Home/Applications/BaRS-Applications/Applications/BaRS-APP4, text:Application 4}}). +The asynchronous response should be thought of as merely another payload, adhering to all the same rules as an initial request or update. Similarly, Sender and Receiver roles are intended to be interchangeable in BaRS and, in most BaRS Applications a supplier is expected to build both Sender and Receiver functionality, something which is reflected in the {{pagelink:Home/Assure/Assure, text:assurance process}}, especially {{pagelink:Home/Core, text:BaRS Core}}. + +Where the workflow dictates an asynchronous response is to be sent, the Sender (originally the Receiver) **must** populate: +* **MessageHeader.response.identifier** with the **Bundle.Id** of the original request payload and set the **MessageHeader.response.code** value to 'ok'. +* Additionally, they **must** follow the above guidance on populating the **MessageHeader**. + + + + + + + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md new file mode 100644 index 00000000..005bd6c2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md @@ -0,0 +1,312 @@ +--- +topic: core-SPComposites-1.3.0 +--- + +## {{page-title}} + +The majority of BaRS operations utilise a single standard approach. Since most BaRS operations involve composites of FHIR resources supporting a particular workflow they all utilise a single type of endpoint designed for processing and consuming of composite resources. This is the $process-message endpoint from the FHIR operations framework. The resource being transmitted in the body of the http request is a FHIR "Bundle" resource. This request payload needs to support two purposes, both the transmission of information as well as an indicator to direct the recieving system to how this particular bundle of resources is to be processed and what workflow should be triggered as a result of its consumption. + +These core functions are: + +* making a referral +* cancelling/amending a referral +* making a booking +* cancelling/amending a booking +* providing a response/feedback communication + +At the highest level this pattern follows the following key steps: + +* **Sender** GET the message definition for the payload/workflow being attempted +* **Sender** composes the bundle (as defined by the message definition) ready for POST-ing. +* **Sender** does a POST request to the **receiver**s' /$process-message endpoint. +* **Receiver** inspects the request header and the bundle MessageHeader resource for the *core workflow variables* indicating how to process and consume the bundle. +* **Receiver** send http response message back to the **sender**. + +Below is a pseudo code example, showing the above process in detail, illustrating how a message could be interpreted using core workflow variables for a message sent to POST /$process-message. + +Each Application will have a tailored example of the below pseudo code. + +<details><summary>> <b class="barslink">Click here to show example</b></summary> + +```c# +Receive_Request +{ + initialise_variable "messageType" + initialise_variable "MessageReason" + initialise_variable "RequestType" + + //HTTP_Headers + { + if (HttpHeaders is null || HttpHeaders not Guid ) + OperationOutcome.issue.code = "invalid" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if (HttpHeaders.RequestId == RequestId.AlreadyReceived) + OperationOutcome.issue.code = "duplicate" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + //Bundle + { + if(Bundle.meta.versionID is null) + OperationOutcome.issue.code = "invariant" + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400 + else if!(Bundle.meta.versionID in versionID.supported) + OperationOutcome.issue.code = "not-supported" + throw exception with "REC_UNPROCESSABLE_ENTITY" + then return with HTTP.ResponseCode 422 + } + //Contents; + { + switch(MessageHeader.eventCoding) + { + case "servicerequest-request": + if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active") + { + switch(ServiceRequest.Category) + { + case "Validation": + if (CarePlan.status != "active") + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + else if(Encounter.Status.In("triaged","in-progress") + {RequestType = "Im Receiving a new Validation Request";} + else + { + RequestType = "unknown"; + OperationOutcome.issue.code = "invariant";//A content validation rule failed + throw exception with "REC_BAD_REQUEST"; + then return HTTP.ResponseCode 400; + } + break; + case "Referral": + if (Careplan.status != "completed") + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + else if(Encounter.Status.In("triaged","finished")) + RequestType = "Im Receiving a new Referral" + else + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if (MessageHeader.reason.code == "update") + { + switch(ServiceRequest.category) + { + case "Validation": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled validation request";} + else if(ServiceRequest.status.In("active","on-hold")) + {RequestType = "im receiving an update to a validation request";} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + case "Referral": + if(ServiceRequest.status.In("entered-in-error","revoked")) + {RequestType = "im receiving a cancelled referral"} + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400 + } + break; + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + + } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400} + break; + case "servicerequest-response": + if (MessageHeader.Response is null ) + { + RequestType = "Invalid servicerequest-response" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + else if ( !Message.Response.identifier.existsLocally()) + { + RequestType = "none or invalid response ID" + OperationOutcome.issue.code = "not-found"//A content validation rule failed + throw exception with "REC_NOT_FOUND" + then return HTTP.ResponseCode 404; + } + switch (ServiceRequest.Category) + { + case "Referral": + if (ServiceRequest.status == "revoked" && MessageHeader.reason.code == "new") + { RequestType = "im receiving a Safeguarding DNA response (noshow)" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + break; + case "Validation": + if(!AnyEncounter.Originates.Local && Encount.Count()<=3) + { + if (MessageHeader.Reason.code == "new" && ServiceRequest.status == "active" && MessageHeader.FocusEncounter.status=="in-progress") + {Request Type = "im receiving a Validation Response interim update" } + else if (MessageHeader.Reason.code.In ("new","update") && ServiceRequest.status == "completed" && MessageHeader.FocusEncounter.status.In("triaged","complete") + {Request Type = "im receiving a final Validation Response" } + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + } + else if(MessageHeader.FocusEncounter.status = "triaged" && ServiceRequest.status == "revoked" && MessageHeader.Reason.code.In("new","update")) + { RequestType = "im receiving a Rejected validation response" } // a new encounter here is an edge case. + else + { + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + default: + RequestType = "unknown" + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return HTTP.ResponseCode 400; + } + case "booking-request": + if (MessageHeader.Reason.code== "new" && Appointment.Status == "booked") + if(slot.IsFree()) + {RequestType = "Im Receiving a new booking.";} + else + { + OperationOutcome.issue.code = "conflict" + throw exception with "REC_CONFLICT" + then return with HTTP.ResponseCode 409 + } + else if (MessageHeader.Reason.code == "update") + MessageHeaderIsUpdate = true; + switch (Appointment.Status) + { + case "cancelled": + RequestType = "Im Receiving a booking cancellation." + break + case "entered-in-error": + RequestType = "Im Receiving a booking cancellation." + break + case "booked": + RequestType = "Im Receiving an update to a booking." + break + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + break; + } + else + { + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with "REC_BAD_REQUEST" + then return with HTTP.ResponseCode 400; + } + break; + case "booking-response": + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + default: + OperationOutcome.issue.code = "invariant"//A content validation rule failed + throw exception with 'REC_BAD_REQUEST' + then return with HTTP.ResponseCode 400 + break; + } + + } + //Submit + { + + if (Message == "update") + { + if (currentLocalData.LastUpdated > originaRequest.ReceivedDate) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + foreach (Entry in Bundle) + { + if (currentLocalData.Item.exists) + { + if (currentLocalData.LastUpdated > originaRequest.Received) + { + OperationOutcome.issue.code = "conflict" + throw exception with 'REC_CONFLICT' + then return with HTTP.ResponseCode 409 + break; + } + if(Entry.LastUpdated > currentLocalData.Item.meta.LastUpdated && Entry.fullUrl = currentLocalData.Item.fullUrl) + currentLocalData.Item = Entry.Item + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + else + ignore + } + else + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + } + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + else + { + foreach(Entry in Bundle) + { + Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated ) + Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated) + return HTTP.ResponseCode 200 'OK' + } + } + } +} +``` + +</details> + + +<br> +<hr> diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md new file mode 100644 index 00000000..02ca54ab --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md @@ -0,0 +1,39 @@ +--- +topic: core-SPUseCaseCategories-1.3.0 +--- + +# {{page-title}} + +## What are use case categories? + +Use case categories define the specific type of referral being requested. The type is categorised at the service level. A BaRS Application can support multiple use cases; a use case can only ever belong to one BaRS Application. For instance, in Application 6 there are three defined use cases: Out of Area, Mutual Aid and Call Assist. All of these use cases relate to referrals between Ambulance Service Trusts but the workflow, timeframes and responses are not universal across all three scenarios. + +The BaRS use case categories are defined in the BARS CodeSystem (https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). All BaRS compliant solutions must adopt use case categories. + +## How to use BaRS use case categories + +The use case category is used in the initial content negotiation phase: +* when a Sender makes a request for MessageDefinitions and the Receiver responds +* when the Sender makes a referral request to the Receiver + + +When a Sender makes a request for MessageDefinitions, the MessageDefinitions returned by the Receiver will contain a use case category code (from the use case categories code system) under Message.Definition.useContext.code. The Sender **must** read this field to verify the Receiver supports the use case workflow they require. The use case category code will also be included in: +* the Sender's service request under ServiceRequest.category +* the Sender’s booking request under Appointment.ServiceCategory + +If this is not a use case supported by the Receiver, they will respond with an error (Operation Outcome). + +The sequence of events occurs as follows: +* the Sender requests the MessageDefinitions +* the Receiver indicates the use-case categories they support +* the Sender reads and only engages in the use-case workflows supported +* the Sender's request includes the use-case category code (the same code they read from the MessageDefinition), under ServiceRequest.category (referral) or Appointment.ServiceCategory (booking) +* the Receiver processes accordingly + + + + + + + + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/index.page.md new file mode 100644 index 00000000..aef8ca69 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/index.page.md @@ -0,0 +1,3 @@ +--- +topic: Core-StandardPattern-1.3.0 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml new file mode 100644 index 00000000..66f49100 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml @@ -0,0 +1,12 @@ +- name: index + filename: index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Standard Pattern For Composites + filename: Standard-Pattern-For-Composites.page.md +- name: Message Headers + filename: Message-Headers.page.md +- name: Cancellation + filename: Cancellation.page.md +- name: Use Case Categories + filename: Use-Case-Categories.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Definition-of-a-retry.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Definition-of-a-retry.page.md new file mode 100644 index 00000000..71386daa --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Definition-of-a-retry.page.md @@ -0,0 +1,14 @@ +--- +topic: Core-TransactionalIntegrity-RetryDefinition-1.3.0 +--- + +## Definition of a retry + +In this context a retry is an attempt to send the same message, without any changes following a failure. This means: + +- the Message body is the same +- the X-Request-ID and X-Correlation-ID are unchanged +- no other header items have changed. (with the potential exemption of the Access Token) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Failure-Scenarios.page.md new file mode 100644 index 00000000..03ec974d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Failure-Scenarios.page.md @@ -0,0 +1,422 @@ +--- +topic: core-TIFailureScenarios-1.3.0 +--- + +## Failure Scenarios + +When a message is received, the X-Request-ID and X-Correlation-ID header values are stored appropriately. In this example, this occurs ahead of the message being processed but after any access control is applied by means of the other available headers. + +If a message fails due to a message with the same header ids having already been processed, the response must be a 409, REC_CONFLICT with an OperationOutcome.issue.code of 'duplicate' as seen below. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-1.0.0.svg) + +<br> + +### 401 Outcome + +<json> + +      { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "security", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_UNAUTHORIZED" + +             "display": "401 - REC_UNAUTHORIZED"         + +           } + +         ] + +       }, + +       "diagnostics": "Details of the Exact problem" + +     } + +   ] + + }    + +</json> + +### 409 Outcome + +<json> + +         { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + }     + +</json> + +In the event of a timeout, a retry attempt is made after a suitable amount of time to ensure the message was received. The same X-Request-ID and X-Correlation-ID must be used. Should a 409 REC_CONFLICT response be received with a OperationOutcome.issue.code of "duplicate", then this can be used as confirmation that the message was received. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Timeout-Failure-Scenario-1.0.0.svg) + + +### 408 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "timeout", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TIMEOUT" + +             "display": "408 - REC_TIMEOUT"         + +           } + +         ] + +       }, + +       "diagnostics": "The connection for this request has timed out." + +     } + +   ] + + } + +</json> + +### 409 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + } + +</json> + +If the processing of a message is not completed prior to the initial retry, the receiver must respond with a 425 REC_TOO_EARLY response, to indicate the initial message is still processing. The receipt is then unconfirmed and the sender can retry after a suitable amount of time until they receive a desired response. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-solution-1.0.0.svg) + + +### 408 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "531e073a-3295-4e67-ae90-e00bd96a9cdd", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "timeout", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TIMEOUT" + +             "display": "408 - REC_TIMEOUT"         + +           } + +         ] + +       }, + +       "diagnostics": "The connection for this request has timed out." + +     } + +   ] + + } + +</json> + +### 425 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "98ae13af-3bc7-8cc5-4ac7-ea4f14d47dc9", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_TOO_EARLY" + +             "display": "425 - REC_TOO_EARLY"         + +           } + +         ] + +       }, + +       "diagnostics": "The Server has not finished processing the previous attempted request." + +     } + +   ] + + } + +</json> + +### 409 Outcome + +<json> + + { + +   "resourceType": "OperationOutcome", + +   "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8", + +   "meta": { + +     "profile": [ + +       "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome" + +     ] + +   }, + +   "issue": [ + +     { + +       "severity": "error", + +       "code": "duplicate", + +       "details": { + +         "coding": [ + +           { + +             "system": "https://fhir.nhs.uk/Codesystem/http-error-codes", + +             "code": "REC_CONFLICT" + +             "display": "409 - REC_CONFLICT"         + +           } + +         ] + +       }, + +       "diagnostics": "This message has already been received and processed" + +     } + +   ] + + } + +</json> + +The scenarios above describe the response where a message is successful. If a message is not successfully processed following a timeout, the receiver should respond with the response that that failure would have generated. In the diagram below the final response inherits its response from the message that has failed after the timeout. + +The relevant 4xx or 5xx response is what the sender receives as a response, ensuring the correct reason for a failure is communicated. + + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Post-409-FailureScenario-2-1.0.0.svg) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Feedback--response--requests.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Feedback--response--requests.page.md new file mode 100644 index 00000000..0e11698e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Feedback--response--requests.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Feedback-1.3.0 +--- + +## Feedback (response) requests + +In the event of feedback (a response), for example, a Safeguarding/DNA message; the receiver (becoming the sender effectively) sends a request to the initial sender with a new X-Request-ID and the same X-Correlation-ID as the original request. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Feedback-Request-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Index.page.md new file mode 100644 index 00000000..1636851a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: Core-TransactionalIntegrity-1.3.0 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Initial-Request.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Initial-Request.page.md new file mode 100644 index 00000000..5b00bc63 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Initial-Request.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Initial-1.3.0 +--- + +## Initial Request + +The X-Correlation-ID is a conversation ID for this Encounter or Case. In our initial request both IDs are supplied by the original sender. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-Request-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Introduction.page.md new file mode 100644 index 00000000..f5c13d94 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Introduction.page.md @@ -0,0 +1,26 @@ +--- +topic: Core-TransactionalIntegrity-Introduction-1.3.0 +--- + +## Transactional Integrity + +Transactional integrity is employed to ensure data integrity is maintained between two parties. It helps ensure that the success or failure of a message is known and can be confirmed. + +There are two existing header items for requests currently available to allow BaRS to meet transactional integrity requirements. They are listed below with their intended uses. The [BaRS API specification](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_0_0) contains example values for these entries. + +| Header | Requirement | Description | Value | +|------------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| X-Correlation-ID | Required | A globally unique identifier for the request that can be used to track related transactions across multiple systems. | string representing a GUID | +| X-Request-ID | Required | A globally unique identifier for the request, used to de-duplicate repeated requests and to trace the request for support purposes if needed. | string representing a GUID | + +Transactional integrity is based on guidance in the [FHIR standard](https://www.hl7.org/fhir/http.html#custom). The header items are used as outlined below: + +- the sender will generate both IDs at the beginning of a request for a message. +- the receiver will respond to this initial message, echoing back both IDs. The receiving server does not need to generate a new ID. +- any feedback requests from receiver to the initial sender shall use a new X-Request-ID but retain the X-Correlation-ID. This will be as a new message of the same conversation. +- any subsequent updates from the sender to the receiver shall use a X-Request-ID but will retain the original X-Correlation-ID. This will be as a new message of the same conversation. +- any onward referrals of a message will use a new X-Request-ID but retain the X-Correlation-ID +- a receiver of any message will not accept two messages with the same request and X-Correlation-IDs + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Onwards-Referrals.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Onwards-Referrals.page.md new file mode 100644 index 00000000..12ffbce8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Onwards-Referrals.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Onward-1.3.0 +--- + +## Onward Referrals + +The X-Correlation-ID is retained in all interactions. This is beneficial for logging and auditing as using the X-Correlation-ID you can see all interactions for this encounter. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Onward-Referral-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Receiver-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Receiver-responsibilities.page.md new file mode 100644 index 00000000..4581f414 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Receiver-responsibilities.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-TransactionalIntegrity-Receiver-1.3.0 +--- + +## Receiver responsibilities + +- return the X-Request-ID and X-Correlation-ID in responses at ALL times, where possible +- reject any message with no X-Request-ID and X-Correlation-ID, without exception with REC_BAD_REQUEST (400) +- in the event that a duplicate message that has already been correctly processed is received, return a response with REC_CONFLICT (409) and an operationOutcome.issue.code of "duplicate" +- this combination of codes can only be used in a duplicate message scenario + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Retry-Scenario.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Retry-Scenario.page.md new file mode 100644 index 00000000..df321078 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Retry-Scenario.page.md @@ -0,0 +1,20 @@ +--- +topic: Core-TransactionalIntegrity-RetryScenario-1.3.0 +--- + +## Retry scenario + +Should a request fail for any reason and the sender not receive a response (in any of the above scenarios) the sender is to retry the request, retaining the same X-Request-ID and X-Correlation-ID as the initial attempt. This allows the receiver to identify whether it has already processed this message or not. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Retry-Scenario-1.0.0.svg) + + +This satisfies the need to be able to handle transaction integrity, and for the most part auditing/logging. There are two more scenarios that need to be clarified: + +- onwards referrals +- sending a booking and referral + +The proposal is to retain the X-Correlation-ID for two separate and distinct messages concerning the same encounter or case. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sender-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sender-responsibilities.page.md new file mode 100644 index 00000000..e2bcd046 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sender-responsibilities.page.md @@ -0,0 +1,30 @@ +--- +topic: Core-TransactionalIntegrity-Sender-1.3.0 +--- + +## Sender responsibilities + +The frequency of retries and the duration of a retry period depends on the scenario and should not disrupt workflow. Exponential backoff is considered best practice however it is at the discretion of the sender to define how many times a retry is attempted. + +- retry in the event X-Request-ID and X-Correlation-ID is not in the response +- retry in the event no OperationOutcome is in the body of the response +- retry when an OperationOutcome from a receiver contains one of the following values and response codes: + - REC_TIMEOUT (408) + - REC_TOO_MANY_REQUESTS (429) + - REC_UNAVAILABLE (503) +-retry when an OperationOutcome from BaRS itself contains one of the following: + - PROXY_TIMEOUT / TIMEOUT (504 indicating 408 internally) + - PROXY_TOO_MANY_REQUESTS / TOO_MANY_REQUESTS (500 indicating a 408 internally) + - PROXY_UNAVAILABLE / UNAVAILABLE (503) +- retry when an OperationOutcome from the BaRS API contains one of the following: + - SEND_TOO_MANY_REQUESTS (429) + - SEND_FORBIDDEN (403), on the assumption the access token issue is resolved +- it is then at the senders discretion as to whether they update other properties of the message accordingly +- do not retry a request again if a response with the following attributes is received, this indicates the message was successfully sent + - REC_CONFLICT (409) + - an operationOutcome.issue.code of "duplicate" + +Any intermediary network device responding 'on behalf or in lieu' of the API or the receiver is not likely to respond with an OperationalOutcome or the required X-Request-ID and X-Correlation-ID. Any response not having either one of these properties can be safely deemed a communications failure, a temporary interruption to connectivity or could potentially indicate a service outage. Any of these scenarios could, but not always, warrant an retry. This would be at the discretion of the suppliers however these failed interactions should be logged with as much detail as possible. Errors outside of the HTTP standard should also be logged locally with as much detail as possible, for example; Transport-Layer error messages. + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sending-an-update.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sending-an-update.page.md new file mode 100644 index 00000000..593640ba --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/Sending-an-update.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Update-1.3.0 +--- + +## Sending an update + +For an update or subsequent message, a new X-Request-ID is generated, therefore allowing the receiver to accept the new message. The X-Correlation-ID remains unchanged to indicate it is part of the same conversation. + +![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Sending-An-Update-1.0.0.svg) + +<br> +<hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/toc.yaml new file mode 100644 index 00000000..659624ab --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Transactional-integrity/toc.yaml @@ -0,0 +1,22 @@ +- name: Index + filename: Index.page.md +- name: Introduction + filename: Introduction.page.md +- name: Initial Request + filename: Initial-Request.page.md +- name: Sending an update + filename: Sending-an-update.page.md +- name: Feedback (response) requests + filename: Feedback--response--requests.page.md +- name: Retry Scenario + filename: Retry-Scenario.page.md +- name: Onwards Referrals + filename: Onwards-Referrals.page.md +- name: Definition of a retry + filename: Definition-of-a-retry.page.md +- name: Receiver responsibilities + filename: Receiver-responsibilities.page.md +- name: Sender responsibilities + filename: Sender-responsibilities.page.md +- name: Failure Scenarios + filename: Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/toc.yaml new file mode 100644 index 00000000..1e31e4e5 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/toc.yaml @@ -0,0 +1,44 @@ +- name: Index + filename: Index.page.md +- name: + filename: End-to-end-workflow +- name: + filename: Core-Functionality-Requirements +- name: + filename: BaRS-FHIR-Usage +- name: + filename: Security-and-Authorisation +- name: + filename: Error-Handling +- name: + filename: Transactional-integrity +- name: + filename: Non-Functional-Requirements +- name: + filename: Standard-Pattern-Composite-Messages +- name: + filename: DocumentReference-StandardPattern +- name: + filename: EndpointCatalogue-StandardPattern +- name: + filename: Appointment-StandardPattern +- name: Core functionality requirements + filename: Core-functionality-requirements.page.md +- name: BaRS FHIR usage + filename: BaRS-FHIR-usage.page.md +- name: Journey ID + filename: Journey-ID.page.md +- name: LastUpdatedDate + filename: LastUpdatedDate.page.md +- name: How to handle times + filename: How-to-handle-times.page.md +- name: Security and authorisation + filename: Security-and-authorisation.page.md +- name: Error handling + filename: Error-Handling.page.md +- name: Transactional integrity + filename: Transactional-integrity.page.md +- name: Non functional requirements + filename: Non-functional-requirements.page.md +- name: Standard Pattern for BaRS Operations + filename: Standard-Pattern-for-BaRS-Operations.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md index 08f43b05..f4d05b71 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md @@ -12,14 +12,10 @@ Each current and available version of Core can be found below. <hr> -{{pagelink:design-core-1.0.6, text:1.0.6}} +{{pagelink:design-core-1.0.7, text:1.0.7}} <hr> -{{pagelink:design-core-1.1.6, text:1.1.6}} - -<hr> - -{{pagelink:design-core-1.2.2, text:1.2.2-alpha (Pre-Release)}} +{{pagelink:design-core-1.3.0, text:1.3.0}} <hr> \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml index 5bbc57cd..5a6bf454 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml @@ -1,8 +1,6 @@ - name: Index filename: Index.page.md -- name: 1.0.6 - filename: 1.0.6 -- name: 1.1.6 - filename: 1.1.6 -- name: 1.2.2 - filename: 1.2.2 \ No newline at end of file +- name: 1.0.7 + filename: 1.0.7 +- name: 1.3.0 + filename: 1.3.0 \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/ReportanIncident.guide.md b/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/ReportanIncident.guide.md new file mode 100644 index 00000000..a1c4d063 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/ReportanIncident.guide.md @@ -0,0 +1,21 @@ +## Report an incident + + +If you are using BaRS in a live environment, then follow the guidance below if you experience a service issue. + +1. Follow your existing support processes with your system supplier +2. If investigations indicate a BaRS Proxy or third-party supplier issue then raise an incident with the National Services Desk. + +### How to contact the National Service Desk + +Email: ssd.nationalservicedesk@nhs.net + +Telephone: 0300 303 5035 + +Online portal: NHS England Customer Portal + +Suppliers can also raise an incident directly from [My developer Hub](https://identity.prod.api.platform.nhs.uk/realms/developer-identity/protocol/openid-connect/auth?client_id=digital-onboarding-service&redirect_uri=https%3A%2F%2Fonboarding.prod.api.platform.nhs.uk%2Fsignin-oidc&response_type=code&scope=openid%20profile&code_challenge=ZUU7cuXAVdAVUUZvKtObefolzxuC13z5K_2DGUdB2yA&code_challenge_method=S256&response_mode=form_post&nonce=638853383078309811.NTIwNDc5MTYtMTlhYy00NmQ3LWIzZWQtODkzODFhODMwNTY1OWQ1MzI1NjgtMTExNy00YTBmLTk3ZjktOGVhNjQ4OWU1YmM2&state=CfDJ8KIg-PX7cpFGqswXYg36_armJbSeBql_hqVXgTDXWUpX8dF__le75Swm8zeNMfwh2D1WLPocxe3LIEZkRx5Ztapv97rTAml6GhesJyJmSNfr16q3jsnNAm_JMFsYF6HnfGSuU35oZTIeFONXgzuxDduXYFyE888OeKoWAD9QUqwdMEpTo1GttkMcGHkBnIqE-KUUnY7cPZClkq4BHqE1B0GmAaH5ieLExlfAwm7xDHcjlgVnKIVKPr7Ofx7W2-GIFBhNES1hNkcTMDtOauOU_lDjemQmd3J-DRkvjW0GD2bieS2SV403nhvdHYPxds7G9fYiv7r8A8C4J_jIA2dfO1suyvAmLWDGm0x1cqDBbizhLo58pWULuK_CEE3Ru3qPypw-pfcyZf1S3rL-YnITOF6pA85VBkuGfTeR9pi602Vi7PICi0jXkx28dfsXxUzB5qtIF2InkIGjCWt455dwU7LntcVQkSmUKLYRFIZgHxm_&x-client-SKU=ID_NETSTANDARD2_0&x-client-ver=6.10.0.0) on the Digital Onboarding Platform. + +### National Service Status (HSCN connection needed) + +View the [status of all our services and sign up for national service updates](https://nww.digital.nhs.uk/servicemanagement/status/) \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/toc.yaml index 6861a5e3..af611472 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Helpandsupport/toc.yaml @@ -6,3 +6,5 @@ filename: Glossary.guide.md - name: Downloads filename: Downloads.guide.md +- name: ReportanIncident + filename: ReportanIncident.guide.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md b/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md index 4d28c58f..a73be532 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md @@ -8,9 +8,9 @@ For more information on the NHS England programme delivering the standard please You can use this guide to support your analysis and define the scope of your solution. However, as a developer, you may wish to start with the following: * {{pagelink:about_bars, text:About BaRS and quick start guide}} -* {{pagelink:design-core-1.1.6, text:End to end workflow }} +* {{pagelink:design-core-1.3.0, text:End to end workflow }} * {{pagelink:Home/Applications/BaRS-Applications, text:BaRS Applications}} -* {{pagelink:core-StandardPattern-appointment-1.2.2, text:Standard Appointment Management (use-case agnostic)}} +* {{pagelink:core-StandardPattern-appointment-1.3.0, text:Standard Appointment Management (use-case agnostic)}} * {{pagelink:build-testing, text:Tooling}} <br> @@ -19,13 +19,13 @@ You can use this guide to support your analysis and define the scope of your sol The guide is divided into a number of sections: * {{pagelink:about_bars}} provides essential background and guiding principles along with prerequisites -* {{pagelink:design-core-1.1.6, text:BaRS Core}} provides a core set of functionality across version of Core +* {{pagelink:design-core-1.3.0, text:BaRS Core}} provides a core set of functionality across version of Core * {{pagelink:Home/Applications/BaRS-Applications,text:BaRS Application summaries}} provides links to implementation guides for released BaRS applications * {{pagelink:build-testing}} provides information about testing and environments * {{pagelink:assure}} describes guidance for the assurance process * {{pagelink:deploy}} provides the deployment toolkit * {{pagelink:fhir_assets}}, a link to the complete directory of FHIR assets * {{pagelink:help}} provides a link to support requests - +* {{pagelink:ReportanIncident}} describes how to report a live service incident for suppliers and providers live with BaRS diff --git a/guides/Live-ImplementationGuide-BaRS/guide.yaml b/guides/Live-ImplementationGuide-BaRS/guide.yaml index eff97ae8..26fbc05c 100644 --- a/guides/Live-ImplementationGuide-BaRS/guide.yaml +++ b/guides/Live-ImplementationGuide-BaRS/guide.yaml @@ -1,5 +1,5 @@ title: NHS Booking and Referral Standard description: FHIR Implementation Guide for the NHS Booking and Referral Standard -version: 1.8.2 +version: 1.9.0 style-root: project style-name: NHSD diff --git a/guides/Live-ImplementationGuide-BaRS/styles/NHSD/master.html b/guides/Live-ImplementationGuide-BaRS/styles/NHSD/master.html index 9bbbbbf3..ea4b707a 100644 --- a/guides/Live-ImplementationGuide-BaRS/styles/NHSD/master.html +++ b/guides/Live-ImplementationGuide-BaRS/styles/NHSD/master.html @@ -147,7 +147,7 @@ data-uipath="document.title"> {{guide-title}} </h1> - <div class="nhsd-t-body" data-uipath="document.summary">Guide v{{ guide-version }} | Core v1.1.6 | <a href="https://simplifier.net/packages/uk.nhsdigital.bars.r4/1.35.0" target="_blank">Package v1.35.0</a></div> + <div class="nhsd-t-body" data-uipath="document.summary">Guide v{{ guide-version }} | Core v1.3.0 | <a href="https://simplifier.net/packages/uk.nhsdigital.bars.r4/1.36.0" target="_blank">Package v1.36.0</a></div> </div> </div> </div>