Using the HL7 FHIR IG Builder for other Standards

As I mentioned earlier this week, there's a way that one can use the IG Builder to profile other content.  It all depends on having a FHIR Structure Definition for that content, as exists for CDA 2.1 and HL7 Version 2 Messages.  These two examples demonstrate that other structured content (such as that used for XDS-b, or NCPDP and X12) can also be documented using the StructuredDefinition resource.  This was one of Grahame's desiderata for constructing that resource, not that it was a requirement at all for FHIR, just a generally good idea he implemented because it was the right thing to do.

Using this structure definitions as the foundation, one can apply other FHIR tools, such as Sushi, or the IG Builder to create an implementation guide.  Sushi would need some work to create example instances using features of the StructureDefinition resource it probably doesn't deal well with right now (e.g., using XML attributes to describe output).

And IG Builder right now defaults to using a set of canonical StructureDefinitions for different versions of FHIR, although I'm sure there's a way to get it to look at others, although it might require additional work to expose that as an option.

Even so, imagine if everyone in healthcare could use the same set of tools to build an IG using standards from multiple SDOs.  It's a nice pipe dream.

Thoughts on a canonical FHIR Implementation Guide Outline

I've been working on implementation guides for decades, first in CDA and then in FHIR, in HL7, IHE and other SDOs.  Everyone has  a slightly different approach, but there's also a lot of commonality.

Assuming a web publication format with highly linkable output, this is how I would put the outline together today:

Home

The home page orients you towards the entire specification.  It contains a short (no more than a paragraph) description of the problem it solves, and allows you to navigate through the main components of the specification. It includes at the end a link to download the specification or subcomponents of it used for implementation, a link to any source code or other materials, et cetera.

Intro

The introduction section describes the content of the IG in more detail.  This includes the audience for the material, the scope of work explicitly included and excluded, describes the conventions used in the document (e.g., key words such as SHALL/SHOULD/MAY, other conventions), describes the organization of the document in detail, and acknowledges contibutors and/or sponsors of the work.  If there's a short glossary, it can go in this section as well, a longer glossary goes at the end in an appendix.

Overview

The overview section gives a clear and detailed statement of the problem that the IG is trying to solve.  It includes an explanatory description of key concepts and terms which may not be familiar to all readers, but these are short (more detailed material can be included as references).  It can also provide a description of the technical environment in which the IG is expected to be used (e.g., what systems, networks, et cetera, are available/used).

Use Cases

The use cases section lists each high level use case (these are user oriented), provides a short description of each one, and then launches into a detailed description of each of the use cases.  The detailed descriptions include sequence diagrams associated with the steps of the use case, along with a narrative description of what happens in each step.

Actors

The actors section lists each technical (e.g., non-human or system) actor identified in the use cases, and specifically identifies the requirements of each of these.  If there's optional behavior for the actors, it can be described in this section.  I'd recommend identifying options by name, and giving requirements for each named option (this is how IHE handles options), as it makes addressing verifying implementations do what they say they will do (a.k.a., Conformity Assessment) a lot easier.

Security

There should be a security considerations section that addresses security concerns.  This section should identify all the security concerns, and may reference more detailed content elsewhere in the IG.  The security concerns section may identify specific actor requirements, but these should be detailed in the requirements for individual actors.  This is so that all requirements are present in one place, not spread throughout the IG.

Interactions

There should be a section to describe all the interactions the IG has between the technical actors it defined (IHE identifies these as transactions).  In a RESTful environment, these are the GET/PUT/POST/DELETE operations that it supports.  In FHIR, these are the operations that the IG describes.  This includes the standard ones such as read, vread, search, create and update, and others such as $expand, but also includes any custom operations described by the IG.

Detailed Interaction Descriptions

Each interaction should describe the requirements of the actors participating in the interaction, and should also include a security considerations section, which should indicate specific security requirements that can be tested during the execution of the interaction (e.g., audit logging, encryption, et cetera).  When the interactions work with profiled content, the requirements should indicate that the interaction shall operate on content that conforms to the specific profile.  That profile should be described in more detail in a separate section.  There are some occasions where a FHIR Resource profile is described in general form (e.g., uses this content), but have specific constraints in the content of some interaction (for example, when a resource is sent via create, it shall not have an id, but when sent for an update, it shall).  In this case, make these specific requirements of the interaction.  One can also create profiles specific to each interaction, but this should only be done when warranted by complexity.

Content Profiles

There should be a section that provides a high level description of each content profile (e.g., resources, extensions, value sets, coding systems, capability statements et cetera).  These should be organized in some way (e.g., by type), and described individually.  Best practice indicates that the resource or extension profile content should include at least some sort of introductory section describing the purpose and rationale.

Detailed Content Profile Descriptions

Each content profile (e.g., Resource, Extension, Value Set) should have not just the requirements, but also an explanation of why they exist (the rationale).  This will help to explain to readers why this item is required and what the purpose is behind its inclusion.

Examples

The examples section (or appendix) provides examples of conforming interactions and content.  One include examples with each interaction and content.  The examples section simply aggregates these these and provides a high level description of each example.

I've been working on a few examples of this.  You can see what I did for the IHE ACDC Profile and the HL7 mHealth App Data Exchange IG on the web.

I'm not perfect, and I haven't managed to hit on all of the above in either profile.  You can also see I have experimented with slightly different organizations of each as well.  I'm working towards the idea that there should be one generalized approach though, and I can see where I might be able to put together a pretty decent outline for use by either IHE or HL7 for use with the FHIR IG Builder.

   Keith

P.S.  While the work I'm doing here is strictly related to FHIR, there's a notion that this could be applied more broadly that would enable this and my earlier post this week for other structured formats such as CDA, HL7 Version 2, even X12 and NCPDP wire formats.  I'll talk about this a little bit later.

Leading the Ride at MITRE is the first FHIR Lord

There's the people that do the work, and then there's the people who make doing the work possible.  Sometimes that means going out and blazing the trail, and at other times, that means giving the team the needed bulldozers so that they can just mow it down themselves.  Dr. Mark Kramer of MITRE is just that kind of person.

Mark is one of those rare technical leads who retains his technical acumen even after being promoted to two orders of magnitude greater responsibility.  In fact, if there's anything that's the opposite of the Peter Principle, it's what I'm going to start calling the Mark Principle, which is that there are some people which really can do it all more than competently.

Mark's been involved in many technical projects which perhaps should have earned him an Ad Hoc Harley long before, including hData, CQL, Synthea, and is leader behind Sushi which recently earned one of his teams the Ad Hoc Bike Week, and the lead contributor to that project also earned a Serious Chrome upgrade to a prior Ad Hoc Harley. 

That should tell you something about the quality of work that Mitre and Mark's teams do.  In fact, Mitre is one of only two organizations* that can claim more than one honoree among Ad Hoc awardees.

Mark now joins a very elite club, as the 2019 inductee to the Ladies and Lords of the Ad Hoc Harley.  In fact, with his accomplishments and this award, he's the first person who could accurately claim to be a FHIR Lord.

Mark Kramer

Semper et semper ascendens deinceps

(ever and ever riding forward)

My Favorite Tools for Building FHIR Implementation Guides for IHE and HL7

I've been doing a lot of implementation guide development lately, and have some favorite tools that I'm starting to work with.  Here's a look at what I've been using.

Source Code

The first of these is a source code repository.  I've been using GIT for source control, and github.com as a free repository for IG development.  You can look at two of the guides I've developed at github.com/IHE/ACDC and github.com/HL7/fhir-project-mhealth to see two of the projects I've built using this toolset.

Editing Content

I like writing content in something simple.  A long time ago I prototyped a process for IHE whereby we created IHE Profile content on the IHE Wiki.  Wikitext in MediaWiki is nearly the same as Markdown.  The value of using something like this is that it allows contributors to focus more on content and less on formatting or making things pretty.  Pretty is good, but that should be the purview of a single person with appropriate design skills rather than a dozen volunteer editors.

Text Content

So, these days, I'm using a the fairly simple Markdown editor provided in Eclipse (more on that later).  There are plenty of Markdown editors you can use, many which work in Eclipse.  I also use FluentMark from time to time.  My favorite XML Editor also supports JSon and Markdown content.

One of the challenges that contributors often have with Markdown is that it's really not very user friendly for editing and creating content pages.  Confluence or other Wiki style pages are a good place to enable not technical users to create content.  Unfortunately, they don't integrate well with source code control systems.  I'm going to look into some solutions whereby we can get some good content editing that integrates into git-based solutions.

Image Content

My biggest used for image content is with structured images, for example UML Use Case, Sequence and Class diagrams.  My goto editor for this material is PlantUML.  PlantUml has an Eclipse plugin that allows you to view UML diagrams within Eclipse while you edit the diagram in a text editor.  You can also run PlantUml from the command line to automate the process of image conversion.  This makes it really useful in automated builds.

XML and JSon Content

I'm really happy with Oxygen XML Editor for editing structured content like XML and JSON documents.  Happily, it also supports Markdown so I can use it for that too.  It has some features that are helpful for finding invalid Unicode characters, something that shows up frequently when you copy and paste text from Word into your markdown documents.

Converting from Microsoft Word or Other Formats

For those that have a lot of content already in Microsoft Word or PDF or other formats, PanDoc is an excellent open source tool for converting content between these formats and Markdown.  PanDoc supports a number of flavors of Markdown, including CommonMark which is the format used by the HL7 Implementation Guide Builder.

FHIR Profiles and Instances

There are a number of different tools that support building FHIR Profiles and instances.  The original FHIR specification build tools allow you to specify profile content in Microsoft Excel, but that's pretty complex tool chain for most user's.  Today, I'm using SUSHI which compiles FHIR Shorthand into Profiles and example instances.  This is an open source tool developed by an award winning team of people over at Mitre.  While still very much a work in progress, it's already saved me a tremendous amount of time, and the Mitre team has been very responsive.

Build Environment

Integrated Development Environment

These days I use Eclipse as my integrated development environment.  I'd love to figure out a way to make of the editing capabilities available using something like Confluence and provide some automated conversions so that when you create or update a content page, you have an easy way to edit the sub-components it requires (e.g., other content pages in links, or images or example content).

Build Automation

Right now my build environment is very much command line and batch file driven.  What I'd like to do is turn it into a Maven project with dependencies on the various editing and other tools described above.  That way I could build a template project which would automate the build of the IG Content.

IG Builder

I use HL7's IG Builder tool to generate an implementation guide.  Between that and github, it automatically deploys my draft IG to http://build.fhir.org/ whenever I commit something.  However, I like to do a local build to confirm that I'm going to get what I want, and it takes less time to test things out that way.

To perform a local build, I also need to install Jekyll, and to use that I need Ruby.

Putting it All Together

To put this all together, what I'd love to see is an installer that would:

1. Install or use an existing Java VM
2. Install or use an existing set of Git Tools
3. Install or use an existing set of Maven Tools
4. Install or use an existing Eclipse installation
5. Install PlantUML with Eclipse
6. Install or use an Node.js installation (required for Sushi)
7. Install or update the current version of Sushi
8. Install or use an existing Ruby installation.
9. Install or use the existing Ruby Dev Tools.
10. Install or use an existing Jekyll installation.
11. Provide an example projects with pre-constructed outlines following best practices for
1. HL7 FHIR Implementation Guides
2. IHE FHIR Implementation Guides / Profiles
3. IHE non-FHIR Profiles (to demonstrate that IG Builder can be used for these).
12. Provide example plantuml files for use cases, sequence diagrams, and actor / transaction diagrams that are often used in IHE profiles and could be used in other Implementation Guides.
13. Provide documentation for the whole package on how to use the various parts of it.

It's that time again, but what? AGAIN!?!

One of the many unwritten rules of the Ad Hoc Harley award is that you can't earn it more than once.  I'm not going to change that now, but one of the previous recipients has done it again.  And for that, I'm awarding the rare (and heretofore never previous awarded) serious chrome upgrade for this contributors latest piece of work.

If you haven't heard about SUSHI (and no, I'm not talking about what I eat when I travel to standards meetings), and you build FHIR implementation guides, or implement FHIR resources, you NEED to learn about it, and the FHIR Shorthand language for creating FHIR Implementation Guide Resources.

Here's why:  Starting at 10:30 on Saturday, and working about 16 hours straight, I was able to do with SUSHI what in the past would have taken me 5 to 10 days of implementation effort.  As a result, I managed to put together an IHE Profile implementation guide from scratch in record time.

The ability to create implementation guides, value sets, capability statements, coding systems, any sample resource you might ever want in this simple language is simply fantastic.

So, here goes:

This certifies that

Chris Moesel of MITRE

has hereby been recognized AGAIN for awesome work with the rarely awarded and highly coveted Serious Chrome Upgrade.

And furthermore, no man is an island, and no open source project like this can possibly be done alone. So I get to repeat the Bike Week award (originally awarded to the Redoc Dozen).

Chris is working with a team of developers at MITRE that includes:

ngfreiter (Nicolas Freiter)

mint-thompson (Mint Thompson)

kjmahalingam (Dylan Mahalingam)

jafeltra (Julia Afeltra)

Let's give them all, and MITRE a round of applause.

Ad Hoc Bike Week Award

Bending the Healthcare Cost Curve means Cutting Jobs

You've all probably seen the charts. We spend far more in the US than other countries for healthcare.

It's been heading in the wrong direction for decades, and is getting worse.

It also isn't the best care in the world.  Other countries do better measured in many ways.  Lifespan is one of them.

And then finally, there's the growth of administrative costs in the US.

If you look at data from this Robert Wood Johnson study, you can see that Canada's administrative costs are about 15% of the US.

If we are to significantly bend the cost curve, the obvious place to go is after administrative expense.  If you consider the attention that the HL7 Da Vinci project has been getting on Prior Auth, you can see that this is definitely a pain point (even for payers).

And what does that mean?  I'm thinking it means that administrative jobs would disappear from the healthcare marketplace if done right, not providers.  Is this a bad thing?  Frankly, I don't think so.  But for those companies who primarily exist in the healthcare market to facilitate healthcare administration might have a different opinion.  After all, nobody who goes into business ever plans to get out of it.

But, that is the bottom line.  There's stuff we are spending money on in healthcare we don't need, and those who provide it will fight to keep it.