### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
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 760d6734..a7bd39f7 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.4.1, text:standard pattern for BaRS Composite Messages}}. +Making a referral for this Application follows the {{pagelink:core-standardpattern-1.5.0, text:standard pattern for BaRS Composite Messages}}. 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 =
### Error Handling -* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}} +* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional -* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}} +* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
\ 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 11da3c80..e6ed1f05 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.4.1, text:standard pattern for BaRS Composite Messages}}. +Making a referral for this application follows the {{pagelink:Core-StandardPattern-1.5.0, text:standard pattern for BaRS Composite Messages}}. The Message Definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}}
@@ -102,7 +102,7 @@ X-Correlation-Id =
@@ -142,7 +142,7 @@ X-Correlation-Id =
@@ -249,7 +249,7 @@ X-Correlation-Id =
@@ -194,7 +194,7 @@ X-Correlation-Id =
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/Index.page.md
index e4a060b9..cf06ff63 100644
--- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/Index.page.md
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/Index.page.md
@@ -24,7 +24,7 @@ topic: Application8
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 f082c06f..72442d03 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
@@ -56,15 +56,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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the referral was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the referral was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the referral was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the update was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the update was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the update was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
* The referral Receiver **must** store all previous versions of the referral
* The referral Receiver **must not** 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
@@ -73,8 +73,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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the cancellation was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the cancellation was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the cancellation was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
* The referral Receiver **must** store all previous versions of the referral
* The referral Receiver **must not** 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
@@ -106,11 +106,11 @@ The payloads and workflow have been designed to support these services. Other {{
### Error Handling
-* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}}
+* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional
-* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}}
+* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
\ 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 82459aa9..24afbfce 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.4.1, text:standard pattern for BaRS Composite Messages}}.
+Making a Validation Request for this application follows the {{pagelink:core-standardpattern-1.5.0, text:standard pattern for BaRS Composite Messages}}.
The Message Definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Validation}}
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 425dfe64..dfae27f3 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
@@ -17,7 +17,7 @@ For Interim Validation Response example bundles see:
### MessageHeader Resource
-For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.4.1, text:Standard Pattern - Message Header}}.
+For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.5.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'
@@ -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.4.1, text:Standard Pattern - Message Header}} for more information.
+For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.5.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'
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 463baf39..2fa8a629 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
@@ -79,14 +79,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 not successful, the Responder **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail
-* Where the Validation Request was not successful, the Requester **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail
+* Where the Validation Request was not successful, the Responder **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail
+* Where the Validation Request was not successful, the Requester **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.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.4.1, 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.5.0, text:failure scenarios}} for more detail
* The Responder **must** store all previous versions of the Validation Request
* The Requester **must not** 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
@@ -147,11 +147,11 @@ For this application we will be referring to the actors as 'Requester' and the '
### Error Handling
-* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}}
+* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional
-* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}}
+* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
\ No newline at end of file
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 8030c845..c1d8399c 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
@@ -175,7 +175,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.4.1, text:standard pattern for BaRS Composite Messages}}.
+Making a referral for this application follows the {{pagelink:core-standardpattern-1.5.0, text:standard pattern for BaRS Composite Messages}}.
The Message Definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}}
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 233e8d11..817317bf 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:
### MessageHeader Resource
-For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.4.1, text:Standard Pattern - Message Header}}.
+For detailed information on the use of MessageHeader please refer to the {{pagelink:core-SPMessageHeader-1.5.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.4.1, 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.5.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/Scope-and-Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP6/Scope-and-Requirements.page.md
index 9878c5bd..f355cfd5 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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the referral was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail
+* Where the referral was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the referral was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the update was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the update was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the update was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
* The referral Receiver **must** store all previous versions of the referral
* The referral Receiver **must not** 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 not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the cancellation was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the cancellation was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the cancellation was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
* The referral Receiver **must** store all previous versions of the referral
* The referral Receiver **must not** 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 {{
### Error Handling
-* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}}
+* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional
-* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}}
+* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
\ No newline at end of file
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 64d8f443..ce99e3ee 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 = 
-To cancel a booking this Application follows the {{pagelink:core-SPCancellation-1.4.1, text:standard pattern for BaRS cancellation}}.
+To cancel a booking this Application follows the {{pagelink:core-SPCancellation-1.5.0, text:standard pattern for BaRS cancellation}}.
The Message Definition that defines the 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/Payloads.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP7/Payloads.page.md
index eeb46550..ecd81e0e 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.4.1, text:Standard Patterns for BaRS Operations}} explains in detail how the **MessageHeader** resource **must** be used.
+{{pagelink:core-SPMessageHeader-1.5.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 ac43f79e..5829bb5a 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 not** include it in the request
-* Where the booking was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
-* Where the booking was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.4.1, text:failure scenarios}} for more detail.
+* Where the booking was not successful, the Receiver **must** send an appropriate response. See {{pagelink:core-failure_scenarios-1.5.0, text:failure scenarios}} for more detail.
+* Where the booking was not successful, the Sender **must** present an appropriate message to the end user. See {{pagelink:core-failure_scenarios-1.5.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 **not** 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 {{
### Error Handling
-* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.4.1, text:error handling guidance}}
+* Suppliers **must** adhere to the {{pagelink:core-ErrorHandling-1.5.0, text:error handling guidance}}
### Non Functional
-* Suppliers **must** adhere to the {{pagelink:core-NFR-1.4.1, text:non functional requirements}}
+* Suppliers **must** adhere to the {{pagelink:core-NFR-1.5.0, text:non functional requirements}}
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/How-does-it-work.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/How-does-it-work.page.md
index 1cb93d3f..fe2a5642 100644
--- a/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/How-does-it-work.page.md
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Applications/BaRS-Applications/Applications/BaRS-APP8/How-does-it-work.page.md
@@ -34,7 +34,7 @@ Directing the referral request will still engage the same BaRS mechanisms; utili
### Make a Referral
-Making a referral for this application follows the {{pagelink:core-standardpattern-1.4.1, text:standard pattern for BaRS Composite Messages}}.
+Making a referral for this application follows the {{pagelink:core-standardpattern-1.5.0, text:standard pattern for BaRS Composite Messages}}.
The Message Definition that defines this payload for this application is: {{link:MessageDefinition-BARS-MessageDefinition-ServiceRequest-Request-Referral}}
Application 8 v1.0.0-alpha.3
v1.1.x
v1.12.0
- v1.5.x
+ v1.5.x
111 Online - ED
111 Online - UTC
S&R - ED
S&R - UTC
| 2.0.0 | v1.0.0 | v1.0.0 | | {{pagelink:application3, text: Referral into UEC (Application 3)}} |
999-CAS Referral
| 2.0.0 | v1.0.0 | v1.0.0 |
| {{pagelink:application4, text: Referral into UEC for Validation (Application 4)}} |
999-CAS Validation
999 AST to Falls Lifting Service
999 AST to Community Services
| 2.0.0 | v1.0.0 | v1.0.0 |
-| {{pagelink:application5, text: Referrals into Pharmacy (Application 5)}} |
Primary Care to Community Pharmacy (Pharmacy First)
Primary Care to Pharmacy Contraception (Oral Contraception)
Primary Care to Pharmacy Blood Pressure Check Service
| 1.2.0 | v1.3.0 | {{pagelink:design-core-1.4.1, text:v1.3.0}} |
+| {{pagelink:application5, text: Referrals into Pharmacy (Application 5)}} |
Primary Care to Community Pharmacy (Pharmacy First)
Primary Care to Pharmacy Contraception (Oral Contraception)
Primary Care to Pharmacy Blood Pressure Check Service
| 1.2.0 | v1.3.0 | {{pagelink:design-core-1.5.0, text:v1.3.0}} |
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 03ed1020..72139818 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.4.1, 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.5.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 16ff7d5a..45131ff7 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.4.1, 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.5.0, text:Headers}} | Name | Value | example | diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Cancel-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Cancel-Booking.page.md new file mode 100644 index 00000000..c82654ba --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Cancel-Booking.page.md @@ -0,0 +1,113 @@ +--- +topic: core-StandardPattern-appointment-cancel-1.5.0 +--- + +### Cancel + +Cancellation is documented for completeness. The technical functionality for cancellation mirrors that of {{pagelink:core-StandardPattern-appointment-update-1.5.0, text:Update}} booking. + +Steps to cancel: + +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) operation using the .id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the {{pagelink:core-StandardPattern-document-reference-Sender-1.5.0, text: Document Reference Standard Pattern - Sender}}. NB: If a match cannot be obtained using this method the process of updating must be performed manually +* Set the Appointment.status value to "cancelled". NB - It is also permissible to update .reasonCode in the request but no other element +* Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} +* Once processed, the Receiver of the booking must [DELETE](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#delete-/DocumentReference/-id-) the pointer in the central Registry, as described in {{pagelink:core-StandardPattern-document-reference-Receiver-1.5.0, text: Document Reference Standard Pattern - Receiver}} + +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" + } + ] +} +``` + +
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Index.page.md
new file mode 100644
index 00000000..fa2a014a
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Index.page.md
@@ -0,0 +1,3 @@
+---
+topic: core-StandardPattern-appointment-1.5.0
+---
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Initial-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Initial-Booking.page.md
new file mode 100644
index 00000000..b24ac6a6
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Initial-Booking.page.md
@@ -0,0 +1,56 @@
+---
+topic: core-StandardPattern-appointment-booking-1.5.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, as outlined below.
+
+### Book
+Making an initial booking through Appointment Management Foundation, outside of the prescribed BaRS Applications, must follow the workflow outlined using the discete [booking endpoints](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#post-/Appointment).
+
+If undertaking a booking within the context of an Application, the guidance stated there takes precedence over this documentation. NB: BaRS Applications are likely to utilise the [$process-message](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#post-/$process-message) endpoint (contact BaRS Team for guidance on use outside of the published Applications - 
\ No newline at end of file
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Introduction.page.md
new file mode 100644
index 00000000..d3fbc665
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Introduction.page.md
@@ -0,0 +1,50 @@
+---
+topic: core-StandardPattern-appointment-Introduction-1.5.0
+---
+
+# Standard Pattern - Appointments
+
+This Section of the Implementation Guide is currently a preview, in an Alpha state and subject to change. Only Internal NHSE programmes are currently permitted to build against this release. If you are interested in building against this documentation, please, contact the BaRS Team
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Reschedule-Existing-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Reschedule-Existing-Booking.page.md
new file mode 100644
index 00000000..f700ffd7
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Reschedule-Existing-Booking.page.md
@@ -0,0 +1,94 @@
+---
+topic: core-StandardPattern-appointment-reschedule-1.5.0
+---
+
+### Reschedule
+
+The Reschedule operation supports amending the slot a booking is made against. The slot is the only element capable of being changed as part of the reschedule operation, if either the .status or .reasonCode require amendment, the {{pagelink:core-StandardPattern-appointment-update-1.5.0, text:Update}} operation can be followed, otherwise, the {{pagelink:core-StandardPattern-appointment-rebook-1.5.0, text:Rebook}} operation.
+
+Steps to Reschedule:
+
+* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) operation using the .id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the {{pagelink:core-StandardPattern-document-reference-Sender-1.5.0, text: Document Reference Standard Pattern - Sender}}. NB: If a match cannot be obtained using this method the process of updating must be performed manually
+* [Request Available slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Slot) from the service
+* Select a new slot
+* Update the resource with the new slot. NB: Only the .slot element of the resource must be updated
+* Perform a [PATCH](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#patch-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}
+* Once processed, the Receiver of the booking must [update (PUT)](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#put-/DocumentReference/-id-) the pointer in the central Registry, as described in {{pagelink:core-StandardPattern-document-reference-Receiver-1.5.0, text: Document Reference Standard Pattern - Receiver}}. The principal update to the pointer is to change the .context element to alter the slot time -
+
+```json
+"context": {
+ "period": {
+ "start": "2025-02-12T12:30:30+00:00",
+ "end": "2025-02-12T12:40:30+00:00"
+ }
+}
+```
+
+
+In this example the Appointment resource is with the existing slot, and updated with the newly selected slot.
+
+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/265a53d7-1d21-4fc6-a5b7-761f650e75eb"
+ }
+ ],
+ "description": "Reason for calling",
+ "start": "2025-02-12T10:00:30+00:00",
+ "end": "2025-02-12T10:10: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-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": "2025-02-12T12:30:30+00:00",
+ "end": "2025-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"
+ }
+ ]
+}
+```
+
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Update-Existing-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Update-Existing-Booking.page.md
new file mode 100644
index 00000000..b7be212a
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/Update-Existing-Booking.page.md
@@ -0,0 +1,92 @@
+---
+topic: core-StandardPattern-appointment-update-1.5.0
+---
+
+### Update
+
+Steps to update:
+
+* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) operation using the .id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, a search of the Registry can be undertaken following the {{pagelink:core-StandardPattern-document-reference-Sender-1.5.0, text: Document Reference Standard Pattern - Sender}}. NB: If a match cannot be obtained using this method the process of updating must be performed manually
+* Update the Appointment resource as required. There is only currently support to alter .status and .reasonCode. NB: The .slot element of the resource must not be updated, if an alternative slot is required either the {{pagelink:core-StandardPattern-appointment-reschedule-1.5.0, text:Reschedule}} or {{pagelink:core-StandardPattern-appointment-rebook-1.5.0, text:Rebook}} processes must be followed
+* Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.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",
+ "reasonCode": [
+ {
+ "coding": [
+ {
+ "system": "http://snomed.info/sct",
+ "code": "165342003",
+ "display": "Patient declined laboratory test (situation)"
+ }
+ ]
+ }
+ ],
+ "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",
+ "reasonCode": [
+ {
+ "coding": [
+ {
+ "system": "http://snomed.info/sct",
+ "code": "165332000",
+ "display": "Laboratory test requested (situation)"
+ }
+ ]
+ }
+ ],
+ "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"
+ }
+ ]
+}
+```
+
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/toc.yaml
new file mode 100644
index 00000000..4c87031c
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Appointment-StandardPattern/toc.yaml
@@ -0,0 +1,14 @@
+- 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: Reschedule a Booking
+ filename: Reschedule-Existing-Booking.page.md
+- name: Rebook Methods
+ filename: Rebook-Methods.page.md
\ No newline at end of file
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Bundle.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Bundle.page.md
new file mode 100644
index 00000000..31c88410
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Bundle.page.md
@@ -0,0 +1,14 @@
+---
+topic: core-FHIRUsage-bundle-1.5.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.
+
++
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md new file mode 100644 index 00000000..d89cd1e6 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/FHIR-Operations-Framework.page.md @@ -0,0 +1,13 @@ +--- +topic: core-FHIRUsage-FHIR-Operations-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Frameworks.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Frameworks.page.md new file mode 100644 index 00000000..543e427e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Frameworks.page.md @@ -0,0 +1,10 @@ +--- +topic: core-FHIRUsage-Framework-1.5.0 +--- + +## Frameworks + +A mix of data exchange frameworks are employed by BaRS to support different workflows. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/How-to-handle-times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/How-to-handle-times.page.md new file mode 100644 index 00000000..01e07837 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/How-to-handle-times.page.md @@ -0,0 +1,18 @@ +--- +topic: core-FHIRUsage-Time-1.5.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) + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Journey-ID.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Journey-ID.page.md new file mode 100644 index 00000000..a2b81d22 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/Journey-ID.page.md @@ -0,0 +1,25 @@ +--- +topic: core-FHIRUsage-JourneyID-1.5.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 +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/LastUpdatedDate.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/LastUpdatedDate.page.md new file mode 100644 index 00000000..5efb2c20 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/LastUpdatedDate.page.md @@ -0,0 +1,17 @@ +--- +topic: core-FHIRUsage-LastUpdated-1.5.0 +--- +## {{page-title}} + +Every resource will include a lastUpdated date in the meta tag. This is to be used for tracking and updating. + +```xml + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/REST.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/REST.page.md new file mode 100644 index 00000000..1d00a8ba --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/REST.page.md @@ -0,0 +1,16 @@ +--- +topic: core-FHIRUsage-REST-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/process-message.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/process-message.page.md new file mode 100644 index 00000000..7b84e5e2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/process-message.page.md @@ -0,0 +1,20 @@ +--- +topic: core-FHIRUsage-Process-Message-1.5.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.5.0, text: Standard Patterns}} for generic guidance for processing messages. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/BaRS-FHIR-Usage/toc.yaml new file mode 100644 index 00000000..cb7ee837 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/Core-Functionality-Requirements/All.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/All.page.md new file mode 100644 index 00000000..2ed88aa7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/All.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-All-1.5.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 + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Receiver.page.md new file mode 100644 index 00000000..28d55ea7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Receiver.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingReceiver-1.5.0 +--- + +### Booking Receiver + +- Provide Slots for a specific service +- Create Booking +- Cancel Booking +- Accept Rebook request (two open Bookings during this routine) + +
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Sender.page.md new file mode 100644 index 00000000..1ccfbe9e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Booking-Sender.page.md @@ -0,0 +1,12 @@ +--- +topic: core-FunctionalityRequirements-BookingSender-1.5.0 +--- + +### Booking Sender + +- Request Slots for a specific service +- Make Booking request +- Cancel Booking request +- Make Rebook request (two open Bookings during this routine) + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Caching.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Caching.page.md new file mode 100644 index 00000000..f9b82c5c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Caching.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-Caching-1.5.0 +--- + +### Caching + +- The local caching of retrieved metadata (Capability Statements and Message Definitions) requests is permitted to improve performance +- Caching of responses **must not** exceed 24 hours (12 hours is recommended) +- There **must** be a mechanism to manually clear the cache + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Index.page.md new file mode 100644 index 00000000..57fef0ea --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-FunctionalityRequirements-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Introduction.page.md new file mode 100644 index 00000000..305ad378 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Introduction.page.md @@ -0,0 +1,17 @@ +--- +topic: core-FunctionalityRequirements-Introduction-1.5.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: + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Receiver.page.md new file mode 100644 index 00000000..96e9a85e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Receiver.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralReceiver-1.5.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) + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Sender.page.md new file mode 100644 index 00000000..ee62d443 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/Referral-Sender.page.md @@ -0,0 +1,11 @@ +--- +topic: core-FunctionalityRequirements-ReferralSender-1.5.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) + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Core-Functionality-Requirements/toc.yaml new file mode 100644 index 00000000..31db240a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md new file mode 100644 index 00000000..af2497fc --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/DocumentReference-Interface.page.md @@ -0,0 +1,45 @@ +--- +topic: core-StandardPattern-document-reference-interface-1.5.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 existing 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
Query: custodian:identifier
Query: next-page-token
Query:type | N/A | BaRS & NRLF | BaRS: Request forwarded verbatim to NRLF Consumer Endpoint
NRLF: NRLF returns Bundle of DocumentReferences matching search criteria. | 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
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
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
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
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 ServiceRequest | 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-5-0/DocumentReference-StandardPattern/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Index.page.md new file mode 100644 index 00000000..555ee4e1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-StandardPattern-document-reference-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Introduction.page.md new file mode 100644 index 00000000..1504e6f2 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Introduction.page.md @@ -0,0 +1,21 @@ +--- +topic: core-StandardPattern-document-reference-Introduction-1.5.0 +--- + +# Standard Pattern - DocumentReference + +
This section of the Implementation Guide is currently a preview, in an Alpha state and subject to change. There is currently only support for Appointment (booking) pointers.
+
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Receiver-DocumentReference.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Receiver-DocumentReference.page.md
new file mode 100644
index 00000000..09c968b3
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Receiver-DocumentReference.page.md
@@ -0,0 +1,118 @@
+---
+topic: core-StandardPattern-document-reference-Receiver-1.5.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 (pointer) for a booking or referral resource on the central Registry. A DocumentReference will be created when a Receiver accepts a booking or referral. Each booking or referral request processed requires a distinct DocumentReference on the Registry.
+
+
+### Step 1: Identify the booking or referral to create a pointer for
+When a Receiver processes a request for a booking (Appointment) or referral (ServiceRequest), the next step in the workflow is to create a pointer for the newly created resource (Appointment or ServiceRequest) on the central Registry. This will be undertaken via a POST [DocumentReference](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#post-/DocumentReference) request to the BaRS Proxy.
+
+
+### Step 2: Set content of the DocumentReference (pointer)
+Create a new instance of the DocumentReference resource and populate the relevant fields. Key fields to include are as follows:
+
+**identifier:** The DocumentReference needs several identifiers which allow the booking or referral to be located at a Receiver service.
+
+The resource .id of the booking (Appointment) or referral (ServiceRequest) (created by the Receiver when processing the request) must be set in the 'value' element of an Identifier, clarified by the system '*https://fhir.nhs.uk/Id/BaRS-Identifier*'.
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/BaRS-Identifier",
+ "value": "8c63d621-4d86-4f57-8699-e8e22d49935d"
+ }
+```
+
+The second identifier of note is the Receiving service who own the resource. The 'system' indicates the Service Discovery tool and the 'value', the identifier. In the code snippet below, the system '*https://fhir.nhs.uk/Id/dos-service-id*' indicates the Receiver service is on the Urgent and Emergency Care Directory of Services (UEC DoS) as service 2000072491. The Sender of any request will use the 'system' and 'value' here to build the base64 encoded HTTP Header NHSD-Target-Identifier, as defined for the [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) or [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest/-id-).
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/dos-service-id",
+ "value": "2000072491"
+ }
+```
+
+The third identifier (currently optional) relates to the product-id, system '*https://fhir.nhs.uk/id/product-id*'. This is forthcoming functionality and further detail on its utility will follow but [working documentation] (https://github.com/NHSDigital/nhse-epr-integration/blob/main/pages/appendix1.md) is being actively updated.
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/product-id",
+ "value": "P.GH7-4TY"
+ }
+```
+
+**type:**, within the DocumentReference resource, indicates whether the pointer is for a booking or referral. BaRS currently only supports bookings (749001000000101) and referrals (736253002), described using SNOMED codes.
+
+```json
+"type": {
+ "coding": [
+ {
+ "system": "https://snomed.info/ict",
+ "code": "749001000000101"
+ }
+ ]
+}
+```
+
+**subject:** specifies the subject of the DocumentReference, which will be the patient associated with the Resource. The patient's NHS number must be used to identify them, as outlined below.
+
+```json
+"subject": {
+ "identifier": {
+ "system": "https://fhir.nhs.uk/Id/nhs-number",
+ "value": "9556274839"
+ }
+},
+```
+
+**custodian:** Set the author of the DocumentReference, which will be the ODS code for the organisation writing the DocumentReference resource entry.
+
+```json
+ "custodian": {
+ "identifier": {
+ "system": "https://fhir.nhs.uk/Id/ods-organization-code",
+ "value": "A1001"
+ }
+ }
+```
+
+**context:** MUST include a period set to the Appointment start and end times.
+
+```json
+"context": {
+ "period": {
+ "start": "2025-02-12T12:30:30+00:00",
+ "end": "2025-02-12T12:40:30+00:00"
+ }
+}
+```
+
+### Step 3: Save and Transmit the DocumentReference (pointer)
+Once all the necessary fields are populated, perform a [POST](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#post-/DocumentReference) of the DocumentReference 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). This can be used to reference or [retrieve](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/DocumentReference/-id-) the DocumentReference in the future.
+
+### Step 4: Verify the DocumentReference
+To ensure that the DocumentReference was created successfully, retrieve it using its [id](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/DocumentReference/-id-) or [search](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/DocumentReference) for it using relevant parameters. Make sure to validate the returned DocumentReference to confirm that all the contents are accurate.
+
+### Updating a DocumentReference
+A DocumentReference can be updated by performing a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#put-/DocumentReference/-id-) request with the updated resource to the /DocumentReference endpoint on the BaRS proxy with the appropriate DocumentReference.id. A read operation must be performed prior to this to ensure that the new DocumentReference is the most up to date.
+
+**Note**: A Receiver can only update DocumentReference resources that they created and own.
+
+### Delete a DocumentReference
+A DocumentReference can be removed by performing a [DELETE](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#delete-/DocumentReference/-id-) request to the /DocumentReference endpoint on the BaRS proxy with the appropriate DocumentReference.id. A read operation must be performed prior to this to ensure that the action is appropriate.
+
+**Note**: A Receiver can only delete DocumentReference resources they created and own.
+
+
+
+
+.
\ No newline at end of file
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Sender-DocumentReference.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Sender-DocumentReference.page.md
new file mode 100644
index 00000000..498dc427
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/Sender-DocumentReference.page.md
@@ -0,0 +1,120 @@
+---
+topic: core-StandardPattern-document-reference-Sender-1.5.0
+---
+
+# {{page-title}}
+
+### Step 1: Understand the Document Reference Resource
+The FHIR DocumentReference resource represents a reference to a clinical document or resource, in the case of BaRS a pointer to an active booking or referral. It contains metadata about the booking or referral, such as its type (booking or referral), author, and subject (the patient's NHS number), as well as a reference to the actual document's .id and where it resides (the service who owns it); the two key data points needed to retrieve it.
+
+### Step 2: Search for the booking or referral pointer (DocumentReference)
+FHIR DocumentReference resources holding pointers for BaRS bookings and referrals are stored in a central Registry, within NRL (National Record Locator), as decribed above, and interrogated through the [BaRS API DocumentReference](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/DocumentReference).
+
+To find a booking or referral location, you need to search for the appropriate DocumentReference resource from the Registry, using search parameters. It is mandatory to include the subject:identifier (the patient's NHS number). Other parameters can be used to filter the response further e.g type of document (booking and referral).
+
+### Step 3: Inspect the booking or referral pointer (DocumentReference)
+Once you retrieve the Document Reference(s) (pointers) from the search, inspect the returned resources to identify the one you need. Look for relevant metadata, as described below, to confirm the correct resource.
+
+**identifier:** The DocumentReference will have several identifiers which are required to locate the booking or referral at a Receiver service.
+
+The .id of the booking or referral is indicated by the system '*https://fhir.nhs.uk/Id/BaRS-Identifier*'. The value can be used to directly request the [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) or [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest/-id-) by .id, once you know Receiver service holding it (see next identifier).
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/BaRS-Identifier",
+ "value": "8c63d621-4d86-4f57-8699-e8e22d49935d"
+ }
+```
+
+The second identifier, required to make the subsequent request for the booking or referral in question, has a system of '*https://fhir.nhs.uk/Id/dos-service-id*' and enables the Sender to direct their request to the Receiver service which owns it. The Sender will use the system and value here to build the base64 encoded HTTP Header NHSD-Target-Identifier, as defined for the [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) or [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest/-id-).
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/dos-service-id",
+ "value": "2000072491"
+ }
+```
+
+The third identifier (currently optional) relates to the product-id, system '*https://fhir.nhs.uk/id/product-id*'. This is forthcoming functionality and further detail on its utility will follow but [working documentation] (https://github.com/NHSDigital/nhse-epr-integration/blob/main/pages/appendix1.md) is being actively updated.
+
+```json
+"identifier": [
+ {
+ "system": "https://fhir.nhs.uk/Id/product-id",
+ "value": "P.GH7-4TY"
+ }
+```
+
+**type:** within the DocumentReference Resource, indicates whether the pointer is for a booking or referral. BaRS currently only supports bookings (749001000000101) and referrals (736253002), described using SNOMED codes. This information is required to direct the subsequent request to the correct endpoint for the [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) or [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest/-id-)
+
+```json
+"type": {
+ "coding": [
+ {
+ "system": "https://snomed.info/ict",
+ "code": "749001000000101",
+ "display": "Appointment (record artifact)"
+ }
+ ]
+}
+```
+
+**subject:** The subject will describe the patient, by means of an NHS number. This element is not explicitly required to request the specific resource dictated by the pointer but could be used to search a service more widely for related [bookings](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment) and [referrals](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest), using the search by patient endpoints.
+
+```json
+"subject": {
+ "identifier": {
+ "system": "https://fhir.nhs.uk/Id/nhs-number",
+ "value": "9556274839"
+ }
+```
+
+**custodian:** The custodian element will describe the organisation 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"
+ }
+ }
+```
+
+**context:** includes a period set to the Appointment start and end times.
+
+```json
+"context": {
+ "period": {
+ "start": "2025-02-12T12:30:30+00:00",
+ "end": "2025-02-12T12:40:30+00:00"
+ }
+}
+```
+
+### Step 4: Retrieve the booking or referral
+The booking or referral resource can be retrieved by making a GET request for the [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/Appointment/-id-) or [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#get-/ServiceRequest/-id-).
+
+The two key values required to make the request are the first two identifiers in the DocumentReference; the resource .id ('*https://fhir.nhs.uk/Id/BaRS-Identifier*') and service id ('*https://fhir.nhs.uk/Id/dos-service-id*'). Use the resource .id populate the location of the request and service id to populate the NHSD-Target-Identifier HTTP Header, as described in the worked example below.
+
+For BaRS, a GET of the relevant resource using the Target Identifiers. In this simplified example, the identifier containing the service id is used in the NHSD-Target-Identifier header, instructing the BaRS proxy to route to the request to that target **note**: The header is not base64Encoded in this example:
+
+```
+cURL --location 'https://int.api.service.nhs.uk/booking-and-referral/FHIR/R4/Appointment/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' \
+```
+
+### Step 5: Handle the Retrieved booking or referral
+Once you have retrieved the booking or referral resource, it can be used in subsequent workflows. 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.
+
+
+
+
+.
+
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/toc.yaml
new file mode 100644
index 00000000..16ed5002
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/DocumentReference-StandardPattern/toc.yaml
@@ -0,0 +1,10 @@
+- name: Index
+ filename: Index.page.md
+- name: Introduction
+ filename: Introduction.page.md
+- name: DocumentReferences for Senders
+ filename: Sender-DocumentReference.page.md
+- name: DocumentReferences for Receivers
+ filename: Receiver-DocumentReference.page.md
+- name:
+ filename: DocumentReference-Interface.page.md
\ No newline at end of file
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Asynchronous-Workflow.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Asynchronous-Workflow.page.md
new file mode 100644
index 00000000..0f35a466
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Asynchronous-Workflow.page.md
@@ -0,0 +1,10 @@
+---
+topic: core-EndToEndWorkflow-AsyncWorkflow-1.5.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-5-0/End-to-end-workflow/Authenticate-with-BaRS.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Authenticate-with-BaRS.page.md
new file mode 100644
index 00000000..f86cd5f0
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Authenticate-with-BaRS.page.md
@@ -0,0 +1,11 @@
+---
+topic: core-EndToEndWorkflow-BaRSAuth-1.5.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.}}
+
++
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Authentication-and-Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Authentication-and-Authorisation.page.md new file mode 100644 index 00000000..c2e0871a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Authentication-and-Authorisation.page.md @@ -0,0 +1,15 @@ +--- +topic: core-EndToEndWorkflow-Auth-1.5.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 | + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/BaRS-FHIR-API.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/BaRS-FHIR-API.page.md new file mode 100644 index 00000000..0d46e794 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/BaRS-FHIR-API.page.md @@ -0,0 +1,14 @@ +--- +topic: core-EndToEndWorkflow-API-1.5.0 +--- + +## BaRS FHIR API + +The [BaRS FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.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.5.0). + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Header.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Header.page.md new file mode 100644 index 00000000..c4874758 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Header.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-HTTPHeader-1.5.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.5.0). + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Response-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Response-Headers.page.md new file mode 100644 index 00000000..c3bd9bb3 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/HTTP-Response-Headers.page.md @@ -0,0 +1,13 @@ +--- +topic: core-EndToEndWorkflow-HTTPResponseHeader-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Index.page.md new file mode 100644 index 00000000..d7e096d1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-EndToEndWorkflow-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Introduction.page.md new file mode 100644 index 00000000..ac4b0ce9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Introduction.page.md @@ -0,0 +1,22 @@ +--- +topic: core-EndToEndWorkflow-Introduction-1.5.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 + + +
+
++
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Logging.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Logging.page.md new file mode 100644 index 00000000..a290e642 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Logging.page.md @@ -0,0 +1,62 @@ +--- +topic: core-EndToEndWorkflow-Logging-1.5.0 +--- + +## {{page-title}} + +
+ +| 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: + +* Appointment.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 + +``` + Appointment.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} + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Processing-Requests.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Processing-Requests.page.md new file mode 100644 index 00000000..22f45c60 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Processing-Requests.page.md @@ -0,0 +1,24 @@ +--- +topic: core-EndToEndWorkflow-Processing-1.5.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.5.0, text: Standard Patterns}} for generic guidance for processing messages. + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Responses.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Responses.page.md new file mode 100644 index 00000000..dcd2fb65 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Responses.page.md @@ -0,0 +1,9 @@ +--- +topic: core-EndToEndWorkflow-Responses-1.5.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. + +
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Reversing-Roles.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Reversing-Roles.page.md new file mode 100644 index 00000000..a673ac59 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Reversing-Roles.page.md @@ -0,0 +1,10 @@ +--- +topic: core-EndToEndWorkflow-ReversingRoles-1.5.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). + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Routing.page.md new file mode 100644 index 00000000..3c707894 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Routing.page.md @@ -0,0 +1,13 @@ +--- +topic: core-EndToEndWorkflow-Routing-1.5.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 | + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Service-Discovery.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Service-Discovery.page.md new file mode 100644 index 00000000..9f850798 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/Service-Discovery.page.md @@ -0,0 +1,11 @@ +--- +topic: core-EndToEndWorkflow-ServiceDiscovery-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/toc.yaml new file mode 100644 index 00000000..7b6ddaf8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/End-to-end-workflow/transactional-Integrity.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/transactional-Integrity.page.md new file mode 100644 index 00000000..ca8d88ef --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/End-to-end-workflow/transactional-Integrity.page.md @@ -0,0 +1,21 @@ +--- +topic: core-EndToEndWorkflow-Transactional-Integrity-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Endpoint-Data.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Endpoint-Data.page.md new file mode 100644 index 00000000..ce2051b1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Endpoint-Data.page.md @@ -0,0 +1,255 @@ +--- +topic: core-StandardPattern-Endpoint-Data-1.5.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 + +
> Organization
++
This resource will describe either the Organisation of the Provider or the Organisation of the Supplier managing an Endpoint
+ {{tree:https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization, hybrid}} + + + +| 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 | + + + +
+
+ This Resource describes the healthcare service that the endpoint is serving.> HealthcareService
+
+
+ This resource describes the endpoint itself including data around how to interact with it > Endpoint
+
+
+## Entity Relationship Diagram
+
+
+
+## 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-5-0/EndpointCatalogue-StandardPattern/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Index.page.md
new file mode 100644
index 00000000..e5ecf2c5
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Index.page.md
@@ -0,0 +1,6 @@
+---
+topic: core-StandardPattern-Endpoints-1.5.0
+---
+
+
+.
\ No newline at end of file
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Interface.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Interface.page.md
new file mode 100644
index 00000000..4ab1051c
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/Interface.page.md
@@ -0,0 +1,329 @@
+---
+topic: core-StandardPattern-Endpoint-Interface-1.5.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.5.0) for Core 1.2.0 and above.
+
+## Request and Response
+
+
| Behaviour | +Initiator | +VERB | +API Path | +Parameters | +Payload | +Payload Definition | +Reactor | +Reactor Behaviour | +Happy Response | +Response Definition | +
|---|---|---|---|---|---|---|---|---|---|---|
| Get Capabilities | +Sender | +GET | +/metadata | +N/A | +N/A | +N/A | +Endpoint Catalogue | +Return a capability statement describing capabilities. | +200: CapabilityStatement | +https://www.hl7.org/fhir/capabilitystatement.html | +
| Get Endpoints | +Sender / Receiver / BaRS / Admin | +GET | +/Endpoint | +query: _has | +N/A | +N/A | +Endpoint Catalogue | +Return a searchset of Endpoints based on the properties of the parent given as a _has HealthcareService.Identifier or Id | +200: Search Bundle | +https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle searchset | +
| query: Endpoint.identifier | +N/A | +N/A | +Endpoint Catalogue | +Return a searchset of Endpoints based on the identifier of the Endpoint itself. this should only be one item. | +200: Search Bundle | +https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle searchset | +||||
| Get Endpoint | +Sender / Receiver / BaRS / Admin | +GET | +/Endpoint/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Return specific Endpoint based on id given. | +200: Endpoint | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | +
| Create Endpoint | +Receiver / Admin | +POST | +/Endpoint | +path: id | +Endpoint | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | +Endpoint Catalogue | +Store a new Endpoint based on id given. | +201: Endpoint | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | +
| Update Endpoint | +Receiver / Admin | +PUT | +/Endpoint/{id} | +path: id | +Endpoint | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | +Endpoint Catalogue | +Update an existing endpoint based on id given. | +200: Endpoint | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Endpoint | +
| Delete Endpoint | +Receiver / Admin | +DELETE | +/Endpoint/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Remove an existing endpoint based on id given | +200: OperationOutcome | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome | +
| Get Organisations | +Sender / Receiver / BaRS / Admin | +GET | +/Organisation? | +query: Organization.identifier | +N/A | +N/A | +Endpoint Catalogue | +Return a list of Organizations based on the identifier given | +200: Search Bundle | +https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle searchset | +
| Get Organisation | +Sender / Receiver / BaRS / Admin | +GET | +/Organisation/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Return a specific Endpoint based on the id given. | +200: Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Create Organisation | +Receiver / Admin | +POST | +/Organisation | +path: id | +Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +Endpoint Catalogue | +Store a new Organization based on the id given. | +201: Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Update Organisation | +Receiver / Admin | +PUT | +/Organisation/{id} | +path: id | +Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +Endpoint Catalogue | +Update an existing Organization based on the id given. | +200: Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Delete Organisation | +Receiver / Admin | +DELETE | +/Organisation/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Remove an existing Organization based on the id given. | +200: OperationOutcome | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome | +
| Get HealthcareService | +Sender / Receiver / BaRS / Admin | +GET | +/HealthcareService | +query: HealthcareService.identifier | +N/A | +N/A | +Endpoint Catalogue | +Return a list of HealthcareServices based on the identifier given | +200: Search Bundle | +https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle searchset | +
| query: HealthcareService.providedBy | +N/A | +N/A | +Endpoint Catalogue | +Return a list of HealthcareServices based on the identifier given | +200: Search Bundle | +https://simplifier.net/guide/NHSBookingandReferrals/UKCore-Bundle searchset | +||||
| Get HealthcareService | +Sender / Receiver / BaRS / Admin | +GET | +/HealthcareService/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Return a specific HealthcareServicesbased on the id given. | +200: HealthcareServices | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Create HealthcareService | +Receiver / Admin | +POST | +/HealthcareService | +path: id | +Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +Endpoint Catalogue | +Store a new HealthcareServicesbased on the id given. | +201: HealthcareServices | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Update HealthcareService | +Receiver / Admin | +PUT | +/HealthcareService/{id} | +path: id | +Organization | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +Endpoint Catalogue | +Update an existing HealthcareServicesbased on the id given. | +200: HealthcareServices | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-Organization | +
| Delete HealthcareService | +Receiver / Admin | +DELETE | +/HealthcareService/{id} | +path: id | +N/A | +N/A | +Endpoint Catalogue | +Remove an existing HealthcareServicesbased on the id given. | +200: OperationOutcome | +https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome | +
| API Path | +Type | +Parameter | +Format | +Purpose | +
|---|---|---|---|---|
| /Endpoint? | +query | +_has | +_has:HealthcareService.Identifier=https://fhir.nhs.uk/Id/dos-service-id|1000099999 | +An identifier for the HealthcareService to which Endpoints belong. in this example an id or DoS id. | +
| _has:HealthcareService.Id=95852b93-d1ab-4c51-8e7d-c24cf9b257a9 | +||||
| /Endpoint? | +query | +Endpoint.identifier | +The identifier of the type of Endpoint. This would be used to say if you want a BaRS endpoint or otherwise. |
+ |
| /Endpoint/{} | +path | +id | +GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91" | +The identifier of the endpoint. | +
| /HealthcareService/? | +query | +HealthcareService.identifier | +https://fhir.nhs.uk/Id/dos-service-id|1000099999 | +an identifier of the healthcareService, in this example, a DoS id. | +
| /HealthcareService/? | +query | +HealthcareService.providedBy | +https://fhir.nhs.uk/Id/ods-organization-code|A001 | +the owning organisations ODS code. | +
| /HealthcareService/{id} | +path | +id | +GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91" | +specific resource id of an HealthcareService. | +
| /Organisation? | +query | +Organization.identifier | +"A001" | +An identifier for the organization. in this example an ODS code. | +
| "https://fhir.nhs.uk/id/ods-organization-code|A001" | +||||
| /Organisation/{id} | +path | +id | +GUID/UUID - "c1ab3fba-6bae-4ba4-b257-5a87c44d4a91" | +specific resource id of an organization. | +
+ +This version of core is strictly a preview of what is currently in development for 1.5.0 and should not be built against. + +
| Core Version | +Minimum Guide Version | +Minimum API Spec Version | +
|---|---|---|
| v1.5.0 | +v1.12.0 | +v1.5.0 | +
+
+
+## Create
+
+Here a Receiving system is creating a resource related to an endpoint.
+
+
+
+
+## Update
+
+Here a Receiving system is updating a resource related to an endpoint.
+
+
+
+.
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/toc.yaml
new file mode 100644
index 00000000..8789f06f
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/EndpointCatalogue-StandardPattern/toc.yaml
@@ -0,0 +1,10 @@
+- name: Index
+ filename: Index.page.md
+- name: Introduction
+ filename: Introduction.page.md
+- name: Interface
+ filename: Interface.page.md
+- name: Endpoint Data
+ filename: Endpoint-Data.page.md
+- name: Sequences
+ filename: Sequences.page.md
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--receiving.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--receiving.page.md
new file mode 100644
index 00000000..68da2f24
--- /dev/null
+++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--receiving.page.md
@@ -0,0 +1,8 @@
+---
+topic: core-ErrorHandling-IntR-1.5.0
+---
+
+## {{page-title}}
+
++
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--sending.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--sending.page.md new file mode 100644 index 00000000..8f490e93 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/BaRS-interactions--sending.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-IntS-1.5.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: + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Diagnostics-Text.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Diagnostics-Text.page.md new file mode 100644 index 00000000..d8cc9186 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Diagnostics-Text.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-Diag-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Example-Errors.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Example-Errors.page.md new file mode 100644 index 00000000..b2564d0c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Example-Errors.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-Examples-1.5.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:
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Bundle-Processing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-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** + +  + + +| 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** + +  + +| 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** + +  + + + +| 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. + + +
> Click here to show example
+ +```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' + } + } + } +} +``` + +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.
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 | +| 408 | 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 | + +back \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Index.page.md new file mode 100644 index 00000000..a83ed198 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: core-failure_scenarios-1.5.0 +--- \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Introduction.page.md new file mode 100644 index 00000000..3390f6e1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Introduction.page.md @@ -0,0 +1,11 @@ +back + +## 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.5.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 OperationOutcome.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-5-0/Error-Handling/Failure-Scenarios-1-1-x/Message-Routing.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Message-Routing.page.md new file mode 100644 index 00000000..fb308120 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios-1-1-x/Message-Routing.page.md @@ -0,0 +1,63 @@ +--- +topic: Core-ErrorHandling-MessageRouting-1.5.0 +--- + +## Endpoint Catalogue - Message routing. + + + +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. + +  + +### 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-5-0/Error-Handling/Failure-Scenarios-1-1-x/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-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-5-0/Error-Handling/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios.page.md new file mode 100644 index 00000000..5ffa06f4 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Failure-Scenarios.page.md @@ -0,0 +1,7 @@ +--- +topic: core-EHFailureScenarios-1.5.0 +--- + +## Failure Scenarios + +For More Detail on error handling, there is specific information on failure scenarios available in the {{pagelink:core-failure_scenarios-1.5.0, text: Failure Scenarios}} section. \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Index.page.md new file mode 100644 index 00000000..4727479e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-ErrorHandling-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Introduction.page.md new file mode 100644 index 00000000..096cdf51 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-ErrorHandling-Introduction-1.5.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.5.0}} section in addition to information included on this page. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/OperationOutcome-Example.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/OperationOutcome-Example.page.md new file mode 100644 index 00000000..66527cfe --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/OperationOutcome-Example.page.md @@ -0,0 +1,61 @@ +--- +topic: core-ErrorHandling-OpOut-1.5.0 +--- + +### OperationOutcome Example + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Overview.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Overview.page.md new file mode 100644 index 00000000..d2f6075c --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Overview.page.md @@ -0,0 +1,21 @@ +--- +topic: core-ErrorHandling-Overview-1.5.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 | + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Receiver-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Receiver-Responsibilities.page.md new file mode 100644 index 00000000..65e78ea0 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Receiver-Responsibilities.page.md @@ -0,0 +1,22 @@ +--- +topic: core-ErrorHandling-RecResp-1.5.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 + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Sender-Responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Sender-Responsibilities.page.md new file mode 100644 index 00000000..08cd3454 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/Sender-Responsibilities.page.md @@ -0,0 +1,14 @@ +--- +topic: core-ErrorHandling-SendResp-1.5.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 + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/toc.yaml new file mode 100644 index 00000000..db958fbf --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Error-Handling/toc.yaml @@ -0,0 +1,24 @@ +- 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: Failure Scenarios + filename: Failure-Scenarios.page.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Index.page.md new file mode 100644 index 00000000..242e251f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Index.page.md @@ -0,0 +1,259 @@ +--- +topic: design-core-1.5.0 +--- +
+
| Core Version | +Minimum Guide Version | +Minimum API Spec Version | +
|---|---|---|
| v1.5.0 | +v1.12.0 | +v1.5.0 | +
> Expand for full Core directory
+ +• {{pagelink:design-core-1.5.0 , text: Core 1.5.0}} + • {{pagelink:core-EndToEndWorkflow-1.5.0 , text:End to end workflow}} + • {{pagelink:core-EndToEndWorkflow-ServiceDiscovery-1.5.0 , text:Service Discovery}} + • {{pagelink:core-EndToEndWorkflow-BaRSAuth-1.5.0 , text:Authenticate with BaRS}} + • {{pagelink:core-EndToEndWorkflow-API-1.5.0 , text:BaRS FHIR API}} + • {{pagelink:core-EndToEndWorkflow-HTTPHeader-1.5.0 , text:HTTP Header}} + • {{pagelink:core-EndToEndWorkflow-Routing-1.5.0 , text:Routing}} + • {{pagelink:core-EndToEndWorkflow-Auth-1.5.0 , text:Authentication and Authorisation}} + • {{pagelink:core-EndToEndWorkflow-Transactional-Integrity-1.5.0 , text:Transactional Integrity}} + • {{pagelink:core-EndToEndWorkflow-HTTPResponseHeader-1.5.0 , text:HTTP Response Headers}} + • {{pagelink:core-EndToEndWorkflow-Processing-1.5.0 , text:Processing Requests}} + • {{pagelink:core-EndToEndWorkflow-Responses-1.5.0 , text:Responses}} + • {{pagelink:core-EndToEndWorkflow-ReversingRoles-1.5.0 , text:Reversing Roles}} + • {{pagelink:core-EndToEndWorkflow-AsyncWorkflow-1.5.0 , text:Asynchronous Workflow}} + • {{pagelink:core-FunctionalityRequirements-1.5.0 , text:Core Functionality Requirements.}} + • {{pagelink:core-FunctionalityRequirements-All-1.5.0 , text:All}} + • {{pagelink:core-FunctionalityRequirements-Caching-1.5.0 , text:Caching}} + • {{pagelink:core-FunctionalityRequirements-BookingSender-1.5.0 , text:Booking Sender}} + • {{pagelink:core-FunctionalityRequirements-BookingReceiver-1.5.0 , text:Booking Receiver}} + • {{pagelink:core-FunctionalityRequirements-ReferralSender-1.5.0 , text:Referral Sender}} + • {{pagelink:core-FunctionalityRequirements-ReferralReceiver-1.5.0 , text:Referral Receiver}} + • {{pagelink:core-FHIRUsage-1.5.0 , text:BaRS FHIR Usage}} + • {{pagelink:core-FHIRUsage-Framework-1.5.0 , text:Frameworks}} + • {{pagelink:core-FHIRUsage-REST-1.5.0 , text:REST}} + • {{pagelink:core-FHIRUsage-FHIR-Operations-1.5.0 , text:FHIR Operations}} + • {{pagelink:core-FHIRUsage-Process-Message-1.5.0 , text:$process-message}} + • {{pagelink:core-FHIRUsage-bundle-1.5.0 , text:Bundle}} + • {{pagelink:core-FHIRUsage-JourneyID-1.5.0 , text:Journey ID}} + • {{pagelink:core-FHIRUsage-Time-1.5.0 , text:How to handle times}} + • {{pagelink:core-FHIRUsage-LastUpdated-1.5.0 , text:LastUpdatedDate}} + • {{pagelink:core-Security-1.5.0 , text:Security and Authorisation}} + • {{pagelink:core-Security-Sender-1.5.0 , text:Sender}} + • {{pagelink:core-Security-Oauth-1.5.0 , text:OAuth Endpoints}} + • {{pagelink:core-Security-Receiver-1.5.0 , text:Receiver}} + • {{pagelink:core-Security-Auth-1.5.0 , text:Authorisation}} + • {{pagelink:core-ErrorHandling-1.5.0 , text:Error Handling}} + • {{pagelink:core-ErrorHandling-Overview-1.5.0 , text:Overview}} + • {{pagelink:core-ErrorHandling-IntS-1.5.0 , text:BaRS interactions(sending)}} + • {{pagelink:core-ErrorHandling-OpOut-1.5.0 , text:OperationOutcome Example}} + • {{pagelink:core-ErrorHandling-Diag-1.5.0 , text:Diagnostic Text}} + • {{pagelink:core-ErrorHandling-Examples-1.5.0 , text:Example Errors}} + • {{pagelink:core-ErrorHandling-SendResp-1.5.0 , text:Sender Responsibilities}} + • {{pagelink:core-ErrorHandling-IntR-1.5.0 , text:BaRs interactions(receiving)}} + • {{pagelink:core-ErrorHandling-RecResp-1.5.0 , text:Receiver responsibilities}} + • {{pagelink:core-failure_scenarios-1.5.0 , text:Failure Scenarios}} + • {{pagelink:Core-TransactionalIntegrity-1.5.0 , text:Transactional Integrity}} + • {{pagelink:Core-TransactionalIntegrity-Initial-1.5.0 , text:Initial Request}} + • {{pagelink:Core-TransactionalIntegrity-Update-1.5.0 , text:Sending an update}} + • {{pagelink:Core-TransactionalIntegrity-Feedback-1.5.0 , text:Feedback (response) requests}} + • {{pagelink:Core-TransactionalIntegrity-RetryScenario-1.5.0 , text:Retry Scenario}} + • {{pagelink:Core-TransactionalIntegrity-Onward-1.5.0 , text:Onwards Referrals}} + • {{pagelink:Core-TransactionalIntegrity-RetryDefinition-1.5.0 , text:Definition of a Retry}} + • {{pagelink:Core-TransactionalIntegrity-Receiver-1.5.0 , text:Receiver responsibilities}} + • {{pagelink:Core-TransactionalIntegrity-Sender-1.5.0 , text:Sender responsibilities}} + • {{pagelink:core-TIFailureScenarios-1.5.0 , text:Failure Scenarios}} + • {{pagelink:core-NFR-1.5.0 , text:Non functional Requirements}} + • {{pagelink:core-NFR-Requirements-1.5.0 , text:Requirements}} + • {{pagelink:core-NFR-Processing-Time-1.5.0 , text:Processing Times}} + • {{pagelink:Core-StandardPattern-1.5.0 , text:Standard Pattern - Composite Messages}} + • {{pagelink:core-SPComposites-1.5.0 , text:Standard Pattern for Composites}} + • {{pagelink:core-SPMessageHeader-1.5.0 , text:Message Headers}} + • {{pagelink:core-SPCancellation-1.5.0 , text:Cancellation}} + • {{pagelink:core-SPFindResource-1.5.0, text:Find Resource Id}} + • {{pagelink:core-SPUseCaseCategories-1.5.0 , text:Use Case Categories}} + • {{pagelink:core-StandardPattern-appointment-1.5.0 , text:Standard Pattern - Appointments}} + • {{pagelink:core-StandardPattern-appointment-booking-1.5.0 , text:Booking}} + • {{pagelink:core-StandardPattern-appointment-update-1.5.0 , text:Updates}} + • {{pagelink:core-StandardPattern-appointment-cancel-1.5.0 , text:Cancellations}} + • {{pagelink:core-StandardPattern-appointment-rebook-1.5.0 , text:Rebook}} + • {{pagelink:core-StandardPattern-document-reference-1.5.0 , text:Standard Pattern - DocumentReference}} + • {{pagelink:core-StandardPattern-document-reference-Sender-1.5.0 , text:Sender}} + • {{pagelink:core-StandardPattern-document-reference-Receiver-1.5.0 , text:Receiver}} + • {{pagelink:core-StandardPattern-document-reference-interface-1.5.0 , text:Interface}} + • {{pagelink:core-StandardPattern-Endpoints-1.5.0 , text:Standard Pattern - Endpoints}} + • {{pagelink:core-StandardPattern-Endpoint-Introduction-1.5.0 , text:Introduction}} + • {{pagelink:core-StandardPattern-Endpoint-Interface-1.5.0 , text:Interface}} + • {{pagelink:core-StandardPattern-Endpoint-Data-1.5.0 , text:Data Model}} + • {{pagelink:core-StandardPattern-Endpoint-Sequences-1.5.0 , text:Sequences}} + + + ++ +# 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.5.0, text: End to End Workflow}} section. + +
+
+ + +# 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.5.0, text: Core Functionality Requirements}} section. + +
+
+ +# 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. + +
+
+ +# 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.5.0, text: BaRS FHIR usage}} section. + +
+
+ +# Security and Authorisation + +For more detail on Security and Authorisation, please visit the {{pagelink:core-Security-1.5.0, text: Security and Authorisation}} section. + +
+
+ +# 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.5.0}} section in addition to information included on this page. + +For more detail please visit the {{pagelink:core-ErrorHandling-1.5.0, text: Error Handling}} section. + +
+
+ +# 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.5.0, text:Transactional Integrity}} section. + +
+
+ +# 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.5.0, text: Non Functional Requirements}} section. + +
+
+ +# 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.5.0, text: Standard Pattern - Composite Messages}} section. + +
+
+ +# Standard Pattern - Appointment + +The key capabilities surrounding appointments are listed below. This section will provide information on how to meet them. + +* view +* book +* update +* cancel +* reschedule +* rebook + +For more detail please visit the {{pagelink:core-StandardPattern-appointment-1.5.0, text: Appointment Standard Pattern}} section. + +
+
+ +# 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.5.0, text: DocumentReference Standard Pattern}} section. + +
+
+ + +# Standard Pattern - Endpoints + + +
+ +This version of core is strictly a preview of what is currently in development for 1.5.0 and should not be built against. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Index.page.md new file mode 100644 index 00000000..ddb10075 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-NFR-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Introduction.page.md new file mode 100644 index 00000000..5d13ac04 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Introduction.page.md @@ -0,0 +1,10 @@ +--- +topic: core-NFR-Introduction-1.5.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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Processing-Times.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Processing-Times.page.md new file mode 100644 index 00000000..2cc0e24a --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Processing-Times.page.md @@ -0,0 +1,15 @@ +--- +topic: core-NFR-Processing-Time-1.5.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-5-0/Non-Functional-Requirements/Requirements.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Requirements.page.md new file mode 100644 index 00000000..b21ff506 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/Requirements.page.md @@ -0,0 +1,19 @@ +--- +topic: core-NFR-Requirements-1.5.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 | + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Non-Functional-Requirements/toc.yaml new file mode 100644 index 00000000..5e962e98 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/Security-and-Authorisation/Authorisation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Authorisation.page.md new file mode 100644 index 00000000..38283272 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Authorisation.page.md @@ -0,0 +1,17 @@ +--- +topic: core-Security-Auth-1.5.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-5-0/Security-and-Authorisation/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Index.page.md new file mode 100644 index 00000000..4796ac28 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Index.page.md @@ -0,0 +1,4 @@ +--- +topic: core-Security-1.5.0 +--- + diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Introduction.page.md new file mode 100644 index 00000000..d04876c9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Introduction.page.md @@ -0,0 +1,8 @@ +--- +topic: core-Security-Introduction-1.5.0 +--- + +# Security and Authorisation + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/OAuth-Endpoints.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/OAuth-Endpoints.page.md new file mode 100644 index 00000000..4a2a7911 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/OAuth-Endpoints.page.md @@ -0,0 +1,15 @@ +--- +topic: core-Security-Oauth-1.5.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 | + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Receiver.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Receiver.page.md new file mode 100644 index 00000000..af76dcf1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Receiver.page.md @@ -0,0 +1,39 @@ +--- +topic: core-Security-Receiver-1.5.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 superseded 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 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) + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Sender.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Sender.page.md new file mode 100644 index 00000000..5df199a7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/Sender.page.md @@ -0,0 +1,18 @@ +--- +topic: core-Security-Sender-1.5.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 + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Security-and-Authorisation/toc.yaml new file mode 100644 index 00000000..3949edb7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Cancellation.page.md new file mode 100644 index 00000000..fc00654d --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -0,0 +1,540 @@ +--- +topic: core-SPCancellation-1.5.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. + +There are two potential routes for performing a cancellation of a booking or referral, dependending on Supplier implementation (see - Capability Statement (GET /metadata) for supported methods), either via $process-message or directly against the single resource (RESTfully). Where $process-message is used a stripped back request containing only the specific resources a Receiver requires to the fulfil the update are included. There are separate MessageDefinitions involved when engaged in the respective [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. Alternatively, where a RESTful pattern for updating a single resource is followed, the independent endpoints for [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#put-/Appointment/-id-) and [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.5.0#put-/ServiceRequest/-id-) support the update process. This workflow follows {{pagelink:core-StandardPattern-appointment-1.5.0 , text:Standard Pattern - Appointments}}. + +It is a prerequisite, when performing a cancellation, to read (GET) the booking or referral to be cancelled, following the {{pagelink:core-SPFindResource-1.5.0, text:find resource}} steps. This ensures the Sender has the key values to build the request and verifies they can proceed with the workflow. The Sender **must** only make a cancellation request if the entity being cancelled 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 resource 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.5.0, text:error}} response. + +## Cancellation Referral Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.5.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. + +
+ +### 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. + +
+
+ +
> Bundle
++ +
The Bundle resource is the container for the event message.
+ {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} ++ + + +| 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.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 | +| 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 | + + + +
+
+
+ A resource that describes the BaRS message being exchanged between two systems.
+
+
+
+
+
+| 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 |
+
+
+
+> Message Header
+
+
+
+
+ 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.
+
+
+
+| 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. |
+
+
+> Service Request
+
+
+ This resource is used to communicate details about the patient who is the subject of the referral.
+
+
+
+
+| 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.> Patient
+
It also includes contact information for third parties when required.
It also includes contact information for third parties when required.
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'.
Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.
Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.
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 |
+
+
+
+
+
+ This resource is used to communicate details about the sender and receiver organisations.
+
+
+
+| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) |
+|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------|
+| Organization | This resource is used to communicate details about the sender organisations. > Organization
+
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 |
+
+
+
+
+
+
+### Entity Relationship Diagram - Cancellation Referral Request
+
+
+
+The below diagram details the Cancellation Referral Request
+
+
+
+
+
+ +## Cancellation Booking Request Payload + +### MessageHeader Resource +{{pagelink:core-SPMessageHeader-1.5.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. + +
+
+ +
> Bundle
++ +
The Bundle resource is the container for the event message.
+ {{tree:https://fhir.nhs.uk/StructureDefinition/BARSBundleMessage, hybrid}} ++ + + +| 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.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 | +| 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 | + +
+
+
+ A resource that describes the BaRS message being exchanged between two systems.
+
+
+
+
+
+| 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 |
+
+
+> Message Header
+
+
+
+
+ This resource will be used to communicate information about an Appointment and is the focus of the Booking interation.
+
+
+
+
+| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) |
+|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------|
+| Appointment | https://simplifier.net/hl7fhirukcorer4/ukcore-appointment > Appointment
+
+
+
+
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 'cancelled' | MUST | 1..1 | cancelled |
+| 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 |
+
+ This resource is used to communicate details about the patient who is the subject of the referral.
+
+
+
+
+| 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.> Patient
+
It also includes contact information for third parties when required.
It also includes contact information for third parties when required.
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'.
Where the contact details relate to the patient this relationship MUST be populated with the value 'self'.
Where the contact details relate to a patient's representative this SHOULD be populated with their relationship to the patient.
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 |
+
+
+
+
+ This resource is used to communicate details about the sender and receiver organisations.
+
+
+
+| Data Item | Implementation Guidance | Necessity | Profile Cardinality | Example Value(s) |
+|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------------------|------------------------------------------------------------------------------------------|
+| Organization | This resource is used to communicate details about the sender organisations. > Organization
+
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 |
+
+
+
+
+
+## Entity Relationship Diagram - Cancellation Booking Request
+
+
+
+The below diagram details the Cancellation Booking Request
+
+
+
+
+
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Find-Resource.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Find-Resource.page.md new file mode 100644 index 00000000..bb3afa2f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Find-Resource.page.md @@ -0,0 +1,24 @@ +--- +topic: core-SPFindResource-1.5.0 +--- + + +## {{page-title}} + +A prerequisite, when undertaking any update routine, is to perform a read (GET) of either the booking or referral to be amended (including cancellation routines). This ensures the Sender has the most recent version of the resource being updated and verifies they can proceed with the workflow. For example, to engage in a cancellation workflow, the status of the entity being cancelled must currently be classed as 'active'. + +As a first step the Sender **must** obtain the (resource).Id of the booking (Appointment) or referral/validation (ServiceRequest) and there are several ways to do this. If the Sender made the original request, they will likely know this and can directly request the specific resource to check the status, using the GET (read) by Id endpoint. Alternatively, if they did not generate the original request (or there was a problem with the synchronous response being received) the full resource can be obtained by searching for active bookings or referrals 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). This will return a (FHIR) bundle of responses (typically, containing only one entry) which the Sender can match, based on dateTime (elements dependent on resource) and use-case category values, to identify the resource of interest. If the Sender cannot accurately match the resource they should advise the user the update cannot be performed and to revert to manual options instead. The diagram under 'Options for obtaining booking or referral' outlines the variations above. + +#### Options for obtaining booking or referral + +
+
+
+The below diagram details the options for obtaining the booking (Appointment) or referral/validation (ServiceRequest) resource, prior to update (including cancellation). The Sender must know the (resource).status and (resource).id values, as minimum, to build a valid update request. +
++
+
++
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Introduction.page.md new file mode 100644 index 00000000..51c88c6b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Introduction.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-StandardPattern-Introduction-1.5.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. + + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Message-Headers.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Message-Headers.page.md new file mode 100644 index 00000000..6cd13727 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Message-Headers.page.md @@ -0,0 +1,47 @@ +--- +topic: core-SPMessageHeader-1.5.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 asynchronous 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 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.category** provides this functionality and, with the addition of {{pagelink:core-SPUseCaseCategories-1.5.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. + +
+
+ + +### 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-5-0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md new file mode 100644 index 00000000..4787659e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Standard-Pattern-For-Composites.page.md @@ -0,0 +1,312 @@ +--- +topic: core-SPComposites-1.5.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. + +
> Click here to show example
+ +```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' + } + } + } +} +``` + ++
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md new file mode 100644 index 00000000..6db59bb9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/Use-Case-Categories.page.md @@ -0,0 +1,39 @@ +--- +topic: core-SPUseCaseCategories-1.5.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-5-0/Standard-Pattern-Composite-Messages/index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/index.page.md new file mode 100644 index 00000000..13a3383e --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/index.page.md @@ -0,0 +1,3 @@ +--- +topic: Core-StandardPattern-1.5.0 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/toc.yaml new file mode 100644 index 00000000..6f501ca9 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Standard-Pattern-Composite-Messages/toc.yaml @@ -0,0 +1,14 @@ +- 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: Find Resource + filename: Find-Resource.page.md +- name: Use Case Categories + filename: Use-Case-Categories.page.md \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Definition-of-a-retry.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Definition-of-a-retry.page.md new file mode 100644 index 00000000..f5aa9629 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Definition-of-a-retry.page.md @@ -0,0 +1,14 @@ +--- +topic: Core-TransactionalIntegrity-RetryDefinition-1.5.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) + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Failure-Scenarios.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Failure-Scenarios.page.md new file mode 100644 index 00000000..97ca9f88 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Failure-Scenarios.page.md @@ -0,0 +1,422 @@ +--- +topic: core-TIFailureScenarios-1.5.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. + + + +
+ +### 401 Outcome + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Index.page.md new file mode 100644 index 00000000..8de1b072 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Index.page.md @@ -0,0 +1,3 @@ +--- +topic: Core-TransactionalIntegrity-1.5.0 +--- diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Initial-Request.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Initial-Request.page.md new file mode 100644 index 00000000..9afdc375 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Initial-Request.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Initial-1.5.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. + + + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Introduction.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Introduction.page.md new file mode 100644 index 00000000..0fe0c72b --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Introduction.page.md @@ -0,0 +1,26 @@ +--- +topic: Core-TransactionalIntegrity-Introduction-1.5.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.5.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 + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Onwards-Referrals.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Onwards-Referrals.page.md new file mode 100644 index 00000000..bffdca45 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Onwards-Referrals.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Onward-1.5.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. + + + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Receiver-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Receiver-responsibilities.page.md new file mode 100644 index 00000000..4d805a08 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Receiver-responsibilities.page.md @@ -0,0 +1,13 @@ +--- +topic: Core-TransactionalIntegrity-Receiver-1.5.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 + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Retry-Scenario.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Retry-Scenario.page.md new file mode 100644 index 00000000..308c41f8 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Retry-Scenario.page.md @@ -0,0 +1,20 @@ +--- +topic: Core-TransactionalIntegrity-RetryScenario-1.5.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. + + + + +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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sender-responsibilities.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sender-responsibilities.page.md new file mode 100644 index 00000000..6ec0c79f --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sender-responsibilities.page.md @@ -0,0 +1,30 @@ +--- +topic: Core-TransactionalIntegrity-Sender-1.5.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 429 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 OperationOutcome 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 a 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. + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sending-an-update.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sending-an-update.page.md new file mode 100644 index 00000000..b82fdef7 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/Sending-an-update.page.md @@ -0,0 +1,12 @@ +--- +topic: Core-TransactionalIntegrity-Update-1.5.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. + + + +
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/Transactional-integrity/toc.yaml new file mode 100644 index 00000000..659624ab --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-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-5-0/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/toc.yaml new file mode 100644 index 00000000..eacac4d1 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1-5-0/toc.yaml @@ -0,0 +1,24 @@ +- 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 \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md index d8fc771c..88eb728a 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/Index.page.md @@ -16,6 +16,6 @@ Each current and available version of Core can be found below.
-{{pagelink:design-core-1.4.1, text:1.4.1}} +{{pagelink:design-core-1.5.0, text:1.5.0}}
\ 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 7182e6ca..53cf9d84 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/toc.yaml @@ -2,5 +2,5 @@ filename: Index.page.md - name: 1.0.7 filename: 1-0-7 -- name: 1.4.1 - filename: 1-4-1 \ No newline at end of file +- name: 1.5.0 + filename: 1-5-0 \ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md b/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md index 5f23d001..1cde63d8 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Index.guide.md @@ -9,7 +9,7 @@ Step 1: {{pagelink:Analysis, text:Analysis}} A group of pages to support you to understand what is required to implement BaRS successfully. These include principles and prerequisites, infrastructure, roles and responsibilities and content negotiation. -Step 2: {{pagelink:design-core-1.4.1, text:BaRS Core }} +Step 2: {{pagelink:design-core-1.5.0, text:BaRS Core }} Familiarise yourself with the core elements of BaRS including end-to-end workflow, security and authorisation, and error handling. Step 3: {{pagelink:Home/Applications/BaRS-Applications, text:BaRS use cases and applications}}