FHIRcast logo

FHIRcast
3.0.0-ballot - ci-build International flag

FHIRcast, published by HL7 International / Infrastructure And Messaging. This guide is not an authorized publication; it is the continuous build for version 3.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhircast-docs/ and changes regularly. See the Directory of published versions

Event Notification

The Hub SHALL notify Subscribers of workflow-related events to which the Subscriber is subscribed. The notification is a JSON object communicated over the WebSocket channel.

Event Notification

The event notification interaction include the following fields:

Field Optionality Type Description
timestamp Required string ISO 8601-2 timestamp in UTC describing the time at which the event occurred.
id Required string Event identifier used to recognize retried notifications. This id SHALL be unique for the Hub, for example a UUID.
event Required object A JSON object describing the event see Event Definition.

The timestamp SHOULD be used by subscribers to establish message affinity (message ordering) through the use of a message queue. Subscribers SHALL ignore messages with older timestamps than the message that established the current context. The event identifier MAY be used to differentiate retried messages from user actions.

Event Notification Request Example

{
	"timestamp": "2018-01-08T01:37:05.14",
	"id": "q9v3jubddqt63n1",
	"event": {
		"hub.topic": "fdb2f928-5546-4f52-87a0-0648e9ded065",
		"hub.event": "Patient-open",
		"context": [{
			"key": "patient",
			"resource": {
				"resourceType": "Patient",
				"id": "ewUbXT9RWEbSj5wPEdgRaBw3",
				"identifier": [{
					"type": {
						"coding": [{
							"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
							"value": "MR",
							"display": "Medication Record Number"
						}]
					}
				}]
			}
		}]
	}
}

Event Notification Response

The Subscriber SHALL respond to the event notification with an appropriate HTTP status code. In the case of a successful notification, the Subscriber SHALL respond with any of the response codes indicated below:

Code   Description
200 OK The Subscriber is able to implement the context change.
202 Accepted The Subscriber has successfully received the event notification, but has not yet taken action. If the Subscriber decides to refuse the event, it will send a SyncError event. Subscribers are RECOMMENDED to do so within 10 seconds after receiving the context event.
409 Conflict The Subscriber refuses to follow the context change. The Hub SHALL send a SyncError indicating the event was refused.
4xx Other Client Error For Subscriber errors other than a 409; Subscribers can return other appropriate 4xx HTTP statuses. The Hub SHALL send a SyncError indicating the event was refused.
500 Server Error There is an issue in the Subscriber preventing it from processing the event. The Hub SHALL send a SyncError indicating the event was not delivered.
5xx Other Server Error If the Subscriber is able to more specifically identify the server error preventing it from processing the event, it can send a 5xx status other than 500. The Hub SHALL send a SyncError indicating the event was not delivered.

The Hub MAY use these statuses to track synchronization state.

Event Notification Response Example

The id of the event notification and the HTTP status code is communicated from the Subscriber to Hub through the existing WebSocket channel, wrapped in a JSON object. Since the WebSocket channel does not have a synchronous request/response, this id is necessary for the Hub to correlate the response to the correct notification.

Field Optionality Type Description
id Required string Event identifier from the event notification to which this response corresponds.
status Required numeric HTTP status code Numeric HTTP response code to indicate success or failure of the event notification within the Subscriber. Any 2xx code indicates success, any other code indicates failure.
{
  "id": "q9v3jubddqt63n1",
  "status": "200"
}

Event Notification Sequence

Event notification flow diagramDriving App Driving App FHIRcastHubFHIRcastHubApp1(Subscriber)App1(Subscriber)App2(Subscriber)App2(Subscriber)request context changeHub is notified ofa context change.Event Notificationcontext change is confirmed{ "id": "q9v3jubddqt63n1", "status": "200"}Event Notificationcontext is changed{ "id": "q9v3jubddqt63n1", "status": "200"}Event Notificationcontext is changed{ "id": "q9v3jubddqt63n1", "status": "200"}
Figure: Event Notification Sequence

Event Notification Errors

If the Subscriber cannot follow the context of the event, for instance due to an error or a deliberate choice to not follow a context, the Subscriber SHALL communicate the error to the Hub in one of two ways.

  • Responding to the event notification with an HTTP error status code as described in Event Notification Response.
  • Responding to the event notification with an HTTP 202 (Accepted) as described above, then, once experiencing the error or refusing the change, send a SyncError event to the Hub. If the Subscriber cannot determine whether it will follow context within 10 seconds after reception of the event it SHOULD send a SyncError event.

If the Hub receives an error notification from a Subscriber, it SHALL generate a SyncError event to the other Subscribers of that topic. SyncError events are like other events in that they need to be subscribed to in order for a Subscriber to receive the notifications and they have the same structure as other events, the context being a single FHIR OperationOutcome resource.

The figure below illustrates the Event Notification Error Sequence.

Event notification error flow diagramDriving App Driving App FHIRcastHubFHIRcastHubApp1(Subscriber)App1(Subscriber)App2(Subscriber)App2(Subscriber)request context changeHub is notified ofa context change.Event Notificationcontext change is confirmed{ "id": "q9v3jubddqt63n1", "status": "200"}Event NotificationApplication is unable tofollow context andresponds with a 409 'conflict'{ "id": "q9v3jubddqt63n1", "status": "409"}Event Notificationcontext is changed{ "id": "q9v3jubddqt63n1", "status": "200"}Subscribing applications are made awarethat one of the subscribed applicationsis outof sync. Clien can choose to rollback, notifyuser or with an implementation specific response.Event notification [SyncError]Event notification [SyncError]Event notification [SyncError]
Figure: Event Notification Error Sequence

More information on the source of notification errors and how to resolve them can be found in Synchronization Considerations.

Hub Generated SyncError Events

In addition to distributing SyncError events sent by one Subscriber to other Subscribers, the Hub MAY generate and communicate SyncError events to Subscribers under the following conditions:

  1. A Subscriber's WebSocket connection is closed with any Connection Close Reason other than 1000 (normal closure) or 1001 (going away) (see WebSocket RFC and WebSocket Status Codes)

  2. A Subscriber does not respond to a FHIRcast event within 10 seconds or an order of magnitude lower than the subscription time-out.

Implementer input is solicited on the amount and specificity of time, in the above.

As with all FHIRcast events, SyncError events are distributed only to Subscribers which have subscribed to them.

Upon communicating a SyncError resulting from an unresponsive Subscriber, the Hub SHALL unsubscribe the Subscriber.

The Hub SHALL NOT generate SyncError events in the following situations:

  1. A Subscriber closes its WebSocket connection to the Hub with a Connection Close Reason of 1000 (normal closure) or 1001 (going away).

During a normal shutdown of a Subscriber, it SHALL unsubscribe, and provide a WebSocket Connection Close Reason of 1000 and not rely upon the Hub recognizing and unsubscribing it as an unresponsive Subscriber.

Implementer feedback is solicited on Hub Generated `SyncError` Events particularly on the following topics:
  • after the first time a Hub has distributed a SyncError indicating that a Subscriber is not responsive, should the nonresponsive Subscriber be automatically unsubscribed (removed from the Hub's list of Subscribers of the topic)? This would avoid SyncError events being sent after subsequent operations; however, it may conflict with the approach of SyncError events generated by the Hub only being distributed to Subscribers of the event which triggered the SyncError event to be generated.
  • should SyncError events generated by the Hub be distributed only to Subscribers of the event which triggered the SyncError event to be generated? However, this could conflict with automatically unsubscribing a non-responsive Subscriber after the initial SyncError is generated and distributed.
  • should all FHIRcast requests trigger SyncError events to be generated by the Hub for an unresponsive Subscriber or only when a context change is requested ([FHIR Resource]-open or [FHIR Resource]-close)?

Hub Generated open Events

This capability is experimental.

If a Hub grants subscriptions to different sets of hub.events to different Subscribers for the same session, the Hub is responsible for generation of implied open events. Close events are typically not generated by the Hub. When distributing a received event, a Hub SHALL ensure open events for the referenced resource types of the received event are also sent to subscribers. Hubs SHOULD either support derived events or require that Subscribers are subscribed to the same context. Hubs SHOULD NOT generate and send duplicative events.