Integrated Reporting Applications
1.0.0 - Trial-Implementation
This page is part of the Integrated Reporting Applications (v1.0.0: Publication) based on FHIR v5.0.0. This is the current published version. For a full list of available versions, see the Directory of published versions
This transaction is used to subscribe to receive events associated with a reporting session. A reporting session may include reporting on multiple reports, each of which has its own context.
The roles in this transaction are defined in the following table and may be played by the actors shown here:
Table 2:4.146.2-1: Actor Roles
Role | Description | Actor(s) |
---|---|---|
Subscriber | Requests a subscription to a reporting session | Image Display Report Creator Worklist Client Evidence Creator Stateless Evidence Creator Watcher |
Manager | Receives and manages subscription requests | Hub |
FHIRcast: Subscribing to Events
Figure 2:4.146.4-1: Interaction Diagram
The Subscriber sends a reporting session subscription request to the Manager.
The Subscriber shall support sending such messages to more than one Manager. The Manager shall support handling such messages from more than one Subscriber.
A Subscriber uses this transaction when:
This message is a FHIRcast Subscription Request. The Subscriber is the FHIRcast Subscriber. The Manager is the FHIRcast Hub.
The request shall have the payload with the parameters in the following table:
Table 2:4.146.4.1.2-1: Subscription Request Parameters
Field | Optionality | Type | Description |
---|---|---|---|
hub.channel.type |
Required | string | The channel type of websocket . |
hub.mode |
Required | string | The literal string subscribe . |
hub.topic |
Required | string | The identifier of the reporting session that the Subscriber wishes to subscribe to. |
hub.events |
Required* | string | Shall include these five events, comma-separated: diagnosticreport-open ,diagnosticreport-close ,diagnosticreport-update , diagnosticreport-select ,syncerror The Subscriber may include other events. |
hub.lease_seconds |
Optional | number | The positive integer indicating the number of seconds that the Subscriber wants the subscription to be active. |
hub.channel.endpoint |
Conditional | string | The WSS URL identifying an existing WebSocket subscription. Required if the Subscriber wants to update or renew an existing subscription. |
subscriber.name |
Required* | string | An explicit identifier of the Subscriber which is likely to be unique in a reporting session. |
Note: Rows with ‘*’ in the Optionality column have constraints different from baseline FHIRcast Subscription Request.
The Manager shall receive and validate the message.
The Manager shall create the reporting session if the session ID specified in hub.topic
does not exist.
The Manager shall add the Subscriber and its subscribed events for the session.
The Manager shall accept any events (including custom events not defined in FHIRcast Event Library) specified in the hub.events
attributes.
If the Subscriber already exists in the session, then the Manager shall:
The Manager sends a response message describing the request outcome to the Subscriber.
The Manager receives a Subscription Request message.
This message is a FHIRcast Subscription Response. The Subscriber is the FHIRcast Subscriber. The Manager is the FHIRcast Hub.
The Manager shall return 400
Bad Request error if:
hub.channel.type
is not websocket
hub.topic
is emptyhub.mode
is subscribe
and there is no hub.events
or its value is emptysubscriber.name
is emptyThe Manager may return other applicable HTTP error status codes.
If the HTTP response code is 202
Accepted, the Subscriber shall extract the websocket WSS URL from hub.channel.endpoint
.
The Subscriber may use the hub.channel.endpoint
in a subsequent Connect to Notification Channel [RAD-147] transaction and subsequent subscription update, renewal or Unsubscribe Session [RAD-152] requests.
If the HTTP response code is 4xx or 5xx, then the Subscriber may adjust the request and retry.
See IRA Security Considerations.
The Subscriber which is a synchronizing application should authenticate and authorize the starting application before it accepts the provided hub.topic
and hub.url
and sends this request.
Local policy should consider what users and systems have permissions to subscribe to events and configure appropriately. More advanced implementations of the Manager might have logic to identify Subscribers that are requesting unnecessarily broad set of events.
Managers that support the ATNA Profile shall audit this transaction.
This transaction corresponds to a Query Information ATNA Trigger Event.