Introduction
cda
cda.code
cda.codeset
cda.code.simple
cda.demographic.name
cda.demographic.address
cda.demographic.phone
cda.dose
cda.help
cda.id
cda.null
cda.time
cda.value
cda.xml

Introduction

Our collection of CDA modules provide 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: http://www.ietf.org/rfc/rfc4646.txt http://www.rfc-editor.org/rfc/rfc5646.txt	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:

name.add
name.simple.add

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:

address.add

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:

phone.add

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:

dose.add

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:

help.set
help.check

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 “>value<”). 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:

id.add
id.template.add

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:

null.set

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:

time.add
time.set
timerange.add
timeperiod.add

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:

value.add: INT and REAL
value.add: PQ
valuerange.add
valuestring.add

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 : Find (or create) the first XML TEXT element
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

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')

Iguana Documentation

CDA API

Introduction

cda [top]

new() [top]

cda.code [top]

add() [top]

set() [top]

originalText.add() [top]

cda.codeset [top]

cda.code.simple [top]

simple.add() [top]

simple.set() [top]

cda.demographic.name [top]

add() [top]

simple.add() [top]

cda.demographic.address [top]

add() [top]

cda.demographic.phone [top]

add() [top]

cda.dose [top]

add() [top]

cda.help [top]

Information:

set() [top]

check() [top]

cda.id [top]

add() [top]

template.add() [top]

cda.null [top]

set() [top]

cda.time [top]

add() [top]

set() [top]

timerange.add() [top]

timeperiod.add() [top]

cda.value [top]

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

add(): adding PQ values [top]

valuerange.add() [top]

valuestring.add() [top]

cda.xml [top]

node.text() [top]

node.setText() [top]

node.setAttr() [top]

node.addElement() [top]

xml.findElement() [top]