Pragmatic use of ITK3 response codes for generic FHIR receive programmes

Not applicable

This code can act as a handling error “catch-all” if more nuanced infrastructure codes have not been implemented.

Not applicable

Negative infrastructure acknowledgement still informs sender that there is a build error in message but is less precise about the nature of the error.

The handling specification flag for infrastructure level response is present but cannot be processed. For example, may be unreadable or contain an incorrect value. This code is mandatory to be supported. 

If the InfAckRequestedvalue received is not ‘true’ or ‘false’ the response code ‘10002’ must be returned to sender.

Suppliers can behave as follows: 

- if value is correctly set, honour purpose of flag, i.e. send or not send response
- always send infrastructure responses irrespective of valid flag value
- end a 10002 or a generic negative response value if flag value cannot be processed

Sender could get back: 

- '10001' (generic) or
- '10002' or 
- '20013' (i.e. positive response because error is not treated as fatal)

The handling specification flag for business level response is present but cannot be processed. For example, may be unreadable or contain an incorrect value. This code is mandatory to be supported.

If the BusAckRequested value received is not ‘true’ or ‘false’ the response code ‘10003’ must be returned to sender.

Suppliers can behave as follows:

- if value is correctly set, honour purpose of flag, i.e. send or not send business response.
- always send business responses irrespective of valid flag value
- send a 10003 or a generic negative response value if flag value cannot be processed - if value is empty use 10001, if unrecognised use 20009

Transfer of Care – Emergency Care eDischarge Implementation Guide 2.6.0-beta. The value must be:

‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-EC-eDischarge-MessageDefinition-4’ 

Suppliers can send:

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back:

- 10001 or 
- 10004 or
- 20013 (i.e. not reported as error)

Transfer of Care – Inpatient (Acute) Discharge eDischarge Implementation Guide 2.6.0-beta. 

The value must be:

‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-eDischarge-MessageDefinition-4’

Suppliers can send:

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

-10001 or 
-10004 or 
-20013 (i.e. not reported as error)

Transfer of Care – Mental Health eDischarge Implementation Guide 2.6.0-beta.  

The value must be: ‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-MH-eDischarge-MessageDefinition-4’ 

Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or
- 20013 (i.e. not reported as error)

Transfer of Care – Outpatient Letter Implementation Guide 2.6.0-beta. 

The value must be: ‘https://fhir.nhs.uk/STU3/MessageDefinition/ITK-OPL-MessageDefinition-4’

Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or
- 20013 (i.e. not reported as error)

Digital Medication – DM Emergency Medication Supply 

“https://fhir.nhs.uk/STU3/MessageDefinition/ITK-DM-EmergencySupply-MessageDefinition-1”  

If any other value is received the response code ‘10004’ must be returned unless is an incorrect version, then follow the guidance below for response code ‘10005’ 

Note: the GP writeback message string is TBA.

Suppliers can send: 

- 10001 if value is empty
- 20013 (positive response) if value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back: 

- 10001 or
- 10004 or 
- 20013 (i.e. not reported as error)

The handling specification for Message Definition is present but the version is not supported by the receiving system. 

If the string received is correct but the version is incorrect, the response code ‘10005’ must be returned to sender.

Suppliers can behave as follows:  

- send a 10001 if value is empty
- send 10004 if message definition value rather than version is checked
- send a 20013 (positive response) if version value is unrecognised but message can be transformed to HRO

For this specific error, sender could get back:

- 10001 or 
- 10004 or 
- 10005 or
- 20013 (i.e. not reported as error)

That is, if HRO cannot be created at receiver end, the sender would be informed via negative response code. 

The handling specification string for Sender Reference is present but cannot be processed. For example, may be unreadable, contain an incorrect value or the use of Sender Reference is not supported by receiving system. 

For the current use cases if any value other than the SenderReference default value of “None” is received the response code ‘10007’ must be returned to sender.

For this specific error, sender could get back:

- 10007 or 
- 20013 (i.e. not reported as error)

The Handling Specification usage does not match business rules for included payload. For example, an acknowledgement flag defined as mandatory by the payload specification is missing. 

This error code should not be used for current use cases as there are no defined process for the correct identification of these rules.

A message has been received that is either corrupted or malformed and cannot be read by the receiving system.

The response code ‘10009’ must be supported and returned to sender.

Sender can expect back: 

- 10009 or 
- 20009 or  
- no application level ITK3 response

It is acknowledged that a non-10009 response makes it difficult for a sender to identify a corruption problem arising during transport since the message held at the sender end would be in a good state when inspected. However, any corruption would be considered extremely rare. If no ITK3 response code is returned for a message sent, the sender would need to consider contacting the recipient GP Practice and / or sending the message again.

The handling specification for Recipient Type is present but cannot be processed. For example, may be unreadable or contain an incorrect value. 

The response code ‘10010’ must be supported and returned to sender.

From a clinical safety perspective, Transfer of Care would expect GP Practice staff to treat all documents received as “For Action” (FA) rather than “For Information” (FI).  In effect the value set is immaterial.   

If a processing problem with Recipient Type is detected sender can choose not to return a negative infrastructure response code. 

Sender can expect back: 

- 10010 or
- 20013 (i.e. not reported as error)

The person referred to as the recipient in the ITK3 MessageHeader when present is not recognised. 

The response code ‘20001’ must be supported and must be returned to sender.

Supplier system may handle this scenario in a few ways: 

- if recipient has previously logged on to the GP practice system but may no longer work there, then document could be reassigned to an appropriate person (for example, usual GP or principal GP) and a 20013 would be generated
- if recipient has been defined with invalid Spine Directory Service ID code then could generate 20001

The sender does not have to name a recipient in the message. If it has done, and it is unrecognised by receiver, can expect the following response codes:

- 20001 or 
- 20013 (i.e. not reported as error)

The organisation referred to as the recipient in the ITK3 MessageHeader when present is not recognised.

The response code ‘20002’ must be supported and returned to sender.

The organisation or person referred to as the sender in the ITK3 MessageHeader is not recognised. Note: This code should not be used where the domain makes use of the “GP look-up” functionality in MESH. 

This error code should not be used for current use cases due to the potential use of GP look-up.

The Receiving system has received an attached file whose file type is not approved for the business domain. 

This error code should not be used for current use cases due to the fact no business domain has defined their non-approved attachment types.

The receiving system has received an attached file which it does not support. 

Note: all receiving systems must support at least .pdf file extensions. 

The response code ‘20005’ must be supported and returned to sender.

The ITK3 header resources or elements are not correct or understandable. The ITK3 Bundle or ITK3 MessageHeader fail conformance against the FHIR schemas: http://hl7.org/fhir/STU3/fhir-all-xsd.zip or HAPI validation using the approved version of the HAPI libraries* 

*This will be the version used by the ITK3 Test Harness. 

Sender can expect the following response codes:

- 10001 or 
- 20006 or 
- 20013 (i.e. problem not reported as error)

That is, sender will get back a negative response if message cannot be transformed to HRO.

Bundle with this message identifier has already been processed. A Payload with this message identifier has already been received and processed by this recipient. A message with this message header.id has already been received and processed. 

As stated in the FHIR standard – An incoming message contains two identifiers: the Bundle.id and the MessageHeader.id. Each time a new message is created, it SHALL be assigned an identifier (MessageHeader.id) that is unique within that message stream. Note that since message streams are often merged with other streams, it is recommended that the identifier should be globally unique. This can be achieved by using a UUID or an OID. Each time a message is sent, the Bundle.id should be changed to a new value.   

See: http://hl7.org/fhir/STU3/messaging.html 

The response code ‘20007’ must be supported and returned to sender, and the message deemed to be a duplicate must be rejected regardless of the content of the payload.

Supplier may provide a solution that requires manual intervention by the end-user in the GP practice to confirm duplicates. The receiver system would under this circumstance return a positive infrastructure code, i.e. 20013 prior to the business response code.   

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their Hazard Log to identify the clinical risk and the mitigations in place. 

A sender needs to have rigorous processes in place to avoid a duplicate message ID being used.

The sender can expect one of following response codes where the error exists: 

- 20007 or 
- 20013 (i.e. problem not reported as error)

Bundle with this document identifier has already been processed. A payload with this document identifier has already been received and processed by this recipient. 

As stated in the FHIR standard The document identifier (mandatory). This is found in Bundle.identifier and is globally unique for this instance of the document, and is never re-used, including for other documents derived from the same composition. 

See: http://hl7.org/fhir/STU3/documents.html

The response code ‘20008’ must be supported and returned to sender, and the document deemed to be a duplicate must be rejected regardless of the content of the payload.

Supplier may provide a solution that requires manual intervention by the end-user in the GP practice to confirm duplicates. The receiver system would under this circumstance return a positive infrastructure code, i.e. 20013 prior to the business response code.   

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their Hazard Log to identify the clinical risk and the  mitigations in place. 
 

A sender needs to have rigorous processes in place to avoid a duplicate message ID being used.

The sender can expect one of following response codes: 

- 20008 or 
- 20013 (i.e. problem not reported as error)

The payload is not correct or understandable. The payload fails conformance test against the FHIR schemas: http://hl7.org/fhir/STU3/fhir-all-xsd.zip

or HAPI validation using the approved version of the HAPI libraries*

*This will be the version used by the ITK3 Test Harness. The response code ‘20009’ must be supported and returned to sender.

Sender can expect back from GP Practice either:

- 20009 or
- 20013  (i.e. problem not reported as error)

That is, sender will get back a negative response if message cannot be transformed to HRO.

The recipient organisation identified in the payload, is not supported by this end point (receiving system). 

The response code ‘20010’ must be supported and returned to sender.

The recipient person identified in the payload, is not supported by this end point (receiving system). 

The response code ‘20011’ must be supported and returned to sender. 

For ToC, 20011 is analogous to an error with the recipient in the letter, and 20001 to an error with the recipient in the envelope.

Supplier may treat this in a similar fashion to the previous scenario code 20001 relating to unrecognised recipient in the ITK3 MessageHeader.

That is, document may be reallocated to another member of staff in the GP Practice.

A positive infrastructure code (20013) would be generated rather than 20011.

The sender does not have to name a recipient in the message. If it has done, and the recipient is not recognised at the GP Practice end then the sender could receive one of the following codes: 

- 20011 or 
- 20013 (i.e. problem not reported as error)

The receiving system identified in the payload is configured to reject messages from unauthorised senders. This code should not be used where the domain makes use of the 'GP look-up' functionality in MESH.

The response code 20012 should not be used.

The message has been processed successfully. A response will be returned stating the fact. However, the message may still fail after further processing and result in another response if the business level response request flag has been sent to 'true'. 

The response code ‘20013’ must be supported must be returned to sender.

A replacement document was received, but the receiver could not process the new document correctly and has therefore marked the new and original documents as “bad” on its system.

The response code ‘20014’ must be supported and returned to sender.

The received document may be in a state where processing cannot be done to recognise it as a replacement. Where processing is possible to the point where the document is confirmed as a replacement, then suppliers should make every effort to indicate to staff that the initial document (i.e. that intended to be replaced) needs to be treated as “bad” to prevent GP Practice staff placing undue reliance on its content for patient care. 

The GP IT supplier must have a clinically appropriate workaround behaviour for this scenario and an entry in their hazard log to identify the clinical risk and the  mitigations in place.

As the sender previously sent a successful original message, the likelihood of not being able to process the replacement document is considered low. 

For this error, the sender can expect back from the GP Practice system the following:

- 10001 negative catch-all infrastructure code or
- a more nuanced code for the specific processing problem such as a 10009 for bad XML, or  
- 20014 to show the error relates to a failed replacement or
- two negative infrastructure response codes in the same ACK message - this would be the more nuanced error code such as 10009, and 20014 to indicate it relates to a replacement document

It is important that sender sites have adequate auditing capabilities so negative response codes can be traced back to the sent messages and any replacement document problems identified swiftly. When the sender identifies the response message as relating to a replacement document then they would need to urgently contact the GP practice via telephone to address any patient safety risks.

Not applicable - new response code

Non-implementation may result in processing problems for the GP Foundation IT system when large messages are received.  This could require GP Practice staff to contact the GP IT supplier’s Support Desk for manual rectification.

Non-implementation means that the GP Practice IT system would return a 30003 response if the patient had been deducted due to their death. GP Practice staff would then have to receive the message via another (non-FHIR) route and manually associate this correspondence with the patient’s record to complete it. When implemented, use would be during a defined time window only. The start of the time window would be the date of the patient’s death and the end of the window just prior to 6 months after this date.  

When the date of receival of the FHIR message falls outside this window (i.e. 6-months or later), a code 30003 would be returned to the sender.