Transaction operations

NB: This is a draft specification!

Creating transactions

ZorgDomein Integrator supports creating transactions in ZorgDomein though the FHIR interface. Creating a transaction in ZorgDomein requires user interaction in the ZorgDomein UI, because a transaction requires the completion of one or more documents in the ZorgDomein UI and the selection of the transaction recipient. Creating transactions in ZorgDomein depends on the exchange of a FHIR Task resource with the application of the initiator. This Task resource represents the transaction in the application of the initiator.

When a user initiates a transaction through SSO to ZorgDomein from his source application, that application can leverage the interface with ZorgDomein to provide contextual and medical data to ZorgDomein. ZorgDomein will use the provided data to automate initialization of the transaction in ZorgDomein as much as possible. This means for instance that patient details are used to set the patient context in ZorgDomein. The application context in ZorgDomein will be derived from a FHIR Task resource that is exchanged between the source application and ZorgDomein. The url of this Task resource is provided in the SSO request, see documentation of SSO to ZorgDomein for additional details. This way the SSO request serves as a front channel notification to ZorgDomein. Subsequently, ZorgDomein will request the Task resource at the source application and it will use the following parameters from this Task resource to set the application context in ZorgDomein:

• Task.for: Reference to a Patient resource that contains the details of the patient who is subject of this transaction. ZorgDomein will request this Patient resource and will use the provided patient details in this resource to set the patient details in ZorgDomein.
• Task.code: Specifies the transaction type the user intents to initiate when launching ZorgDomein.
• Task.owner: AGB-code or name of the intended recipient of the transaction (this only applies to sending reports).

Additionally, ZorgDomein will send a FHIR search query to the Coverage endpoint of the source application to obtain insurance details for the patient:

GET [base]/Coverage?subsriber=[PatientId]&_include=Coverage:payor 

Almost all transactions in ZorgDomein include the creation of one or more documents. ZorgDomein will request medical patient data at the source application to prefill this document in the ZorgDomein UI as much as possible. This data will be requested at the source application in the form of Health and Care Information models (HCIMs (English) or zibs (Dutch)), exchanged as FHIR resources. s When the user starts a transaction to send a report, ZorgDomein will use the value of Task.input to initialize the document for the user. If there is an input value where input.type = "document" and input.valueReference refers to a Composition resource, ZorgDomein will request the Composition resource at the source application and will extract the following data from it:

• Composition.type: Document type the user intends to send.
• Composition.text.div: Body text of the document that the user intends to send.
• Composition.section.where(code.coding.where(system='http://zorgdomein.nl/terminology/code-system/document-section' and code='attachments'))].entry: Reference(s) to DocumentReferences resources that should be added as attachment to the document.

Updating existing transactions

Both the initiator and the recipient of a transaction can update existing transactions with new input or output. The way by which this data is exchanged differs for both actors.

Updating existing transactions as initiator

When a transaction has been started through a FHIR interface with the application of the initiator, the initiator of that transaction can provide new input to that transaction through that interface. From the initiator’s perspective, the initiating application is the source of the transaction. Therefore, transaction updates should initially be applied to the FHIR server of the initiating application and then be exchanged using the notified-pull exchange pattern. This means that the initiating application should send a notification to inform ZorgDomein about an updated transaction. This notification may be a front channel notification (i.e. SSO request) or a back channel notification. When ZorgDomein receives this notification, it will request the Task resource at the initiating application to see what’s new using a FHIR read request:

GET [AppFhirServerUrl]/Task/[AppTaskId]

ZorgDomein supports exchanging status updates and new input documents (e.g., a supplementary document (nazending) or a transfer document following a placement request) for the initiator of the transaction by updates in the following Task parameters:

• Task.status: can only be changed to cancelled
• Task.input:
  • Slice document:
    • input.type: document (fixed value)
    • input.valueReference: Reference to a Composition resource with additional details about the document that should be added as input to the transaction. If this reference is provided, ZorgDomein will request the Composition resource and will extract the following data from it:
• Composition.type: Document type the user intends to send.
• Composition.section[].text: Body text of the document that the user intends to send.
• Composition.section[?(@.code.coding[0].code==‘attachments’)].entry: Reference(s) to binary resources that should be added as attachment to the document.
• Composition.extension[name=‘template’].valueReference: Reference to a Questionnaire resource that defines the questions (or sections) to be answered. This parameter requires user interaction in ZorgDomein to finish the document.

Updating existing transactions as recipient

The recipient of a transaction may update the transaction with output data as it processes the service request or report that was issued by the initiator. From the recipient’s perspective, ZorgDomein is the source of the transaction. Therefore, all updates from the recipient to the transaction are exchanged using the push exchange pattern, i.e., a FHIR update request on the Task resource at ZorgDomein:

PUT [ZdFhirServerUrl/Task/[ZdTaskId]

See the specifications for update requests at the resource provider for additional details. The update might include references to FHIR resources that are residing at the FHIR server of the recipient. If needed, ZorgDomein can request these resources at FHIR server of the recipient.

ZorgDomein supports exchanging status updates and new output documents (e.g., a progress report) for the recipient of the transaction by updates in the following Task parameters:

• Task.status: accepted values for transaction recipients: received, accepted, rejected
• Task.input:
  • Slice document:
    • input.type: document (fixed value)
    • input.valueReference: Reference to a Composition resource with additional details about the document that should be added as input to the transaction. If this reference is provided, ZorgDomein will request the Composition resource and will extract the following data from it:
      • Composition.type: Document type the user intends to send.
      • Composition.section.text: Body text of the document that the user intends to send.
      • Composition.section[?(@.code.coding[0].code==‘attachments’)].entry: Reference(s) to binary resources that should be added as attachment to the document.
      • Composition.extension[name=‘template’].valueReference: Reference to a Questionnaire resource that defines the questions (or sections) to be answered. This parameter requires user interaction in ZorgDomein to finish the document.
• Task.output:
  • Slice appointment:
    • output.type: appointment (fixed value).
    • output.valueReference: reference to an Appointment resource at an external application that represents an appointment at a healthcare supplier.
  • Slice patient-intake:
    • output.type: patient-intake (fixed value).
    • output.valueReference: reference to a CarePlan resource at an external application that represents a patient intake at a healthcare supplier.

If the new output document requires user interaction to be finished and submitted, the receiving application must send an SSO request to ZorgDomein right after the Task update to enable the user to finish the document in ZorgDomein. In this SSO request, the receiving application should provide the url of the Task resource at ZorgDomein that represents the transaction that this document belongs to (see specifications for SSO to ZorgDomein for details about providing the ZD-number in the SSO request).

Updating referenced resources

In many cases, transaction updates from either the initiator or the recipient are not reflected in the Task resource directly, but in other referenced resources. For example, an update to an existing appointment is reflected in an Appointment resource that is referenced by a Task resource, and not in the Task resource itself. Therefore, exchanging these kinds of updates with ZorgDomein by exchanging an update in the Task resource is pointless, because the update is not reflected in the Task resource. The only way that ZorgDomein is able to detect updates in referenced resources after a Task update, is to request all referenced resources at the external application. However, that is not desirable, because it might require a lot of data requests to detect a single change in one resource. Therefore, transaction updates that are only reflected in referenced resource are exchanged by an update to those referenced resources. Therefore, updates to resources are exchanged by a notified-pull exchange pattern if the external application is the source of these resources. That starts with a notification from the external application to ZorgDomein:

POST [ZdNotificationUrl]/[UpdatedResourceType]/[AppResourceId]

Subsequently, ZorgDomein will request the updated resource at the external application using a FHIR read request:

GET [AppFhirServerUrl]/[UpdatedResourceType]/[AppResourceId]

Receiving transaction data

Both the initiator and the recipient of a transaction should receive all new and updated data that is added to that transaction. The way by which this data is exchanged differs for both actors.

Receiving transaction data as initiator

The initiator of a transaction must be informed about all new transaction data that is created in or passed through by ZorgDomein. In the example of a GP sending a referral to a hospital, the GP (being the initiator of the transaction) generates a referral letter in ZorgDomein which must be archived in the GP’s information system. Hence that referral letter must be exchanged with that information system as part of an update of the transaction in the GP’s information system. When a transaction has been started through a FHIR interface with the application of the initiator, a Task resource has been provided by that application to ZorgDomein. That implies that the initiating application is the source of the transaction from the initiator’s perspective. Therefore, all updates from ZorgDomein to the transaction are exchanged using the push exchange pattern, i.e., a HTTP PUT request on the Task resource at the application of the initiator:

PUT [AppFhirServerUrl]/Task/[AppTaskId]

See the specifications for update requests for additional details.
The update might include references to FHIR resources that are residing at ZorgDomein. If needed, the initiating application can request these resources at ZorgDomein using FHIR read requests:

GET [ZdFhirServerUrl]/[ResourceType]/[ZdResourceId]

ZorgDomein may update the following attributes in the Task resource of the initiating application:

• Task.identifier: ZD-number of the transaction in ZorgDomein.
• Task.status: status of the transaction.
• Task.owner:
  • Task.owner.reference: Reference to an Organization resource if the recipient of the transaction is an organization; reference to a Practitioner resource if the recipient is an individual Practitioner.
  • Task.owner.identifier:
    • Task.owner.identifier.system: http://fhir.nl/fhir/NamingSystem/agb-z (fixed value).
    • Task.owner.identifier.value: AGB-code of the recipient of the transaction.
    • Task.owner.identifier.display: Display name of the recipient of the transaction.
• Task.input:
  • Slice document:
    • input.type: document (fixed value)
    • input.valueReference: reference to a Composition resource at ZorgDomein that represents an input document that was generated in ZorgDomein.
• Task.output:
  • Slice document:
    • input.type: document (fixed value)
    • input.valueReference: reference to a Composition resource that represents an output document from the recipient that was generated in or passed through by ZorgDomein.

Receiving transaction data as recipient

The recipient of a transaction must be informed about all new transaction data that is created in or passed through by ZorgDomein. In the example of a GP sending a referral to a hospital, the GP generates a transaction with a referral letter in ZorgDomein which must be delivered at the hospital. Therefore, that transaction including the referral letter must be exchanged with the information system of the hospital. From the recipient’s perspective, ZorgDomein is the source of the transaction. Therefore, all new and updated transactions are exchanged using the notified-pull exchange pattern. This means that ZorgDomein will send a notification to the receiving application to inform the recipient about new or updated transaction data.

POST [AppNotficationUrl]/Task/[ZdTaskId]

Subsequently, the receiving application should request the Task resource ZorgDomein using a FHIR read request:

GET [ZdFhirServerUrl]/Task/[ZdTaskId]

If the external application detects a new reference to an external resource in the Task resource, it should request that resource at ZorgDomein using a FHIR read request:

GET [ZdFhirServerUrl]/[ResourceType]/[ZdResourceId]

Receiving updates in referenced resources

In many cases, updated transaction data is not reflected in the Task resource directly, but in other referenced resources. For example, an update to an existing document is reflected in a Composition resource that is referenced by a Task resource, and not in the Task resource itself. Therefore, exchanging these kind of updates with external applications by exchanging an update in the Task resource is pointless, because the update in not reflected in the Task resource. The only way that an external application is able to detect updates in referenced resources after a Task update, is to request all referenced resources. However, that is not desirable, because it might require a lot of data requests to detect a single change in one resource. Therefore, transaction updates that are only reflected in referenced resources are exchanged by an update to those referenced resources. Both for transaction initiators and transaction recipients, ZorgDomein can be considered as the source of those resources. Therefore, updates to these resources are exchanged by a notified-pull exchange pattern. That starts with a notification from ZorgDomein to the external application:

POST [AppNotificationUrl]/[UpdatedResourceType]/[ZdResourceId]

Subsequently, the external application can request the updated resource at ZorgDomein using a FHIR read request:

GET [ZdFhirServerUrl]/[UpdatedResourceType]/[ZdResourceId]