NBRS-4840 - Update Timeout, Retry and Conflict Guidance

Updated guidance to both senders and receivers on how to respond to timeout, retry and conflict messages.

Author: d-dreyer

guides/Live-ImplementationGuide-BaRS/Home/Core/1-6-0/Error-Handling/Failure-Scenarios-1-1-x/Bundle-Processing.page.md

@@ -79,7 +79,7 @@ Below is a simplified example of how how to handle the Transaction Integrity HTT
           }
         ]
       },
-      "diagnostics": "This message has been recognised as having already been successfully processed."
+      "diagnostics": "This message has been recognised as having already been successfully processed. Reference ID: ID-12345"
     }
   ]
 }
@@ -198,7 +198,7 @@ if (Message == "update")
           }
         ]
       },
-      "diagnostics": "Information received has been updated locally and may cause loss, or presents a conflict, of data"
+      "diagnostics": "Information received has been updated locally and may cause loss, or presents a conflict, of data. Reference ID: ID-12345"
     }
   ]
 }

guides/Live-ImplementationGuide-BaRS/Home/Core/1-6-0/Transactional-integrity/Failure-Scenarios.page.md

@@ -6,7 +6,7 @@ topic: core-TIFailureScenarios-1.6.0
 
 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.
+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. In the event that the request resulted in a new unique identifier on the receiver system, the receiver must return the reference ID as part of the OperationOutcome.issue.diagnostics.
 
 ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-1.0.0.svg)
 
@@ -114,7 +114,7 @@ If a message fails due to a message with the same header ids having already been
 
 	      },
 
-	      "diagnostics": "This message has already been received and processed"
+	      "diagnostics": "This message has already been received and processed. Reference ID: ID-12345"
 
 	    }
 
@@ -124,7 +124,7 @@ If a message fails due to a message with the same header ids having already been
 
 </json>
 
-In the event of a timeout, a retry attempt is made after a suitable amount of time to ensure the message was received. The same X-Request-ID and X-Correlation-ID must be used. Should a 409 REC_CONFLICT response be received with a OperationOutcome.issue.code of "duplicate", then this can be used as confirmation that the message was received.
+In the event of a timeout, a retry attempt should be made to ensure the message was received. Senders should wait a suitable amount of time before attempting a retry to allow the receiver to finish processing the original message. The same X-Request-ID and X-Correlation-ID must be used. Should a 409 REC_CONFLICT response be received with a OperationOutcome.issue.code of "duplicate", then this can be used as confirmation that the message was received. In the event that the request resulted in a new unique identifier on the receiver system, the receiver must return the reference ID as part of the OperationOutcome.issue.diagnostics.
 
 ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Timeout-Failure-Scenario-1.0.0.svg)
 
@@ -231,7 +231,7 @@ In the event of a timeout, a retry attempt is made after a suitable amount of ti
 
 	      },
 
-	      "diagnostics": "This message has already been received and processed"
+	      "diagnostics": "This message has already been received and processed. Reference ID: ID-12345"
 
 	    }
 
@@ -241,7 +241,7 @@ In the event of a timeout, a retry attempt is made after a suitable amount of ti
 
 </json>
 
-If the processing of a message is not completed prior to the initial retry, the receiver must respond with a 425 REC_TOO_EARLY response, to indicate the initial message is still processing. The receipt is then unconfirmed and the sender can retry after a suitable amount of time until they receive a desired response.
+If the processing of a message is not completed prior to the initial retry, the receiver must respond with a 425 REC_TOO_EARLY response, to indicate the initial message is still processing. The receipt is then unconfirmed and the sender should retry until they receive a desired response. Senders must wait a suitable amount of time in between retry attempts to provide time for the receiver to finish processing the original message. 
 
 ![BaRS FHIR API end-to-end process](https://raw.githubusercontent.com/NHSDigital/NHSDigital-FHIR-BookingAndReferrals/main/BaRS-Images/TransactionIntegrity/Initial-failure-scenario-solution-1.0.0.svg)
 
@@ -404,7 +404,7 @@ If the processing of a message is not completed prior to the initial retry, the
 
 	      },
 
-	      "diagnostics": "This message has already been received and processed"
+	      "diagnostics": "This message has already been received and processed. Reference ID: ID-12345"
 
 	    }
 

guides/Live-ImplementationGuide-BaRS/Home/Core/1-6-0/Transactional-integrity/Receiver-responsibilities.page.md

@@ -7,6 +7,7 @@ topic: Core-TransactionalIntegrity-Receiver-1.6.0
 - 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"
+- in the event of the above point, if the duplicate message is received that has already been correctly processed, and this message resulted in a record with a new unique identifier on the receiver side, a reference to the new unique identifier must be returned as part of the operationOutcome.issue.diagnostics.
 - this combination of codes can only be used in a duplicate message scenario
 
 <br>

guides/Live-ImplementationGuide-BaRS/Home/Core/1-6-0/Transactional-integrity/Sender-responsibilities.page.md

@@ -23,8 +23,9 @@ The frequency of retries and the duration of a retry period depends on the scena
 - 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"
+    - In the event that the original message resulted in a new unique identifier on the receiver, the receiver may return a reference to the new unique identifier as part of the operationOutcome.issue.diagnostics. In this case, the sender may extract the reference to the receiver ID and update their own records, if appropriate.
 
-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.
+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. In the event of a retry, the sender should wait an appropriate amount of time between retry attempts to allow receivers to finish processing, or give room for intermediate transport-level issues to resolve and recover. Errors outside of the HTTP standard should also be logged locally with as much detail as possible, for example; Transport-Layer error messages.
 
 <br>
 <hr>