Installation Guide of Gazelle Objects Checker

Table of Content

  1. Introduction
  2. Clone Project
  3. Run Tests (Optional)
  4. Prepare BBR
  5. Generate Artifact
  6. Generate Validator
  7. Generation Validator form UML (Alternative)
  8. Validate CDA
  9. Utility Scripts
  10. Extras

1. Introduction

In this guide, we will show how to retrieve the new version of Gazelle Objects Cheker, build it and generate a CDA Validator in a generic case, and client specific case

Requirements:

  • JDK 11 or higher
  • Maven 3.5.x /!\ You need to respect this version, or the tool won’t work
    • Thanks to maven wrapper, this version is packaged now with GOC, you can find it in gazelle-objects-checker/hl7templates/hl7templates-packager-jar/src/main/resources/maven-wrapper
  • Git

2. Clone Project

the project is not maintained by the forge anymore.
Gazelle Objects Checker has been migrated to Gitlab and packaged under one module called gazelle-objects-checker
If you worked already with the previous versions of GOC, the following structure could be familiar to you:

  • Archetypes
    • generated-validator
  • Hl7templates
    • gocmodel-jar
    • hl7templates-model-jar
    • hl7templates-api-jar
    • hl7templates-generator-jar
    • hl7templates-packager-jar
  • Models
    • cda-models
    • cdaepsos-models
    • datatypes-models
    • common-models
    • infr-model
    • model-resources
    • nblock-model
    • voc-model

In the current version 3.x.x, the Archtypes and Hl7templates modules (with all their submodules) are packaged in one module Gazelle Objects Checker
The resources models are packaged in a module called UML Models.

Project Link Gitlab
Gazelle Objects Checker https://gitlab.inria.fr/gazelle/library/gazelle-objects-checker
UML Models https://gitlab.inria.fr/gazelle/library/uml-models


Cloning gazelle-objects-checker:

you need to have git and maven installed

Run the following command:

> git clone https://gitlab.inria.fr/gazelle/library/gazelle-objects-checker.git
> cd gazelle-objects-checker

Notice: the installation of gazelle-objects-checker will be done in the Generate Artifact section.
You can skip tests if you want, but it’s not recommend.

You don’t have to install the uml-models module, it’s already released

3. Run Tests (Optional)

/!\ You can skip this section, but it’s recommended to have all tests passed before continue

GOC provides two types of tests, unit tests and integration tests.
The unit tests are environment independent. The integration tests create some temporary resources (UML Models) using the uml-modes (no need to have it installed locally, it has been packaged in Nexus)
Run Unit tests

> cd gazelle-objects-checker

> mvn test

Run Integration Tests

> cd gazelle-objects-checker

> mvn verify

If Something went wrong, make sure you have mentioned in maven logs:

  • Resources created successfully
  • Resources deleted successfully

If not, try to run the creation resources script CreateResourcesForTest.java in:

  • gazelle-objects-checker/gocmodel-jar/src/main/java/net.ihe.gazelle.goc.script

4. Prepare BBR

BBR is an abbreviation of Building Block Repository, a large XML file containing all the functional specifications, that will be used by GOC to generate OCL which is converted finally to a Java validator.
So Basically, the BBR is considered as the main input for GOC

Each client provide his own BBR, and we can retrieve it from the ART-DECOR platform that belong to this client.
We’ll take the example of a BBR in SEQUOIA’s ART-DECOR.

To retrieve the project follow the link:

https://gazellecontent.sequoiaproject.org/apps/decor/services/RetrieveProject

Choose project as (BBR) Consolidated CDA (en-US).
Make sure to select the Compiled version.
Then check the Download radio.
Press send button.

Once you download it, you need to adapt it before using it in the next section of generation.

You first need to open it (as it is a very large file, I recommend you to use VSCode as it’s optimized for that ) then change ccda- by ccda(version)- for example for version 2.1: ccda21- (without the ‘.’)

NOTICE: A script could be released for this, due to performance issues

5. Generate Artifact

After having all tests working (not mandatory but recommended) we can now install the gazelle-objects-checker module and generate the artifact.
The Artifact generated is a .jar suffixed by jar-with-dependencies as it’s created as a standalone application.

To do we run the following command:

> mvn clean install
or
> mvn clean install -DskipTests=true #(to skip tests)

The Artifact is generated at gazelle-objects-checker/hl7templates-packager-jar/target/hl7templates-packager-jar-X.X.X-SNAPSHOT-jar-with-dependencies.jar

The X.X.X refers to the current SNAPSHOT version

HINT: if you still have compile errors, you can install just the archetypes module (as it’s required at runtime) with:

cd gazelle-objects-checker/archetype/generated-validator

mvn clean install

And retrieve GOC Artifact from nexus.

here: GOC Artifact Nexus Choose the latest version, and download the: hl7templates-packager-jar-X.X.X-jar-with-dependencies.jar artifact

6. Generate Validator

This section remains to run Gazelle Objects Checker and generate the CDA MBVal validator.

we will need the following parameters to run GOC and generate the validator:

Parameters Description Type Example is Required
-bbr Path to the BBR file (provided by ART-DECOR) XML File /home/mylap/Documents/bbr-eHDSI-5.0.1.xml Required
-out Path where to generate the validator Directory /home/mylap/Documents/CDA-Validators/output-pivot-19-10-2021 Required
-mvn Path to maven binary Binary (executable) /opt/apache-maven-3.5.4/bin/mvn Required
-serviceName Validation Service Name String Pivot not Required
-HL7TEMP_CDACONFFOLDERNAME HL7template CDA config folder name cdabasic or cdaepsos cdaepsos not Required (default=cdabasic)
-ignoreTemplateIdRequirements ignore TemplateId Requirements when generating the constraints (useful for C-CDA validation tools) name Boolean VOID, parameter present ==> it's true, not present ==> it's false not Required (default=false [Not present])
-ignoreCdaBasicRequirements ignore TemplateId Requirements when generating the constraints (useful for C-CDA validation tools) name Boolean VOID, parameter present ==> it's true, not present ==> it's false not Required (default=false [Not present])
-versionLabel VersionLabel that will be used during the generation String 2.1 not Required
-rootClassName DEPRECATED:Root class name of generated classes Path to java class (see example) net.ihe.gazelle.cdaepsos3.POCDMT000040ClinicalDocument not Required
-HL7TEMP_RESOURCES_PATH DEPRECATED: Path to hl7templates resources folder String /home/mylap/Documents/hl7templates-resources not Required

Move to the hl7templates-packager-jar/target directory and run the following command with java 11:

>cd gazelle-objects-checker/hl7templates/hl7templates-packager-jar/target

Generic command with all possible parameters:

> java -jar hl7templates-packager-jar-X.X.X[-SNAPSHOT]-jar-with-dependencies.jar -bbr <Path_To_BBR> 
-out <Path_To_Output> -mvn <Path_To_MVN> [-serviceName <Service_Name>] [-HL7TEMP_CDACONFFOLDERNAME <cdabasic|cdaepsos>] 
 [-ignoreTemplateIdRequirements <true|false>] [-ignoreCdaBasicRequirements <true|false>]
[-versionLabel <version>] [-rootClassName <Root_ClassName>] [-HL7TEMP_RESOURCES_PATH <Path_To_Resources>]

The [X.X.X] refers to the current used version of GOC, and it’s not present if we retrieve a release from Nexus.

Example with SEQUOIA:

> java -jar hl7templates-packager-jar-3.0.0-SNAPSHOT-jar-with-dependencies.jar -bbr ~/Documents/BBR-SEQUOIA.xml
 -out home/mylap/Documents/GOC-OUTPUT/output-sequoia-mu3 -mvn /opt/apache-maven-3.5.4/bin/mvn
 -serviceName "HL7 - C-CDA R2.1 - Meaningful Use Stage 3" -ignoreTemplateIdRequirements 
 -ignoreCdaBasicRequirements  -versionLabel 2.1

For logs:

Go to the root folder of the provided output path, then logs/logs-[generation_date_time]

cd /home/mylap/Documents/GOC-OUTPUT/logs/logs-[generation_date_time]

Logs are separated as follows:

  • generated_report.log: contains synthetic report about the generation process (Warnings and Errors)
  • detailed_report.log: contains all the logging information from the generation process (Infos, Warnings, Errors)
  • cmdOutput.log: contains the Standard Output of executed commands during generation (maven command to init project with archetype, generate code from OLC, packaging…)
  • cdeModelsErrors.txt: contains all detected inconsistencies between the provided BBR and pre-defined models used by GOC

Logs Conception

7. Generate Validator from UML (Alternative)

This section is just an alternative way to regenerate the validator when the functional specifications change without re-running GOC, but just from the generated model.uml file.

> cd /home/mylap/Documents/GOC-OUTPUT/validator/[validator-name]-validator-jar/model/[validator-name].uml

for example for epsos5

> cd /home/mylap/Documents/GOC-OUTPUT/validator/epsos5-validator-jar/model/epsos5.uml

Then you can edit it with a Text Editor, or a dedicated modeling tool (ex: TopCased).

After saving your model, you need to:

Go to GOC-OUTPUT/epsos5-validator-jar and do the following:

> cd /home/mylap/Documents/GOC-OUTPUT/validator/epsos5-validator-jar
> mvn exec:exec@generateValidator -DmvnPath="/opt/apache-maven-3.5.4/bin/mvn" -DcdaProps="cdaepsos" -DprojectName="epsos5"
> mvn clean package

The generic form of the command is:

> mvn exec:exec@generateValidator -DmvnPath="[maven-path]" -DcdaProps="[cdaepsos or cdabasic]" -DprojectName="[validator-name]"

Your validator will be available at: GOC-OUTPUT/epsos5-validator-jar/target/appassembler/bin and do the following:

> cd /home/mylap/Documents/GOC-OUTPUT/epsos5-validator-jar/target/appassembler/bin
> chmod +x validator.sh

Now you can refer to Section 8 to Validate a CDA document with your new validator.

8. Validate CDA

Now we are going to use the generated validator.

We will suppose we generated a validator with a BBR containing the following version: epsos5-.

Open the following directory:

> cd <Path_To_Output>/epsos5-validator-app/bin

> chmod +x validator.sh  #if on linux 

> ./validator.sh -path <Path_to_CDA.xml> -out <Path_To_output_result.xml>

For SEQUOIA with version ccda21, you need to adapt it to SVS first, and for that we have a generation script that handle all of that automatically:

> cd gazelle-objects-checker/hl7templates/hl7templates-packager-jar/target
> ./SEQUOIAGeneration.sh
# or just for adapting SVS you can use the SEQUOIASVSAdaptation.sh

Then:

> cd <Path_To_Output>/ccda21-validator-jar/target/appassembler/bin

> chmod +x validator.sh  #if on linux 

> ./validator.sh -path <Path_to_CDA.xml> -out <Path_To_output_result.xml>

Here is a summary of possible parameters for the validator:

Parameters Description Type Example is Required
-path Path to the CDA Document we want to validate Path to an XML file /home/mylap/Documents/eHDSI_CDA.xml Required
-out Path to save the generated results Path to an XML file ../../results1.xml Recommended: If not provided, output is redirected to STDOUT
-b64 Provide a path to a document in Base64 Path to an XML file /home/mylap/Documents/eHDSI_CDA_B64.xml Don't use it if you use the -path parameter
-html Generate html as output of validation Boolean VOID, parameter present ==> it's true, not present ==> it's false Not Required
-resources Full path to the resources folder (XSD schema + valueSets) Path to directory /home/mylap/resources/ Not Required

Here is an example to validate a document with normal case:

> ./validator.sh -path /home/mylap/eHDSI_CDA.xml -out ../../results1.xml

HINT If you got some errors related to the XSD Validation, you can adapt your XSD at:

cd <Path_To_Output>/epsos5-validator-app/bin/resources/valresources/xsd.<br>

If you want to test the generated validator, you can use the provided SoapUI project provided in:

gazelle-objects-checker/testing/MBValGOC-soapui-project.xml

Just import it to SoapUI and run the test cases.

9. Utility Scripts

As we saw in the previous section: Generate Validator, there is too many options to remember for generating a validator.
Therefore, that decreases the usability of the tool, so we created some utility scripts for both common generation types:

  • CDA Epsos Generation (for eHDSI)
  • CDA Basic Generation (for Sequoia Project)

/!\ You need to set $JAVA_HOME before running the script, or override it inside.

You can find the scripts directly in the target directory:

> cd gazelle-objects-checker/hl7templates/hl7templates-packager-jar/target
> ./eHDSIGeneration.sh

And just follow the instructions shown by the interactive script.

HINT: if the script doesn’t work, try:

chmod +x eHDSIGeneration.sh

And re-run it

For SEQUOIA:

> cd gazelle-objects-checker/hl7templates/hl7templates-packager-jar/target
> ./SEQUOIAGeneration.sh

10. Extras

You can find some previous made documentation here (belong the old GOC, and could probably not represent the actual version):

Next released documentation

  • Functional description of GOC

Last generated: 29 November 2021 16:35:45

Copyright 2021 IHE International