This page last changed on Oct 01, 2009 by christian.ohr.

CDA Header

Building the CDA header also explains the different kinds of elements and attributes and how they a created using the CDA builder.

def document = builder.build {
  clinicalDocument {
  // templateId(root:'2.16.840.1.113883.3.27.1776')        // 1
     id(root:'2.16.840.1.113883.19.4', extension:'c266')   // 2
     code(                                                 // 3
        code:'11488-4', 
        codeSystem:'2.16.840.1.113883.6.1', 
        codeSystemName:'LOINC',
        displayName:'Consultation note'
     )
     effectiveTime('20000407')                             // 4
     title('Good Health Clinic Consultation Note')         // 5
     versionNumber(2)                                      // 6
     ...
  }
}

clinicalDocument is the schema-name, containing a closure to nest other elements. id is the name for the first element - the CDA Builder knows the internal structure of a CDA document and creates an object of the HL7v3 RIM type II. root and extension are the key-name for the corresponding attributes of a II element, and they are assigned the value '2.16.840.1.113883.19.4' and 'c266', respectively.

Let's examine this piece of code line by line

  1. In general, infrastructure attributes (templateId, classCode, moodCode, typeCode) with static defaults are not required to be set. Generic CDA documents always carry the same templateId, so you can omit this element.
  2. This adds an id element with a root and extension attribute. Under the hood, the builder checks that the root attribute is present, otherwise an Exception is thrown. Also note that id is mandatory, so omitting would throw an Exception, too.
  3. Adding a code just works like adding the id. Remember, you never have to care about the class of the corresponding CDA model object.
  4. Looking at the CDA specification, effectiveTime and title appear in inverted order. As we are not building the XML document directly, we don't have to care, as the rendering process restores the correct ordering of elements. effectiveTime requires a date value (HL7 TS datatype), but the builder allows to use its simple string representation (YYYYMMDD).
  5. The title is of HL7 ST datatype. Again, you can just pass a string and conversion is done for you.
  6. The versionNumber is of HL7 INT datatype. Here you can pass an integer value.

The next part of the CDA header definition introduces a couple of other 'shortcuts' available.

...
     confidentialityCode('N')                           // 1
//      code:'N', 
//      codeSystem:'2.16.840.1.113883.5.25')
     recordTarget {                                     // 2
        patientRole {
           id('12345@2.16.840.1.113883.19.5')           // 3
//            extension='12345' 
//            root='2.16.840.1.113883.19.5'
           patient {
              name {
                 given('Henry') 
                 family('Levin')
                 suffix('the 7th')
              }
              administrativeGenderCode('M')             // 4
//               code='M' 
//               codeSystem='2.16.840.1.113883.5.1'

              birthTime('19320924')
           }
           providerOrganization {
              id('2.16.840.1.113883.19.5')              // 5 
           }
        }
    }
...
  1. Codes with more or less fixed code systems have their OID and, if applicable, code system name predefined. In this case, you can specify the code as content and skip the codeSystem and codeSystemName attributes. The rendered CDA XML will nevertheless contain all attributes.
  2. In this block, we traverse the RIM model from the document act over a Participation (recordTarget) and a Role (patientRole) to the Entity (patient).
  3. id elements can be created by specifying a 'extension@root' content rather than the attribute map as shown above. Both notations are equivalent.
  4. This is another example for a predefined code system.
  5. id elements may contain only a root attribute, but no extension. In this case, you can provide the root attribute as content.

For reference purposes, here's the remainder of a rather complete CDA header definition. Note that most of the elements are optional - check the CDA specification or RMIM diagram. If any mandatory elements are skipped, the CDA Builder will complain with an Exception before you get the clinical document as result.

...
           author {
             time('2000040714')
             assignedAuthor {
                id(extension:'KP00017',root:'2.16.840.1.113883.19.5')
                assignedPerson {
                   name {
                      given('Robert')
         	          family('Dolin')
                      suffix('MD')
             	   }
                }
                representedOrganization {
                   id(root:'2.16.840.1.113883.19.5')
                }
             }
          }
             	
          custodian {
             assignedCustodian {
                representedCustodianOrganization {
             	   id('2.16.840.1.113883.19.5')
             	   name('Good Health Clinic')
             	}
             }
          }
          legalAuthenticator {
             time('20000408')
             signatureCode('S')
             assignedEntity {
                id(extension:'KP00017', root:'2.16.840.1.113883.19.5')
             	assignedPerson {
             	   name {
         	          given('Robert')
         	          family('Dolin')
         	          suffix('MD')
             	   }
             	}
             	representedOrganization {
             	   id('2.16.840.1.113883.19.5')
             	 }
              }
           }
           relatedDocument(typeCode:'APND') {                                    // 1
              parentDocument {
                 id(extension:'a123', root:'2.16.840.1.113883.19.4')
             	 setId(extension:'BB35', root:'2.16.840.1.113883.19.7')
             	 versionNumber(1)
              }
           }
           componentOf {
              encompassingEncounter {
                 id(extension:'KPENC1332', root:'2.16.840.1.113883.19.6')
             	 effectiveTime {
             	    low('20000407')
             	 }
             	 encounterParticipant(typeCode:'CON') {
             	    time('20000407')
             	    assignedEntity {
             	       id(extension:'KP00017',root:'2.16.840.1.113883.19.5')
             	       assignedPerson {
             	          name {
             	             given('Robert')
             	             family('Dolin')
             	             suffix('MD')
             	          }
             	       }
                       representedOrganization {
                          id(root:'2.16.840.1.113883.19.5')
                       }
             	    }
             	 }
             	 location {
             	    healthCareFacility {
             	       code(
             	           code:'GIM',
             	           codeSystem:'2.16.840.1.113883.5.10588',
             	           displayName:'General internal medicine clinic'
             	       )
             	    }
             	 }
             }
         }
     }
  }
Document generated by Confluence on Oct 20, 2010 15:54