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 (Lloyd 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 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

Documentation for Atom Bundle Representation - very hard to find on FHIR site.

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 Lloyd'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.

Referencing Resources

Reading the FHIR documentation it appears that it is common to have one Resource nested inside another Resource. This is not the case. What you are seeing is a documentation problem with the model. Resources never nest. What you see is actually a nested reference to a resource. Some argue, recently on the FHIR mailing list, that the element ResourceReference should be used instead of Resource. This seems to be an ongoing debate. Each apparent nested Resource is intended to be a reference, a URI, to the Resource. Each Resource instance has its own unique URI.

Contained and FHIR Resource Identity Management

In many FHIR examples you see a section at the top with an outer element of

  <contained/>

A Resource submission is the submission of a single Resource. When a Resource has supporting Resources it is expected that the supporting Resources be submitted separately and the referencing Resources include the link in their content. In DocumentSharing and other places this does not work so well since a concept of an information model may require multiple Resource to describe and it is therefore natural to submit them together.

When this happens, a submission is constructed with focus on the top level Resource. The child Resources are bundled into the contained section.

What happens at the receiving end, the FHIR server, is not really specified. It is a local decision. The most natural approach, from the point of view of FHIR, is to store each Resource separately making it separately addressable. Of course with this view use of the contained model is irrelevant.

In Document Sharing we commonly have a DocumentEntry with one or more nested Author structures. The most natural mapping of this to FHIR is to have the DocumentReference Resource referencing one or more Practitioner Resources. The Practitioner Resources would not be separately addressable since they are not in the ebRIM binding. The FHIR-based Provide and Register transaction, aka MHD Put Document Dossier [ITI-65], would include the DocumentReference and its Practitioner Resources would be carried in the subsequent contained section. The MHD Document Recipient/XDS Document Source grouped actors would construct a DocumentEntry with embedded Author structure according to existing XDS rules.

On the consumer end, the XDS DocumentEntry would be transformed into a Resource Bundle with separate DocumentReference and Practitioner Resources linked in the required FHIR manner. This sounds straight forward but has issues.

When a Resource is submitted, it takes on a permanent URI as its address/identity. From the FHIR perspective, the submitted Practitioner Resource must have the same URI as the retrieved copy. Again from the FHIR perspective, the entire XDS environment looks like a very complicated FHIR server and the same rules would be expected to apply. To meet this goal, the XDS environment would have to do extra work to maintain the Practitioner URI. This makes the linkage to FHIR non-transparent.

This apparent issue appears in a second place. A DocumentEntry submitted from a traditional XDS Document Source would of course submit traditional XDS metadata. Later when retrieved via the MHD Document Consumer the Practitioner Resource would be constructed. Repeat retrievals of this Resource would be expected to carry the same URI as its identity.

To be truly FHIR compliant this object/resource identity management issue appears to be a problem.

In a way we already have this issue with the ebRIM binding. The ebRIM ClassificationScheme used to construct the Author structure has identity through its id attribute. This id can be assigned by the Document Source as a UUID or left as a symbolic id to be overridden by the Document Registry with a UUID. Technically the Document Registry must maintain this value and return it consistently in the Stored Query Response. Current IHE testing does not verify the consistency of this id and I have never heard a vendor complain about a fellow vendors's lack of consistency. Given that the ClassificationScheme is always a nested element this identity serves no purpose in the current model. As mentioned above this issue of nesting is handled very differently in FHIR.

But, this analysis offers a potential solution. If in the mapping between ebRIM and FHIR we stipulate that the Practitioner URI be constructed out of the ClassificationScheme id (a UUID format value) then this identity can be carried through the XDS infrastructure. It is still possible that a particular vendor implication of a Document Registry will have problems because they have never bothered to carry this UUID value. Technically this is a conformance issue with their implementation even though IHE testing has never bothered to check for it in the past. That may have to change.