FHIR Data Standards Wales for PSOM v1.0.0-rc3
Important: This is the release candidate of the FHIR Data Standards Wales for PSOM version 1.0.0-rc2 Implementation Guide. It is intended for trial use, and is published for early comment and feedback. Click here to give feedback.

Handling Exceptions

This page provides guidance on how to handle the most common exception types in the PSOM context through FHIR messaging. Please note that the list of scenarios below is not exhaustive. Moreover, this page should be interpreted as a guideline, as the nature of an exception is not always unambiguous, and Health Boards and PROM Providers may have established their individual exception handling processes. The FHIR specification provides more detail on error handling in general.

Exception response message

To communicate an exception, an Exception Response message can be sent, containing a FHIR Bundle consisting of:

  • one MessageHeader resource with
    • .eventCoding.code = exception-response;
    • .response.identifier = the MessageHeader.id of the message to which this message is a response;
    • .response.code = transient-error | fatal-error;
    • .response.details populated with a reference to the OperationOutcome containing the outcome of processing the request.
  • one OperationOutcome resource (referenced in MessageHeader.response.details) with
    • .issue.severity = relevant code from the IssueSeverity ValueSet;
    • .issue.code = relevant code from the IssueType ValueSet;
    • .issue.diagnostics populated with relevant textual information about the cause of the issue;
    • .issue.expression populated with a FHIRPath expression to pinpoint the element that causes the issue to arise.

When sending an exception response, the MessageHeader.response must be supplied as it contains vital information on the message that has raised the exception. In particular it contains an .identifier which actually links the exception response to the initial message, and .details on the issue(s) that was/were present in the initial message.

Within the OperationOutcome.issue, the .severity and .code are general codes, while .diagnostics and .expression are necessary for the client to understand the exact cause of the issue.

Scenarios

Received message does not conform to the PSOM FHIR specifications

When the received message does not conform to the PSOM FHIR specifications (i.e. PSOM profiles) or it contains invalid JSON/XML, the server cannot process the message. The exception message to the client should consist of:

  • HTTP Code 400 - Bad Request (only applicable to RESTful exchange)
  • FHIR Bundle for the exception-response message type with
    • MessageHeader.response.code = fatal-error;
    • OperationOutcome.issue.severity = error;
    • OperationOutcome.issue.code = invalid (or a more specific child code from the IssueType ValueSet);
    • Relevant details in OperationOutcome.issue.diagnostics and OperationOutcome.issue.expression.

Upon receipt of the exception message, the client should solve the cause of the issue and resend the updated request message.

Example

Received message does not conform to the PSOM FHIR specifications

Received message contains unavailable PROMs version

An unavailable PROMs version in the received message may arise from either the client or server not supporting a certain PROMs version. The server shall first confirm if the requested version of PROMs is installed. If the server does not have that version installed, they should proceed to do so if it is a version they should support (e.g. if it is the latest version, or an earlier version that is mandatory to be supported according to the PSOM guidelines), and retry processing the request message. If it is not possible to process the request after installing the requested version, or if the requested version does not exist or does not need to be supported (anymore), the server shall send an exception message to the client consisting of:

  • HTTP Code 422 - Unprocessable Entity (only applicable to RESTful exchange)
  • FHIR Bundle for the exception-response message type with
    • MessageHeader.response.code = fatal-error;
    • OperationOutcome.issue.severity = error;
    • OperationOutcome.issue.code = not-supported;
    • Relevant details in OperationOutcome.issue.diagnostics and OperationOutcome.issue.expression.

Upon receipt of the exception message, the client should investigate the reason of the issue, and potentially update the version in all applicable FHIR resources accordingly and resend the updated request message.

Example

Received message contains unavailable PROMs version

Received message violates pathway restrictions e.g. age

When the received message contains data elements that violate pathway restrictions such as age, the server cannot process the request. The exception message to the client should consist of:

  • HTTP Code 422 - Unprocessable Entity (only applicable to RESTful exchange)
  • FHIR Bundle for the exception-response message type with
    • MessageHeader.response.code = fatal-error;
    • OperationOutcome.issue.severity = error;
    • OperationOutcome.issue.code = business-rule;
    • Relevant details in OperationOutcome.issue.diagnostics and OperationOutcome.issue.expression.

Upon receipt of the exception message, the client should solve the cause of the issue and resend the updated request message or cancel the request.

Example

Received message violates pathway restrictions e.g. age

Missing information

When the received message has missing information that is optional according to the PSOM FHIR profiles, but is necessary for the server to process the PROMs collection for a certain PROMs pathway, such as location, treatment information or laterality, the server cannot process the request. The exception message to the client should consist of:

  • HTTP Code 422 - Unprocessable Entity (only applicable to RESTful exchange)
  • FHIR Bundle for the exception-response message type with
    • MessageHeader.response.code = fatal-error;
    • OperationOutcome.issue.severity = error;
    • OperationOutcome.issue.code = business-rule;
    • Relevant details in OperationOutcome.issue.diagnostics and OperationOutcome.issue.expression.

Upon receipt of the exception message, the client should supplement the request with the necessary data and resend the updated request message.

Example

Missing information

Duplicate collection requests

When the received message contains a request for a PROMs collection that is already in progress, the server cannot process the request. The exception message to the client should consist of:

  • HTTP Code 409 - Conflict (only applicable to RESTful exchange)
  • FHIR Bundle for the exception-response message type with
    • MessageHeader.response.code = fatal-error;
    • OperationOutcome.issue.severity = error;
    • OperationOutcome.issue.code = duplicate;
    • Relevant details in OperationOutcome.issue.diagnostics and OperationOutcome.issue.expression.

Upon receipt of the exception message, the client should cancel the duplicate request.

Example

Duplicate collection request