CDA API

Introduction

Our collection of CDA modules provides a wide variety of functions and lookup tables that you can use to build and customize your CDA document. We’ve also included extensive auto-completion support to help you develop your code correctly.

The following table is a quick snap-shot of the modules and functions that you can use in your CDA scripts. For more information about a module, simply click its name in the first column:

CDA Module Function Definition
cda cda.new Create an empty CDA document
cda.code cda.code.add Identify a specific concept by its associated code and code system
cda.code.set Update an existing code element
cda.code.originalText.add Add a text element to an existing code element
cda.codeset cda.codeset.xxx Look up a code based on its corresponding description
cda.codeset.xxx.reverse Look up a description based on its corresponding code
cda.code.simple cda.code.simple.add Add a code that implies its own code system
cda.code.simple.set Update an exisiting simple code element
cda.demographic.name cda.demographic.name.add Add a full name to your document (first, last, prefix, etc.)
cda.demographic.name.simple.add Add a name consisting of a simple string
cda.demographic.address cda.demographic.address.add Add an address to your document
cda.demographic.phone cda.demographic.phone.add Add a phone number to your document
cda.dose cda.dose.add Add medical dosage information to your document
cda.help cda.help.set Set the help for a module function
cda.help.check Check the help parameters for a module function
cda.id cda.id.add Identify a RIM class
cda.id.template.add Identify a CDA template
cda.null cda.null.set Provide a specific reason for the absence of required data
cda.time cda.time.add Add a time value to your document
cda.time.set Update a time value in your document
cda.timerange.add

Add a time range to your document

cda.timeperiod.add Add a time period to your document
cda.value cda.value.add Add a measured value to your document
cda.valuerange.add Add a range value to your document
cda.valuestring.add Add a string value to your document
cda.xml node.setText Set an XML TEXT element
node.setAttr Set an XML attribute
node.addElement Append an empty XML element
xml.findElement Find an XML element

As you can see in the table above, several functions come in two flavours: “add” and “set”. The difference is fairly straightforward:

  • .add functions create a new XML element under the root element identified by the function’s ‘target’ argument
  • .set functions simply update an existing element that you’ve identified with the function’s ‘target’ argument

cda [top]

This module provides the basic template for new CDA documents. It includes a customizable schema that produces a near-complete CDA header.

This function creates an empty CDA document:

  • new : Create an empty CDA document

new() [top]

Usage: cda.new()

Creates a new, empty CDA document.

Returns:

  • An empty cda document with a near-complete header

Parameters:

This function requires no parameters.

Example:
local Doc = cda.new()

Example Result:

<ClinicalDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:hl7-org:v3"
        xmlns:cda="urn:hl7-org:v3" xmlns:sdtc="urn:hl7-org:sdtc">
	<realmCode code="US"/>
	<typeId root="2.16.840.1.113883.1.3" extension="POCD_HD000040"/>
	<templateId root="2.16.840.1.113883.10.20.22.1.1"/>
	<templateId root="2.16.840.1.113883.10.20.22.1.2"/>
	<id extension="" root=""/>
	<code/>
	<title></title>
	<effectiveTime/>
	<confidentialityCode/>
	<languageCode code=""/>
	<setId extension="" root=""/>
	<versionNumber value=""/>
</ClinicalDocument>

cda.code [top]

CDA documents rely on codes that the health system uses to express medical concepts. These codes can represent actions, roles, gender, etc.

These functions add/update the codes used in your CDA document:

  • code.add : Add a new code element to your CDA document
  • code.set : Update an existing code element in your CDA document
  • code.originalText.add : Add a new text element to an existing code element

add() [top]

Usage: cda.code.add{target=<{PARENT}>, element=<ELEMENT>, system=<CODESYSTEM>, value=<DISPLAYNAME>, lookup=<{LOOKUPTABLE}>, datatype=<CODETYPE>}

Add a code and its associated code system to identify a specific concept (such as a medication or a family of disorders). Includes a lookup feature that searches tables to set the values of the other arguments. These tables are defined in the cda.codeset module.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target:The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating

Optional parameters:

  • system: The OID of the code system. These can be found in the cda.codeset.cat table (defined in the cda.codeset module).
  • value: The coded value usually obtained from the relevant codeset table
  • lookup: A table to give the display string of the coded value
  • datatype: The type of the data stored in the resulting XML element, typically CD

Example:
cda.code.add{target=P, element='administrativeGenderCode', system=cda.codeset.cat["HL7 AdministrativeGender"], value=cda.code.sex.Female, lookup=cda.code.sexTable}

Example Result:

<administrativeGenderCode code="F" codeSystem="2.16.840.1.113883.5.1" codeSystemName="HL7 AdministrativeGender" displayName="Female"></administrativeGenderCode>

set() [top]

Usage: cda.code.set{target=<{ELEMENT}>, system=<CODESYSTEM>, value=<DISPLAYNAME>, lookup=<{LOOKUPTABLE}>}

Updates an existing code XML element with new values.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The XML element that you wish to update

Optional parameters:

  • system: The OID of the code system
  • value: The coded value usually obtained from the relevant codeset table
  • lookup: A table to give the display string of the coded value

Example:
Note: In this example, we are updating an XML element named ‘CodeElement’.

cda.code.set{target=CodeElement, system=cda.codeset.cat["LOINC"], value=cda.codeset.loinc['Consultative note'], lookup=cda.codeset.loincTable}

Example Result:

<code code="11488-4" codesystem="2.16.840.1.113883.6.1" codeSystemName="LOINC" displayName="Consultative note"></code>

originalText.add() [top]

Usage: cda.code.originalText.add{target=<{CODEPARENT}>, reference=<text>}

Code elements can have also originalText XML elements embedded within them. This functions adds a text reference to a code element.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The parent code tag under which you wish to add the new element
  • reference: The ID associated with the human readable element that this element refers to

Example:
Note: In this example, we are adding text to an XML element named ‘CodeElement’.

cda.code.originalText.add{target=CodeElement, reference='ID'}

Example Result:

<code ...>
    <originalText reference="ID"></originalText>
</code>

cda.codeset [top]

This module contains the most common CDA code tables, all designed to locate codes based on code descriptions. There is also ‘reverse’ table for each code set, allowing you to look up a code’s description. These features are very useful when combined with Iguana’s auto-completion feature.

Note: You can easily add code sets to this module! Simply copy the format of the existing tables. In addition, if an existing code set is incomplete, simply extend it by adding extra values to the table.

The following code tables are included:

Table Name Code Set OID
cda.codeset.cat Catalog of codeset OIDs n/a
cda.codeset.act HL7 ActCode (fhir)
HL7 ActCode (hl7.de)
2.16.840.1.113883.5.4
cda.codeset.actClass

HL7 ActClass (fhir)

HL7 ActClass (hl7.de)

2.16.840.1.113883.5.6

cda.codeset.actNoImmunization

HL7 ActReason (fhir)

HL7 ActReason (hl7.de)

2.16.840.1.113883.5.8

cda.codeset.actPriority HL7 ActPriority (fhir)
HL7 ActPriority (hl7.de)

2.16.840.1.113883.5.7

cda.codeset.address HL7 AddressUse (hl7.de) 2.16.840.1.113883.5.1119
cda.codeset.advancedDirectivesTypes HL7 Advance Directive Type (description) 2.16.840.1.113883.1.11.20.2
cda.codeset.confidentiality HL7 Confidentiality (fhir)
HL7 Confidentiality (hl7.de)

2.16.840.1.113883.5.25

cda.codeset.cpt AMA C4
AMA C4 (standard)
AMA C4 (description)(Current Procedure Terminology Evaluation and Management codes)

2.16.840.1.113883.6.12

cda.codeset.cvx CDC NCIRD CVX(Vaccines administered)

2.16.840.1.113883.12.292

cda.codeset.ethnicGroup CDCRace and Ethnicity Code Set
CDCRace and Ethnicity Code Set (description)This shares the same OID with ‘cda.codeset.race’ (they are both subsets of the full codeset).
2.16.840.1.113883.6.238
cda.codeset.healthcareServiceLocation CDC HealthcareServiceLocation

2.16.840.1.113883.6.259

cda.codeset.icf WHO ICF(International Classification of Functioning, Disability and Health)

2.16.840.1.113883.6.254

cda.codeset.interpretation HL7 ObservationInterpretation (fhir)
HL7 ObservationInterpretation (hl7.de)

2.16.840.1.113883.5.83

cda.codeset.language Internet Society RFC 4646/Library of Congress ISO 639 LanguageThere is no definitive list, but you can always create new codes:

2.16.840.1.113883.1.11.11526
cda.codeset.languageAbilityMode HL7 LanguageAbilityMode (fhir)
HL7 LanguageAbilityMode (hl7.de)

2.16.840.1.113883.5.60

cda.codeset.loinc LOINC LOINC
LOINC (description)(Logical Observation Identifiers Names and Codes)

2.16.840.1.113883.6.1

cda.codeset.marriage HL7 MaritalStatus (fhir)
HL7 MaritalStatus (hl7.de)

2.16.840.1.113883.5.2

cda.codeset.nameUses HL7 EntityNameUse

2.16.840.1.113883.5.45

cda.codeset.nci NCI Route Of Administration 2.16.840.1.113883.3.26.1.1
cda.codeset.personalRelationshipRole HL7 PersonalRelationshipRoleType

2.16.840.1.113883.1.11.19563

cda.codeset.proficiencyLevel HL7 LanguageAbilityProficiency (fhir)
HL7 LanguageAbilityProficiency (hl7.de)

2.16.840.1.113883.5.61

cda.codeset.providerCodes NUCC Health Care Provider Taxonomy

2.16.840.1.113883.6.101

cda.codeset.providerRoles HL7 Provider Role (description)

2.16.840.1.113883.12.443

cda.codeset.race CDCRace and Ethnicity Code Set
CDCRace and Ethnicity Code Set (description)This shares the same OID with ‘cda.codeset.ethnicGroup’ (they are both subsets of the full codeset).

2.16.840.1.113883.6.238

cda.codeset.religion HL7 ReligiousAffiliation

2.16.840.1.113883.5.1076

cda.codeset.roleClass HL7 RoleClass (fhir)
HL7 RoleClass (hl7.de)

2.16.840.1.113883.5.110

cda.codeset.rxnorm NLM RxNorm
NLM RxNorm (standard)
NLM RxNorm (description)

2.16.840.1.113883.6.88

cda.codeset.sex HL7 V2AdministrativeSex (description)In HL7 V3, this codeset is “replaced” by AdministrativeGender (fhir), AdministrativeGender (hl7.de)(2.16.840.1.113883.5.1) 2.16.840.1.113883.12.1
cda.codeset.signature HL7 ParticipationSignature (fhir)
HL7 ParticipationSignature (hl7.de)

2.16.840.1.113883.5.89

cda.codeset.snomedCT NIH SNOMED-CT (standard)
NIH SNOMED-CT (description)(SNOMED Controlled Terminology)

2.16.840.1.113883.6.96

cda.codeset.status HL7 ActStatus (fhir)
HL7 ActStatus (hl7.de)

2.16.840.1.113883.5.14

cda.codeset.templates* HL7 Template ID n/a

*Template IDs are common template identifiers used to specify constraints for Sections and Entries (as specifed in CDA R2). Because template identifiers are (by definition) user-definable, there is no standard list and no OID (and no corresponding entry in our module). If a list of “common templates” with an OID were to be created in the future, you could add an entry to ‘cda.codeset.cat’. For more information, check out these resources:

cda.code.simple [top]

Sometimes the XML tag already implies the coding system that you are referring to. In these cases, the coding system is assumed and only the code is required.

These functions add/update “simple” codes used in your CDA document:

  • code.simple.add : Add a new code element that already implies its code system
  • code.simple.set : Update an existing code element that already implies its code system

simple.add() [top]

Usage: cda.code.simple.add{target=<{PARENT}>, element=<ELEMENT>, value=<DISPLAYNAME>}

Add a simple code element to your CDA document.

Note: Notice the absence of both the system and lookup parameters.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating
  • value: The coded value usually obtained from the relevant codeset table

Example:

cda.code.simple.add{target=P, element='languageCode', value=cda.codeset.language['English - US']}

Example Result:

<languageCode code="en-US"></languageCode>

simple.set() [top]

Usage: cda.code.set{target=<{ELEMENT}>, value=<DISPLAYNAME>}

Update an existing simple code element with the appropriate attributes.

Note: Notice the absence of both the system and lookup parameters.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The XML element that you wish to update
  • value: The coded value usually obtained from the relevant codeset table

Example:
Note: In this example, we are updating an XML element named ‘CodeElement’.

cda.code.simple.set{target=CodeElement, value=cda.codeset.language['English - US']}

Example Result:

<languageCode code="en-US"></languageCode>

cda.demographic.name [top]

These functions add names (of people, places, clinics, etc.) to your CDA document:


add() [top]

Usage: cda.demographic.name.add{target=<{PARENT}>, given=<value>, family=<value>, nickname=<value>, prefix=<value>, element=<ROOT NAME>, use=<value>}

Beyond first and last names, names elements can include prefix and nickname components.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • given: Given name, i.e., “Mary”
  • family: Family name, i.e., “Smith”

Optional parameters:

  • prefix: Prefix, i.e., Dr or Mrs
  • nickname: Nickname
  • element: The specific name of the tag you are creating (default element = “name”)
  • use: Identifies the type of name

Example:

cda.demographic.name.add{target=P, given='Isabella', nickname='Isa', family='Jones', use=cda.code.nameUses.Legal}

Example Result:

<name use="L">
   <given>Isabella</given>
   <nickname>Isa</nickaname>
   <family>Jones</family>
</name>

simple.add() [top]

Usage: cda.demographic.name.simple.add{target=<{PARENT}>, name=<value>}

On occasion, a name can simply be a single string of text.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • name: The name itself, as a string value

Example:

cda.demographic.name.simple.add{target=O, name='Community Health and Hospitals'}

Example Result:

<name>Community Health and Hospitals</name>

cda.demographic.address [top]

This function adds address information to your CDA document:


add() [top]

Usage: cda.demographic.address.add{target=<{PARENT}>, use=<TYPE>, street=<STREET>, street2=<STREET2>, city=<CITY>, state=<STATE>, zip=<ZIP>}

Add an address to your CDA document. Addresses apply to many RIM classes (such as patients, authors, and organizations).

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element

Optional parameters:

  • use: Type of address
  • street: The street value
  • street2: Optional second street line
  • city: The city, i.e., Toronto
  • state: The state or province, i.e., ON
  • zip: The zip code
  • country: The country

Example:

cda.demographic.address.add{target={PARENT}, use=cda.code.address.Home, street='1357 Amber Drive', city='Beaverton', state='OR', zip='97867', country='US'}

Example Result:

<addr use="HP">
    <streetAddressLine>1357 Amber Drive</streetAddressLine>
    <city>Beaverton</city>
    <state>OR</state>
    <postalCode>97867</postalCode>
    <country>US</country>
</addr>

cda.demographic.phone [top]

This function adds telephone information to your CDA document:


add() [top]

Usage: cda.demographic.phone.add{target=<{PARENT}>, phone=<PHONE>, use=<TYPE>}

Add a new telecom XML element to your document. Telecom data applies to many RIM classes (usually the same ones that include addresses).

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element

Optional parameters:

  • phone: The actual phone number
  • use: The type of phone number (i.e. HP for home phone number)

Example:

cda.demographic.phone.add{target={PARENT}, phone='(816)276-6909', use=cda.code.address.Home}

Example Result:
<telecom use="HP" value="tel:(816)276-6909"></telecom>

cda.dose [top]

This function adds dosage information to your CDA document:


add() [top]

Usage: cda.dose.add{target=<{PARENT}>, element=<ELEMENT>, numerator=<NUMERATOR>, denominator=<DENOMINATOR>}

Add dosage information to your CDA document.

Note: Both the numerator and denominator are optional fields. If they are not provided, they are replaced by the nullFlavor “UNK” (meaning “unknown”).

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target:The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating

Optional parameters:

  • numerator: The numerator portion of the dose value
  • denominator: The denominator portion of the dose value

Example:

cda.dose.add{target={PARENT}, element='maxDoseQuantity', numerator='12', denominator='35'}

Example Result:

<maxDoseQuantity>
    <numerator value='12'></numerator>
    <denominator value='35'></denominator>
</maxDoseQuantity>

cda.help [top]

This CDA modules rely heavily on the use of the Iguana help system. This makes the template much more useable with auto-completion of parameters for module functions. We simplified the built-in help functions by wrapping them in a format that is easier on the eye. We also added a helpful “check” function that raises an error when you use an incorrect parameter.

These functions are used to add and update help for the functions in the modules:

Information:

Now if we look at the normal API that is part of Iguana we would be populating Lua tables like this:

local addCodeHelp = {
   Title="cda.code.set",
   Usage=[[cda.code.set{root=&lt;XML Root&gt;, system=&lt;value&gt;, value=&lt;value&gt;,label=&lt;value&gt;}]],
   Desc=[[This function will populate a code element with the appropriate attributes.]],
   Returns={
      {Desc="The created code element"},
   },
   ParameterTable=true,
   Parameters={
      {root={Desc='The XML element to populate the attributes of'}},
      {system={Desc='The OID of the system, typically something like cda.code.LOINC'}},
      {value={Desc='The value'}},
      {label={Desc='The displayName to describe the code'}},
      {blah={Desc='Some optional parameter', Opt=true}}
   },
   Examples={[[local Result = cda.code.set{root=Doc, system=cda.code.LOINC, code='11488-4', label='Consultative note'}]]},    
}

And here is the new format:

It uses clearer naming “description” instead of “Desc” and “parameters” instead of “ParameterTable”. For simplicity it escapes the “<>” characters in the “usage” field, so you can use the more intuitive “<value>” (rather than “&gt;value&lt;”). However these are not escaped in the “example” field as there are times that you actually need to use html formatting in your examples (the set example below uses escaping and html formatting). Also it uses the standard Iguana lower case names for consistency with the other built-in APIs (rather than Pascal case).

addCodeHelpShort = {
   title="cda.code.set",
   usage="cda.code.set{root=<XML Root>, system=<value>, value=<value>,label=<value>}",
   description="This function will populate a code element with the appropriate attributes.",
   returns={"The created code element"},
   parameters={
      [1]{['parameter']='root',['description']='The XML element to populate the attributes of'},
      [2]={['parameter']='system',['description']='The OID of the system, typically something like cda.code.LOINC'},
      [3]={['parameter']='value',['description']='The value'},
      [4]={['parameter']='label',['description']='The displayName to describe the code'},
   },
   optional_parameters={
        [1]{['parameter']='blah,['description']='Some optional parameter'},
   },
   examples={"local Result = cda.code.set{root=Doc, system=cda.code.LOINC, code='11488-4', label='Consultative note'}"},
}

Note: The numbered entries in the parameters (and optional_parameters) table are required to ensure that the parameters are displayed in the correct order in the interactive help.


set() [top]

Usage: cda.help.set{func=<FUNCTION>, info=<{TABLE CONTAINING THE HELP INFORMATION}>}

Sets up the help for a function using the simplified help format passed as the second parameter.

Returns: Nothing

Required parameters:

  • func: The name of the function to set the help for
  • info: The help information formatted in a Lua table

Example:

This is the help table for cda.dose.add, it uses all the fields and some html formatting:

local cdaDoseAddHelp = {
   title="cda.dose.add",
   usage=[[cda.dose.add{target=<{PARENT}>, element=<ELEMENT>, numerator=<NUMERATOR>, denominator=<DENOMINATOR>}}]],
   description=[[Add dosage information to your CDA document.<br /><br />
<strong>Note</strong>: Both the numerator and denominator are optional fields. If they are not provided, they are replaced by the nullFlavor "UNK" (meaning "unknown").]],
   returns={"A parsed tree representing the populated XML element"},
   parameters={
      [1]={['param']='target',['desc']='The parent tag under which you wish to add the new element'},
      [2]={['param']='element',['desc']='The specific name of the tag you are creating'}, 
   },
   optional_parameters={
      [1]={['param']='numerator',['desc']='The numerator portion of the dose value'},
      [2]={['param']='denominator',['desc']='The denominator portion of the dose value'}, 
   },
   examples={[[ cda.dose.add{target={PARENT}, element='maxDoseQuantity', numerator='12', denominator='35'}

&lt;span style="font-size:12px;line-height:12px;"&gt;&lt;span style="font-family:verdana"&gt;&lt;strong&gt;Example Result&lt;/strong&gt;:&lt;/span&gt;&lt;/span&gt;

&lt;maxDoseQuantity&gt;
    &lt;numerator value='12'&gt;&lt;/numerator&gt;
    &lt;denominator value='35'&gt;&lt;/denominator&gt;
&lt;/maxDoseQuantity&gt;]]}

This is the call that sets the help for cda.dose.add:

cda.help.set{func=cda.dose.add, info=cdaDoseAddHelp}

check() [top]

Usage: cda.help.check(<{FUNC: FUNCTION CALL PARAMETERS}>, <{INFO: TABLE CONTAINING THE HELP INFORMATION}>)

Checks for unknown parameters and raises an error if an incorrect parameter names is used. Typical use is to call cda.help.check at the start of each module function to check for invalid calls. Notice that we use rounded brackets instead of curly braces.

Note: Checking only occurs when you are editing the channel (it is disabled at runtime).

Returns: Nothing

Required parameters:

  • func: Table of parameters from the function call
  • info: The help information formatted in a Lua table

Example:

Note: A variable “check” is used used as a shorthand, to make the call more concise (this is created at the start of each module).

local check = cda.help.check -- create shortcut

function cda.code.add(I)
   check(I, cdaCodeAddHelp)             -- use shorcut
   -- cda.help.check(I, cdaCodeAddHelp) -- equivalent no shortcut

   I.target = addElement(I.target, I.element)
   I.element = nil
   local T = cda.code.set(I)

   return T
end

cda.id [top]

These functions add CDA-specific identifiers to your document:


add() [top]

Usage: cda.id.add{target=<{PARENT}>, value=<EXTENSION>, id_type=<ROOT>}

A RIM class may have an associated ID value that you will need to include in your document.

Note: Predefined root values used in the id_type argument can be found in the cda.codeset.templates table.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element

Optional parameters:

  • value: The extension (or specific value) of the ID
  • id_type: The root identifier (object ID) of the desired ID

Example:

cda.id.add{target={PARENT}, value='998991', id_type=cda.codeset.cat.HL7ExampleOid}

Example Result:

<id extension="998991" root="2.16.840.1.113883.19.5.99999.2"></id>

template.add() [top]

Usage: cda.id.template.add{target=<{PARENT}>, value=<EXTENSION>, id_type=<ROOT>}

CDA documents are made up of a collection of templates that describe a particular actor or event. Every template has an associated template ID.

Note: Predefined root values used in the id_type argument can be found in the cda.codeset.templates table.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element. The templateID tag is inserted into position 1.
  • id_type: The root identifier (object ID) of the desired ID

Optional parameters:

  • value: The extension (or specific value) of the ID

Example:

cda.id.template.add{target={PARENT}, id_type=cda.codeset.templates.Assessment}

Example Result:

<templateId root="2.16.840.1.113883.10.20.22.2.8"></templateId>

cda.null [top]

Sometimes data is not available for a required element; however, CDA requires that we provide a reason for this absence of data. As such, a “nullFlavor” must be applied to the XML element. The table below shows the ‘nullFlavor’ options that we’ve included the CDA API:

cda.null.flavor = {
   NoInformation='NI',
   Other='OTH',
   Invalid='INV',
   NegativeInfinity='NINF',
   PositiveInfinity='PINF',
   Unencoded='UNC',
   Derived='DER',
   Unknown='UNK',
   AskedButUnknown='ASKU',
   NotAvailable='NAV',
   SufficientQuantity='QS',
   NotAsked='NASK',
   Trace='TRC',
   Masked='MSK',
   NotApplicable='NA'
}

This function sets the ‘nullFlavour’ value:


set() [top]

Usage: cda.null.set(<{ELEMENT}>, <NULLFLAVOR>)

Set the ‘nullFlavour’ for a missing required element. Notice that we use rounded brackets instead of curly braces.

Note: This function removes all children, including attributes and sub-elements, and replaces them with the ‘nullFlavor’ attribute. The only exception is the “xsi:type” attribute found in ‘value‘ elements. Those must remain to ensure NIST validation.

Returns:

  • A parsed tree representing the populated XML element

Required parameters:

  • element: The element to which null will be applied.
  • nullFlavor: The type of null. The module’s table provides the possible values.

Example:

As an example, suppose we had the following XML element:

<id root="" extension=""></id>

Imagine that we simply don’t know the ID. Also suppose that variable Id represents the XML element above. To rectify this in our CDA document, we need to add the following line of code:

cda.null.set(Id, cda.null.flavor.Unknown)

Example Result:

<id nullFlavor="UNK"></id>

cda.time [top]

These functions add time values to your CDA document:

Note: These functions use the dateparse() function to create the resulting value.


add() [top]

Usage: cda.time.add{target=<{PARENT}>, element=<ELEMENT>, time=<DATETIME>}

Add a time value to your CDA document. There is no validity check, it is your responsibility to use the correct time format.

Note: The time zone defaults to UTC (GMT), to change zone you just add an increment/decrement, e.g., +500 for EST.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target:The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating

Optional parameters:

  • time: A valid date-time string

Example:

Note: In this example we are using EST (+500)

cda.time.add{target={PARENT}, element='effectiveTime', time='20000323000000+500'}

Example Result:

<effectiveTime value='20000323000000+0500'></value>

set() [top]

Usage: cda.time.set{target=<{ELEMENT}>, time=<DATETIME>}

Update a time value to your CDA document.There is no validity check, it is your responsibility to use the correct time format.

Note: The time zone defaults to UTC (GMT), to change zone you just add an increment/decrement, e.g., +500 for EST.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target:The XML element that you wish to update

Optional parameters:

  • time: A valid date-time string

Example:

Note: In this example we are using EST (+500).

cda.time.set{target=ET, time='20000323000000+500'}

Example Result:

<effectiveTime value='20000323000000+0500'></value>

timerange.add() [top]

Usage:
local TimeRange = cda.timerange.add{target=<{PARENT}>, element=<ELEMENT>}
— use cda.time.add{} to add the dates for the Time Range
cda.time.add{target=TimeRange, element=<LOW>, time=<DATETIME>}
cda.time.add{target=TimeRange, element=<HIGH>, time=<DATETIME>}

To create a time interval, you must first create the interval root element. Then you can add the sub-elements defining the interval range. There is no validity check, it is your responsibility to use the correct time format.

Note: The time zone defaults to UTC (GMT), to change zone you just add an increment/decrement, e.g., +500 for EST.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target:The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating

Example:

Note: In this example we are using EST (+500).

local ET = cda.timerange.add{target={PARENT}, element='effectiveTime'}
-- use cda.time.add{} to add the dates for the Time Range
cda.time.add{target=ET, element='low', time='20080501000000+500'}
cda.time.add{target=ET, element='high', time='2009022700000+500'}

Example Result:

<effectiveTime xsi:type="IVL_TS">
    <low value="20080501000000+0500"></low>
    <high value="20090227000000+0500"></high>
</effectiveTime>

timeperiod.add() [top]

Usage: cda.timeperiod.add(target=<{PARENT}>, element=<ELEMENT>, period=<PERIOD>, unit=<UNIT>}
Add a specific time period to your CDA document.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target:The parent tag under which you wish to add the new element
  • element: The specific name of the tag you are creating
  • period: The period of time you wish to add
  • unit: The time period unit

Example:
cda.timeperiod.add{target={PARENT}, element='effectiveTime', period='6', unit='h'}

Example Result:

<effectiveTime xsi:type="PIVL_TS" institutionSpecified="true" operator="A">
    <period value="6" unit="h"></period>
</effectiveTime>

cda.value [top]

Clinical documents often describe some measured value. CDA supports the following value types:

  • INT (integer)
  • REAL (number with a fractional component)
  • ST (string)
  • PQ (measure value)

Note: To add a code value (CD), we recommend using the cda.code module instead.

The functions add values to your CDA document:


add(): adding INT and REAL values [top]

Usage: cda.value.add{target=<{PARENT}>, element=<ELEMENT>, datatype=<[INT | REAL]>, value=<VALUE>}

Add integers or fractions to your CDA document.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • element: The element with the value attribute
  • datatype: Type of data stored in element (in this case, INT or REAL)

Optional parameters:

  • value: The actual value
  • unit: The unit of measurement

Example:

cda.value.add{target={PARENT}, element='value', datatype='INT', value='7'}

Example Result:
<value xsi:type="INT" value="7"></value>

add(): adding PQ values [top]

Usage: cda.value.add{target=<{PARENT}>, element=<ELEMENT>, datatype=’PQ’, value=<VALUE>, unit=<UNIT>}

Add a measurement to your CDA document. Notice that, to create a PQ value, you must add a unit argument and specify “PQ” as the datatype.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • element: The element with the value attribute
  • datatype: Type of data stored in element (in this case, INT or REAL)

Optional parameters:

  • value: The actual value
  • unit: The unit of measurement

Example:

cda.value.add{target={PARENT}, element='value', datatype='PQ', value='57', unit='a'}

Example Result:

<value xsi:type="PQ" value="57" unit="a"></value>

valuerange.add() [top]

Usage:

local Range = cda.valuerange.add{target=<{PARENT}>, element=<ELEMENT>, datatype=’IVL_*’}

— use cda.value.add{} to add the values for the Range

cda.value.add{target=Range, element=<LOW>, datatype=<DATATYPE>, value=<VALUE>, unit=<UNIT>}

cda.value.add{target=Range, element=<HIGH>, datatype=<DATATYPE>, value=<VALUE>, unit=<UNIT>}

INT, REAL and PQ values can also appears as intervals. To create an interval in your clinical document, you must first create the interval root element, then add the sub-elements defining the interval range. Essentially, you are adding a value XML element that encapsulates a value range.

Note: Intervals have a datatype of “IVL_*” (where * is replaced by the subtype that makes up the interval). For example, if an interval is made of PQ subtypes, then the type of the interval is ‘IVL_PQ’.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • element: The element with the value attribute
  • datatype: Type of data stored in element (in this case, IVL_*)

Example:

local Range = cda.valuerange.add{target={PARENT}, element='value', datatype='IVL_PQ'}
cda.value.add{target=Range, element='low', datatype='PQ', value='4.3', unit='10+3/ul'}
cda.value.add{target=Range, element='high', datatype='PQ', value='10.8', unit='10+3/ul'}

Example Result:

<value xsi:type="IVL_PQ">
   <low value="4.3" unit="10+3/ul"></low>
   <high value="10.8" unit="10+3/ul"></high>
</value>

valuestring.add() [top]

Usage: cda.util.valuestring.add{target={PARENT}, string=<VALUE>}

Add a value XML element with inner content represented by text.

Note: A “value” element is added by default and its type is set to “ST”.

Returns: A parsed tree representing the populated XML element

Required parameters:

  • target: The parent tag under which you wish to add the new element
  • string: The inner content of the value

Example:

cda.util.valuestring.add{target={PARENT}, value='1 pack per day'}

Example Result:

<value xsi:type="ST">1 pack per day</value>

cda.xml [top]

These functions are used to add, set or find XML elements:


node.text() [top]

Usage: node.text(<TARGET: PARENT XML ELEMENT>)

Finds and returns the first XML TEXT element. This works with a simple text element, or a “complex element” (one with sub-elements). If a text element does not exist it is appended to the parent element, then returned. Notice that we use rounded brackets instead of curly braces.

Returns: The first XML TEXT element

Required Parameters:

  • target: Parent element that contains the TEXT element

Example:

Note: In this example the first XML TEXT contains the string “Good Health Clinic Consultation Note”

CD.title:text()

Example Result:

<title>Good Health Clinic Consultation Note</title>

Note: In this example there is no XML TEXT element, so an empty one is created and returned

CD.title:text()

Example Result:

<name>
    <given>Ralph</given>
    <family>Jones</family>
    -- an empty text element is appended and returned
</name>

node.setText() [top]

Usage: node.setText(<TARGET: PARENT XML ELEMENT>, <VALUE: TEXT STRING>)

Sets the text in an XML TEXT element. This works with a simple text element, or a “complex element” (one with sub-elements). If a text element does not exist it is appended to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns: Nothing

Required Parameters:

  • target: Element to set the text for
  • value: Text string value for the element

Example:

Note: A variable “setText” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local setText = node.setText -- create shortcut

setText(CD.title, 'Good Health Clinic Consultation Note')

Example Result:

<title>Good Health Clinic Consultation Note</title>

Note: In this example we append a text element to a complex element

local setText = node.setText -- create shortcut
setText(GP.name, 'Append a text element')

Example Result:

<name>
    <given>Ralph</given>
    <family>Jones</family>
    Append a text element  -- appended text element
</name>

node.setAttr() [top]

Usage: node.setAttr(<TARGET: PARENT XML ELEMENT>, <ATTRIBUTE>, <VALUE: TEXT STRING>)

Sets the named attribute to a specified value. If a the specified attribute does not exist it is appended to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns:

  • The updated parent element

Required Parameters:

  • target: The parent element
  • attribute: The name of the attribute to set
  • value: Text string value for the attribute

Example:

Note: A variable “setAttr” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local setAttr = node.setText -- create shortcut

setAttr(PE, 'classCode', 'PLC')

Example Result:

<playingEntity classCode="PLC">              -- appended attribute
   <name>Community Urgent Care Center</name>
</playingEntity>

Note: In this example we append a second attribute to the “playingEntity”

local setAttr = node.setText -- create shortcut
setAttr(PE, 'another', 'attribute')

Example Result:

<playingEntity classCode="PLC" another="attribute"> -- another appended attribute
   <name>Community Urgent Care Center</name>
</playingEntity>

node.addElement() [top]

Usage: node.addElement(<TARGET: PARENT XML ELEMENT>, <ELEMENT: ELEMENT NAME>)

Appends an empty named element to the parent element. Notice that we use rounded brackets instead of curly braces.

Returns:

  • The appended element

Required Parameters:

  • target: The parent element
  • element: The name of the element to append

Example:

Note: A variable “addElement” is used as a shorthand, to make the call more concise (this is created at the start of each module)

local addElement = node.setAttr -- create shortcut

local P = addElement(birthplace, 'place')

Example Result:

<birthplace>
   <place>
   </place>
</birthplace>

xml.findElement() [top]

Usage: xml.findElement(<TARGET: XML ELEMENT>, <ELEMENT: ELEMENT NAME>)

Find the first element of the specified name in the target. If the target is a tree, it will do a depth-first search of tree. Notice that we use rounded brackets instead of curly braces.

Note: If there are multiple elements with the same name this function will only find the first one.

Returns:

  • The first element found that matches the name specified

Required Parameters:

  • target: Element to search within
  • element: The name of the element to search for

Example:
xml.findElement(G,'guardianPerson')

Leave A Comment?