diff --git a/docs/installation-guide.md b/docs/installation-guide.md index 1669b2b9b6d3d011cb1f65e09e68a4fd550daa2c..7111cbe38d6994931eee66a97ab5eccb2be1edc6 100644 --- a/docs/installation-guide.md +++ b/docs/installation-guide.md @@ -1,11 +1,11 @@ --- -title: Installation & usage documentation -subtitle: Instalation Guide of Gazelle Objects Checker +title: Installation & user manual +subtitle: Installation Guide of Gazelle Objects Checker authors: Achraf Achkari date: 19/10/2021 --- -# Instalation Guide of Gazelle Objects Checker +# Installation Guide of Gazelle Objects Checker ### Table of Content 1. ##### [Introduction](#introduction) @@ -16,24 +16,27 @@ date: 19/10/2021 6. ##### [Generate Validator](#generateValidator) 7. ##### [Generation Validator form UML (Alternative)](#generateValidatorFromUML) 8. ##### [Validate CDA](#validateCDA) -9. ##### [Extras](#extra) +9. ##### [Utility Scripts](#utilityScripts) +10. ##### [Extras](#extras) <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 +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 **5.x.x** /!\ You need to respect this version, or the tool won't wokr -- git +- 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 + <div id='cloneProject'/> -## 2. Clone Project +## 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: +Gazelle Objects Checker has been migrated to **[Gitlab](https://gitlab.inria.fr)** and packaged under one module called **gazelle-objects-checker**<br> +If you worked already with the previous versions of GOC, the following structure could be familiar to you: - Archetypes - generated-validator - Hl7templates @@ -52,8 +55,8 @@ If you worked already with the pervious versions of GOC, the following structure - 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`. +In the current version `3.x.x`, the `Archtypes` and `Hl7templates` modules _(with all their submodules)_ are packaged in one module `Gazelle Objects Checker` <br> +The resources models are packaged in a module called `UML Models`. <table> <thead> @@ -81,9 +84,9 @@ Run the following command: > 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. -> +> Notice: the installation 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 recommend. +> > You don't have to install the `uml-models` module, it's already released @@ -93,10 +96,10 @@ You can skip tests if you want, but it's not recommand to do. ## 3. Run Tests (Optional) -_/!\ You can skip this section, but it's recommanded to have all tests passed before continue_ +_/!\ You can skip this section, but it's recommended 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_. +GOC provides two types of tests, unit tests and integration tests.<br> +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](https://gazelle.ihe.net/nexus/#nexus-search;quick~uml-models)) <br> **Run Unit tests** @@ -115,7 +118,7 @@ The integration tests create some temporary resources (UML Models) using the `um If Something went wrong, make sure you have mentioned in maven logs: - Resources created successfully -- Ressources deleted 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_ @@ -123,24 +126,24 @@ If not, try to run the creation resources script `CreateResourcesForTest.java` i <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> +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.<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> +Each client provide his own BBR, and we can retrieve it from the ART-DECOR platform 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> +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 )_ +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 '.') @@ -150,7 +153,7 @@ 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. +After having all tests working _(not mandatory but recommended)_ 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> @@ -158,36 +161,34 @@ To do we run the following command: ```bash > mvn clean install or -> mvn clean install -DskipTests=true (to skip tests) +> 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 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: -> +> > ```bash > cd gazelle-objects-checker/archetype/generated-validator > > mvn clean install > ``` -> +> > And retrieve GOC Artifact from nexus. -> -> here: [GOC Artifact Nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~gazelle-objects-checker) +> +> here: [GOC Artifact Nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~hl7templates-packager) +> Choose the latest version, and download the: **hl7templates-packager-jar-X.X.X-jar-with-dependencies.jar** artifact <div id='generateValidator'/> ## 6. Generate Validator -This section remains to **run** Gazelle Objects Checker and generate the CDA MBval 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: +we will need the following parameters to run GOC and generate the validator: <table> <thead> <th>Parameters</th> @@ -235,14 +236,14 @@ we will need the following parameters to run GOC and generate the validator: <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>VOID, parameter present ==> it's true, not present ==> 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>VOID, parameter present ==> it's true, not present ==> it's false</td> <td>not Required (default=false [Not present])</td> </tr> <tr> @@ -282,7 +283,7 @@ Generic command with all possible parameters: <br> [-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._ +_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: ```bash @@ -294,22 +295,22 @@ Example with SEQUOIA: **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 follow:** +**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 Stanrd Output of executed commands during generation (maven command to init project with archetype, generate code from OLC, packaging...) -- **cdeModelsErros.txt:** contains all detected inconsetencies between the provided BBR and pre-defined models used by GOC +- **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 - + <div id='generateValidatorFromUML' /> -## 7. Generate Validator from UML (Alternative) +## 7. Generate Validator from UML (Alternative) -This section is just an alternative way to regenerate the validator when the functional specifications changes +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. ```bash @@ -321,11 +322,11 @@ for example for epsos5 > cd /home/mylap/Documents/GOC-OUTPUT/epsos5-validator-jar/model/epsos5.uml ``` -Then you can edit it with a Text Edito, or a dedicated modeling tool (ex: Topcased). +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: +Go to GOC-OUTPUT/epsos5-validator-jar and do the following: ```bash > cd /home/mylap/Documents/GOC-OUTPUT/epsos5-validator-jar > mvn exec:exec@generateValidator -DmvnPath="/opt/apache-maven-3.5.4/bin/mvn" -DcdaProps="cdaepsos" -DprojectName="epsos5" @@ -339,14 +340,14 @@ The generic form of the command is: ``` Your validator will be available at: GOC-OUTPUT/epsos5-validator-jar/target/appassembler/bin -and do the following: +and do the following: ```bash > cd /home/mylap/Documents/GOC-OUTPUT/epsos5-validator-jar/target/appassembler/bin > chmod +x validator.sh ``` -Now you can refere to [Section 8](#validateCDA) to Validate a CDA document with your new validator. +Now you can refer to [Section 8](#validateCDA) to Validate a CDA document with your new validator. @@ -390,7 +391,7 @@ Here is a summary of possible parameters for the validator: <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> + <td><b>Recommended: </b>If not provided, output is redirected to STDOUT</td> </tr> <tr> <td>-b64</td> @@ -403,7 +404,7 @@ Here is a summary of possible parameters for the validator: <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>VOID, parameter present ==> it's true, not present ==> it's false</td> <td>Not Required</td> </tr> <tr> @@ -416,29 +417,37 @@ Here is a summary of possible parameters for the validator: </table> -Here is an example to validate a document with normal case: +Here is an example to validate a document with normal case: ```bash > ./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: -<Path_To_Output>/epsos5-validator-app/bin/resources/valresources/xsd +If you got some errors related to the XSD Validation, you can adapt your XSD at:<br> +```bash +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: -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 +> gazelle-objects-checker/testing/MBValGOC-soapui-project.xml Just import it to SoapUI and run the test cases. + + <div id='utilityScripts'/> + ## 9. Utility Scripts As we saw in the previous section: [Generate Validator](#generateValidator), there is too many options to remember for generating a validator.<br> -Therefore, that decreases the usability of the tool, so we created some utility scripts for both common generation types: +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) /!\ not complete yet due to the needed hack +- 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: @@ -448,23 +457,31 @@ You can find the scripts directly in the **target** directory: ``` And just follow the instructions shown by the interactive script. ->HINT: if the script doesn't work, try: +>HINT: if the script doesn't work, try: > ```bash > chmod +x eHDSIGeneration.sh > ``` > **And re-run it** -<div id='extra'/> +For SEQUOIA: +```bash +> cd gazelle-objects-checker/hl7templates/hl7templates-packager-jar/target +> ./SEQUOIAGeneration.sh +``` + + +<div id='extras'/> + ## 10. 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) +You can find some previous made documentation here _(belong the old GOC, and could probably not represent the actual version)_: +- [GOC Installation guide for developers](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 +- Prepare validator for SEQUOIA +- Use interactive scripts for generation