Link from a CDA narrative to another CDA document in an XDS repository

Previous: Add Pathology Report Attachments to NEHTA Clinical Documents »

Link from a CDA narrative to another CDA document in an XDS repository

Jun 29, 2012

So, a use case has come up in the pcEHR for a CDA document that links to another CDA document in an XDS repository (Consolidated View, actually, for those who want to know). So how to do that? Well, firstly, this use case corresponds relatively directly to the one described here:

For a variety of reasons, it is desirable to refer to the document by its identity, rather than by linking through a URL.

The identity of a document does not change, but the URLs used to access it may vary depending upon location, implementation, or other factors.

Referencing clinical documents by identity does not impose any implementation specific constraints on the mechanism used to resolve these references, allowing the content to be implementation neutral. For example, in the context of an XDS Affinity domain the clinical system used to access documents would be an XDS Registry and one or more XDS Repositories where documents are stored. In other contexts, access might be through a Clincial Data Repository (CDR), or Document Content Management System (DCMS). Each of these may have different mechanisms to resolve a document identifier to the document resource.

The identity of a document is known before the document is published (e.g., in an XDS Repository, Clincial Data Repository, or Document Content Management System), but its URL is often not known. Using the document identity allows references to existing documents to be created before those documents have been published to a URL. This is important to document creators, as it does not impose workflow restrictions on how links are created during the authoring process.

h/t to Keith Boone for that link, btw. So that’s pretty much our use case: to link to a document that’s found in the pcEHR. And you can’t do that by URL, because there’s no URL that directly addresses an XDS getDocument call, and anyway, some background machinery to do with trust is required. So how to do that?

Firstly, in the structured data representation of the CDA, we need to assert that some entry is a reference to another document. For that, we use an external document reference:

This says that this entry is a reference (typeCode=”REFR”) to the external Document. And while we’re at it, we can use the code to indicate what type of document it is, and the templateId to indicate which particular implementation guide it conforms to. And the id of the document - that’s the id by which to request the document from the XDS repository (the pcEHR in this case).

<entry>
 <!-- snip -->
 <reference typeCode='REFR'>
  <externalDocument classCode='DOC' moodCode='EVN'> 
   <templateId extension="1.3" root="1.2.36.1.2001.1001.101.100.1002.120" />  
   <id root="d22de837-9d35-438d-933d-74f08d7657f5"/>
   <code code="60591-5" codeSystem="2.16.840.1.113883.6.1" displayName="Patient Summary" />
  </externalDocument>
 </reference>

So that’s the logical reference to the Shared Health Summary with id “d22de837-9d35-438d-933d-74f08d7657f5”. A clinical system encountering this knows that it needs to retrieve that document from it’s cache or the pcEHR or some other local repository as configured. But what about the narrative?

Linking to an external document from Narrative

The Consolidated view is delivered as a CDA document because.. what other standard way to do is there? Everything else is CDA anyway…. so we might as well use it, which means we need to have a narrative, and it needs to refer to the document. This, it turns out, is not so easy. We need to use to refer to the other document:

 <text>
  <paragraph>
    <linkHtml href="..."/>Other document</linkHtml>
  </paragraph>
 </text>

The problem is what to put in the href attribute. The obvious thing to put in is an id reference (e..g. #a3) to the external document, which refers to the external d:

 <reference typeCode='REFR'>
  <externalDocument ID="a3" classCode='DOC' moodCode='EVN'>

But you can’t have an ID on the externalDocument, and anyway, the rules for an internal reference on linkHtml are:

The target of an internal reference is an identifier of type XML ID, which can exist on other elements in the same or a different narrative block, or XML ID attributes that have been added to the <section>, , or elements

So that’s a dead end. The IHE page I referred to above which describes the problem nicely suggests a way to link the external reference to the linkHtml:

<text><paragraph><linkHtml ID="a3" href="..."/></paragraph></text>
<!-- snip -->
<entry>
 <!-- snip -->
 <reference typeCode='REFR'>
  <externalDocument classCode='DOC' moodCode='EVN'> 
   <templateId extension="1.3" root="1.2.36.1.2001.1001.101.100.1002.120" />  
   <id root="d22de837-9d35-438d-933d-74f08d7657f5"/>
   <code code="60591-5" codeSystem="2.16.840.1.113883.6.1" displayName="Patient Summary" />
   <text><reference value="#a3"></reference>
  </externalDocument>
 </reference>

Only, I don’t think that’s right. The contents of the external document are not the contents of the linkHtml element (which is what that precisely means), and it’s not even really right to say that the contents of the document are the target of the linkHtml, and anyway, we still haven’t resolved what that actually is - pointing something else to the linkHtml element doesn’t resolve what it points to in the href attribute. So while I think that IHE described the problem very nicely, I don’t think they’ve solved it.

This brings us back to the URL portion of linkHtml. It just happens to defined as an xs:string, with the rule: “It can be used to reference identifiers that are either internal or external to the document”. I guess this means that the right way to fill it for external references is with a logical identifier uri. And 3 come to mind:

<linkHtml href="oid:0.1.2.3.4.5.6.7.8.9..."/>
<linkHtml href="uuid:d22de837-9d35-438d-933d-74f08d7657f5"/>
<linkHtml href="hl7-att:root[:extension]"/>

The first two (and their logical variants urn:uuid:… and urn:oid:… - which of these to use is complicated but largely, in the end, irrelevant, because everyone’s going to have to cut code to support whatever goes in here anyway) are obvious places to look, since they are defined externally, but they both suffer the problem that what if the document identifier includes an extension? (and it’s allowed to). For this reason, the V3 data types R2 defined the protocol hl7-att as:

the form hl7-att:[II.literal], such as hl7-att:2.1.16.3.9.12345.2.39.3:ABC123. The scheme hl7-att is used to make references to HL7 Attachments. HL7 attachments may be located in the instance itself as an attachment on the Message class, or in some wrapping entity such as a MIME package, or stored elsewhere. ..[snip].. Attachments SHALL be globally uniquely identified. Attachment id is mandatory, and an ID SHALL never be re-used. Once assigned, an attachment id SHALL be accosiated with exactly one byte-stream as defined for ED.data.

The language there is that of the v3 data types, but the concepts are applicable in this case, and the ground rules are all applicable. Hence, this is the right way to do a reference from one CDA document to another by a logical identifier. To recap, in the structured data:

<entry>
 <!-- snip -->
 <reference typeCode='REFR'>
  <externalDocument classCode='DOC' moodCode='EVN'> 
   <templateId extension="1.3" root="1.2.36.1.2001.1001.101.100.1002.120" />  
   <id root="d22de837-9d35-438d-933d-74f08d7657f5"/>
   <code code="60591-5" codeSystem="2.16.840.1.113883.6.1" displayName="Patient Summary" />
  </externalDocument>
 </reference>

and in the narrative:

<text><paragraph><linkHtml href="hl7-att:d22de837-9d35-438d-933d-74f08d7657f5"/></paragraph></text>

Thanks to Keith Boone for assistance with this post.

p.s. Is it valid to use a URL scheme defined in data types R2 in CDA R2, which use data types R1? Yes, it is, because it’s valid to use scheme’s defined anywhere else as well.