Mentions légales du service

Skip to content
Snippets Groups Projects
Commit 9704469d authored by Achraf Achkari's avatar Achraf Achkari
Browse files

Update Docs

parent 3cab1673
No related branches found
No related tags found
1 merge request!15Release 3.0.2
Hide whitespace changes
Inline Side-by-side
docs/installation-guide.md
+ 83
− 66
View file @ 9704469d
---
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
![Logs Conception](Improved_Logging_Conception_v2.jpg "LogsConception")
![Logs Conception](media/Improved_Logging_Conception_v2.jpg "LogsConception")
<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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment