Document Subscription for Mobile (DSUBm)
1.0.1-current - ci-build International flag

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

2:3.111 Resource Publish [ITI-111]

This section corresponds to the Resource Publish [ITI-111] transaction of the IHE Technical Framework. The Resource Publish [ITI-111] transaction is used by the Resource Notification Publisher and Resource Notification Broker Actors. This transaction is used to communicate events about DocumentReference, Folder type List and SubmissionSet type List Resources.

2:3.111.1 Scope

The Resource Publish [ITI-111] transaction delivers information from the Resource Notification Publisher to the Resource Notification Broker about events regarding DocumentReference, Folder type List and SubmissionSet type List resources. This information can be evaluated by the Resource Notification Broker against active Subscriptions and which MAY trigger a notification.

2:3.111.2 Actors Roles

Table 2:3.111.2-1: Actor Roles

Actor Role
Resource Notification Publisher Publishes information to the Resource Notification Broker when applicable events occur about DocumentReference, Folder type List and SubmissionSet type List resources for which a subscription MAY exist
Resource Notification Broker Receives and processes information about events for which there MAY be a subscription

2:3.111.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0.1

2:3.111.4 Messages

Resource Notification PublisherResource Notification BrokerResource Publish Request MessageResource Publish Response Message
Figure 2:3.111.4-1: Resource Publish [ITI-111] Interactions


2:3.111.4.1 Resource Publish Request Message

This method uses an HTTP POST method on the target Resource Notification Broker endpoint to communicate a event that MAY have a subscription.

2:3.111.4.1.1 Trigger Events

When an event occurs for which a Subscription MAY exist, the Resource Notification Publisher will trigger a Resource Publish Request message to the Resource Notification Broker. The basic events that could trigger this message are:

  • creation of a DocumentReference Resource;
  • creation of a SubmissionSet type List Resource.

Note that these events could be determined by DocumentEntry and SubmissionSet Objects events in an XDS environment.

2:3.111.4.1.1.1 DocumentReference Subscription for Minimal Update Option Trigger Events

When the Resource Notification Publisher supports the DocumentReference Subscription for Minimal Update Option, in addition to the basic events, events that could trigger this message also are:

  • update of the status of a DocumentReference Resource,
  • deletion of a DocumentReference Resource.

Note that also these events could be determined by DocumentEntry Objects events in an XDS environment.

2:3.111.4.1.1.2 DocumentReference Subscription for Full Events Option Trigger Events

When the Resource Notification Publisher supports the DocumentReference Subscription for Full Events Option, in addition to the basic events, events that could trigger this message also are:

  • update of a DocumentReference Resource,
  • deletion of a DocumentReference Resource.

Note that also these events could be determined by DocumentEntry Objects events in an XDS environment.

2:3.111.4.1.1.3 Basic Folder Subscription Option Trigger Events

When the Resource Notification Publisher supports the Basic Folder Subscription Option, in addition to the basic events, events that could trigger this message also are:

  • creation of a Folder type List Resource,
  • update of a Folder type List Resource to insert a new document in the Folder.

Note that also these events could be determined by Folder and Association Objects events in an XDS environment.

2:3.111.4.1.1.4 Folder Subscription for Minimal Update Option Trigger Events

When the Resource Notification Publisher supports the Folder Subscription for Minimal Update Option, in addition to the basic events, events that could trigger this message also are:

  • creation of a Folder type List Resource,
  • only the update of a Folder type List Resource to insert a new document in the Folder,
  • only the update of a Folder type List Resource to remove a document from the Folder,
  • only the update of a Folder type List Resource to update the “status”.

Note that also these events could be determined by Folder and Association Objects events in an XDS environment.

2:3.111.4.1.1.5 Folder Subscription for Update Option Trigger Events

When the Resource Notification Publisher supports the Folder Subscription for Update Option, in addition to the basic events, events that could trigger this message also are:

  • creation of a Folder type List Resource,
  • update of a Folder type List Resource.

Note that also these events could be determined by Folder and Association Objects events in an XDS environment.

2:3.111.4.1.1.6 Folder Subscription for Full Events Option Trigger Events

When the Resource Notification Publisher supports the Folder Subscription for Full Events Option, in addition to the basic events, events that could trigger this message also are:

  • creation of a Folder type List Resource,
  • update of a Folder type List Resource,
  • deletion of a Folder type List Resource.

Note that also these events could be determined by Folder and Association Objects events in an XDS environment.

2:3.111.4.1.2 Message Semantics

The Resource Notification Publisher SHALL initiate a FHIR “transaction” using a “create” action by sending an HTTP POST request method composed of a FHIR Bundle Resource containing: one SubmissionSet type List Resource; zero or more DocumentReference Resources; zero or more Folder type List Resources.

The Bundle resource SHALL contain all the FHIR resources related to the event that has occurred in the Bundle.entry element.

The media type of the HTTP body SHALL be either application/fhir+json or application/fhir+xml.

See http://hl7.org/fhir/R4/http.html#transaction for complete requirements of a transaction. See http://hl7.org/fhir/R4/bundle-transaction.html for example of a transaction Bundle.

The Provide Document Bundle message is sent to the base URL as defined in FHIR. See http://hl7.org/fhir/R4/http.html for the definition of “HTTP” access methods and “base”.

It is possible to use HTTP protocol or HTTPS protocol. The HTTPS protocol is highly recommended.

For complete information on constructing a FHIR Bundle Resource, see http://hl7.org/fhir/R4/bundle.html.

For the basic events, the FHIR Bundle SHALL be conform to the Minimal Metadata Bundle of Provide Document Bundle [ITI-65] transaction of MHD Profile.

2:3.111.4.1.2.1 DocumentReference Subscription for Minimal Update Option Bundle

When supported the DocumentReference Subscription for Minimal Update Option the FHIR Bundle that SHALL be used for transmitting the DocumentReference Subscription for Minimal Update Trigger Events SHALL have the following constraints:

2:3.111.4.1.2.2 DocumentReference Subscription for Full Events Option Bundle

When the DocumentReference Subscription for Full Events Option is supported the FHIR Bundle that SHALL be used for transmitting the DocumentReference Subscription for Full Events Option Trigger Events SHALL be the Extended Publishing Bundle.

2:3.111.4.1.2.3 Subscription with Basic Folder Subscription Option Bundle

When the Basic Folder Subscription Option is supported the FHIR Bundle that SHALL be used for transmitting the Subscription with Basic Folder Subscription Option Trigger Events SHALL be conform to the Minimal Metadata Bundle of Provide Document Bundle [ITI-65] transaction of MHD Profile.

2:3.111.4.1.2.4 Folder Subscription for Minimal Update Option Bundle

When the Folder Subscription for Minimal Update Option is supported the FHIR Bundle that SHALL be used for transmitting the Folder Subscription for Minimal Update Option Trigger Events SHALL be conform to the Minimal Metadata Bundle of Provide Document Bundle [ITI-65] transaction of MHD Profile.

2:3.111.4.1.2.5 Folder Subscription for Update Option Bundle

When the Folder Subscription for Update Option is supported the FHIR Bundle that SHALL be used for transmitting the Folder Subscription for Update Option Trigger Events SHALL be conform to the Minimal Metadata Bundle of Provide Document Bundle [ITI-65] transaction of MHD Profile.

2:3.111.4.1.2.6 Folder Subscription for Full Events Option Bundle

When the Folder Subscription for Full Events Option is supported the FHIR Bundle that SHALL be used for transmitting the Folder Subscription for Full Events Option Trigger Events SHALL be the Extended Publishing Bundle.

2:3.111.4.1.3 Expected Actions

The Resource Notification Broker SHALL accept both media types application/fhir+json and application/fhir+xml.

The Resource Notification Broker SHALL process the bundle atomically as specified in http://hl7.org/fhir/R4/http.html#transaction.

The Resource Notification Broker SHALL validate the Bundle first against the FHIR specification. Guidance on what FHIR considers a valid Resource can be found at http://hl7.org/fhir/R4/validation.html.

If necessary for processing, the Resource Notification Broker SHALL retrieve Resources referenced by absolute URLs in the FHIR Bundle Resource.

If the Resource Notification Broker validations failed, the Resource Notification Broker SHALL return an error, as documented in Resource Publish Response Message.

If the validation of the Resource Publish Request Message is completed, the Resource Notification Broker SHALL evaluate the DocumentReference, the Folder type List and the SubmissionSet type List Resources that are present in the Bundle against the active Subscriptions. The Resource Notification Broker MAY not care about the other resources present in the Bundle. If there are matching subscriptions, the Resource Notification Broker SHALL send the Event Notification Message [ITI-112] to the appropriate Resource Notification Recipient.

2:3.111.4.2 Resource Publish Response Message

The Resource Notification Broker sends a Resource Publish Response Message to respond to a Resource Publish Request Message.

2:3.111.4.2.1 Trigger Events

The Resource Notification Broker has received a Resource Publish Request Message.

2:3.111.4.2.2 Message Semantics

The Resource Notification Broker SHALL return a Bundle, with type set to transaction-response, that contains one entry for each entry in the request, in the same order as received, with the Bundle.entry.response.outcome indicating the results of processing the entry. TheResource Notification Broker SHALL comply with FHIR http://hl7.org/fhir/R4/bundle.html#transaction-response and http://hl7.org/fhir/R4/http.html#transaction-response.

To indicate success the overall http 200 response is used. The Bundle.entry.response.status SHALL be 201 and the location element SHALL be populated if the Resource has been created or deleted. The Bundle.entry.response.status SHALL be 200 and the location element SHALL be populated if the Resource has been updated.

2:3.111.4.2.3 Expected Actions

The Resource Notification Publisher processes the results according to application-defined rules.

2:3.111.5 CapabilityStatement Resource

The Resource Notification Publisher implementing this transaction SHALL provide a CapabilityStatement Resource as described in ITI TF-2x: Appendix Z.3 indicating the transaction has been implemented. The possible CapabilityStatements for the Resource Notification Publisher are listed in Section 1:54.1.1.3 Resource Notification Publisher.

The Resource Notification Broker implementing this transaction SHALL provide a CapabilityStatement Resource as described in ITI TF-2x: 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.

2:3.111.6 Security Considerations

See DSUBm Security Considerations.

It is highly RECOMMENDED that the Resource Notification Publisher SHOULD use some form of authentication method when sending the Resource Publish Request Message. The Resource Notification Broker SHOULD always verify the authentication token used in this transaction before considering the message received.

2:3.111.6.1 Security Audit Considerations

The Resource Notification Publisher, when grouped with ATNA Secure Node or Secure Application Actor, SHALL be able to record fundamental AuditEvents for Resource Notification Publisher Publish, when performing this transaction.

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 Publish, when performing this transaction.