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 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.
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.
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 |
FHIR-R4 HL7 FHIR Release 4.0.
The Resource Notification Subscriber Request Message is a parameterized HTTP GET that queries the Resource Notification Broker for information about Subscriptions.
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.
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.
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
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.
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.
The Resource Notification Broker completed the processing of the Subscription Search Request Message.
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:
Bundle.type element valued searchsetMore information about search response can be found at http://hl7.org/fhir/R4/http.html#search.
The Resource Notification Subscriber SHALL process the results according to application-defined rules.
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.
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.
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.
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
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.
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.
The Resource Notification Broker completed the processing of the Subscription Status Search Request Message.
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:
Bundle.type element valued searchsetThe Resource Notification Subscriber SHALL process the results according to application-defined rules.
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.
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.
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.
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.).
The Resource Notification Broker returns an HTTP status code appropriate to the processing as well as a Bundle containing the events.
The Resource Notification Broker completed the processing of the Subscription Events Search Request Message.
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:
Bundle.type element valued historycontent query parameter in the request and the Subscription.payload.content and the notificationShape element defined in the Topic of the Subscription.The Resource Notification Subscriber SHALL process the results according to application-defined rules.
The Resource Notification Subscriber Request Message is an HTTP GET that retrieve a known Subscription from the Resource Notification Broker.
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.
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]
Read the Subscriptions with id=1234:
GET [base]/Subscription/1234
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.
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.
The Resource Notification Broker completed the processing of the Subscription Read Request Message.
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.
The Resource Notification Subscriber SHALL process the results according to application-defined rules.
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.
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.
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:
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