Bills-FHIR-page

These are my notes on FHIR. As they become mature they will probably migrate to John's page.

FHIR class

March 11, 12 2014 I took FHIR class given by HL7 (Floyd taught). The slides from that class are available for download from here

As a summary of the class, I believe that the full semantics of XDS.b can be translated to FHIR with the exception of Folders. I have not looked into Folders yet. This would mean replacing the ebXML Registry binding with the FHIR binding and replacing the SOAP binding with the combination of FHIR REST and ATOM. I describe it this way because FHIR has its own flavor of REST and ATOM. (a comment, not a criticism).

The class was quite overwhelming in the same way that drinking from a fire hose is overwhelming.

What follows below are my notes from the class. I will continue to add to this page as I discover more things that I learned (see fire hose).

A recording for the FHIR discussion call dated March 25, 2014 is available [ https://himss.webex.com/himss/lsr.php?RCID=50c82cc0cad841998bbfb0e26d45661b/ here]

Terminology

We are going to have a hard time with terminology. FHIR and DS use a lot of the same terms. They just don't have the same meaning. The following sections offer some important terminology, how it is used by FHIR and how it related to DS and ebRIM.

Global and local ids

In ebRIM a global ID is a UUID and a local ID is any other value. In FHIR a global ID is a URI which can be dereferenced to obtain the content referenced and a local ID is a UUID.

Resource

In FHIR a resource is a predefined object (XML or JSON or RDF) that describes something interesting about heath care. There are currently about 50 resource types defined. Eventually there will be about 100. The DocumentReference resource maps approximately to a DocumentEntry. The the Manifest resource maps approximately to a SubmissionSet. Most of the detail coded in a resource is optional so you can use what you need. Resources can be extended using, wait for it, Extensions. We will be writing a bunch of extensions.

In the most basic form of FHIR, a resource is created/retrieved one at a time using REST GET/PUT/POST. They can also be created/retrieved in collections (more than one resource at a time). The most basic collection is called a Bundle. This will be discussed more later since additional background is necessary to understand.

Metadata

In ebRIM metadata is the collection of attributes describing a document. In FHIR metadata is a collection of details about a resource. Metadata is not part of the resource, it stands alone. Metadata can be sent/received in a request or response to pass information about the resource but it is not part of the resource. It's scope may be limited to the request/response. Request/response usually means a REST request or response. An example of metadata is the URI of a resource returned from a GET. The metadata contains the URI including version information. Confidentially information is coded as metadata since it may change over the lifetime of the resource. If the resource is signed then a simple change to confidentially information would trigger a new version of the resource and a new signature. So metadata contains information about the resource that can reasonably change over the lifetime of the resource without really impacting the content of the resource.

In some contexts metadata is also called Tags. Metadata is handled differently depending on the context of the transfer. The two major examples are transfer of a single resource via REST and transfer of a resource as part of a transaction.

Message vs request/response vs transaction

These are 3 totally separate concepts in FHIR.

A simple REST request/response transfers a single resource. Each resource is individually addressable (is assigned a permanent URI). Using PUT/POST/GET a resource can be created, updated and retrieved. In this environment, metadata about the resource can be transferred as Tags. Tags are coded as HTTP headers. So a GET of a resource will return the resource in the body of the GET response and will also return relevant metadata as HTTP headers in the response.

A transaction is the submission/retrieval of a collection of resources. The transactions carries the expected semantics: all or none (in the context of a submission). A later section will describe how to map IHE Document Sharing transactions into FHIR transactions. FHIR transactions are much more general than we need but our semantics can be defined using FHIR transactions.

Messages are request/response pairs that occur in response to an external event. This is a much more advanced topic and we can safely ignore it for now.

REST vs Transaction addresing (URIs)

FHIR has transactions and it has REST. Here I mean REST in the form of direct addressing of individual objects like DocumentEntry and SubmissionSet (XDS terms).

On the direct addressing side, one can submit a single object, say DocumentReference, assigning it a permanent ID or allowing the server to assign the ID. To submit allowing the server to assign the ID you would POST the single DocumentReference object to

    http://server.com/xds/DocumentReference

where

http://server.com/xds

defines the server and service supporting FHIR (yes, I made them up). The FHIR server would reply giving status (HTTP status) and giving you the permanent address of the object in a HTTP header. This header is technically FHIR metadata and more specifically called a Tag:

    Location: http://server.com/xds/DocumentReference/1002/_history/1

where 1002 is the assigned ID (server controlled) and the _history/1 indicates that this is the first version of this object. The object can be retrieved with a GET to

    http://server.com/xds/DocumentReference/1002

which will return the most recent version or via

    http://server.com/xds/DocumentReference/1002_history/1

to specifically request version 1.

This shows the most simple submit/retrieve operation on Document Sharing metadata.

The simple submit/retrieve has been done via REST. No transaction was involved.

Bundles

Bundles are used everywhere in FHIR. In some ways bundles in FHIR are like multi-part in SOAP but the comparison probably is more harmful than helpful. They allow a collection of resources to be included. Bundles, like everything else, are coded in XML or JSON or RDF (RDF is a format on the near horizon - not in the current documentation).

Bundles are used differently in submission and retrieve. Raw bundles are use in retrieve/query response since there is no obvious connection between the individual objects returned. In submit, there is structure that must be coded in the same way that in our Provide and Register transaction there is a DocumentEntry that is linked to an attached Document through the rules of MTOM. Our Provide and Register or Register transactions will require FHIR transaction semantics to construct the equivalent Document Sharing semantics.

Documents

FHIR Documents are unrelated to what IHE Document Sharing calls documents.

A Document Sharing document maps to a FHIR binary resource. It's just an un-interpreted collection of bytes.

In FHIR a document is a structured/organized collection of resources. A document can be submitted. When received at the server it can be saved as a document OR broken apart into individual resources. This is a decision of the server. If the server keeps the document as a single entity then it can be retrieved as a single object (will have a permanent URI assigned). If the server saved it as individual resources then the individual resources can be retrieved individually (they will each have a permanent URI).

To fully appreciate this semantic you must realize that HL7 anticipates that FHIR will eventually replace V2, V3, and CDA. Maintaining a document as a single entity would mimic the behavior of the current CDA specification with one very large expansion of capability. Individual parts of a document can be web addressable (have their own URI). Again, a choice of the receiving server.

Documents are bundles organized using the ATOM Feed structure. A document is flattened to a list of entries (entry is an element defined in the ATOM structure). The first entry is always the document's header. The header is an instance of the Composition resource. The header includes references to other entries in the document. Actually, any entry may include a reference to another entry. There may be a digital signature on the whole bundle to attest to the content of the document.

This example, taken from Floyd's class, shows how the ATOM feed is a collection of entries. Each entry contains a FHIR resource (Composition, Observation, Device, Prescription, Patient). Each of these resources may link to one or more of the others. The Composition resource links to all of them.

<feed>
    <entry>
        <Composition/>
    </entry>
    <entry>
        <Observation/>
    </entry>
    <entry>
        <Device/>
    </entry>
    <entry>
        <Prescription/>
    </entry>
    <entry>
        <Patient/>
    </entry>
</feed>

To map Document Sharing semantics onto FHIR documents we examine, at a very high level, how the Provide and Register transaction and Register transaction would use FHIR documents. A later section will describe how to build up the necessary FHIR documents.

The Document Sharing Register transaction conveys a SubmissionSet and a collection of DocumentEntry objects. We will ignore Folders and Associations for now. In FHIR this would be a Manifest resource and a collection of DocumentReferent resources. These would be assembled into a FHIR Document and sent to the Document Registry. The Document Registry would disassemble the Document and store the individual Manifest and DocumentReference resources. We can do this because we have our record of what was submitted together, the connection to the SubmissionSet/Manifest. The Document Registry now has the content to service query requests.

The FHIR based Register transaction would be constructed as a FHIR transaction so the all-or-none semantics apply. FHIR documents are always submitted via transactions so nothing special is happening here.

The Document Sharing Provide and Register transaction is obviously more complicated. It must include the binary resource representing the DS documents and the DS documents must be linked to the appropriate DocumentReference (DocumentEntry) resource. The FHIR document structure allows these additional resources to be added and the linkage between objects, DocumentReference resource to binary resource, is possible. The FHIR based Document Repository has the identical responsibilities as the ebRIM based one: remove and store the binary resources, update the DocumentReference resources and forwarding on the FHIR Register transaction. Because FHIR is REST based by default, instead of having a repositoryUniqueId that maps to a SOAP endpoint, the binary resource (aka DS Document) has a URI so it can be retrieved via a HTTP GET. Also, since the FHIR server representing the Document Repository is responsible for assigning the permanent globally unique identifier to the binary resource, it can use the DocumentEntry.uniqueId present in the Provide and Register transaction.

Communicating Documents

Documents can be sent to a server's root URI for processing as a transaction. Each resource is processed separately. Document Id and signature are lost.

Documents can be dropped on a FHIR mailbox. No storage or disassembly is implied. The server determines the behavior.

How are these approaches different? The same?

Events are a separate topic in FHIR. Mailboxes are used as the target/recipient of transactions containing messages that are identified by an event code. This does not apply to Document Sharing. We will focus on transactions.

How to construct documents

We already said that the Provide and Register transaction and the Register transaction would be constructed using FHIR documents. This section describes how these documents are constructed our of FHIR resources.

First, a FHIR document is constructing using an ATOM feed object containing the content. The ATOM feed object is then transferred via a REST POST. One way to think of this is that the ATOM feed object maps to MTOM and Multipart. Not exactly accurate but a good start.

More specifically, the document is coded as a bundle. In XML, a bundle is coded as an ATOM Feed.