FHIR Documents

Introduction

One of the core functionalities of the ZorgDomein application is to generate transactions such as referrals and healthcare requests. Using these transactions, healthcare practitioners can share logistic and medical patient information with each other. This information is exchanged using clinical documents. The FHIR edition of our interface expresses these documents as FHIR documents. According to the formal definition of FHIR Documents , FHIR resources can be used to build documents that represent a composition: a set of coherent information that is a statement of healthcare information, including clinical observations and services. A document is an immutable set of resources with a fixed presentation that is authored and/or attested by humans, organizations and devices.

Document structure

All FHIR documents have the same structure. The document itself is represented by a FHIR Bundle resource, which is (as the name suggests) a bundle of several different resources that together make up the content of the document.  The first resource in the Bundle is always  a Composition resource, followed by a series of other resources, referenced from the Composition resource. The Bundle gathers all the content of the document into a single XML or JSON document. The Composition resource is the foundation of the clinical document. It:

• Provides identity and its purpose, sets the context of the document
• Carries key information such as the subject and author, and who attests to the document
• Divides the document up into a series of sections, each with their own narrative

According to the ZD Document profile, the key attributes of the Composition resource in the ZorgDomein FHIR Document are: 

• extension.zd-sender - reference to a PractitionerRole resource which represents the responsible sender of the document. The PractitionerRole resource refers to:
  • PractitionerRole.practitioner - Practitioner resource that represents the actual responsible sender.
  • PractitionerRole.organization - Organization resource that represents the organization that the responsible sender belongs to.
  • PractitionerRole.location - Location resource that represents the location of the organization that the responsible sender belongs to.
• extension.zd-actingpractitioner -  reference to a Practitioner resource which represents the acting sender of the document. Please note that there is a difference between the acting sender and the responsible sender. ZorgDomein supports the scenario in which an acting practitioner acts on behalf of a responsible practitioner. 
• extension.zd-recipient - reference to a PractitionerRole resource which represents the intended recipient of the document. The PractitionerRole resource refers to:
  • PractitionerRole.practitioner - Practitioner resource that represents the intended recipient in case the document is to be delivered at a specific person.
  • PractitionerRole.organization - Organization resource that represents the organization that the document is aimed at.
  • PractitionerRole.location - Location resource that represents the location of the organization that the document is aimed at.
• extension.zd-destination - reference to a PractitionerRole resource which represents to which the document must be routed. The PractitionerRole resource refers to:
  • PractitionerRole.practitioner - Practitioner resource that represents the destination in case the document must be routed to an individual practitioner.
  • PractitionerRole.organization - Organization resource that represents the organization that the document must be routed to.
  • PractitionerRole.location - Location resource that represents the location of the organization that the document must be routed to.
• zd-pdfDocument - reference to a DocumentReference resource that contains a Base64 encoded representation of the document in pdf format.
• identifier - ZD number of the transaction to which the document belongs.
• type - document type, see specification of the Document type code system for a complete list of all document types. 
• subject - reference to a Patient resource which represents the patient that is the document’s subject.
• date - creation date of the document.
• author - Practitioner resource that represents the actual responsible sender.

Please note:

• The difference between the zd-recipient and zd-destination extensions may not be evident, but is crucial. For documents that are delivered at the intended recipient these values are identical. However, if the sender of the document has logged in to ZorgDomein through a FHIR interface, ZorgDomein also sends a copy of the submitted document back to the sender. For these copies, the values of these two extensions are different: 
  • For copy documents, zd-recipient points to the intended recipient of the document
  • For copy documents, zd-destination points to the sender of the document This means that the zd-destination  extension should be used for delivering the document at the right organization or user in the receiving application.
    Furthermore, by comparing the values of zd-recipient and zd-destination, the receiving application can determine wether the document is a copy of a sent message (which can be archived as outgoing message) or an incoming new message that should be notified by the recipient. If the values of these two extension are identical, the document is a new message, if the values are different it is a copy document. 
• The author attribute refers to the same Practitioner resource as referred to by the zd-sender extension. Because the author attribute only allows for references to Practitioner resources, we have chosen to introduce the zd-sender extention which is a reference to a PractitionerRole resource which allows us to refer to a Practitioner, Organization and Location resource. 

Any resource referenced directly in the Composition will be included in the Bundle. See the diagram below for a schematic representation of the structure of a FHIR Document and how the different resource refer to each onther (each block within the Bundle represents a resource in the Bundle). 

Receiving documents

Assembled documents will be sent by ZorgDomein to the Bundle-endpoint of the receiving application. This is done by the HTTP POST-method, so a Document with id 123-456 will be POST to /Bundle/ with the XML- or JSON-representation of the document in the body of the HTTP-call.

Delivering documents

Once a document has been received, the receiving application must deliver and publish the document to the intended recipient. It is important that we can ensure that the document is delivered to the right recipient. Therefore, the recipient of a document is always labelled with a unqiue identifier that is known at both the receiving application as at ZorgDomein. Only then we can ensure that both parties know the recipient, and that the receiving application is able to deliver the document at the intended recipient. Documents can be directed at either individual practitioners or organizational units (see this paragraph for more details). 

Delivering to individual practitioners

If the recipient is an individual practitioner it is important that both the receiving application and ZorgDomein have exchanged a unique identifier for this practitioner. The exchange of this identifier is established by the SSO mechanism. During the SSO flow the application must supply a user ID to ZorgDomein in the user-id.system and user-id.value claims in the SSO token. When ZorgDomein receives this token, it will try to find a registered user for the supplied user-id values in the SSO-token. If it fails to find one, ZorgDomein will prompt the user to login manually. After successful login, ZorgDomein will store the provided values for user-id.system and user-id.value in the user account. This way ZorgDomein has obtained the user identifier that the application uses to identify the user.

The application user ID that ZorgDomein obtained through the SSO mechanism is added to each FHIR Document that is to be delivered to a specific user. This way the receiving application can determine to which specific user the document should be made available. This user ID is included in the HTTP POST of the FHIR Bundle in both the HTTP header and body: 

• ZorgDomein will populate the identifier attribute of the Practitioner resource that is referenced by the zd-destination extension in the Bundle with the local application user ID and system that are stored in ZorgDomein for this user.  
• ZorgDomein will include a JSON web token in the Authorization header of the HTTP POST of the Bundle. The user-id.system and user-id.value claims in this JWT will contain the values of the application user ID and system that are stored in ZorgDomein for this user. 

Delivering to organizational units

If the recipient is an organizational unit it is important that both the receiving application and ZorgDomein have exchanged a unique identifier for the organization. The exchange of this identifier is established by the auto-activation mechanism. This is a one-time process by which an application can provide a unique identifier for a known organization to ZorgDomein. Once this process has finished, ZorgDomein has stored this unique organization identifier and will include this indentifier in the HTTP POST of the FHIR Bundle in both the HTTP header and body: 

• ZorgDomein will populate the identifier attribute of the Organization resource that is referenced by the zd-destination extension in the Bundle’s Composition with the organization identifier as echanged during auto-activation. 
• ZorgDomein will include a JSON web token in the Authorization header of the HTTP POST of the Bundle. The org-id.system and org-id.value claims in this JWT will contain the values of the organization identifier as echanged during auto-activation. 

Besides delivering the document at the right organization, the receiving application may deliver the document at the right organizational unit (named “cluster” in ZorgDomein). This yields a more granual delivery mechanism, which helps the receiving organization to address the request more quickly. The name of the cluster is specified in the PractitionerRole.healthcareService.display attribute of the PractitionerRole resource that is referenced by the zd-destination extension in the Bundle’s Composition. Our interface does not support automatic exchange of cluster identifiers, so if you would like to differentiate your delivery mechanism for clusters, you will need to implement a mapping table for each connector implementation where ZorgDomein cluster names can be mapped to corresponding organizational units in your application. 

Attachments

When sending a document like a referral letter or request form, the sender may optionally add one or more attachments to the document. These attachments will be delivered in a separate FHIR document. Therefore, when receiving a FHIR document it is important to check whether the received document is an attachment document or not. Attachment documents can be recognized by the the ZD Attachment Document profile to which the Composition resource in the Bundle claims to conform. This Composition resource contains one or more instances of the ZD DocumentReference Reference extension. Each of these instances points to a DocumentReference resource in the Bundle that contains the base64 encoded binary data in DocumentReference.content.attachment.data. 

An attachment document is always linked to the main document. That means that the document type in Composition.type will have the same value as the main document. This way an attachment document belonging to a referral letter can be distinguished from an attachment document belonging to a supplemental letter for example.