installation-guide.md

title:  Installation & usage documentation
subtitle: Instalation Guide of Gazelle Objects Checker
authors: Achraf Achkari
date: 19/10/2021

Instalation Guide of Gazelle Objects Checker

Table of Content

1. Introduction

2. Clone Project

3. Run Tests (Optional)

4. Generate Artifact

5. Prepare BBR

6. Generate Validator

7. Validate CDA

8. 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
• git

2. Clone Project

the project is not maintained by the forge anymore.
Gazelle Objects Checker has been migred to Gitlab and package under one module called gazelle-objects-checker
If you worked already with the pervious 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.0.0, the Archtypes and Hl7templates modules (with all their sub modules) 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 install of gazelle-objects-checker will be done in the Generate Artifact section.
You can skip tests if you want, but it's not recommand to do.

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 recommanded to have all tests passed before continue

GOC provide two types of tests, units tests and integration tests.
The unit tests are environement independents. 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
• Ressources 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 abreveation of Building Block Repository, a large XML file containing all the fonctional specifications, that will be used by GOC to generate OCL which is converted finally to a Java validatorrr.
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 plateform 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 recommand 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 recommanded) 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)

Alert: even if GOC is in Standalone mode, it's need to have the Archetype installed locally at Runtime

This could be improved in a future release

The Artifcat 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 /!\ to be updated after GOC Release

6. Generate Validator

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

Reminder: you need to have at least the Archetype installed as it's used at Runtime

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 persent ==> it's true, not presenet ==> 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 persent ==> it's true, not presenet ==> 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:

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] 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:

Root folder of the provided output path

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

More details about logs will be provided later.

7. 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-.
We didn't use the SEQUOIA's BBR because the validator needs a hack (access to SVS) before it could be used

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>

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	Recomanded: 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 persent ==> it's true, not presenet ==> 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

8. Extras

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

• GOC Instalation guide fo developper
• Gazelle Object Checker General Public info - GOC

Next released documentation

• Functional description of GOC
• Pepare validator for SEQUOIA
• Use interactif scripts for generation
• New Archetecture used for logging