HL7 Officer Elections are now open, I'm running for Chair, please VOTE (for me).

The CDA Book is sometimes listed for Kindle here and it is also SHIPPING from Amazon! See here for Errata

Thursday, August 14, 2014

An Apple for my Teacher

As promised yesterday, here is my update on HealthKit.  This was a homework assignment for my Informatics class at OHSU.

Is tracking consumer health data the next big niche for Apple?  

His iPhone alarm goes off at 7:30.  He hits his alarm, stumbles into the Kitchen to make coffee.  After downing his morning medications, he opens up an application on his iPhone and records that he remembered to take his blood pressure medication.  Slipping a blood pressure cuff over his wrist, he takes his daily reading.  He then sips his coffee, and realizes he forgot the cream.  On his way to the refrigerator to get the cream, he stops by the nearby scale and weighs himself.  Opening another app, he records that data.  Finally, he adds the cream to his coffee and begins reading his e-mails.  He wishes that he could have just one app for all these details, or that he could at least have a single app to show the impact of his weight on his blood pressure, and what happens when he forgets his medications.  

The story above is very nearly real life.  While I do not have an application to record whether or not I took my medications (I just look at my pill box), I might use one .  However, it is already too frustrating having to use two applications to track my health data.  There are presently more than 30,000 Health and Fitness Apps and 24,000 Medical Apps in the App Store(4) for Apple’s IOS based products.  Almost all of these applications do not work together in any way to share information.   However, Apple’s newest operating system feature for its iPhone devices could soon change that.

Recently Apple announced Health Kit(6), a new feature found in the IOS 8 Operating system to be released later this year, and a new Health App co-developed with Mayo Clinic.  Apple also announced a partnership with Epic, in which Health Kit may be used to share information with Epic’s MyChart portal application  for patients(7).  Other Apps by health and fitness recording device manufacturers Nike, FitBit, and iHealth were also hinted at during the Apple announcement.

From a software developer’s perspective(8), Health Kit is a framework of components that come with the IOS Developer tools used by programmers to develop applications on the IOS Platform.  These tools provide developers with basic components supporting the recording of user characteristics such as birth date and gender, and data samples, such as activity, caloric intake, weight, blood pressure, et cetera.  It also includes tools to create this information, and to access it through queries and aggregate statistic functions like sum, min, max and average.

Founded in 1976, Apple designs, builds and sells cell phones (i.e., iPhone), tablet computers (i.e., iPad and iPad Mini), personal computers (i.e., Mac), media devices (e.g., iPod and Apple TV) and software, services (e.g., iCloud and iLive) and content (e.g., iTunes and iBooks) that are supported on those devices.  Products are sold directly through retail outlets and online stores, and through third parties such as cellular network carriers (e.g., AT&T), retailers (e.g., Best Buy) and value added resellers(1).  With a market capitalization of $587B, worldwide distribution and manufacturing channels, and over $160B in cash, Apple could be a very strong competitor in any market it chose to enter.

Apple rarely competes on price, their products are typically targeted at the premium market, rather than the bottom(3).  Apple has also focused on key niche markets: The Apple II concentrated on the K-12 education market.  The MacIntosh focused on media creation; specifically graphic design, image manipulation, and music and video editing.  In the iPhone and iPad markets, Apple has again targeted the high end, prestige seeking user.  In the Healthcare sector, the iPad remains the tablet of choice according to a recent summary of two tablet market reports(5) and physicians also seem to favor the iPhone over other smart phones.
Historically, Apple has been noted for its attention to user experience with its products.  In 6 Reasons Apple Is So Successful, industry analyst Tim Barjarin enumerates why he feels Apple has succeeded(2).  The reasons include:

  1. People creating the product must want it themselves
  2. Products have to be easy to use
  3. Things should be kept simple
  4. Offer great customer service and in-store experiences
  5. Only make products if Apple can do it better
  6. Stay at least two years ahead of competitors

Every single one of these reasons speaks to various aspects of user experience.  The product needs to be desirable, easy to use, and simple to understand.  The customer should have a great experience, and the best and most technologically advanced product.  This focus on user experience may be the key to differentiating Health Kit form other offerings.

How Health Kit may be different from Other Offerings

Neither Google Health nor Microsoft HealthVault seem to have been great successes for their respective owners.  Google dropped out the personal health record market three years ago, and Sean Nolan recently left his position as General Manager of HealthVault at Microsoft.  Using the cloud for personal health data seems to be on very shaky ground.  Is the consumer market really ready for yet another big vendor’s entre into (and potential early exit) from the consumer health space?

Apple’s foray into this space is a bit different than those of Google Health or Microsoft HealthVault.  Google Health and HealthVault were principally focused on storage of Health data in the cloud for consumers, and not on development for App makers.  However, Apple appears to be more focused on the App developer channel, rather than data in the cloud as being of interest to its consumers.  While Steve Jobs hinted at the future of medical data in the cloud(10), little information has been provided by Apple about where a Health Kit based Health Store lives, or how (or even if) it is synchronized between a user’s different mobile devices, and how iCloud services come into play.  A bit of research indicates that the Health Store object where all Health Kit data lives is not presently supported on iPad devices.  If the Health Store object were simply iCloud based, it would almost have to be supported on the iPad. Further investigation shows that the Health Kit data is presently limited to local storage on iPhone devices(11).

The developer base for IOS is a captive audience for Apple, similar to the MacIntosh before it and the Apple II before that.  Because developers have a great impact on the user experience of its customers, Apple strongly controls that channel.  One must be a Registered Apple Developer just to list an application in the company’s App Store.  As Apple’s App Store is the only method supported by the manufacturer to obtain apps for IOS devices, developers rely heavily on Apple for tools, SDKs, documentation and distribution.   Developers agree to Apple’s Program License Agreement, Human Interface Guidelines, and various other restrictions(9), including subjecting their application to review by Apple before inclusion into the App Store.

Both Microsoft and Google provided APIs and SDKs to access their services in web-based applications, but neither were developing APIs for a nearly captive audience like Apple has.  While Microsoft strongly controlled the Windows APIs, they did not have a lock on the Windows application distribution channel like Apple does.  Microsoft today supports the HealthVault .Net SDK and provides Open Source libraries for about a half-dozen other development platforms to use its HealthVault API.  Google Health had provided a library delivered over Google Code (Google’s own Open Source network) to support its API, but provided little else.  Developers consuming these APIs worked on diverse platforms, and were not readily controlled by either Microsoft or Google.  There was often no direct relationship between these developers and the companies hosting the health data in the cloud.

Apple’s developer channel has fewer development platform choices.  While the rest of the industry has focused on programming languages like C, C++, C#, Java and others for development, Apple has focused on Objective C as its programming language of choice. This stems from Apple’s acquisition of NeXT and the NeXTStep operating system from Steve Jobs, from which later Apple operating systems including IOS are eventually derived. The different development platform, and focus on customer experience makes Apple developers stand apart from the rest of the computing industry. It is essential to use Apple supplied development tools, APIs and selected programming environments and languages to develop for Apple products.  The focus on a single development platform makes it easier for Apple to develop for this market.  There are a few development platforms that support other languages in the IOS space, but these are principally targeted at companies developing Apps for multiple mobile platforms (e.g., Android, Windows Mobile and IOS) at the same time.

Competing Clouds

Fitness and Health Device vendors like FitBit and iHealth presently have their own consumer facing cloud storage offerings that work with their devices.  Several devices also have the capability to share data with Microsoft HealthVault.  Apple’s initial offering in Health Kit supporting local storage of health data appears non-threatening to these vendors because it does not propose to limit their ability to drive customers to their independent cloud solutions.  However, the tempting capabilities offered by Health Kit today could be driving more of cloud business to Apple tomorrow.  The only choice for some device developers may be to partner with Apple and use iCloud as their data provider to provide the same user experience for users of some of these devices.

Some device makers, like FitBit, are not wholly bound to Apple for their user experience.  The iPhone or iPad App simply provides transportation from the Bluetooth connected health or fitness device to the Internet and enables display of recent history.  Risks for these device makers in using Health Kit seem marginal.  However, Apple’s insistence that App developers follow Apple’s rules and use Apple’s APIs to support capabilities could hinder future health data exchange outside of iCloud.  For example, Apple’s Push Notifications API is the only way that Apps can receive push notifications, even though numerous other push technologies could be implemented in software under IOS.  Apps which are found to implement these other methods are not permitted in the App Store and can be removed from it should Apple discover later that they exist.  Similar restrictions on API use in the future could prevent device makers from utilizing something other than Apple’s APIs to push health data out to the web. This seems an unlikely strategy for Apple. Clearly the partnership with Epic and its MyChart product promises that data will flow from the Apple device to the physician chart, and perhaps even back again.

Industry experts have pointed out the complexity of multiple device access and security(11). Synchronization of health data across multiple devices is also challenging.  It is not surprising that Apple chose not to support that capability in its first release.  Apple’s documentation over the Health Kit API and developer guidelines shows a strong integration of security into not just the HealthKit framework, but also the Health Kit user experience.  With all of the attention being paid to security of Health data, Apple may well be waiting until it gets the fingerprint scanner (now integrated in new iPhone models) into the new models of the iPad and iPad mini before supporting Health Kit on those products.


Health Kit promises to solve real problems for consumers and their healthcare providers by enabling them to selectively share health data via various Health and Fitness Apps.  By focusing on the App developer channel, Apple can approach this problem in ways that neither HealthVault nor Google Health were able.  The Health Kit API seems to have been developed to support straightforward migration for existing Apps manipulating health data.  Apples engagement with key industry leaders, such as Mayo Clinic, Nike, and Epic in the recent announcement of HealthKit should also encourage other App and Health and Fitness device vendors to line up behind it.

Avoiding complex challenges like multiple device synchronization and cloud storage also makes the capability easier to understand.  It also becomes simpler for App developers and consumers who may have some concerns about security of their data in the cloud.  There are many obvious ways that Apple could advance Health Kit in the future; however, Apple appears to be proceeding with caution to see how well Health Kit takes hold.  The company has a long history of secretive strategy development which it unfolds over time.
I look forward to using my first Health Kit enabled apps on my personal device, where presently I keep track of various health data in different apps, none of which can share data with each other today.  I also look forward to a time when I can share some of that data with my physician, a capability already promised with some EHR systems in the recent announcement.  To summarize: I want it, it looks easy, it feels better than other solutions, and appears to have a strong future.  In short, Health Kit appears like another example of Apple following a time honored recipe for success.

1. Apple Inc (AAPL.O) Company Profile: Reuters; 2014 [cited 2014 July 30. Available from: http://www.reuters.com/finance/stocks/companyProfile?rpc=66&symbol=AAPL.O.
2. Bajarin T. 6 Reasons Why Apple Is Successful: Time; 2012 [updated May 07, 2012; cited 2014 July 30]. Available from: http://techland.time.com/2012/05/07/six-reasons-why-apple-is-successful/.
3. Nair S. Apple’s premium pricing strategy and product differentiation: Yahoo! Finance; 2014 [cited 2014 July 30]. Available from: http://finance.yahoo.com/news/apple-premium-pricing-strategy-product-191247308.html.
4. App Store Metrics: Pocket Gamer.biz; 2014 [cited 2014 July 30]. Available from: http://www.pocketgamer.biz/metrics/app-store/categories/.
5. Kirk P. Physician Use of Tablet PCs for Medical Purposes and to Access Clinical Pathology Laboratory Tests Results Predicted to Include Majority of U.S Doctors by End of 2013: Dark Daily; 2013 [updated October 2, 2013; cited 2014 July 30]. Available from: http://www.darkdaily.com/physician-use-of-tablet-pcs-for-medical-purposes-and-to-access-clinical-pathology-laboratory-tests-results-predicted-to-include-75-of-u-s-doctors-by-end-of-2013#axzz38xpI1d8F.
6. Apple Inc. Apple - iOS 8 - Health: Apple; 2014 [cited 2014 July 30]. Available from: https://www.apple.com/ios/ios8/health/.
7. Moukheiber Z. Behind Epic Systems' Alliance With Apple: Forbes; 2014 [updated June 4, 2014; cited 2014 June 30]. Available from: http://www.forbes.com/sites/zinamoukheiber/2014/06/04/behind-epic-systems-alliance-with-apple/.
8. Apple Inc. Introducing HealthKit. WWDC 2014 Session Videos - Apple Developer: Apple; 2014.
9. Apple Inc. App Store Review Guidelines - App Store Resource Center: Apple; 2014 [cited 2014 July 30]. Available from: https://developer.apple.com/appstore/resources/approval/guidelines.html.
10. Isaacson W. Steve Jobs: Simon & Schuster; 2011.
11. Shaughnessy H. The Revolution Hidden In The Apple Health Kit: Forbes; 2014 [cited 2014 July 30]. Available from: http://www.forbes.com/sites/haydnshaughnessy/2014/06/17/the-revolution-hidden-in-the-apple-health-kit/.

Wednesday, August 13, 2014


I think it was a Steve Perry book (The Man Who Never Missed) where I read about some future group develops a science called integratics. For me, it is not about predicting tornadoes from butterflies, but rather how I integrate my informatics classes into my day job, so it becomes a mashup of those two words (Portmanteau is the word for that)

Twice this term I have to write an individual paper which supports a team paper, and so I let my day job influence the topics about which I write.  Both papers will be shared outside of my classroom experience. The first paper, and accompanying presentation was to be on a Healthcare IT Vendor and Product.  I chose Apple and HealthKit for two reasons.  First, because I wanted to learn more about HealthKit than I was able to cover in my initial post.  Secondly because I could get information from Apple that I would not, due to my employment, be able to get from another vendor easily.  That was for my Business of Healthcare class, and you will see it here later this week.

The second paper is for my Organizational Behavior class, where small teams must do a case study on an organization.  I applied some of my HL7 influence last week to request board approval for our team's case study on that organization, which would get the team some inside information to make it easier to do the study.  There's plenty of information publicly available on HL7 already, so even if we were refused (I abstained from voting), we could still do it.  That one will also go to the HL7 Board when we are done with it.

Both papers will help me both in my classes, and professionally.  And by combining my day job with my night classes, I might be able to get more sleep.


Thursday, August 7, 2014

Localizing Time in HL7 CDA Rendering with XSLT

One of the questions that has come my way from several different sources is how to display times that appears in a CDA document in a way that is locally relevant.  Since the document narrative does very nothing with time that is under the viewer's control, there are really only two places where date time values might appear in CDA:

  1. The Document Header
  2. CDA Entries
While CDA entries do include date and time, rendering them as part of the display of document sections is rarely done.  The same techniques I mention for the header could also be applied to entries in the document sections though, if you happen to need something like that.

Date and Time values in the Header

There are numerous places within the document header where date and time could appear.  Perhaps the most visible one is the /ClinicalDocument/effectiveTime element, which indicates when the document was created.  Others include:
  • author/time (the date and time the author wrote the document)
  • legalAuthenticator/time (the date and time the document was legally signed)
  • documentationOf/serviceEvent/effectiveTime (the date and time associated with the documented service)
  • componentOf/encompassingEncounter/effectiveTime (the date and time associated with the encounter)

Time Zone or Locally Relevant Time?

Time zone is a function of politics, not math.  When the author writes a document at 201408041452-0700, what is the time zone?  Well, it depends upon where they are.  They could be in California, in which case the time zone is PDT.  But they could also be in Flagstaff, Arizona (where I will be next week for the HL7 Board Retreat), or in Zona Noroeste in the state of Baja California, in Mexico.  Time zone then, is a function of where you are, not when you are, and even if you have the when, it doesn't narrow the where down sufficiently.  A few years back, the US changed when it entered daylight savings time, so when you are, is also not just a function of time of day, but also of day, month and year.  Give up yet?  Good.  Don't try to show the time zone in these cases.  Just use the time offset.

Locally Relevant Time Zones

But people don't know what time 1200-0700 is, you say?  OK, so what you need is to convert that to a locally relevant time in your stylesheet.  So, how would you do that?  I'm not going to go into a lot of detail here, but I will make some design recommendations:
  • If possible, use XSLT 2.0 and the fn:adjust-dateTime-to-timeZone() function. In your transform.  Get the locale from the user agent.
  • If XSLT 2.0 is not available to you, try using EXSL date-time extensions with your XSLT processer.
  • To determine the local time zone offset from UTC (which is not the same as the time zone, but will serve for this purpose), try using the getTimezoneOffset() function on a JavaScript Date object.

XSLT 2.0

Let's look at how you might do this with XSLT 2.0 first.  You need to get the time zone from the browser. I'll assume you have a form somewhere, and that you submit that form at some point to the server.  Here is how you might pass the time zone as offset in minutes from UTC (note that getTimezoneOffset() returns offset of UTC from the current time zone, and we want the inverse, the offset of the time zone from UTC, so we just negate it).

<input type='hidden' id='TZ' name='TZ' value=''/>
<script type='text/javascript'>
  Date d = new Date();
  document.getElementById('tz').value = -d.getTimezoneOffset();
On the server size, you'd simply pass TZ as a parameter to your transform (you ARE executing this CDA transform server side, aren't you?  There are some very good reasons why you should do it that way).

In your stylesheet, you might do something like this to turn the offset in minutes into a time zone:
<xsl:variable name='tzString'>
   <xsl:if test='fn:number($TZ) &lt; 0'>-</xsl:if>
   <xsl:text>PT</xsl:text><xsl:value-of select='fn:abs(fn:number($TZ))'/>
<xsl:variable name='tzDuration' select='xs:dayTimeDuration($tzString)'/>

Then, when generating a time, you'd do something like this:
<xsl:variable name='timeValue'>
  <xsl:call-template name='reformatTimeFromHL7toXML'>
    <xsl:with-param name='time' select='...'/>
<xsl:value-of select='format-time(xs:adjust-dateTime-to-timeZone($timeValue,$tzDuration),$myTimeFormat)'/>

Without XSLT 2.0

If you don't have an XSLT 2.0 parser, it gets a bit tricky.  There are a couple of different ways to handle date/time formatting, but you really don't want to write any of that code yourself in XSLT.  My favored way of handling it is by calling out to Java code to handle this sort of mess.  You can use standard date/time functions in Java in this case.  The java.text.SimpleDateFormat and java.util.GregorianCalendar classes provide just about everything you need to parse date/time values, and format them.

Below are a pair of templates using Java that are based on some work I used to convert CDA documents to XDS submission sets.  With a little bit of tweaking, you could use this to format date time values however you wanted.
    Take a V3 date/time stamp with or without milliseconds, and with or 
    without timezone specification and convert it to a date/time stamp in 
    the specified zone precise to seconds, or less
  <xsl:template name="toZone">
    <xsl:param name="time"/>
    <xsl:param name="precision" select="14"/>
    <xsl:param name="length"
        translate($time, '-', '+'),'+'), '+'))"/>
    <xsl:param name="zone"/>
    <xsl:variable name="fmtString">
      <xsl:value-of select="substring('yyyyMMddHHmmss',1,$length)"/>
      <xsl:if test="contains($time, '+') or contains($time, '-')">Z</xsl:if>
    <xsl:variable name="inputFormatter" 
    <xsl:variable name="parsedDate" select="java:parse($inputFormatter, $time)"/>
    <xsl:call-template name="dateInZone">
      <xsl:with-param name="time" select="$parsedDate"/>
      <xsl:with-param name="precision" select="$precision"/>
      <xsl:with-param name="zone" select="$zone"/>

    Take a Java Date and convert it to a date/time stamp in zone, precise
    to seconds, or less
  <xsl:template name="dateInZone">
    <xsl:param name="time"/>
    <xsl:param name="precision" select="14"/>
    <xsl:variable name="outputFormatter"
    <xsl:variable name="MyZone"
    <xsl:variable name="void" 
      select="java:setTimeZone($outputFormatter, $MyZone)"/>
      select="substring(java:format($outputFormatter, $time), 1, $precision)"/>

Of course, this assumes your platform is Java.  What about all those .Net folk who are stuck with C#? The same principles apply, as C# has similar capabilities, I just don't know what they are ;-)

There is also a platform independent way to handle this, relying on EXSLT date and time extensions.  But, as mentioned there, no XSLT processors support that natively.  So you might just as well use a platform dependent implementation.

Wednesday, August 6, 2014

More on Designing IHE XDW Workflows

So, more on building XDW workflows: As I began working through how to get data out of the spreadsheet I discovered several things.


I need to count three different things:

  1. Steps in the workflow, 
  2. alternatives within a step, 
  3. and actions within an alternative. 

Once I have that numbering, building a BPMN diagram describing the workflow from the spreadsheet is basically automatic. This gives me a very good structure to use to generate the description of tasks, and the specific requirements of actors.

The steps are the point, not the triggers

In several cases I had different triggers doing the same pieces of work in the same workflow I was developing. So, I combined the triggers and merged the steps. For example, one actor in a referral would basically be doing the same work on evaluating a new referral as they would evaluating a referral that had additional data provided because it was requested. So, when the Request Information task completes, or a Respond to Referral request goes to IN_PROGRESS, those two triggers can start the same step (as far as the workflow is concerned).

Actions that Transition Tasks Generate new Triggers which should be Assigned to Steps

The nice thing about the spreadsheet is that whenever I transition a task to a status in the action row, I know there needs to be a trigger added so that some other task can act on that transition.  I discovered I had missed a bunch in the workflow I created, so I'm having to clean all of that up.

Proper use of Status

On the workflow statuses, I did a bit of digging into XDW and Human Task, and established some principles that I document only the required transitions and stay silent on the rest. That requires that I rework a number of transitions because having a common description for what these states means is very useful for dash-boarding (a key component of existing referral solutions they have):

CREATEDTask is Unassigned (has no owner) and is not ready to be acted upon.
READYTask is Assigned (has an owner) and is ready to be acted upon (but may not yet have been acted on by the task owner)
IN_PROGRESSTask is Assigned, is ready to be acted upon, and some work has been done by the task owner
COMPLETEDTask is done, usually by the task owner.
FAILURETask could not be completed, usually by the task owner, but perhaps by others.

So, Actor 1 executing Task A could certainly create Task B owned by Actor 2, but SHOULD NOT indicate that it is IN_PROGRESS, only that it is READY. It would be up to Task B to indicate that it is IN_PROGRESS. That requires a number of different changes in the spreadsheet and I have to go somewhat carefully.  However, in my original spreadsheet, I didn't start with those definitions. So now I have to go back through and change a bunch of things in the spreadsheet, and am about halfway through it.

Notification can be Automated

One thing that I discovered through all of this is that notifications should pretty much be automatic, with very view workflow dependent exceptions.

  1. Any "Workflow Manager" or "Workflow Monitor" participant dealing with the workflow should always be notified. 
  2. The task owner should always be notified whenever a task assigned to it has had its status changed by any workflow participant other than itself. 
  3. The task creator should always be notified whenever a task created by it has had its status changed by any workflow participant other than itself.

That leaves me only a few special cases to handle for notification in my complex workflow.  All other cases are handed by the above three rules.

Finishing the Workflow

I still have to figure out how to document that a workflow is completed.  There are at least three ways I can do that.  For now, I'm just going to use the notes for that.

Here are the column heads for my spreadsheet.

Step #
Step Name
Trigger Events
Responsible Actor
Action #
Workflow Task
Task Status
Task Owner
Input Documents
Output Documents

Tuesday, August 5, 2014

In the style of the Onion

This is the press release that should have crossed my desk today.  Three points and bragging rights if you even get what I'm talking about...

TWITTER, The Internet. Citing a recent report using data that is entirely suspect and out of date, the ____ office claimed today that the ___ in HHS is not doing enough to make its job easier.  "They've got this money they are spending, and they aren't focusing on our issues." claims department head ___ ",so we issued this report, because, well, it looks pretty good that we did this work, even if it was a while ago, and it splashes a lot of mud on somebody else."

"After all, who cares if the program we analyzed isn't even going on any more, or that it was hastily erected to be replaced by something more permanent.  Surely if they skimped here, they messed up elsewhere. Right? And while we're at it, it looks pretty good if we drag ____ agency into the fray.  There the guys who are supposed to know all the standards on this stuff, whereas we can barely spell the acronyms for some of these SOD things."

Monday, August 4, 2014

It's Simply a Matter of ...

Be wary whenever someone starts with that line, and avoid doing it yourself if you can.  It is rarely every simply one thing.  Even a simple fix can require three times as much effort as you thought or even expected.  A former colleague of mine is a brilliant Ph.D Linguist and computer scientist.  He and I together have developed some really cool natural language processing software in the past.  He would often finish a dissertation on the latest algorithm he had developed with the phrase "The rest is a simple matter of programming."

And of course, for him, programming was simple, because that wasn't what he did, that was what I did.  Of course he developed algorithms and wrote code, but not the way we'd eventually have to deliver it to the customer.  Those issues were not his problem, and it truly was a good division of labor.  Which brings us back to my main point.  Whenever someone (or even I) am about to say, "It is simply a matter of ...", we are likely doing one of two things:

  1. Oversimplifying the effort involved because we don't understand the effort where it is performed, OR
  2. Forgetting about other important details of what we eventually must deliver to the customer.
It is rarely ever as simple as what we thought, even when we discover something new.  When it is always that way in interoperability, my work will be done.

Thursday, July 31, 2014

Building IHE XDW Workflows

I've been working on a few XDW workflows lately, mostly dealing with variations on eReferral and Transfer. In developing these, it became pretty important to understand how the workflow itself works.  We've documented it in general using BPMN.  Ideally, what I would like to do is be able to represent the workflow description entirely in BPMN with a few annotations describing some key pieces of metadata about the workflow.  I haven't quite gotten there yet, but am pretty close.

What I have figured out is that the key to defining the workflow is a single spreadsheet table with the following columns:
  • Trigger Event
  • Responsible Actor
  • Conditions
  • Action
  • Workflow Task
  • Task Status
  • Task Owner
  • Input Documents
  • Output Documents
  • Notify
  • Notes
The trigger event takes the form of "Workflow Task - Task Status", as in Request - COMPLETED, or a narrative description of an event, such as "Referral Response timed out" (e.g., indicating a maximum duration for a response was exceeded).  This tells you what initiates the activity.  The next two columns tell you who and when.  The responsible actor column is the workflow participant that has to do something, and the conditions tell you if there are additional preconditions that must be met.  For example, if the maximum time for a response timed out, AND there are no other acceptable responses, then the responsible actor must do something with another task.

And the next two columns start a "sub table", listing the things that the responsible actor must do.  It may for example, transition one task to another state, AND create two new tasks.  Each one of these gets a row. The action is usually create or transition, or create/transition, and the workflow task is one to be acted upon. Create is used to create a task that hasn't already existed.  Transition is used to transition a task that already exists to a new state.  Create/Transition is used when you don't know what the current status is for the task (it may not have been created yet, but it could exist).  Task Status indicates what the final state is for the task that was acted upon.  The task owner indicates who the task owner is.  Tasks can be created by the task owner, but may also be created by other workflow participants.  For example, in the workflow I'm looking at, one participant creates a Respond to Request task for each possible edge system that could respond, encouraging them to complete some activity.  During these actions, input or output documents can be added to the workflow.  Usually input documents are added during CREATE and IN_PROCESS states, and Output documents are added during IN_PROCESS, COMPLETE or FAILURE transitions.  It isn't usually the case that an input is added at the end of the task.  In some cases (although I haven't had to do this yet), the only action an actor may have is to add an input or output document to another task, and do nothing else.

An important step is that a notification should be given to the task owner and any expected actor who will be triggered by the state transition on the task.  Thus, is the Referral Requester workflow participant has a trigger on Response COMPLETED, then when the Referral Responder workflow participant the Response task to COMPLETED, it should notify the Referral Requester.  For this, I'm assuming that the DSUB transaction is used for notifications, and that the workflow participants are duly notified by some other actor (perhaps the Workflow Manager) of these cases.  There's no real subscription to set up, its just assumed that the notification transaction will occur under the appropriate cases.  When you use a Workflow Manager actor (as I did in my definition), one thing that you could do is make sure that 
  1. It is listed as the intended recipient of the workflow document (meaning that it will be managing the workflow),
  2. Some system, such as the registry or repository, interprets the intendedRecipient metadata in the provide and register transaction as a signal that a DSUB style notification should be given to the actor identified (in some way) in the Intended Recipient metadata. 
  3. That workflow manager notifies any task owner of transitions that have occured on a task that were NOT performed by the task owner itself.  For example, task creations, FAILURE or COMPLETION transitions that may be caused by other external events, et cetera.
  4. That workflow manager also notifies any actor responsible for activity on a trigger event that it can detect, e.g., a transition of a task.
In defining workflow in this manner, the table defines what MUST be done in the XDW workflow document, BUT, it does not prohibit additional transactions.  For example, in the Referral Request task, we only note that when a referral is needed (a narrative trigger event), the Referral Requester must create a Referral Request with final status being COMPLETED, and an input document of a Referral Request Document.  I don't say anything at all about the existence of intermediate states, such as CREATED, or IN_PROCESS.  It is quite possible that these states are recorded and the various transitions shown in the XDW document over time.  However, my definition doesn't depend on their existence, and doesn't prohibit it.  This enables other useful behaviors to be added later.  These states are essentially implicit in the workflow, and simply aren't documented with any requirements.

An important point in building these tables is that you have to consider that the state of the workflow should be transparent to an outside reviewer that does NOT have any understanding of the internal business rules associated with the workflow.  So, while you might assume that since a request has been completed, it is expected that the Referral Responder actors might be tasked with generating a respond, you wouldn't be able to tell if a task didn't exist for those actors.  Thus, some tasks that don't exactly need to be recorded in the workflow document to manage the state among the workflow participants still need to be made explicit so that others (such as dashboarding applications), can still provide a good indication to an outside viewer what the status of the workflow is.

I've transposed an short example of the table below (because I usually make it horizontal rather than vertically oriented).  I'll explain the key points after the table.  This is an example meant to illustrate different features of the table, it's not the actual workflow that I wound up defining.

Metadata\Trigger EventReferral neededReferral Request IN_PROGRESSReferral Response READYReferral Response COMPLETED -or- FAILURE
Responsible ActorReferral RequesterWorkflow ManagerReferral ResponderWorkflow Manager
Referral can be acceptedReferral cannot be acceptedAcceptable Response availableNo acceptable response available and more responses expectedNo acceptable responses available and no more responses expected
Workflow TaskReferral RequestDispatch ReferralReferral ResponseReferral ResponseReferral Request
Referral Request
Task OwnerReferral RequesterWorkflow ManagerReferral ResponderReferral ResponderReferral Requester
Input DocumentsRequest for Referral
Request for ReferralRequest for ReferralRequest for ReferralRequest for ReferralRequest for Referral
Output Documents
Referral Response (Required)
Referral Response (Optional)Referral Response (Required)N/AReferral Responses (Optional)
NotifyWorkflow ManagerReferral RequesterReferral ResponderWorkflow ManagerReferral Requester
Referral Requester

This task is created for each possible referral responder.
Normal CompletionWait, hopefully someone will respond positivelyNobody responded positively, include all negative responses as output to allow manual review/escalation.

The idea of this workflow is to handle a managed referral request process, where there is a single requestor, and multiple possible referral responders.  There's a workflow manager participant that handles the business processing of the responses to choose among acceptable responses.  When an acceptable response is received, the referral request task is considered to be completed.  There are a lot of different ways to extend this workflow by adding new columns to it.  For example, you could be nice, and transition each outstanding referral response task to the FAILURE state once a referral response has been accepted, so that the Referral Responders can now ignore these tasks if it hasn't gotten to them.  You could also add a time out event to allow the Workflow Manager to renotify Responders of tasks that they haven't paid attention to, or escalate the request, et cetera.

Getting to Other Views

Having developed this table, there are now a couple of different things that you can do with it.  Often you need to explain multiple viewpoints of the workflow definition to satisfy to all and sundry stakeholders what is happening.  The table allows me to generate three different views:


You can start to diagram the workflow in BPMN.  The general rules I've been following is that each workflow task becomes a task or activity in the BPMN diagram, and that each workflow participant (aka actor or task owner) gets a swim lane or pool. Conditions are used as conditional entry points into a task. Input and output documents are often included as components of the messages passed between tasks in different lanes/pools.

In an ideal world, I'd have the time to do some automation with a modeling tool so that I could graphically create the content in BPMN and subsequently generate the table, or import the table from a spreadsheet, and dynamically generate the diagram.  For now, I can live with managing the diagram separately from the table and going back and forth between the two.  It's just simply a matter of time and priorities.

Actor Requirements

When you sort this table by responsible actors and task sequence (effectively time), you get a description of the responsible actors view of the task to be performed, and what their required behaviors are.

Task oriented View

When you sort it through by workflow task and task sequence, you get a view of the steps of the workflow.

Generalizing and Specializing

The beauty of this table format is that it also allowed me to build more complex workflows by specializing from simpler ones, again by adding columns (rows really in my spreadsheet).  In my case though, what we wound up doing was defining the most complicated workflow, and then removing columns (generalizing) to get to simpler ones.  It doesn't really matter the direction that you do it in, what matters is that you can simplify or generalize these behaviors.

Notification (ala DSUB) is an important component of this workflow description, and the mechanism I've used is pretty straightforward.  I'm not sure if that's something to submit as a modification to the XDW profile (e.g., the Notification option), or in a specific workflow profile, but I think it is probably worthwhile to consider.