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.110 Resource Subscription [ITI-110]

This section corresponds to the Resource Subscription [ITI-110] transaction of the IHE Technical Framework. The Resource Subscription [ITI-110] transaction is used by the Resource Notification Subscriber and Resource Notification Broker Actors to submit a subscription in order to receive a notification.

2:3.110.1 Scope

The Resource Subscription [ITI-110] transaction passes a Resource Subscription Request from a Resource Notification Subscriber to a Resource Notification Broker. This transaction can be used to create a new Subscription or to update an existing Subscription. The update of the subscription is intended to be used only to unsubscribe (deactivate) an existing Subscription or re-activate an already existing Subscription (in case of errors or deactivation).

2:3.110.2 Actors Roles

Table 2:3.110.2-1: Actor Roles

Actor Role
Resource Notification Subscriber Sends the Subscription request to the Resource Notification Broker
Resource Notification Broker Receives and processes the Subscription request

2:3.110.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0.1

2:3.110.4 Messages

Resource Notification SubscriberResource Notification BrokerSubscribeCreate Subscription Request Messagealt[if successfully evaluated]Create Subscription Response Message[if unsuccessfully evaluated]Subscription Error Response MessageUpdateUpdate Subscription Request Messagealt[if successfully evaluated]Update Subscription Response Message[if unsuccessfully evaluated]Subscription Error Response Message
Figure 2:3.110.4-1: Resource Subscription [ITI-110] Interactions


2:3.110.4.1 Create Subscription Request Message

This message uses the HTTP POST method on the target Resource Notification Broker endpoint to submit the Subscription resource.

2:3.110.4.1.1 Trigger Events

This method is invoked when the Resource Notification Subscriber needs to submit a new subscription resource to the Resource Notification Broker. The Resource Notification Subscriber SHALL have already discovered the SubscriptionTopics supported by the Resource Notification Broker in order to create a subscription. The discovery SHOULD be performed by the Resource SubscriptionTopic Search [ITI-114] transaction or MAY be performed by any other methods that are out of the scope of this profile.

2:3.110.4.1.2 Message Semantics

The Resource Notification Subscriber SHALL initiate an HTTP request according to the requirements defined in the HL7® FHIR® standard for the “create” interaction. The message uses an HTTP POST method to submit a Subscription FHIR Resource as specified in 3.110.5.2.1 Subscription Resource paragraph.

The Resource Notification Subscriber SHALL submit the FHIR Subscription 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 Subscription 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.

2:3.110.4.1.2.1 Subscription Resource

The Subscription resource SHALL be compliant with the Subscription resource and SHALL be compliant with the Profile: R4/B Topic-Based Subscription.

The Subscription.criteria element SHALL include the canonical URL to a Basic resource that represents the Topic that the Subscription resource is related to. The Subscription.criteria element SHALL support the FilterBy Criteria extension. This extension SHALL be used to narrow the subscription triggering events defined in the topic represented in the Basic resource.

All the Subscription resources SHALL support the following extensions:

The Resource Notification Subscriber SHALL indicate in the Subscription.payload.content element the level of detail of the future notification that the Resource Notification Broker will send. The payload content extension defines three types of payload:

  • empty = No resource content is transmitted in the notification payload.
  • id-only = Only the resource id is transmitted in the notification payload.
  • full-resource = The entire resource is transmitted in the notification payload.

All the Subscription resources SHALL have Subscription.status="requested", channel.type = "rest-hook", and channel.endpoint SHALL contain the URL that identifies where the Resource Notification Recipient receives the notification.

All the Subscription resources MAY have Subscription.end element set, indicating the instant when the subscription automatically terminates.

For documents, different types of subscription resources MAY be submitted to the Resource Notification Broker.

This profile defines the following types of Subscriptions with related SubscriptionTopics, which the Resource Notification Broker SHALL support and the Resource Notification Subscriber SHALL support at least one of them:

Subscription type SubscriptionTopic
Patient-Dependent DocumentReference Subscription Patient-Dependent DocumentReference SubscriptionTopic
Multi-Patient DocumentReference Subscription Multi-Patient DocumentReference SubscriptionsTopic
Patient-Dependent SubmissionSet Subscription Patient-Dependent SubmissionSet SubscriptionTopic
Multi-Patient SubmissionSet Subscription Multi-Patient SubmissionSet SubscriptionTopic

2:3.110.4.1.2.1.1 Subscription with DocumentReference Subscription for Minimal Update Option

When supporting the DocumentReference Subscription for Minimal Update Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Patient-Dependent DocumentReference Subscriptions with DocumentReference Subscription for Minimal Update Option Patient-Dependent DocumentReference SubscriptionTopic with DocumentReference Subscription for Minimal Update Option
Multi-Patient DocumentReference Subscription DocumentReference Subscription for Minimal Update Option Multi-Patient DocumentReference SubscriptionTopic with DocumentReference Subscription for Minimal Update Option

2:3.110.4.1.2.1.2 Subscription with DocumentReference Subscription for Full Events Option

When supporting the DocumentReference Subscription for Full Events Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Patient-Dependent DocumentReference Subscriptions with DocumentReference Subscription for Full Events Option Patient-Dependent DocumentReference SubscriptionTopic with DocumentReference Subscription for Full Events Option
Multi-Patient DocumentReference Subscription with DocumentReference Subscription for Full Events Option Multi-Patient DocumentReference SubscriptionTopic with DocumentReference Subscription for Full Events Option

2:3.110.4.1.2.1.3 Subscription with Basic Folder Subscription Option

When supporting the Basic Folder Subscription Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Basic Folder Subscriptions Basic Folder SubscriptionTopic

2:3.110.4.1.2.1.4 Subscription with Folder Subscription for Minimal Update Option

When supporting the Folder Subscription for Minimal Update Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Folder Subscriptions with Folder Subscription for Minimal Update Option Folder SubscriptionTopic with Folder Subscription for Minimal Update Option

2:3.110.4.1.2.1.5 Subscription with Folder Subscription for Update Option

When supporting the Folder Subscription for Update Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Folder Subscriptions with Folder Subscription for Update Option Folder SubscriptionTopic with Folder Subscription for Update Option

2:3.110.4.1.2.1.6 Subscription with Folder Subscription for Full Events Option

When supporting the Folder Subscription for Full Events Option, this profile also defines the following types of Subscriptions with related SubscriptionTopics:

Subscription type SubscriptionTopic
Folder Subscriptions with Folder Subscription for Full Events Option Folder SubscriptionTopic with Folder Subscription for Full Events Option
2:3.110.4.1.3 Expected Actions

Upon receiving the request message the Resource Notification Broker SHALL verify the following conditions:

  • the Basic resource (that represents the topic which the Subscription resource is related to) referred in the Subscription.criteria element received in the Subscription resource is valid;
  • all requested filters are defined in the requested topic;
  • the channel-type is rest-hook;
  • the channel endpoint is valid for the channel provided (i.e., it is a valid URL, according with the data type);
  • the payload configuration is known and implemented by the server;
  • the payload configuration is valid for the channel type requested (e.g., complies with the Resource Notification Broker security policy);
  • the termination time (Subscription.end), if present, express a valid timestamp in the future.

The Resource Notification Broker shall enforce all the Security Considerations.

The Resource Notification Broker MAY enforce to not duplicate a Subscription on the basis of the information transmitted in the request message (e.g., criteria, endpoint, user authentication, etc.) in order to prevent multiple Subscriptions and Notifications.

Based on the outcome of the conditions above, the Resource Notification Broker SHALL accept or reject the subscription resource received. If one or more of the conditions are false the Resource Notification Broker SHALL reject the Subscription resource and respond with an error message, which is defined in Subscription Error Response Message [ITI-110]. Otherwise, the Resource Notification Broker SHALL accept the Subscription resource, create the subscription, respond with a success message, which is defined in Create Subscription Response Message [ITI-110] and proceed to performing the handshake process.

The Resource Notification Broker SHALL support the handshake process to verify that the endpoint that identifies the Resource Notification Recipient, in the Subscription.channel.endpoint element of the subscription resource, is reachable before effectively activating the subscription. The Resource Notification Broker SHALL set initial status to requested, pending verification of the nominated endpoint URL. Then, the Resource Notification Broker SHALL send to the Resource Notification Recipient a Handshake Notification Message [ITI-112]. After a successful handshake notification has been sent and accepted, the Resource Notification Broker SHALL update the status to active. Any errors in the initial handshake SHALL result in the status being changed to error. Note that the Resource Notification Subscriber SHOULD implement the Subscription Search [ITI-113] transaction in order to verify the activation of the subscription.

When the Subscription resource uses the heartbeatPeriod, if accepted, the Resource Notification Broker SHOULD send one Heartbeat Notification Message [ITI-112] per interval on the accepted and active subscription.

Once the Subscription is activated, the Resource Notification Broker SHALL monitor resources based on the Subscription criteria and, if matches, SHALL send the appropriate Resource Notification Recipient a Event Notification Message [ITI-112].

Further considerations needs to be done, for the activation of a Subscription, considering DSUBm as an interface for a DSUB environment.

2:3.110.4.1.3.1 Expected Actions with DSUBm as an interface for DSUB

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, if the subscription is accepted, the Resource Notification Broker SHALL also trigger a Subscribe Request message towards the DSUB Document Metadata Notification Broker from the DSUB Document Metadata Subscriber with an Document Metadata Subscribe [ITI-52] transaction.

The mapping between the Subscription resource contained in the Resource Subscription [ITI-110] transaction and the Document Metadata Subscribe [ITI-52] transaction SHALL be as following:

  • If the Subscription resource has a Subscription.payload = "full-resource" the Document Metadata Subscribe [ITI-52] transaction SHALL have a “ihe:FullDocumentEntry” Topic Expression. Otherwise a “ihe:MinimalDocumentEntry” Topic Expression SHALL be used.

  • Depending on the type of the Subscription, the AdHocQuery/@id attribute and the Filters parameter of the Document Metadata Subscribe [ITI-52] transaction SHALL be set as follows:

    Subscription type AdHocQuery/@id Filter parameter
    Patient-Dependent DocumentReference Subscriptions urn:uuid:aa2332d0-f8fe-11e0-be50-0800200c9a66 Mapping based on Table 2:3.110.4.7-1
    Multi-Patient DocumentReference Subscriptions urn:uuid:742790e0-aba6-43d6-9f1fe43ed9790b79 Mapping based on Table 2:3.110.4.7-1
    Patient-Dependent SubmissionSet Subscriptions urn:uuid:fbede94e-dbdc-4f6b-bc1f-d730e677cece Mapping based on Table 2:3.110.4.7-2
    Multi-Patient SubmissionSet Subscriptions urn:uuid:868cad3d-ec09-4565-b66c-1be10d034399 Mapping based on Table 2:3.110.4.7-2
    Basic Folder Subscriptions urn:uuid:9376254e-da05-41f5-9af3-ac56d63d8ebd Mapping based on Table 2:3.110.4.7-3

  • If the Subscription resource has the Subscription.end element set, the Document Metadata Subscribe [ITI-52] transaction SHALL have a wsnt:InitialTerminationTime element set.

When the Document Metadata Subscribe [ITI-52] transaction has a successful result, the Resource Notification Broker SHALL maintain the coupling between the Subscription Resource id and the webservice endpoint present in the Address element of the Document Metadata Subscribe [ITI-52] response message, in order to be capable of managing a later unsubscribe.

If the DSUB Document Metadata Notification Broker sends an assigned duration for the subscription, the Resource Notification Broker SHALL associate the assigned duration with the accepted subscription request and eventually unsubscribe towards the DSUB Document Metadata Notification Broker when expired.

2:3.110.4.2 Create Subscription Response Message

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

2:3.110.4.2.1 Trigger Events

When the Resource Notification Broker has finished successfully evaluating the subscription received and the operation, the Resource Notification Broker sends this message to the Resource Notification Subscriber acknowledging the result of the creation of the resource.

2:3.110.4.2.2 Message Semantics

The Resource Notification Broker SHALL respond with an HTTP 201 Created status code as indicated for “create” and the Resource Notification Broker SHALL return the entire resource in which the status SHALL be requested. If the Resource Notification Broker has assigned a termination time, the element end SHALL be set.

2:3.110.4.2.3 Expected Actions

The Resource Notification Subscriber processes the response according to application-defined rules.

For the Subscription creation:

  • If the Resource Notification Subscriber had not indicated a requested duration for the subscription, the Resource Notification Broker MAY send an assigned duration for the subscription (if any), using the Subscription.end element.

  • If the Resource Notification Broker sends an assigned duration for the subscription, the Resource Notification Subscriber SHALL associate the assigned duration with the accepted subscription request.

  • The Resource Notification Subscriber SHALL associate the accepted subscription request with the subscription id assigned by the Resource Notification Broker in order to be able to send cancellations for existing subscriptions.

2:3.110.4.3 Update Subscription Request Message

This message uses the HTTP PUT method on the target Resource Notification Broker endpoint to update an existing Subscription resource in order to:

  • unsubscribe, or
  • re-activate it.
2:3.110.4.3.1 Trigger Events

This method is invoked when the Resource Notification Subscriber needs to:

  • unsubscribe an already existing subscription
  • re-activate an already existing subscription

so it sends an update of the Subscription resource to the Resource Notification Broker.

2:3.110.4.3.2 Message Semantics

The Resource Notification Subscriber SHALL initiate an HTTP request according to requirements defined in the HL7® FHIR® standard for “update” interaction. The message uses an HTTP PUT method to update a Subscription FHIR Resource previously created (see section 2:3.110.4.1 Create Subscription Request Message).

The Subscription.id element SHALL be valued with the id of the Subscription to be updated.

In order to unsubscribe, the Subscription Resource SHALL have status=off.

In order to re-activate an already existing Subscription, the Subscription Resource SHALL have status=requested.

The Resource Notification Subscriber SHALL submit the FHIR Subscription 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 Resource Subscription 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.

2:3.110.4.3.3 Expected Actions

Upon receiving the request message the Resource Notification Broker SHALL verify the following conditions:

  • that the Subscription resource to be updated exists (Prevent Update as Create);
  • the Subscription.status sended is off or the Subscription.status sended is requested and the actual Subscription.status is error or off.

The Resource Notification Broker SHALL enforce all the Security Considerations.

Based on the outcome of the conditions above the Resource Notification Broker SHALL accept or reject the update of the subscription resource received. If all the conditions are true the Resource Notification Broker SHALL:

  • in case of unsubscribe, update the Subscription resource and deactivate the subscription (status=off). When deactivated, the Resource Notification Broker SHOULD sent a Subscription Deactivation Notification [ITI-112] to the Resource Notification Recipient. No other notification SHALL be sent.
  • in case of re-activation of an already existing subscription, follow the Expected Actions which are reported in Section 2:3.110.4.1.3 Expected Actions.

Further considerations needs to be done in the following paragraph, considering DSUBm as an interface for DSUB environment.

2:3.110.4.3.3.1 Expected Actions with DSUBm as an interface for DSUB for unsubscribe

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, if the update of the subscription is accepted, the Resource Notification Broker SHALL trigger the Document Metadata Subscriber to send an Unsubscribe Request message towards the Document Metadata Notification Broker with an [ITI-52] Document Metadata Subscribe transaction. The message SHALL be sent to the webservice endpoint previously associated to the Subscription id (see section 2:3.110.4.1.3.1 Expected Actions section).

2:3.110.4.3.3.2 Expected Actions with DSUBm as an interface for DSUB for re-activation

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 the update is for re-activate errored Subscription (Subscription.status sended is requested and the actual Subscription.status is error) this grouping does not require further Expected Actions.

Instead, for this grouping, when the update is for re-activate turned off Subscription (Subscription.status sended is requested and the actual Subscription.status is off) the Resource Notification Broker SHALL consider the re-activation like a new Subscription that SHALL be propagated to the DSUB Document Metadata Notification Broker. So, the Resource Notification Broker SHALL trigger a Subscribe Request message towards the DSUB Document Metadata Notification Broker from the DSUB Document Metadata Subscriber with an Document Metadata Subscribe [ITI-52] transaction, following what is defined in Section Expected Actions with DSUBm as an interface for DSUB.

2:3.110.4.4 Update Subscription Response Message

The Resource Notification Broker sends a Resource Subscription Response Message to respond to an Update Subscription Request Message.

2:3.110.4.4.1 Trigger Events

When the Resource Notification Broker has finished successfully evaluating the subscription received and the operation, the Resource Notification Broker sends this message to the Resource Notification Subscriber acknowledging the result the update of the resource.

2:3.110.4.4.2 Message Semantics

The Resource Notification Broker SHALL respond with an HTTP 200 OK status code as indicated for “update” and the Resource Notification Broker SHALL return the entire resource in which the status SHALL be off for subscription deactivation or requested for subscription re-activation from error.

2:3.110.4.4.3 Expected Actions

The Resource Notification Subscriber processes the response according to application-defined rules.

2:3.110.4.5 Subscription Error Response Message

The Resource Notification Broker sends a Resource Subscription Response Message to respond in case of error to an Create Subscription Request Message or to an Update Subscription Request Message.

2:3.110.4.5.1 Trigger Events

When the Resource Notification Broker has finished evaluating the Subscription received and the operation, evaluating that it cannot proceeds due to error(s), the Resource Notification Broker sends this message to the Resource Notification Subscriber acknowledging the result the creation or the update of the resource.

2:3.110.4.5.2 Message Semantics

The Resource Notification Broker SHALL respond with an appropriate HTTP failure status code, based on the issue found. Further specifics, including the use of the OperationOutcome resource in the response message, SHALL follow what is indicated in “create” and “rejecting-updates” sections of FHIR core, based on the operation that is occurring on the Subscription resource.

2:3.110.4.5.3 Expected Actions

The Resource Notification Subscriber processes the response according to application-defined rules.

2:3.110.4.6 Subscription Topic and Filter Expressions

This section clarifies the Subscription Topics and the filter parameters for each type of Subscription that this profile defines.

Further, for each type of subscription, the events for which subscriptions are possible are specified that the Resource Notification Broker SHALL evaluate. The Resource Notification Broker becomes aware of such events either via a Resource Publish [ITI-111] transaction, or via other mechanisms not specified by this profile.

2:3.110.4.6.1 Patient-Dependent DocumentReference Subscription Topic

For this type of subscription, the stream of events for which subscriptions are possible is limited to events representing the creation of DocumentReference Resources related to Documents. Note that these events could be determined by Document Entry Objects creation in XDS environment. Note that these creation events could be happened with other events.

For this type of subscription, the possible subscription filter parameters are:

  • author.given and author.family
  • category
  • event
  • facility
  • format
  • patient
  • patient.identifier
  • security-label
  • setting
  • type
  • status

For the definition of these parameters see ITI-67 Query Search Parameters.

At least one of the patient or patient.identifier parameters SHALL be used.

With the exception of status and patient or patient.identifier, all parameters MAY be multi-valued.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocumentReference-PatientDependent.

The Resource Notification Broker SHALL support all the filter parameters that are expressed in the SubscriptionTopic. The Resource Notification Broker SHALL determine if there is a Subscription which matches any of the DocumentReference resources in an event. The evaluation performed is likely a search operation using the criteria in the Subscription. If it matches, the Resource Notification Broker SHALL send an Event Notification Message [ITI-112]. If the Subscription.payload.content includes resources, the DocumentReference resources SHALL be present.

The canonical instance of this SubscriptionTopic is reported here: Patient-Dependent DocumentReference SubscriptionTopic.

2:3.110.4.6.1.1 Patient-Dependent DocumentReference Subscription Subscription with DocumentReference Subscription for Minimal Update Option Topic

When supporting the DocumentReference Subscription for Minimal Update Option, this Subscription Topic extends the Patient-Dependent DocumentReference SubscriptionTopic in this way:

  • the stream of events for which subscriptions are possible also includes events representing only the update of the “status” and the deletion of DocumentReference resources related to Documents. Note that these events could be determined by Document Entry Objects updated or deleted in an XDS environment.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocReference-PatientDependent-MinUpdate.

The canonical instance of this SubscriptionTopic is reported here: Patient-Dependent DocumentReference SubscriptionTopic with DocumentReference Subscription for Minimal Update Option.

2:3.110.4.6.1.2 Patient-Dependent DocumentReference Subscription Subscription with DocumentReference Subscription for Full Events Option Topic

When supporting the DocumentReference Subscription for Full Events Option, this Subscription Topic extends the Patient-Dependent DocumentReference SubscriptionTopic in this way:

  • the stream of events for which subscriptions are possible also includes events representing the update and the deletion of DocumentReference Resources related to Documents. Note that these events could be determined by Document Entry Objects updated or deleted in an XDS environment.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocReference-PatientDependent-AllEvents.

The canonical instance of this SubscriptionTopic is reported here: Patient-Dependent DocumentReference SubscriptionTopic with Updates to document sharing resources Option.

2:3.110.4.6.2 Multi-Patient DocumentReference Subscriptions Topic

For this type of subscription, the stream of events for which subscriptions are possible is limited to events representing the creation of DocumentReference Resources related to Documents. Note that these events could be determined from Document Entry Objects created in an XDS environment. Note that these creation events could happen with other events.

For this type of subscription, the possible subscription filter parameters are:

  • author.given and author.family
  • category
  • event
  • facility
  • format
  • security-label
  • setting
  • type
  • status

For the definition of these parameters see ITI-67 Query Search Parameters.

With the exception of status, all parameters MAY be multi-valued.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocumentReference-MultiPatient.

The Resource Notification Broker SHALL support all the filter parameters that are expressed in the SubscriptionTopic. The Resource Notification Broker SHALL determine if there is a Subscription which matches any of the DocumentReference resources in an event. The evaluation performed is likely a search operation using the criteria in the Subscription. If it matches, the Resource Notification Broker SHALL send a Event Notification Message [ITI-112]. If the Subscription.payload.content includes resources, the DocumentReference resources SHALL be present.

The canonical instance of this SubscriptionTopic is reported here: Multi-Patient DocumentReference SubscriptionTopic.

2:3.110.4.6.2.1 Multi-Patient DocumentReference Subscription Subscription with DocumentReference Subscription for Minimal Update Option Topic

When the DocumentReference Subscription for Minimal Update Option is supported, the following Subscription Topic extends the Multi-Patient DocumentReference Subscriptions Topic in this way:

  • the stream of events for which subscriptions are possible also includes events representing only the update of the “status” and the deletion of DocumentReference Resources related to Documents. Note that these events could be determined by Document Entry Objects updated or deleted in an XDS environment.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocReference-MultiPatient-MinUpdate.

The canonical instance of this extended SubscriptionTopic is reported here: Multi-Patient DocumentReference SubscriptionTopic with DocumentReference Subscription for Minimal Update Option.

2:3.110.4.6.2.2 Multi-Patient DocumentReference Subscription Subscription with DocumentReference Subscription for Full Events Option Topic

When the DocumentReference Subscription for Full Events Option is supported, the following Subscription Topic extends the Multi-Patient DocumentReference Subscriptions Topic in this way:

  • the stream of events for which subscriptions are possible also includes events representing the update and the deletion of DocumentReference Resources related to Documents. Note that these events could be determined by Document Entry Objects updated or deleted in an XDS environment.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-DocReference-MultiPatient-AllEvents.

The canonical instance of this extended SubscriptionTopic is reported here: Multi-Patient DocumentReference SubscriptionTopic with DocumentReference Subscription for Full Events Option.

2:3.110.4.6.3 Patient-Dependent SubmissionSet Subscription Topic

For this type of subscription, the stream of events for which subscriptions are possible is limited to events representing the creation of SubmissionSet type List Resources related to SubmissionSet. Note that these events could be determined from SubmissionSet Objects created in an XDS environment. Note that these creation events could be happened with other events.

For this type of subscription, the possible subscription filter parameters are:

  • code
  • patient
  • patient.identifier
  • source.given and source.family
  • sourceId
  • intendedRecipient

For the definition of these parameters see ITI-66 Query Search Parameters.

At least one of the patient or patient.identifier parameters SHALL be used.

Only the source.given, source.family, sourceId and intendedRecipient parameters MAY be multi-valued.

The canonical URL of this Subscription Topic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-SubmissionSet-PatientDependent.

The Resource Notification Broker SHALL support all the filter parameters that are expressed in the SubscriptionTopic. The Resource Notification Broker SHALL determine if there is a Subscription which matches any of the SubmissionSet type List resources in an event. The evaluation performed is likely a search operation using the criteria in the Subscription. If it matches, the Resource Notification Broker SHALL send an Event Notification Message [ITI-112]. If the Subscription.payload.content includes resources, the SubmissionSet type List resources SHALL be present.

The canonical instance of this SubscriptionTopic is reported here: Patient-Dependent SubmissionSet SubscriptionTopic.

2:3.110.4.6.4 Multi-Patient SubmissionSet Subscription Topic

For this type of subscription, the stream of events for which subscriptions are possible is limited to events representing the creation of SubmissionSet type List Resources related to SubmissionSet. Note that these events could be determined from SubmissionSet Objects creation in an XDS environment. Note that these creation events could happen with other events.

For this type of subscription, the possible subscription filter parameters are:

  • code
  • source.given and source.family
  • sourceId
  • intendedRecipient

For the definition of these parameters see ITI-66 Query Search Parameters.

All the parameters MAY be multi-valued.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-SubmissionSet-MultiPatient.

The Resource Notification Broker SHALL support all the filter parameters that are expressed in the SubscriptionTopic. The Resource Notification Broker SHALL determine if there is a Subscription which matches any of the SubmissionSet type List resources in an event. The evaluation performed is likely a search operation using the criteria in the Subscription. If it matches, the Resource Notification Broker SHALL send an Event Notification Message [ITI-112]. If the Subscription.payload.content includes resources, the SubmissionSet type List resources SHALL be present.

The canonical instance of this SubscriptionTopic is reported here: Multi-Patient SubmissionSet SubscriptionTopic.

2:3.110.4.6.5 Basic Folder Subscription Topic

When the Basic Folder Subscription Option is supported, this type of subscription is admitted. For this type of subscription, the stream of events for which subscriptions are possible is limited to events representing the creation of Folder type List Resources and the update to insert new documents in Folder. Note that these events could be determined from Folder Objects created or updated and Association Object creation in an XDS environment. Note that these creation or updating events could happen with other events.

For this type of subscription, the possible subscription filter parameters are:

  • code
  • patient
  • patient.identifier
  • identifier
  • designationType
  • status

For the definition of these parameters see ITI-66 Query Search Parameters.

At least one of the patient or patient.identifier parameters SHALL be used.

Only the identifier and designationType parameters MAY be multi-valued.

The canonical URL of this SubscriptionTopic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-Basic-Folder-Subscription.

The Resource Notification Broker SHALL support all the filter parameters that are expressed in the SubscriptionTopic. The Resource Notification Broker SHALL determine if there is a Subscription which matches any of the Folder type List resources in an event. The evaluation performed is likely a search operation using the criteria in the Subscription. If it matches, the Resource Notification Broker SHALL send an Event Notification Message [ITI-112]. If the Subscription.payload.content includes resources, the Folder type List resources SHALL be present.

The canonical instance of this SubscriptionTopic is reported here: Basic Folder SubscriptionTopic.

2:3.110.4.6.5.1 Folder Subscription with Folder Subscription for Minimal Update Option Topic

When the Folder Subscription for Minimal Update Option is supported, this Subscription Topic extends the Basic Folder Subscription Topic in this way:

  • the stream of events for which subscriptions are possible includes also events representing the update to remove documents and update of the “status” of Folder type List Resources related to Folders. Note that these events could be determined from Folder Objects update or Association Objects update or delete in an XDS environment.

The canonical URL of this Subscription Topic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-Folder-Subscription-MinUpdateOpt.

The canonical instance of this SubscriptionTopic is reported here: Folder SubscriptionTopic with Folder Subscription for Minimal Update Option.

2:3.110.4.6.5.2 Folder Subscription with Folder Subscription for Update Option Topic

When the Folder Subscription for Update Option is supported, this Subscription Topic extends the Basic Folder Subscription Topic in this way:

  • the stream of events for which subscriptions are possible includes also events representing all the updates of Folder type List Resources related to Folders. Note that these events could be determined from Folder Objects update or Association Objects creation, update or delete in an XDS environment.

The canonical URL of this Subscription Topic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-Folder-Subscription-UpdateOpt.

The canonical instance of this SubscriptionTopic is reported here: Folder SubscriptionTopic with Folder Subscription for Minimal Update Option.

2:3.110.4.6.5.3 Folder Subscription with Folder Subscription for Full Events Option Topic

When the Folder Subscription for Full Events Option is supported, this Subscription Topic extends the Basic Folder Subscription Topic in this way:

  • the stream of events for which subscriptions are possible includes also events representing all the updates and the deletion of Folder type List Resources related to Folders. Note that these events could be determined from Folder Objects update or deletion, or Association Objects creation, update or delete in an XDS environment.

The canonical URL of this Subscription Topic that SHALL be used in the Subscription.criteria element is https://profiles.ihe.net/ITI/DSUBm/DSUBm-SubscriptionTopic-Folder-Subscription-for-Full-Events.

The canonical instance of this SubscriptionTopic is reported here: Folder SubscriptionTopic with Folder Subscription for Full Events Optionn.

2:3.110.4.7 Mapping between DSUBm Criteria and DSUB subscription Filters.

If the Resource Notification Broker is grouped with Document Metadata Subscriber and Document Metadata Notification Recipient, considering DSUBm as an interface for DSUB model, the Subscription.criteria available parameters in the Subscription resource SHALL be mapped with the DSUB filter Expression.

Table 2:3.110.4.7-1: DSUBm DocumentReference subscription criteria mapping to DSUB DocumentEntry Filters

DSUBm
Subscription.criteria		 DSUB
DocumentEntry Filters
author.given / author.family $XDSDocumentEntryAuthorPerson
category $XDSDocumentEntryClassCode
event $XDSDocumentEntryEventCodeList
facility $XDSDocumentEntryHealthcareFacilityTypeCode
format $XDSDocumentEntryFormatCode
patient or patient.identifier $XDSDocumentEntryPatientId
security-label $XDSDocumentEntryConfidentialityCode
type $XDSDocumentEntryTypeCode
status none

Table 2:3.110.4.7-2: DSUBm SubmissionSet subscription criteria mapping to DSUB DocumentEntry Filters

DSUBm
Subscription.criteria		 DSUB
SubmissionSet Filters
code none
patient or patient.identifier $XDSSubmissionSetPatientId
source.given or source.family $XDSSubmissionSetAuthorPerson
sourceId $XDSSubmissionSetSourceId
intendedRecipient $XDSSubmissionSetIntendedRecipient

Table 2:3.110.4.7-3: DSUBm Folder subscription criteria mapping to DSUB DocumentEntry Filters

DSUBm
Subscription.criteria		 DSUB
Folder Filters
code none
patient or patient.identifier $XDSFolderPatientId
identifier $XDSFolderUniqueId
designationType $XDSFolderCodeList
status none

2:3.110.5 CapabilityStatement Resource

The Resource Notification Subscriber 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 Subscriber ar listed in Section 1:54.1.1.2 Resource Notification Subscriber.

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 ar listed in Section 1:54.1.1.1 Resource Notification Broker.

2:3.110.6 Security Considerations

See DSUBm Security Considerations.

The Resource Notification Broker SHALL control that the Resource Notification Subscriber is acceptable and authorized to create or update a Subscription Resource. It’s highly RECOMMENDED that the Resource Notification Subscriber SHOULD use some form of authentication method when creating or updating a Subscription. The Resource Notification Broker SHALL also be aware and enforce any agreed policy in order to control that the Subscription criteria received, that describe the notification event, are permitted to the authenticated Resource Notification Subscriber. For example a veterinary clinical record MAY be allowed to request a subscription but the Resource Notification Broker SHALL verify that the Subscription is related only to documents produced for animal subjects and SHALL reject any subscription made for documents produced for human subjects.

If there is a policy that needs to be enforced in order to control which subscriber can Subscribe or Unsubscribe then, the Resource Notification Broker might maintain a whitelist of acceptable senders for the ITI-110 transactions. The Resource Notification Broker MAY enforce some control on the channel.endpoint element of the Subscription resource received in order to control where the notification will be sent. The Resource Notification Broker might maintain an allow-list of acceptable endpoints or trusted certificate authorities for rest-hook channels. The Resource Notification Broker MAY control the Subscription.payload element of Subscription resource received in order to mitigate the risk of disclosing sensitive information. For example, if the Subscription criteria includes sensitive documents, the Resource Notification Broker MAY allow just ‘id-only’ payloads. In this way further authorization mechanisms SHALL be enforced when the Resource Notification Recipient tries to retrieve the information using the id.

2:3.110.6.1 Security Audit Considerations

The Resource Notification Subscriber, when grouped with ATNA Secure Node or Secure Application Actor, SHALL be able to record fundamental AuditEvents for:

The Resource Notification Broker, when grouped with ATNA Secure Node or Secure Application Actor, SHALL be able to record fundamental AuditEvents for: