Rendering Attachments in CDA

Jun 29, 2012

Yesterday’s post about pathology attachments in NEHTA Clinical Documents generated two follow-up questions which are pretty general to CDA: * What’s the difference between linkHtml and renerMultiMedia?

  • How do you render these things?

Taking the first question first, CDA defines linkHtml and renderMultimedia, and then says the following two things about them:

is a generic referencing mechanism, similar, but not identical, to the HTML anchor tag. It can be used to reference identifiers that are either internal or external to the document. Multimedia that is integral to a document, and part of the attestable content of the document requires the use of the ObservationMedia CDA entry, which is referenced by the element (see (§ 4.3.5.6 )). Multimedia that is simply referenced by the document and not an integral part of the document can use (Section 4.3.5.2)

and

Multimedia that is simply referenced by the document and not an integral part of the document must use . The expected behavior is that the referenced multimedia should be rendered or referenced at the point of reference. (Section 4.3.5.6)

It sounds as though the two are technically equivalent, and the only difference is whether they are attestable or not - but they’re rather different in form, the way that html’s and differ - not a small difference. So the intent of this is that you can only make something attested content if it’s visible inline - if it’s not, then it shouldn’t be visible - this maintains a clear separation between what is and isn’t attestable content for the author.

An implication of this is that content that isn’t rendered inline - such as attached laboratory reports in PDF - can’t be part of the attested content.

So given a CDA package - and you have to have some kind of package - either an explicit package per the way we do it in the NEHTA specifications, or an implicit package through naming and attachment rules, perhaps using an XDS repository that contains a mix of documents and attachments. Given a package like this, an xml document with a set of named attachments that aren’t directly referenceable by a URL, how do you handle this?

How you render links, for either linkHtml or renderMultiMedia, depends on your application. There’s three general possibilities:

  1. You’re writing a web application, and you transform the CDA document to part of a web page (usually server side, but could potentially be done client side with javascript)
  2. You’re write a GUI application, and you transform the CDA document into a a web page, and present that in a hosted web browser library
  3. You load the CDA document into some other formatting control

I don’t know anyone other than me doing #3, and if you are doing #3, you know enough about this stuff not to bother reading a post on it. So I won’t consider #3 anymore.

Web Application

In a web application, you’re going to serve up the CDA document, transformed to html, and the transform has to convert the local references to server side references that the server knows how to convert to references back to the package. Generally, this goes something like this: The webserver is at http://acme.local/apps/docviewer and has the relative page /[id].htm (where id identifies the document) that addresses the document - i.e. this loads a page that contains the transformed CDA document inside it. In this case, you need the CDA -> XHTML transform to work the urls over so that:

  • internal urls to other narrative pieces stay as internal references
  • other internal urls become something like http://acme.local/apps/docviewer/images?id=[id]&ref=[ref] where [ref] is the internal reference
  • relative urls become something like http://acme.local/apps/docveiwer/attachments?id=[id]&name=[name] where name is the relative reference
  • absolute urls are not changed - unless they need to be to point to a reverse proxy or local facade/cache (depends on local arrangements whether this is needed)

Of course, the actual url arrangements will vary wildly depending on platform, policy, dev tools, etc. It doesn’t matter; the point is that the internal and relative references are resolved at a different time to the display of the document, and they need the id of the document (load the document, examine the internal link and the context of the document respectively when doing this.

Known variations:

  • In the NEHTA context, the id of the document is also the identifier of the context of the package - but this might not always be the case
  • For small images, you can embed them in the reference using a data: url. This works well - and fast for small images - but the size limit varies for different versions of different browsers (not good for clinical safety)
  • If you were really a masochist, you could ship the whole package to a javascript client, and unpack the package, and keep everything local…. like I said, if you really liked hard work…

GUI Applications using a Web Browser

Fundamentally, this is a variation of a web application - the rendering engine is a web browser, and you get to create a little mini-internet of your own for it to live in inside your application, so the general approach is the same. But there’s some variations.

If you include IE inside your application (on windows/dotnet, this is the easiest, because the dev tools generally have this built in, and because you don’t have to distribute it, though you get to subject to versioning issues), then you get the problem that you can’t prevent it from actually hitting the wire and trying to retrieve the content. I’ve spent hours hacking it and ploughing through stackoverflow etc, and it seems the only way to do this is to write a custom url scheme handler, which is really hard work. So the easiest way to handle it is to set up your own web server right inside your application, and you’re back to the first case for real.

Alternatively, you can include Chrome; this involves a lot more mucking around to set it up (libraries… distribution..), but once you have, it works a whole lot better because you get more control - you can feed it content directly, and control it’s behaviour more, and you distribute the version you tested with your application. In this case, you still get to do fun stuff with URLs like above, but you can make your own up  (much more fun).

I don’t know anything about including browser controls in *nix and OSX/iOS.

Other choices

I don’t think I’ve really answered the question well - it’s a tough one because there’s so much variation in application architecture. One option I haven’t really covered is to drop the whole content to the local temp directory, including all the images and any other attachments. This has obviously performance and security ramifications etc. - and there’s still some reprocessing of the URLs to make them work (i.e internal references to non-narrative content still need to be replaced with relative names in the directory, and you might have to re-sort paths in relative names to make sure that the local filing system is ok with the names).

So the one constant is that you’re most likely going to have to reprocess the URLs for your local system, according to your local requirements. This is one reason why the PCEHR doesn’t allow the author to send stylesheets that the renderer must execute - because how can you hope to transform the transform on the fly for this sort of stuff?