--- 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](#introduction) 2. ##### [Clone Project](#cloneProject) 3. ##### [Run Tests (Optional)](#runTests) 4. ##### [Generate Artifact](#generateArtifact) 5. ##### [Prepare BBR](#prepareBBR) 6. ##### [Generate Validator](#generateValidator) 7. ##### [Validate CDA](#validateCDA) 8. ##### [Extras](#extra) <div id='introduction'/> ## 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 <div id='cloneProject'/> ## 2. Clone Project the project is not maintained by the _forge_ anymore.<br> Gazelle Objects Checker has been migred to **[Gitlab](https://gitlab.inria.fr)** and package under one module called **gazelle-objects-checker**<br> 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` <br> The resources models are packaged in a module called `UML Models`. <table> <thead> <th>Project</th> <th>Link Gitlab</th> </thead> <tr> <td>Gazelle Objects Checker</td> <td><a href="https://gitlab.inria.fr/gazelle/library/gazelle-objects-checker">https://gitlab.inria.fr/gazelle/library/gazelle-objects-checker</a></td> </tr> <tr> <td>UML Models</td> <td><a href="https://gitlab.inria.fr/gazelle/library/uml-models">https://gitlab.inria.fr/gazelle/library/uml-models</a></td> </tr> </table> <br> ##### Cloning gazelle-objects-checker: you need to have `git` and `maven` installed<br><br> Run the following command: ```bash > 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](#generateArtifact) section.<br> 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 <div id='runTests'/> ## 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.<br> 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](https://gazelle.ihe.net/nexus/#nexus-search;quick~uml-models)) <br> **Run Unit tests** ```bash > cd gazelle-objects-checker > mvn test ``` **Run Integration Tests** ```bash > 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_ <div id='prepareBBR'/> ## 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.<br> 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.<br> 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](https://gazellecontent.sequoiaproject.org/apps/decor/services/RetrieveProject) Choose project as _**(BBR) Consolidated CDA (en-US)**_.<br> Make sure to select the **_Compiled_** version. <br> Then check the **_Download_** radio.<br> Press **_send_** button.<br> Once you download it, you need to adapt it before using it in the next section of generation.<br> 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 <div id='generateArtifacts'/> ## 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. <br> The Artifact generated is a `.jar` suffixed by `jar-with-dependencies` as it's created as a **standalone** application. <br><br> To do we run the following command: ```bash > 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: > > ```bash > 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 <div id='generateValidator'/> ## 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: <table> <thead> <th>Parameters</th> <th>Description</th> <th>Type</th> <th>Example</th> <th>is Required</th> </thead> <tr> <td>-bbr</td> <td>Path to the BBR file (provided by ART-DECOR)</td> <td>XML File</td> <td>/home/mylap/Documents/bbr-eHDSI-5.0.1.xml</td> <td><b>Required</b></td> </tr> <tr> <td>-out</td> <td>Path where to generate the validator</td> <td>Directory</td> <td>/home/mylap/Documents/CDA-Validators/output-pivot-19-10-2021</td> <td><b>Required</b></td> </tr> <tr> <td>-mvn</td> <td>Path to maven <b>binary</b></td> <td>Binary (executable)</td> <td>/opt/apache-maven-3.5.4/bin/mvn</td> <td><b>Required</b></td> </tr> <tr> <td>-serviceName</td> <td>Validation Service Name</td> <td>String</td> <td>Pivot</td> <td>not Required</td> </tr> <tr> <td>-HL7TEMP_CDACONFFOLDERNAME </td> <td>HL7template CDA config folder name</td> <td>cdabasic or cdaepsos</td> <td>cdaepsos</td> <td>not Required (default=cdabasic)</td> </tr> <tr> <td>-ignoreTemplateIdRequirements</td> <td>ignore TemplateId Requirements when generating the constraints (useful for C-CDA validation tools) name</td> <td>Boolean</td> <td>VOID, parameter persent ==> it's true, not presenet ==> it's false</td> <td>not Required (default=false [Not present])</td> </tr> <tr> <td>-ignoreCdaBasicRequirements</td> <td>ignore TemplateId Requirements when generating the constraints (useful for C-CDA validation tools) name</td> <td>Boolean</td> <td>VOID, parameter persent ==> it's true, not presenet ==> it's false</td> <td>not Required (default=false [Not present])</td> </tr> <tr> <td>-versionLabel</td> <td>VersionLabel that will be used during the generation</td> <td>String</td> <td>2.1</td> <td>not Required</td> </tr> <tr> <td>-rootClassName</td> <td><i>DEPRECATED:</i>Root class name of generated classes</td> <td>Path to java class (see example)</td> <td>net.ihe.gazelle.cdaepsos3.POCDMT000040ClinicalDocument</td> <td>not Required</td> </tr> <tr> <td>-HL7TEMP_RESOURCES_PATH</td> <td><i>DEPRECATED</i>: Path to hl7templates resources folder</td> <td>String</td> <td>/home/mylap/Documents/hl7templates-resources</td> <td>not Required</td> </tr> </table> Move to the hl7templates-packager-jar/target directory and run the following command with java 11: Generic command with all possible parameters: <br> ```bash > 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: ```bash > 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. <div id='validateCDA'/> ## 7. Validate CDA Now we are going to use the generated validator.<br> We will suppose we generated a validator with a BBR containing the following version: epsos5-.<br> _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: ```bash > 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: <table> <thead> <th>Parameters</th> <th>Description</th> <th>Type</th> <th>Example</th> <th>is Required</th> </thead> <tr> <td>-path</td> <td>Path to the CDA Document we want to validate</td> <td>Path to an XML file</td> <td>/home/mylap/Documents/eHDSI_CDA.xml</td> <td><b>Required</b></td> </tr> <tr> <td>-out</td> <td>Path to save the generated results</td> <td>Path to an XML file</td> <td>../../results1.xml</td> <td><b>Recomanded: </b>If not provided, output is redirected to STDOUT</td> </tr> <tr> <td>-b64</td> <td>Provide a path to a document in Base64</td> <td>Path to an XML file</td> <td>/home/mylap/Documents/eHDSI_CDA_B64.xml</td> <td>Don't use it if you use the -path parameter</td> </tr> <tr> <td>-html</td> <td>Generate html as output of validation</td> <td>Boolean</td> <td>VOID, parameter persent ==> it's true, not presenet ==> it's false</td> <td>Not Required</td> </tr> <tr> <td>-resources</td> <td>Full path to the resources folder (XSD schema + valueSets) </td> <td>Path to directory</td> <td>/home/mylap/resources/</td> <td>Not Required</td> </tr> </table> Here is an example to validate a document with normal case: ```bash > ./validator.sh -path /home/mylap/eHDSI_CDA.xml -out ../../results1.xml ``` <div id='extra'/> ## 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](https://docs.google.com/document/d/1G5bmLhFKNjOvg_rxEllidTofYrwxBeZG_kigTM0pqXM/edit?usp=sharing) - [Gazelle Object Checker General Public info - GOC](https://docs.google.com/document/d/1265YcvKk983Fna2Y8TI6V9O1wnKqERFAibIlVGYgW20/edit?usp=sharing) #### Next released documentation - Functional description of GOC - Pepare validator for SEQUOIA - Use interactif scripts for generation - New Archetecture used for logging