Tutorial: Setting Up Content Validation For Your Local C-CDA Reference Validator

[Mat Davis]

Hi all. Please see below.

Thanks - Mat Davis

https://dynamichealthit.com

NOTE: These steps are from a Windows Server perspective

Prerequisites

1. Already have the C-CDA Reference Validator installed locally and working using the latest available WAR file (06/23/2025 as of this conversation)
   1. See here for more info
   2. Instructions - https://github.com/onc-healthit/reference-ccda-validator
   3. Latest WAR - https://github.com/onc-healthit/reference-ccda-validator/releases/tag/1.1.1
2. Have access to login into Tomcat Apache Manager to reload the web app
3. Have access to restart the Tomcat Apache Service if needed

Blockers

• Based on what I can tell and have found, Content Validation requires Scenario Files which will be XMLs that meet each Patient Specific Scenario, scenarios like b1 > Amb > Sample 1 or e1 > Inp > Sample 2
• These XMLs will be referred to as the "answer key XMLs"
• The last time these "answer key XMLs" were provided were from CURES and PRECURES via Github
• https://github.com/onc-healthit/content-validator-api/tree/v1.1.4/src/test/resources/preCures/ref
• https://github.com/onc-healthit/content-validator-api/tree/v1.1.4/src/test/resources/cures/ref
• There currently aren't any accessible USCDIv3  "answer key XMLs" that I have been able to find on Github at this time

Step by Step For Proof Of Concept

NOTE: The only goal of these steps is to confirm how the Scenario File process works from end to end

1. Ensure you have a target Scenario Files Folder
   1. Here is my current example path
   2. C:\Temp\ONC\Scenarios
2. Update the following config file param to match this same Scenarios Folder path
   1. Config File Path = "C:\Program Files\Apache Software Foundation\Tomcat 8.5\conf\Catalina\localhost\referenceccdaservice.xml"
   2. Config Param For Folder Path =     <Parameter name="content.scenariosDir" value="C:\Temp\ONC\Scenarios\" override="true"/>
3. Now, we're going to drop 3 random XML files into C:\Temp\ONC\Scenarios\
   1. Pick any 3 XML files you'd like from the following location:
   2. https://github.com/onc-healthit/content-validator-api/tree/v1.1.4/src/test/resources/cures/ref
   3. Copy those 3 XML files to C:\Temp\ONC\Scenarios\
   4. Do not place any folders inside C:\Temp\ONC\Scenarios\ as they will be ignored and not used
   5. See here for more info - https://github.com/onc-healthit/content-validator-api/blob/master/src/main/java/org/sitenv/contentvalidator/configuration/ScenarioLoader.java#L28
      
      
      
4. Access the Tomcat Apache Server Manager
   1. Navigate to http://localhost:8080/ where the Tomcat server is installed
   2. Click on "Manager App" to the far right
   3. Login
   4. Find the /referenceccdaservice web app
   5. Click on reload
      
      
      
      
      
5. Once the reload has completed (a confirmation will display), check the following logs:
   1. NOTE: you may have to restart Tomcat Apache itself if you're not seeing expected results
   2. SDTOUT
      1. "C:\Program Files\Apache Software Foundation\Tomcat 8.5\logs\tomcat8-stdout.[YYYY-MM-DD].log"
      2. Example = "C:\Program Files\Apache Software Foundation\Tomcat 8.5\logs\tomcat8-stdout.2025-10-19.log"
      3. Scroll to the very bottom of the log text
      4. You should see "LOADING SCENARIO FILES AT " with your Scenarios Folder path
   3. Content Validator
      1. "C:\Program Files\Apache Software Foundation\Tomcat 8.5\logs\contentvalidator.[YYYY-MM-DD].log"
      2. Example = "C:\Program Files\Apache Software Foundation\Tomcat 8.5\logs\contentvalidator.2025-10-19.log"
      3. Open the log via notepad++ and search for all instances of the text "Parsing File"
         
         
      4. Here, you will see that the XML files that you placed in the Scenarios Folder have been parsed on the reload of the app
      5. NOTE: In the screenshot above, I renamed one of my Scenario files to "170.315_b1_toc_amb_sample2_v2.xml" so it could match the PDF name of the Scenario I chose in the Validator UI
6. To put this Content Validation Testing to use, navigate to http://localhost:8080/referenceccdaservice/static/validationui.html 
   1. Select a Scenario that fits one of the 3 XML files you pasted into the Scenario Folder
   2. Ensure the PDF file name that you select in the UI matches one of your XML file names in the Scenarios Folder
   3. When uploading an XML to validate, make sure it doesn't meet at least one expectation
      
      
      
   4. For example - I'm using the Scenario File "170.315_b1_toc_amb_sample2_v2.pdf" which is "Jeremy Bates"
   5. My XML file that I upload will have a patient with a first name and last name of "Alice Newman"
   6. Due to that mismatch, I should get an error for first name and last name for the Reference Validation / Scenario Test
   7. This will confirm that Scenario Testing is working
      
      
      
      
      
7. Unfortunately, mimicking the SITE Test Tool Content Validation with a local instance of the Validator will not work for USCDIv3 Scenarios until USCDIv3 "answer key XMLs" are provided or created manually to place inside the Scenarios Folder

Scenario Error Message

• If you have files in the Scenarios Folder and you've chosen Scenarios in the Validator UI but some kind of match isn't made, I usually see the follow error messages in the logs
• Log = "C:\Program Files\Apache Software Foundation\Tomcat 8.5\logs\contentvalidator.2025-10-19.log"