10.3.1 | Twiin-01 | Send Notification Task
- Ben van der Stigchel
This section describes the transaction needed for the notification.
Scope
This transaction delivers a notification from the Sending GtK to the Receiving GtK based on the specified referral.
Use Case Roles
Actor: Sending GtK
Role: Sends Notification Tasks on behalf of a referring user.
Actor: Receiving GtK
Role: Receives and processes Notification Tasks
Referenced Standards
HL7® FHIR® standard STU3 https://hl7.org/fhir/stu3
Messages
Request message
The Notification message is sent by the Sending GtK when it needs to notify the Receiving GtK about one or more FHIR® resources that have been made available to the Receiving GtK.
The Notification that is sent to the Receiving GtK must be able to convey at least the following details:
Identification of Sending GtK, Sending Organization and practitioner
Identification of Receiving Organization
Identification of the patient who is the subject of information exchange
References to individual FHIR® resources that have been made available at the Sending System
FHIR® search queries that can be used to retrieve FHIR® resources that have been made available at the Sending GtK
Authorization base (see Authorization base)
The payload of this message consists of a https://hl7.org/fhir/stu3/task.html resource that contains at least the details mentioned above. This message is sent to communicate both a new and an updated data set to the Receiving GtK. The message results in a Task instance that will be referred to as the Notification Task.
For the time being, the STU3 version of the FHIR® standard will be used because this TA will first be applied in the context of the BgZ (Basisgegevensset Zorg). Within that context, data is exchanged based on FHIR® STU3. As soon as data has to be exchanged using the Notified Pull pattern for newer FHIR® versions, it becomes opportune to provide or adopt a specification of the Notification for the corresponding FHIR® version.
The Sending GtK must initiate the Notification message using a create interaction, i.e. sending an HTTP POST request to the Task endpoint of the Receiving GtK.
The media type of the HTTP body must be either application/fhir+json or application/fhir+xml.
When generating the Notification message, the Sending GtK must set the Task attributes as specified in the table below. For complete information on constructing a FHIR® Task Resource, see https://hl7.org/fhir/stu3/task.html .
Attribute | Card. | Description |
basedOn | 0..* | Optional reference to a request-Type resource that produced this event. If a workflow has been initiated and a Workflow Task is present, this must be referenced. |
groupIdentifier | 1..1 | Unique identifier of the data set that is made available. An update to an existing data set at the Sending System triggers a new Notification Task, and thus a new Notification Task instance. Multiple Notifications Tasks on the same data set must share one unique identifier so that the Receiving System can identify them as relating to the same data set at the Sending System. |
identifier | 1..1 | Business identifier of the task. This is a required field for traceability and cancellation of individual Notifications. |
status | 1..1 | The state communicated by this event.
|
intent | 1..1
| Indicates the "level" of actionability associated with the Task[2].
|
code.coding | 1..1 | A code briefly describing what the task involves:
|
restriction.period | 0..1 | The period during which the data will be available for retrieval. |
requester.agent.identifier | 1..1 | Identifier of the system that initiated the Notification. |
requester.onBehalfOf.identifier | 1..1 | Identifier of the Organization at which the data has been made available. The identifier shall be in the system “http://fhir.nl/fhir/NamingSystem/ura” |
owner.identifier | 1..1 | Identifier of the Receiving Organization. |
input:authorization-base | 0..1 | The authorization base to be used when retrieving the data. Constraints:
|
input:get-workflow-task | 0..1 | An indicator to show whether or not all available resources are part of this Notification. Constraints:
Where valueBoolean:
|
input: read-available-resource | 0..* | The FHIR®-read interactions that can be performed to retrieve the data that was made available. Constraints:
Where:
|
input: query-available-resources | 0..* | The FHIR®-search interactions that can be performed to retrieve the data that was made available. Constraints:
Where:
|
The Sending GtK MAY choose not to list the available FHIR® resources in Task.input. In that case, the Sending GtK MUST provide a reference to a Workflow Task resource in Task.basedOn. This Workflow Task MUST list the available FHIR® resources in Task.input, in the same format that is specified for the Notification Task. Additionally, in this case the Notification Task MUST have an entry in Task.input with the following values:
Task.input.type.coding.system: "http://fhir.nl/fhir/NamingSystem/TaskParameter"
Task.input.type.coding.value: “get-workflow-task”
ask.input.valueBoolean: true
The Receiving System must accept both media types application/fhir+json and application/fhir+xml.
On receiving the submission, the Receiving GtK must validate the resource and respond with one of the HTTP codes defined in the Notification response.
The Notification should trigger an event in the Receiving GtK to process the expected Pull.
Persistence of the Notification Task as a FHIR® resource is not necessary.
When the data set for which a Notification message has been sent is updated in the Sending GtK, the Sending GtK must inform the Receiving GtK about this update by sending a new Notification Message. In this case, Task.input:read-available-resource and Task.input:query-available-resources should only list the updated FHIR® resources. This way, the update can be communicated as a delta to the original data set. This relieves the Receiving GtK of determining which resources have changed in a larger set of resources. Note that the value of Task.identifier for the new Notification Task must differ from the value of Task.identifier Notification Task for the original data set, while the value of Task.groupIdentifier must be the same for all Notification Tasks on the same data set. This way, consecutive Notification Tasks on the same data set can be related to each other by the value of Task.groupIdentifier.
Response message
This message must be provided when a success or error condition needs to be communicated in response to an inbound request message. Success is only indicated once the Notification is received and completely processed.
To enable the Sending GtK to know the outcome of technical / syntactic processing of the Notification Task, the Receiving GtK must return either an empty body or an OperationOutcome resource. This body must be accompanied with the correct HTTP status code, e.g.:
200 OK – Notification received and not persisted.
201 Created – Notification received and persisted. In this case http-headers Location and Etag should be filled.
400 Bad Request – Notification could not be parsed or failed basic FHIR® validation rules.
404 Not Found – Resource type not supported, or wrong endpoint.
412 Precondition Failed – The processing of the Notification Task could not be finished, since the criteria were not selective enough.
422 Unprocessable Entity – The Notification Task resource violated applicable server business rules. This should be accompanied by an OperationOutcome resource providing additional detail.
Whether or not the resources in input can be retrieved shall not be a factor in the HTTP status.
The Sending GtK processes the response according to application defined rules.