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:

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:

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.

{
  "id": "q9v3jubddqt63n1",
  "status": "200"
}

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.

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 fails to respond to a Heartbeat.html event (because occasional missed Heartbeat.htmls are expected and are not a context synchronization failure).
2. 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

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 NOT generate and send duplicative events.