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

## 2:3.113 Resource Subscription Search [ITI-113]

This section corresponds to the Resource Subscription Search [ITI-113] transaction of the IHE Technical Framework. The Resource Subscription Search [ITI-113] transaction is used by the Resource Notification Subscriber and Resource Notification Broker Actors. The Resource Subscription Search [ITI-113] transaction is used to query Subscriptions and get back the results.

### 2:3.113.1 Scope

The Resource Subscription Search [ITI-113] transaction passes a Resource Subscription Search message from a Resource Notification Subscriber to a Resource Notification Broker in order to discover Subscriptions, to be aware of Subscriptions status, or to be aware of previous events related to Subscriptions.

### 2:3.113.2 Actors Roles

Table 2:3.113.2-1: Actor Roles

Actor | Role
--- | ---
Resource Notification Subscriber | Sends the query request to the Resource Notification Broker
Resource Notification Broker | Receives the query and responds

### 2:3.113.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0.

### 2:3.113.4 Messages

Figure 2:3.113.4-1: Resource Subscription Search [ITI-113] interactions

#### 2:3.113.4.1 Subscription Search Request Message

The Resource Notification Subscriber Request Message is a parameterized `HTTP GET` that queries the Resource Notification Broker for information about Subscriptions.

##### 2:3.113.4.1.1 Trigger Events

A Resource Notification Subscriber sends this message to the Resource Notification Broker when it needs to discover one or more Subscription Resources that are not known.

##### 2:3.113.4.1.2 Message Semantics

The Resource Notification Subscriber sends an `HTTP GET` request to the Resource Notification Broker.

This request SHALL comply with requirements specified in the HL7® FHIR® standard https://hl7.org/fhir/R4/http.html#search.

The search target URL follows the FHIR HTTP specification https://hl7.org/fhir/R4/http.html, addressing the Subscription Resources that the Resource Notification Subscriber is interested to discover.

The Resource Notification Subscriber Request Message can be expressed by addressing the Subscription Resource with different parameters at the URL:

> GET [base]/Subscription?[Parameters]

The Resource Notification Subscriber SHOULD support and MAY supply, and the Resource Notification Broker SHALL be capable of processing all parameters reported in Table 3.113.5.2-1. All parameter values SHALL be appropriately encoded per RFC3986 “percent” encoding rules. Note that percent encoding does restrict the character set to a subset of ASCII characters which is used for encoding all other characters used in the URL. Resource Notification Broker MAY choose to support additional parameters beyond the subset listed below. Any additional parameters supported SHALL be supported according to Search parameters section and also the search parameter included in the Subscription R5 Backport Implementation Guide. Such additional parameters are considered out of scope for this transaction. Any additional parameters not supported SHOULD be ignored.

FHIR defines methods of supporting multiple parameter values in an AND and OR relationship. The Resource Notification Broker SHALL support both AND and OR relationships. See FHIR specification on Composite Search Parameters https://hl7.org/fhir/R4/search.html#combining.

Table 2:3.113.4.1.2-1: Subscription Search Request Message Search Parameters

Name | Type | Description
--- | --- | ---
_id | string | The id of the Subscription
status | token | The current state of the subscription
url | uri | The URI that will receive the notifications
filter-criteria | string | This SearchParameter enables query of subscriptions by filter criteria
topic | uri | This SearchParameter enables query of subscriptions by canonical topic-url

The Resource Notification Subscriber MAY provide the optional parameter “_format” to specify the desired MIME-types in the response message. The Resource Notification Broker SHOULD accept `application/fhir+xml` and `application/fhir+json` as _format parameters. For example, indicating `application/fhir+json` could result in the response from the Resource Notification Broker being a json FHIR Bundle with all the content encoded as FHIR resources.

###### 2:3.113.4.1.2.1 Subscription Search Request Message Examples

Search for all active subscriptions with `endpoint=X` without knowing the type of subscription:

> GET [base]/Subscription?status=active&channel.endpoint=X

Search for all the subscriptions made for documents produced for a specific patient with `patientId = Y`:

> GET [base]/Subscription?filter-criteria=documentReference%3Fsubject=Y

Search for all the subscriptions that are referring to a specific SubscriptionTopic resource with `id=1234`:

> GET [base]/Subscription?criteria=http://hl7.org/SubscriptionTopic/1234

##### 2:3.113.4.1.3 Expected Actions

The Resource Notification Broker who received the message SHALL process the request and respond with a Resource Subscription Search Response Message.

After receiving a Subscription Search request, the Resource Notification Broker SHALL return a Bundle with the Subscription Resources that matches the query parameters in the request message.

#### 2:3.113.4.2 Subscription Search Response Message

The Resource Notification Broker returns an HTTP status code appropriate to the processing as well as a Bundle containing a list of the matching Subscription resources.

##### 2:3.113.4.2.1 Trigger Events

The Resource Notification Broker completed the processing of the Subscription Search Request Message.

##### 2:3.113.4.2.2 Message Semantics

The response SHALL adhere to the FHIR Bundle constraints specified in ITI TF-2: Appendix Z.7

Based on the query results, the Resource Notification Broker will either return an error or success. Guidance on handling Access Denied related to the use of 200, 403, and 404 can be found in ITI TF-2: Appendix Z.7. When the Resource Notification Broker needs to report an error, it SHALL use HTTP error response codes and SHOULD include a FHIR OperationOutcome with more details on the failure. See FHIR https://hl7.org/fhir/R4/http.html and https://hl7.org/fhir/R4/operationoutcome.html.

If the Resource Subscription Search message is processed successfully, whether or not any Subscription Resources are found based on the request parameters, the response SHALL be an `HTTP 200` status code. The Resource Subscription Search Response message SHALL be a Bundle Resource that SHALL have:

- the `Bundle.type` element valued `searchset`
- zero or more entries containing the Subscription Resources;
- zero or one OperationOutcome Resource that contains warnings, if the Resource Subscription Broker is sending warnings.

More information about search response can be found at http://hl7.org/fhir/R4/http.html#search.

##### 2:3.113.4.2.3 Expected Actions

The Resource Notification Subscriber SHALL process the results according to application-defined rules.

#### 2:3.113.4.3 Subscription Status Search Request Message

The Subscription Status Search Request Message is a parametrized `HTTP GET` that allows to search or retrieve, from the Resource Notification Broker, information about the status of the Subscriptions.

##### 2:3.113.4.3.1 Trigger Events

This message can be used by the Resource Notification Subscriber to be aware of the status of one or more Subscriptions, using the $status operation.

##### 2:3.113.4.3.2 Message Semantics

The Resource Notification Subscriber sends an `HTTP GET` request to the Resource Notification Broker.

The Resource Notification Subscriber Request Message SHALL be a FHIR operation request as defined in FHIR (http://hl7.org/fhir/operations.html) with the $status operation definition and the input parameters in Table 3.113.6.2-1, in order to be aware of the Subscriptions status.

The URL for this operation is one of:

> GET [base]/Subscription/$status

> GET [base]/Subscription/[id]/$status

Table 2:3.113.4.3.2-1: Subscription Status Search Request Message Parameters

Name | Cardinality | Type | Description
--- | --- | --- | ---
id | 0..* | id | At the Instance level, this parameter is ignored. At the Resource level, one or more parameters containing a FHIR id for a Subscription to get status information for. In the absence of any specified ids, the server returns the status for all Subscriptions available to the caller. Multiple values are joined via OR (e.g., “id1” OR “id2”)
status | 0..* | code | At the Instance level, this parameter is ignored. At the Resource level, a Subscription status to filter by (e.g., “active”). In the absence of any specified status values, the server does not filter contents based on the status. Multiple values are joined via OR (e.g., “error” OR “off”)

The Resource Notification Subscriber MAY provide the optional parameter “_format” to specify the desired MIME-types in the response message. The Resource Notification Broker SHOULD accept `application/fhir+xml` and `application/fhir+json` as _format parameters. For example, indicating `application/fhir+json` could result in the response from the Resource Notification Broker being a json FHIR Bundle with all the content encoded as json FHIR resources.

###### 2:3.113.4.3.2.1 Subscription Status Search Request Message examples

Get all the SubscriptionStatus resources for all the subscription that are active `status=active`:

> GET [base]/Subscription/$status?status=active

Get the SubscriptionStatus for the subscription with `id=1234`:

> GET [base]/Subscription/1234/$status

##### 2:3.113.4.3.3 Expected Actions

The Resource Notification Broker who received the message SHALL process the request and respond with a Resource Subscription Search Response Message.

After receiving a Subscription Status Search Request Message, the Resource Notification Broker SHALL return a Bundle with the SubscriptionStatus Resources related to the Subscriptions that matched the query parameters in the request message.

#### 2:3.113.4.4 Subscription Status Search Response Message

The Resource Notification Broker returns an HTTP status code appropriate to the processing as well as a Bundle containing a list of the matching SubscriptionStatus resources.

##### 2:3.113.4.4.1 Trigger Events

The Resource Notification Broker completed the processing of the Subscription Status Search Request Message.

##### 2:3.113.4.4.2 Message Semantics

The response SHALL adhere to the FHIR Bundle constraints specified in ITI TF-2: Appendix Z.7

Based on the query results, the Resource Notification Broker will either return an error or success. Guidance on handling Access Denied related to the use of 200, 403, and 404 can be found in ITI TF-2: Appendix Z.7. When the Resource Notification Broker needs to report an error, it SHALL use HTTP error response codes and SHOULD include a FHIR OperationOutcome with more details on the failure. See FHIR https://hl7.org/fhir/R4/http.html and https://hl7.org/fhir/R4/operationoutcome.html.

If the $status operation request is processed successfully the response SHALL be an `HTTP 200` status code. The Resource Subscription Search Response message SHALL be a Bundle Resource that SHALL have:

- SubscriptionStatus Bundle
  - the `Bundle.type` element valued `searchset`
  - zero or more entries containing the SubscriptionStatus Resources for the $status operation;
  - zero or one OperationOutcome Resource that contains warnings, if the Resource Subscription Broker is sending warnings.

##### 2:3.113.4.4.3 Expected Actions

The Resource Notification Subscriber SHALL process the results according to application-defined rules.

#### 2:3.113.4.5 Subscription Events Search Request Message

The Resource Notification Subscriber Request Message is a parametrized `HTTP GET` that allows to retrieve, from the Resource Notification Broker, the events about a specific Subscription that have occurred.

##### 2:3.113.4.5.1 Trigger Events

When the Subscription Resource is known, this message can be used by the Resource Notification Subscriber to be aware of previous events related to that Subscription, using the $events operation.

##### 2:3.113.4.5.2 Message Semantics

The Resource Notification Subscriber sends an `HTTP GET` request to the Resource Notification Broker.

The Subscription Events Search Request Message SHALL be a FHIR operation request as defined in FHIR (http://hl7.org/fhir/operations.html) with the $events operation definition and the input parameters in Table 3.113.7.2-1, in order to be aware of previous events related to a Subscription.

The URL for this operation is:

> GET [base]/Subscription/[id]/$events

Table 2:3.113.4.5.2-1: Subscription Events Search Request Message Parameters

Name | Cardinality | Type | Description
--- | --- | --- | ---
eventsSinceNumber | 0..1 | string | The starting event number, inclusive of this event (lower bound)
eventsUntilNumber | 0..1 | string | The ending event number, inclusive of this event (upper bound)
content | 0..1 | code | Requested content style of returned data. Codes from backport-content-value-set (e.g., empty, id-only, full-resource). This is a hint to the server what a client would prefer, and MAY be ignored

The Resource Notification Subscriber MAY provide the optional parameter “_format” to specify the desired MIME-types in the response message. The Resource Notification Broker SHOULD accept `application/fhir+xml` and `application/fhir+json` as _format parameters. For example, indicating `application/fhir+json` could result in the response from the Resource Notification Broker being a json FHIR Bundle with all the content encoded as json FHIR resources.

##### 2:3.113.4.5.3 Expected Actions

The Resource Notification Broker who received the message SHALL process the request and respond with a Resource Subscription Events Search Response Message.

After receiving a Subscription Events Search Request Message, the Resource Notification Broker SHALL return a Bundle with the SubscriptionStatus Resource and the previous events related to the Subscription that match the query parameters in the request message. The Resource Notification Broker MAY use implementation-specific criteria to restrict availability of events (e.g., most recent 10 events, events within the past 30 days, only the events from the last $events operation performed by a Resource Notification Subscriber, etc.).

#### 2:3.113.4.6 Subscription Events Search Response Message

The Resource Notification Broker returns an HTTP status code appropriate to the processing as well as a Bundle containing the events.

##### 2:3.113.4.6.1 Trigger Events

The Resource Notification Broker completed the processing of the Subscription Events Search Request Message.

##### 2:3.113.4.6.2 Message Semantics

The response SHALL adhere to the FHIR Bundle constraints specified in ITI TF-2: Appendix Z.7

Based on the query results, the Resource Notification Broker will either return an error or success. Guidance on handling Access Denied related to the use of 200, 403, and 404 can be found in ITI TF-2: Appendix Z.7. When the Resource Notification Broker needs to report an error, it SHALL use HTTP error response codes and SHOULD include a FHIR OperationOutcome with more details on the failure. See FHIR https://hl7.org/fhir/R4/http.html and https://hl7.org/fhir/R4/operationoutcome.html.

If the $events operation request is processed successfully the response SHALL be an `HTTP 200` status code. The Resource Subscription Search Response message SHALL be a Bundle Resource that SHALL have:

- SubscriptionEvent Bundle
  - the `Bundle.type` element valued `history`
  - in the first the first entry the SubscriptionStatus for the $events operation;
  - zero or more additional entries, with either URLs or resources representing contents, depending on the `content` query parameter in the request and the `Subscription.payload.content` and the `notificationShape` element defined in the Topic of the Subscription.

##### 2:3.113.4.6.3 Expected Actions

The Resource Notification Subscriber SHALL process the results according to application-defined rules.

#### 2:3.113.4.7 Subscription Read Request Message

The Resource Notification Subscriber Request Message is an `HTTP GET` that retrieve a known Subscription from the Resource Notification Broker.

##### 2:3.113.4.7.1 Trigger Events

A Resource Notification Subscriber sends this message to the Resource Notification Broker when it needs to retrieve one Subscription Resources with a known resource id.

##### 2:3.113.4.7.2 Message Semantics

The Resource Notification Subscriber sends an `HTTP GET` request to the Resource Notification Broker.

This request SHALL comply with requirements specified in the HL7® FHIR® standard https://hl7.org/fhir/R4/http.html#read.

The Resource Notification Subscriber Request Message SHALL be expressed by addressing the Subscription Resource URL, providing the resource id of the Subscription being retrieved. The target is formatted as:

> GET [base]/Subscription/[id]

###### 2:3.113.4.7.2.1 Subscription Read Request Message example

Read the Subscriptions with `id=1234`:

> GET [base]/Subscription/1234

##### 2:3.113.4.7.3 Expected Actions

The Resource Notification Broker who received the message SHALL retrieve the Subscription record indicated by the Resource id on the HTTP GET supplied by the Resource Notification Subscriber.

#### 2:3.113.4.8 Subscription Read Response Message

The Resource Notification Broker returns an HTTP status code appropriate to the processing as well as the matching Subscription resources. The Resource Notification Broker SHALL respond to the retrieve request bas on the outcome of the interaction.

##### 2:3.113.4.8.1 Trigger Events

The Resource Notification Broker completed the processing of the Subscription Read Request Message.

##### 2:3.113.4.8.2 Message Semantics

The Subscription Read Response Message is sent from the Resource Notification Broker to the Resource Notification Subscriber as a single Subscription Resource.

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for guidance for Access Denied.

If the Resource Notification Broker is unable to produce a response in the requested format, it SHALL respond with an `HTTP 400` error indicating that it was unable to fulfill the request. The Resource Notification Broker MAY be capable of servicing requests for response formats not listed, but SHALL, at minimum, be capable of producing XML and JSON encodings.

##### 2:3.113.4.8.3 Expected Actions

The Resource Notification Subscriber SHALL process the results according to application-defined rules.

### 2:3.113.5 CapabilityStatement Resource

The Resource Notification Subscriber 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 Subscriber are 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-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.

### 2:3.113.6 Security Considerations

See DSUBm Security Considerations.

The implementers SHOULD be aware that a specific Resource Notification Subscriber MAY acquire sensitive information if searching for Subscriptions created by other Subscribers. The Resource Notification Broker SHOULD follow an implementing policy in order to allow or prohibit the search for Subscription resources created by other Subscribers.

It is highly RECOMMENDED that the Resource Notification Subscriber SHOULD use some form of authentication method when searching for existing Subscription. The Resource Notification Broker SHOULD always verify the authentication token used in this transaction before returning the information requested.

#### 2:3.113.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:

- Resource Notification Subscriber SubscriptionTopic Query, when a search interaction is performed;
- Resource Notification Subscriber SubscriptionTopic Read, when a read interaction is performed.

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 SubscriptionTopic Query, when a search interaction is performed;
- Resource Notification Broker SubscriptionTopic Read, when a read interaction is performed.