Build a CDA document

Review what you've learned

What is the number one thing that we want you to take away from this tutorial? Despite the seemingly complex nature of CDA documents, our method produces a very simple, repeatable process for creating any CDA document.Let’s quickly review that process right now, to make sure you get the full picture:

Step 1: Customize the CDA header template

You can customize our CDA header template to match your specific needs at any time!


  • Make static changes that will affect all your CDA documents
  • Make dynamic changes that can be tailored to meet different CDA requirements

Reference: Customize the CDA header template.

Step 2: Create an empty CDA

Create an empty CDA document with a pre-built header using only a few simple lines of code.


  • Use to create the empty CDA document

Reference: Create a blank CDA document.

Step 3: Populate the user-specific header attributes/elements

This is a simply a process of plugging data into the empty attributes and elements using the CDA API’s handy functions.

Note: If you used a “minimal template” with no empty header fields then this step is not required. You can simply append elements/attributes in the next step.


  • Update existing attributes:
    • Usually you will use Lua “dot syntax” to assign values: = 'TT998'
    • You can also use setAttr(), but it is less concise: setAttr(, 'extension', 'TT998')
  • Update existing elements:
    • Usually you will use an CDA API “set” function to set all the attributes for an element with a single function call: cda.time.set{target=CD.effectiveTime, time='20070415000000+0500'}
    • If an element (i.e., setId) does not have a “set” function, you can assign values to its attributes individually:
      • Usually you will use Lua “dot syntax” to assign values: CD.setId.extension = 'BB35'
      • You can also use setAttr(): setAttr(CD.setId, 'extension', 'BB35')
      • Alternatively, you could create a new “set” function like
    • You can also add attributes to an element individually with setAttr(): setAttr(, 'extension', 'TT998')
    • Use setText() to set a text element: setText(CD.title, 'Good Health Clinic Consultation Note')

Reference: Populate the CDA header

Step 4: Append the remaining header elements in the correct order

Use the CDA API’s “add” functions (or a combination of addElement() + setAttr()) to append the elements used in your CDA. At a minimum. you will need to add the required header elements: ‘recordTarget’, ‘author’, and ‘custodian’.

Note: If you extended your template to include all the necessary header elements then this step is not required. Instead you would have filled in the elements and attributes in the previous step.


  • Use a CDA API “add” function: cda.time.add{target=A, element='time', time='20070415000000+0500'}
  • You can also build elements “manually”, step by step:
    • Use addElement to append the element: addElement(CD, 'languageCode')
    • Use setAttr() to create and set each attribute: setAttr(CD.languageCode, 'code', cda.codeset.language["English - US"])
  • Building an element “manually” has two common applications:
    • When you only want to use a subset of the attributes available in an element
    • When the CDA API does not contain an “add” function for the element you are adding. For example, there is no “add” for the setId element!
      • Use addElement and setAttr() is a simple workaround
      • Alternatively, you could create a new “add” function like


Step 5: Add the CDA body

The CDA document’s body is composed of a ‘component’ element containing a ‘structuredBody’ sub-element. Use addElement() to append these.

Note: If you extended your template to include all the necessary body elements then this step is not required.


  • Two calls to addElement() are needed:
    • Append the ‘component’ element: local Body = CD:addElement('component')
    • Append the ‘structuredBody’ element: local SB = Body:addElement('structuredBody')

Reference: Add the CDA body

Step 6: Develop the CDA body in the correct order

Use the CDA API “add” functions (or a combination of addElement + setAttr()) to develop and populate the body elements/attributes required in your CDA document.

Note: If you customized the CDA header template to include all the necessary body elements, then adding elements not required. Instead, simply fill the elements/attributes in the same manner as Step 3.


  • Use the same techniques as Step 4.
  • Use setInner() to add XML (or HTML, audio, video, images etc) content directly to a CDA “encapsulated text” (ED) element

Reference: Populate the CDA body

Performance Tuning

After profiling the code two major changes were made, for about a 60% reduction in execution time:

  • Fuzzy date parsing using dateparse module was removed, for about 33% percent improvement.
  • Functions were stored in local variables, for a further 28% improvement. See “Lua Performance Tips” by Roberto Lerusalimschy for an explanation.

Please contact us at if you need more information.

What’s Next?

Now that you have a better understanding of how our CDA process works, we recommend that you take a moment to browse our CDA API Guide to get better acquainted with all the tools at your disposal. When you are ready to start developing your own CDA documents, we also offer some additional resources:

  • If you forget any of this basic process, we have a very brief CDA Cheat Sheet that summarizes the steps at a glance.
  • Leverage the code that we provided in this tutorial to build a similar CDA document of your own.
  • We also provide a useful bucket of CDA templates that represent various CDA document types. Feel free to use these completed scripts as a basis for your own CDA documents!
  • Innovate! Think outside the box! And let us know what you come up with.

Leave A Comment?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.