Document Subscription for Mobile (DSUBm)
1.0.1-current - ci-build
Document Subscription for Mobile (DSUBm)
1.0.1-current - ci-build
Document Subscription for Mobile (DSUBm), published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.1-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.DSUBm/ and changes regularly. See the Directory of published versions
This section corresponds to the Resource Notify [ITI-112] transaction of the IHE Technical Framework. The Resource Notify [ITI-112] transaction is used by the Resource Notification Broker and Resource Notification Recipient.
The Resource Notify [ITI-112] transaction delivers a notification from the Resource Notification Broker to the Resource Notification Recipient about an event which matches an existing subscription.
The notifications from the Resource Notification Broker also include the Handshake Notification and the Heartbeat Notification in order to verify the reachability of the Resource Notification Recipient in the subscription activation process and during the existence of the subscription itself.
Further, the Subscription Deactivation Notification can be sent to inform about the deactivation of the Subscription.
Table 2:3.112.3-1: Actor Roles
| Actor | Role |
|---|---|
| Resource Notification Broker | Sends the Notification Bundle Request to the Resource Notification Recipient |
| Resource Notification Recipient | Receives the notification |
FHIR-R4 HL7 FHIR Release 4.0.1
This message uses the HTTP POST method on the target Resource Notification Recipient endpoint to submit the Handshake Notification.
In order to verify the reachability of the Resource Notification Recipient in the subscription activation process, after receiving a Create Subscription Request Message [ITI-110], the Resource Notification Broker will trigger this message to the corresponding Resource Notification Recipient.
The Resource Notification Broker SHALL initiate an HTTP POST request message to submit a Bundle FHIR Resource.
The Bundle resource SHALL be compliant with Bundle and SHALL be compliant with R4B Topic-Based Subscription Notification Bundle.
The Resource Notification Subscriber actor SHALL submit the FHIR Bundle resource in either XML format or JSON format thus the media type of the HTTP body SHALL be either application/fhir+json or application/fhir+xml respectively. The format SHALL match the MIME type on the Subscription.channel.payload element.
The Bundle is sent to the URL present in the Subscription.channel.endpoint element, that identifies where the Resource Notification Recipient receives the notification.
It is possible to use HTTP protocol or HTTPS protocol. The HTTPS protocol is highly recommended.
The Bundle Resource sent by the Resource Notification Broker SHALL have:
Bundle.type element set to history;Bundle.entry with the Handshake Subscription Status resource and the Bundle.entry.request element SHALL be filled out to match a request to the $status operation;The Resource Notification Recipient processes the message according to application-defined rules and produces a Handshake Notification Response.
If the Resource Notification Broker has not been able to send the Handshake Notification Message because of connection problem, it SHALL NOT activate the Subscription and set the Subscription.status=error.
If the Resource Notification Broker has been able to send the Handshake Notification Message but it has not received any Handshake Notification Response from the Resource Notification Recipient, it SHALL NOT activate the Subscription and set the Subscription.status=error.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
The Resource Notification Recipient sends a Handshake Notification Response to respond to an Handshake Notification Message.
When the Resource Notification Recipient receives the Handshake Notification Message from the Resource Notification Broker, it send this message to acknowledging the reception of the notification.
When the Resource Notification Recipient has processed the request it SHALL return an HTTP response with an overall status code.
If the processing of the request message is successful the Resource Notification Recipient SHALL return a 200 OK HTTP status code and the http response body SHALL be empty.
Otherwise the Resource Notification Recipient SHALL return a status code 4xx or 5xx, according to application-defined rules. In this case, the http response body MAY contain an OperationOutcome Resource with the description of the problem.
The Resource Notification Broker processes the message according to application-defined rules.
If the Resource Notification Broker receives a positive response, it SHALL activate the Subscription that triggered the handshake process, setting the Subscription.status=active.
If the Resource Notification Broker receives a negative response (based on HTTP status), it SHALL NOT activate the Subscription and it SHALL set the Subscription.status=error.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
This message uses the HTTP POST method on the target Resource Notification Recipient endpoint to submit the Heartbeat Notification in order to verify the reachability of the Resource Notification Recipient.
In order to verify the reachability of the Resource Notification Recipient during the existence of the Subscription, after its activation, the Resource Notification Broker will trigger this message to the corresponding Resource Notification Recipient. If in the Subscription the heartbeatPeriod element is set, the Resource Notification Broker SHOULD attempt to send a Heartbeat Notification Message after each interval set in that element.
The Resource Notification Broker SHALL initiate an HTTP POST request message to submit a Bundle FHIR Resource.
The Bundle resource SHALL be compliant with Bundle and SHALL be compliant with R4 Topic-Based Subscription Notification Bundle.
The Resource Notification Subscriber SHALL submit the FHIR Bundle resource in either XML format or JSON format thus the media type of the HTTP body SHALL be either application/fhir+json or application/fhir+xml respectively. The format SHALL match the MIME type on the Subscription.channel.payload element.
The Bundle is sent to the URL present in Subscription.channel.endpoint element, that identifies where the Resource Notification Recipient receives the notification.
It is possible to use HTTP protocol or HTTPS protocol. The HTTPS protocol is highly recommended.
The Bundle Resource sent by the Resource Notification Broker SHALL have:
Bundle.type element set to history;request element SHALL be filled out to match a request to the $status operation;The Resource Notification Recipient processes the message according to application-defined rules and produces a Heartbeat Notification Response.
If the Resource Notification Broker has not been able to send the Heartbeat Notification Message because of connection problem, it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
If the Resource Notification Broker has been able to send the Heartbeat Notification Message but it has not received any Heartbeat Notification Response Message from the Resource Notification Recipient, it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
The Resource Notification Recipient sends a Heartbeat Notification Response to respond to a Heartbeat Notification Message.
When the Resource Notification Recipient receives the Heartbeat Notification Message from the Resource Notification Broker, it send this message to acknowledge the reception of the notification.
When the Resource Notification Recipient has processed the request it SHALL return an HTTP response with an overall status code.
If the processing of the request message is successful the Resource Notification Recipient SHALL return a 200 OK HTTP status code and the http response body SHALL be empty.
Otherwise the Resource Notification Recipient SHALL return a status code 4xx or 5xx, according to application-defined rules. In this case, the http response body MAY contain an OperationOutcome Resource with the description of the problem.
The Resource Notification Broker processes the message according to application-defined rules.
If the Resource Notification Broker receives a negative response (based on the HTTP status or the OperationOutcome received), it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
This message uses the HTTP POST method on the target Resource Notification Recipient endpoint to submit the Event Notification.
When an event occurs where the topics of the event match the filter requirements of one or more active Subscriptions, the Resource Notification Broker SHALL trigger this message to the corresponding Resource Notification Recipient.
The Resource Notification Broker SHALL initiate an HTTP POST request message to submit a Bundle FHIR Resource.
The Bundle resource SHALL be compliant with Bundle and SHALL be compliant with the R4 Topic-Based Subscription Notification Bundle.
The Resource Notification Subscriber SHALL submit the FHIR Bundle resource in either XML format or JSON format thus the media type of the HTTP body SHALL be either application/fhir+json or application/fhir+xml respectively. The format SHALL match the MIME type on the Subscription.channel.payload element.
The Bundle is sent to the URL present in Subscription.channel.endpoint element, that identifies where the Resource Notification Recipient receives the notification.
It is possible to use HTTP protocol or HTTPS protocol. The HTTPS protocol is highly recommended.
The Bundle Resource sent by the Resource Notification Broker SHALL have:
Bundle.type element set to history;request element SHALL be filled out to match a request to the $status operation;Subscription.payload.content and the notificationShape defined in the Topic of the Subscription; for additional entries, the request SHOULD be filled out in a way that makes sense given the Subscription (e.g., a POST or PUT operation on the resource, matching the event happened to that resource that trigger the notification). However, a Resource Notification Broker MAY choose to simply include a GET to the relevant resource instead.When the payload content includes the resources, the notification shape SHALL be based on the definitions from the Topic of the Subscription:
Note that Resource Notification Broker SHOULD attempt to provide the resources described in the topic, however Resource Notification Recipient SHALL expect that any resource beyond the focus resource are not guaranteed to be present.
The Resource Notification Recipient processes the message according to application-defined rules and produces an Event Notification Response.
If the Resource Notification Broker has not been able to send the Event Notification Message because of connection problem, it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
If the Resource Notification Broker has been able to send the Event Notification Message but it has not received any Event Notification response Message from the Resource Notification Recipient, it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
The Resource Notification Recipient sends an Event Notification Response to respond to an Event Notification Message.
When the Resource Notification Recipient receives the Event Notification Message from the Resource Notification Broker, it send this message to acknowledge the reception of the notification.
When the Resource Notification Recipient has processed the request it SHALL return an HTTP response with an overall status code.
If the processing of the request message is successful the Resource Notification Recipient SHALL return a 200 OK HTTP status code and the http response body SHALL be empty.
Otherwise the Resource Notification Recipient SHALL return a status code 4xx or 5xx, according to application-defined rules. In this case, the http response body MAY contain an OperationOutcome Resource with the description of the problem.
The Resource Notification Broker processes the message according to application-defined rules.
If the Resource Notification Broker receives a negative response (based on the HTTP status or the OperationOutcome received), it SHOULD immediately set the Subscription.status=error or it could do that after a reasonable number of times. This SHOULD be done based on the capability of the connection infrastructure.
Further consideration on managing errors are reported in Section 2:3.112.4.9 Handling Errors in Notification.
This message uses the HTTP POST method on the target Resource Notification Recipient endpoint to submit the notification.
When a Subscription deactivation occurs the Resource Notification Broker SHOULD trigger this message to the corresponding Resource Notification Recipient, in order to inform that the Subscription is no longer active.
The deactivation, Subscription.status=off, could be performed:
The Resource Notification Broker SHALL initiate an HTTP POST request message to submit a Bundle FHIR Resource.
The Bundle resource SHALL be compliant with Bundle and SHALL be compliant with the R4 Topic-Based Subscription Notification Bundle.
The Resource Notification Subscriber SHALL submit the FHIR Bundle resource in either XML format or JSON format thus the media type of the HTTP body SHALL be either application/fhir+json or application/fhir+xml respectively. The format SHALL match the MIME type on the Subscription.channel.payload element.
The Bundle is sent to the URL present in Subscription.channel.endpoint element, that identifies where the Resource Notification Recipient receives the notification.
It is possible to use HTTP protocol or HTTPS protocol. The HTTPS protocol is highly recommended.
The Bundle Resource sent by the Resource Notification Broker SHALL have:
Bundle.type set to history;request element SHALL be filled out to match a request to the $status operation;The Resource Notification Recipient processes the message according to application-defined rules and produces an Subscription Deactivation Response.
If the Resource Notification Recipient is grouped with the Resource Notification Subscriber, the Resource Notification Subscriber SHOULD be aware if this notification received is related to its own unsubscribe, if it is related to an unsubscribe performed by another Resource Notification Subscriber, or it is related to deactivation performed by the Resource Notification Broker at the expiration time of the Subscription, and then proceeds according to its application-defined rules.
The Resource Notification Recipient sends an Event Notification Response to respond to a Subscription Deactivation Message.
When the Resource Notification Recipient receives the Subscription Deactivation Message from the Resource Notification Broker, it send this message to acknowledge the reception of the notification.
When the Resource Notification Recipient has processed the request it SHALL return an HTTP response with an overall status code.
If the processing of the request message is successful the Resource Notification Recipient SHALL return a 200 OK HTTP status code and the http response body SHALL be empty.
Otherwise the Resource Notification Recipient SHALL return a status code 4xx or 5xx, according to application-defined rules. In this case, the http response body MAY contain an OperationOutcome Resource with the description of the problem.
The Resource Notification Broker processes the message according to application-defined rules.
After setting the Subscription.status=error, the Resource Notification Broker SHOULD continue to send other Heartbeat Notification Request Message with status=error and it MAY continue to send other Event Notification Request Message (if events occur) with status=error. The RECOMMENDED way for the Resource Notification Broker to proceed is to continue to send Heartbeat Notification Request Message and Event Notification Request Message for a implementation defined number of times, and evaluating if errors continue to occur in notifications before totally deactivating the Subscription, setting the Subscription.status=off. This SHOULD be done based on the capability of the connection infrastructure. Note that, if the Resource Notification Broker is grouped with DSUB Document Metadata Subscriber and DSUB Document Metadata Notification Recipient, considering DSUBm as an interface for DSUB model, when it deactivates the Subscription it SHALL follow what is define in Section 2:3.110.4.3.3.1 Expected Actions with DSUBm as an interface for DSUB for unsubscribe.
If the Resource Notification Recipient is grouped with the Resource Notification Subscriber in an application, the Resource Notification Subscriber MAY handle errors or broken connections by using the $events and $status operations on the transaction Resource Subscription Search [ITI-113] and following what is defined in Detecting Errors as a Subscriber, Broken Communication and Recovering from Errors sections of the Subscriptions R5 Backport. Moreover, once the application has returned to a functional state, Resource Notification Subscriber SHOULD request the subscription is re-activated sending a Update Subscription Request Message to the Resource Notification Broker.
The Resource Notification Broker implementing this transaction SHALL provide a CapabilityStatement Resource as described in ITI TF-2: Appendix Z.3 indicating the transaction has been implemented. The possible CapabilityStatements for the Resource Notification Broker are listed in Section 1:54.1.1.1 Resource Notification Broker.
The Resource Notification Recipient implementing this transaction SHALL provide a CapabilityStatement Resource as described in ITI TF-2: Appendix Z.3 indicating the transaction has been implemented. The possible CapabilityStatements for the Resource Notification Recipient are listed in Section 1:54.1.1.4 Resource Notification Recipient.
See DSUBm Security Considerations.
The Resource Notification Broker SHOULD confirm that the Resource Notification Recipient is still authorized to receive the information that it is searching for. To assess if a Resource Notification Recipient is still authorized to receive the information the Resource Notification Broker MAY utilize additional policy defined between the actors in order to prevent the sending of notifications in particular cases. If an authorization token is used to verify the authorization of a Recipient to receive notifications, the Resource Notification Broker SHALL also verify that this token has not been revoked before sending the Notification Bundle Request message.
It is highly RECOMMENDED that the Resource Notification Broker SHOULD use some form of authentication method when sending a notification Message and the Resource Notification Recipient SHOULD always verify the authentication token used in this transaction.
The Resource Notification Recipient SHOULD also be defensive and robust to a malicious client that MAY send a large volume of fake notifications with empty notifications, which would cause the Resource Notification Recipient to send many (potentially expensive) queries to a server.
The Resource Notification Broker, when grouped with ATNA Secure Node or Secure Application Actor, SHALL be able to record fundamental AuditEvents for Resource Notification Broker Notify, when performing this transaction.
The Resource Notification Recipient, when grouped with ATNA Secure Node or Secure Application Actor, SHALL be able to record fundamental AuditEvents for Resource Notification Recipient Notify, when performing this transaction.
IG © 2023+ IHE IT Infrastructure Technical Committee. Package ihe.iti.dsubm#1.0.1-current based on FHIR 4.0.1. Generated 2024-10-21
Links: Table of Contents |
QA Report
| New Issue | Issues
Version History |
|
Propose a change