This page is part of the Document Subscription for Mobile (DSUBm) (v1.0.0: Publication) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.114 Resource SubscriptionTopic Search [ITI-114]

This section corresponds to the Resource SubscriptionTopic Search [ITI-114] transaction of the IHE Technical Framework.

2:3.114.1 Scope

The Resource SubscriptionTopic Search [ITI-114] is used by the Resource Notification Subscriber to Resource Notification Broker Actors, in order to search for a Basic resource to be used as subscription topic in a Subscription resource.

2:3.114.2 Actors Roles

Table 2:3.114.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.114.3 Referenced Standards

FHIR-R4 HL7 FHIR Release 4.0.1

2:3.114.4 Messages

2:3.114.4.1 Resource SubscriptionTopic Search Request Message

The Resource Notification Subscriber Request Message is a parametrized HTTP GET that allows to search for a list of Basic resources (that are representing the subscription topics) managed by the Resource Notification Broker, based on a set of search parameters.

2:3.114.4.1.1 Trigger Events

A Resource Notification Subscriber sends this message to the Resource Notification Broker when it needs to discover a Basic resource (that are representing the subscription topics). This normally happens before the Subscriber creates a Subscription.

2:3.114.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 Resource Notification Subscriber Request Message SHALL be expressed by addressing the Basic Resource in the path as follows:

GET [base]/Basic?code=SubscriptionTopic&[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 2:3.114.4.1.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. Such additional parameters are considered out of scope for this transaction. Any additional parameters not supported SHOULD be ignored.

In the query string the search parameter code is REQUIRED and it SHALL be valued as code=SubscriptionTopic.

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.114.4.1.2-1: Resource SubscriptionTopic Search Request Message Search Parameters

Name	Type	Description
code	token	Kind of Resource (MANDATORY parameter valued code=SubscriptionTopic )
_id	string	The id of the Basic resource
resource	uri	Allowed Data type or Resource (reference to definition) for this definition, searches resourceTrigger, eventTrigger, and notificationShape, and canFilterBy for matches.
derived-or-self	uri	A server defined search that matches either the url or derivedFrom
status	token	The RECOMMENDED value SHOULD be active when searching for available Basic resources
url	uri	Logical canonical URL to reference this Basic (globally unique)

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.114.4.1.3 Expected Actions

The Resource Notification Broker who received the message SHALL process the request, according to application-defined rules, and also evaluate if the Resource Notification Subscriber can access the information.

If the access is granted, the Resource Notification Broker SHALL produce a response in which SHALL be present at least the following Basic Resources (that are representing the subscription topics), if parameters match:

• Patient-Dependent DocumentReference SubscriptionTopic
• Multi-Patient DocumentReference SubscriptionTopic
• Patient-Dependent SubmissionSet SubscriptionTopic
• Multi-Patient SubmissionSet SubscriptionTopic

If the Resource Notification Broker supports the DocumentReference Subscription for Minimal Update Option, the following Basic resources SHALL also be present in the response, if parameters match:

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

If the Resource Notification Broker supports the DocumentReference Subscription for Full Events Option, the following Basic resources SHALL also be present in the response, if parameters match:

• Patient-Dependent DocumentReference SubscriptionTopic with Updates to document sharing resources Option
• Multi-Patient DocumentReference SubscriptionTopic with DocumentReference Subscription for Full Events Option

If the Resource Notification Broker supports the Basic Folder Subscription Option, the following Basic resources SHALL also be present in the response, if parameters match:

• Basic Folder SubscriptionTopic

If the Resource Notification Broker supports the Folder Subscription for Minimal Update Option, the following Basic resources SHALL also be present in the response, if parameters match:

• Folder SubscriptionTopic with Folder Subscription for Minimal Update Option

If the Resource Notification Broker supports the Folder Subscription for Update Option, the following Basic resources SHALL also be present in the response, if parameters match:

• Folder SubscriptionTopic with Folder Subscription for Minimal Update Option

If the Resource Notification Broker supports the Folder Subscription for Full Events Option, the following Basic resources SHALL also be present in the response, if parameters match:

• Folder SubscriptionTopic with Folder Subscription for Full Events Option

2:3.114.4.2 Resource SubscriptionTopic 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 Basic resources (that are representing the subscription topics).

2:3.114.4.2.1 Trigger Events

The Resource Notification Broker completed the processing of the request message.

2:3.114.4.2.2 Message Semantics

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 SubscriptionTopic Search message is processed successfully, the HTTP status code SHALL be 200. The Resource SubscriptionTopic Search Response message SHALL be a Bundle Resource containing the Basic Resources. If the Resource Notification Broker is sending warnings, the Bundle Resource SHALL also contain an OperationOutcome Resource that contains those warnings.

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

2:3.114.4.2.3 Expected Actions

The Resource Notification Subscriber SHALL process the results according to application-defined rules and be aware of the subscription topic supported by the Resource Notification Broker.

2:3.114.4.3 SubscriptionTopic Read Request Message

The Resource Notification Subscriber Request Message is an HTTP GET that retrieve a known Basic resource representing the subscription topic from the Resource Notification Broker.

2:3.114.4.3.1 Trigger Events

A Resource Notification Subscriber sends this message to the Resource Notification Broker when it needs to retrieve one Basic resource representing the subscription topic with a known resource id.

2:3.114.4.3.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 Basic Resource URL, providing the resource id of the Basic resource being retrieved. The target is formatted as:

GET [base]/Basic/[id]

2:3.114.4.3.2.1 SubscriptionTopic Read Request Message example

Read the Basic resource, representing a subscription topic, with id=1234:

GET [base]/Basic/1234

2:3.114.4.3.3 Expected Actions

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

2:3.114.4.4 SubscriptionTopic Read Response Message

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

2:3.114.4.4.1 Trigger Events

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

2:3.114.4.4.2 Message Semantics

The SubscriptionTopic 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.114.4.4.3 Expected Actions

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

2:3.114.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.114.6 Security Considerations

See DSUBm Security Considerations.

2:3.114.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.