title: Installation manual subtitle: CDA Generator author: Abderrazek BOUFAHJA function: Engineer date: 22/12/2016 toolversion: 2.1.x version: 1.03 status: approved document reference: KER3-MAN-IHE_EUROPE-CDA_GENERATOR_INSTALLATION-1_03
Here is a guide to help you installing CDAGenerator
Debian squeeze or ubuntu 12.04 64bits with an Internet access.
Database : PostGresql 9.1+
Java virtual machine : JDK 1.7
Application server : Jboss 7.2.0
It must be installed in: /usr/local/jboss7
To install those requirements you can refer to the documentation of installation of jboss : General Requirements JBOSS 7
CDAGenerator can be installed using gazelle user on your server:
checkout the sources of CDAGenerator : svn checkout https://scm.gforge.inria.fr/svn/gazelle/Maven/CDAGenerator/trunk CDAGenerator
execute on the root of the project : mvn clean install
create a database : cda-generator, in postgresql (createdb -U gazelle -EUTF8 cda-generator)
copy the ear from CDAGenerator-ear/target/CDAGenerator.ear to /usr/local/jboss7/standalone/deployment/
start your jboss
Per default the CDA generator is using the folder /opt/CDAGenerator in order to store files and to access XSD and XSL files. The tar file to be installed is located here.
mkdir /opt/CDAGenerator
cd /opt/CDAGenerator
tar zxvf cda-generator-init-files.tgz
The names of the databases are defined in the pom.xml file. Use the following commands :
su postgresql
psql
postgres=\# CREATE USER gazelle;
postgres=\# ALTER USER gazelle WITH ENCRYPTED PASSWORD 'password';
postgres=\# CREATE DATABASE "cda-generator" OWNER gazelle ENCODING UTF-8;
postgres=\# \\q
exit
To insert values you can connect to the database
psql -U gazelle cda-generator
Then copy paste the folowing script:
-- PostgreSQL database dump
--
SET statement\_timeout = 0;
SET client\_encoding = 'UTF8';
SET standard\_conforming\_strings = on;
SET check\_function\_bodies = false;
SET client\_min\_messages = warning;
SET search\_path = public, pg\_catalog;
--
-- Data for Name: cmn\_application\_preference; Type: TABLE DATA; Schema: public; Owner: gazelle
--
INSERT INTO cmn\_application\_preference VALUES (1, 'java.lang.Boolean', '', 'application\_database\_initialization\_flag', 'true');
INSERT INTO cmn\_application\_preference VALUES (2, 'java.lang.String', '', 'application\_name', 'CDAGenerator');
INSERT INTO cmn\_application\_preference VALUES (3, 'java.lang.String', '', 'application\_admin\_name', 'Eric Poiseau');
INSERT INTO cmn\_application\_preference VALUES (4, 'java.lang.String', '', 'application\_admin\_email', 'epoiseau@irisa.fr');
INSERT INTO cmn\_application\_preference VALUES (5, 'java.lang.String', '', 'application\_email\_account\_for\_history', 'epoiseau@irisa.Fr');
INSERT INTO cmn\_application\_preference VALUES (6, 'java.lang.String', '', 'application\_issue\_tracker\_url', 'jira');
INSERT INTO cmn\_application\_preference VALUES (7, 'java.lang.String', '', 'application\_gazelle\_release\_notes\_url', '[*https://gazelle.ihe.net/jira/browse/CDAGEN*](https://gazelle.ihe.net/jira/browse/CDAGEN)\#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel');
INSERT INTO cmn\_application\_preference VALUES (8, 'java.lang.String', '', 'time\_zone', 'time\_zone');
INSERT INTO cmn\_application\_preference VALUES (9, 'java.lang.String', '', 'application\_zone', 'dd');
INSERT INTO cmn\_application\_preference VALUES (10, 'java.lang.String', '', 'application\_profile', 'prod');
INSERT INTO cmn\_application\_preference VALUES (11, 'java.lang.String', '', 'application\_admin\_name', 'Eric Poiseau');
INSERT INTO cmn\_application\_preference VALUES (12, 'java.lang.String', '', 'dds\_ws\_endpoint', '[*https://gazelle.ihe.net/DDSWS/DemographicDataServerBean?wsdl*](https://gazelle.ihe.net/DDSWS/DemographicDataServerBean?wsdl)');
INSERT INTO cmn\_application\_preference VALUES (14, 'java.lang.String', '', 'schematron\_validator', '[*http://jumbo.irisa.fr:8080/SchematronValidator-SchematronValidator-ejb/GazelleObjectValidatorWS?wsdl*](http://jumbo.irisa.fr:8080/SchematronValidator-SchematronValidator-ejb/GazelleObjectValidatorWS?wsdl)');
INSERT INTO cmn\_application\_preference VALUES (15, 'java.lang.String', '', 'gazelle\_bin', '/opt/gazelle/bin');
INSERT INTO cmn\_application\_preference VALUES (16, 'java.lang.String', '', 'cda\_result\_detail', '[*https://gazelle.ihe.net/EVSClient/xsl/schematronResultStylesheet.xsl*](https://gazelle.ihe.net/EVSClient/xsl/schematronResultStylesheet.xsl)');
INSERT INTO cmn\_application\_preference VALUES (13, 'java.lang.String', '', 'xsl\_path', '[*https://gazelle.ihe.net/xsl/*](https://gazelle.ihe.net/xsl/)');
INSERT INTO cmn\_application\_preference VALUES (17, 'java.lang.String', '', 'sex\_oid', '1.3.6.1.4.1.21367.101.101');
INSERT INTO cmn\_application\_preference VALUES (18, 'java.lang.String', '', 'religion\_oid', '1.3.6.1.4.1.21367.101.122');
INSERT INTO cmn\_application\_preference VALUES (19, 'java.lang.String', '', 'race\_oid', '1.3.6.1.4.1.21367.101.102');
INSERT INTO cmn\_application\_preference VALUES (21, 'java.lang.String', '', 'application\_url', '[*https://gazelle.ihe.net/CDAGenerator*](https://gazelle.ihe.net/CDAGenerator)');
INSERT INTO cmn\_application\_preference VALUES (25, 'java.lang.String', '', 'evs\_url', '[*https://gazelle.ihe.net/EVSClient*](https://gazelle.ihe.net/EVSClient)');
INSERT INTO cmn\_application\_preference VALUES (23, 'java.lang.String', '', 'cda\_xsd', '/opt/CDAGenerator/xsd/ihe\_lab/infrastructure/cda/LabCDA.xsd');
INSERT INTO cmn\_application\_preference VALUES (24, 'java.lang.String', '', 'cdaepsos\_xsd', '/opt/CDAGenerator/xsd/cda\_epsos/CDA\_extended.xsd');
INSERT INTO cmn\_application\_preference VALUES (26, 'java.lang.String', '', 'doc\_path', '/opt/CDAGenerator/doc/');
INSERT INTO cmn\_application\_preference VALUES (22, 'java.lang.String', '', 'svs\_repository\_url', '[*https://gazelle.ihe.net*](https://gazelle.ihe.net)');
INSERT INTO cmn\_application\_preference VALUES (27, 'java.lang.String ', '', 'app\_documentation', '[*https://gazelle.ihe.net*](https://gazelle.ihe.net)');
INSERT INTO cmn\_application\_preference VALUES (31, 'java.lang.String', '', 'cdapharm\_xsd', '/opt/CDAGenerator/xsd/xsd-pharm-tiani/extendedschemas/CDA\_extended\_pharmacy.xsd');
INSERT INTO cmn\_application\_preference VALUES (35, 'java.lang.Boolean', 'Enable or Disable http security headers', 'security-policies', 'false');
INSERT INTO cmn\_application\_preference VALUES (36, 'java.lang.String', 'Sites can use this to avoid clickjacking attacks, by ensuring that their content is not embedded into other sites', 'X-Frame-Options', 'SAMEORIGIN');
INSERT INTO cmn\_application\_preference VALUES (34, 'java.lang.String', '', 'svs\_endpoint', '[*https://gazelle.ihe.net/SVSSimulator/rest/RetrieveValueSetForSimulator*](https://gazelle.ihe.net/SVSSimulator/rest/RetrieveValueSetForSimulator)');
INSERT INTO cmn\_application\_preference VALUES (37, 'java.lang.String', 'Application should return caching directives instructing browsers not to store local copies of any sensitive data.', 'Cache-Control', 'private, no-cache, no-store, must-revalidate, max-age=0');
INSERT INTO cmn\_application\_preference VALUES (38, 'java.lang.String', 'is a security feature that lets a web site tell browsers that it should only be communicated with using HTTPS, instead of using HTTP', 'Strict-Transport-Security', 'max-age=31536000 ; includeSubDomains');
INSERT INTO cmn\_application\_preference VALUES (39, 'java.lang.String', ' is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks', 'X-Content-Security-Policy', '');
INSERT INTO cmn\_application\_preference VALUES (40, 'java.lang.String', 'Chrome flag, uses X-Content-Security-Policy values', 'X-WebKit-CSP', 'Use X-Content-Security-Policy values');
INSERT INTO cmn\_application\_preference VALUES (41, 'java.lang.String', 'Chrome flag, uses X-Content-Security-Policy-Report-Only values', 'X-WebKit-CSP-Report-Only', 'Use X-Content-Security-Policy-Report-Only values');
INSERT INTO cmn\_application\_preference VALUES (42, 'java.lang.String', 'Configuring Content Security Policy involves deciding what policies you want to enforce, and then configuring them and using X-Content-Security-Policy to establish your policy.', 'X-Content-Security-Policy-Report-Only', 'default-src ''self'' \*.ihe.net www.epsos.eu; script-src ''self'' ''unsafe-eval'' ''unsafe-inline''; style-src ''self'' ''unsafe-inline'';');
INSERT INTO cmn\_application\_preference VALUES (43, 'java.lang.Boolean', 'Enable or Disable Sql Injection filter', 'sql\_injection\_filter\_switch', 'false');
INSERT INTO cmn\_application\_preference VALUES (44, 'java.lang.String', '', 'assertion\_manager\_url', '[*https://gazelle.ihe.net/AssertionManager*](https://gazelle.ihe.net/AssertionManager)');
INSERT INTO cmn\_application\_preference VALUES (45, 'java.lang.String', '', 'svs\_simulator\_restful\_url', '[*https://gazelle.ihe.net/SVSSimulator/rest/RetrieveValueSetForSimulator*](https://gazelle.ihe.net/SVSSimulator/rest/RetrieveValueSetForSimulator)');
INSERT INTO cmn\_application\_preference VALUES (29, 'java.lang.String', '', 'ip\_login\_admin', '.\*');
INSERT INTO cmn\_application\_preference VALUES (28, 'java.lang.Boolean', '', 'ip\_login', 'f');
INSERT INTO cmn\_application\_preference VALUES (48, 'java.lang.Boolean', '', 'cas\_enabled', 'true');
INSERT INTO cmn\_application\_preference VALUES (47, 'java.lang.String', '', 'application\_works\_without\_cas', 'false');
INSERT INTO cmn\_application\_preference VALUES (46, 'java.lang.String', '', 'cas\_url', '[*https://gazelle.ihe.net/cas/*](https://gazelle.ihe.net/cas/)');
INSERT INTO cmn\_application\_preference VALUES (47, 'java.lang.String', ' ', 'bbr_folder', '/opt/CDAGenerator/BBR/');
INSERT INTO cmn\_application\_preference VALUES (48, 'scorecard_root_oid', 'An OID with trailing DOT (.)', 'java.lang.String', 'The root OID for identifying scorecards');
INSERT INTO cmn\_application\_preference VALUES (49, 'scorecard_next_index', '1', 'java.lang.Integer', 'The next index to be used for identifying scorecards');
```
--
-- PostgreSQL database dump complete
--
| **variable** | **Description** | **type** | **default** |
|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------|-------------------|-------------------------------------------------------------------------------------------------------------------|
| app\_documentation | link to documentation of the tool | java.lang.String | https://gazelle.ihe.net/content/cda-model-based-validation |
| application\_admin\_email | email of the admin | java.lang.String | epoiseau@irisa.fr |
| application\_admin\_name | name of the admin | java.lang.String | Eric Poiseau |
| application\_database\_initialization\_flag | inserted by the application | java.lang.Boolean | true |
| application\_email\_account\_for\_history | email of the admin | java.lang.String | eric.poiseau@inria.fr |
| application\_gazelle\_release\_notes\_url | release notes' url | java.lang.String | https://gazelle.ihe.net/jira/browse/CDAGEN\#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel |
| application\_issue\_tracker\_url | issue tracker url | java.lang.String | jira |
| application\_name | application's name | java.lang.String | CDAGenerator |
| application\_profile | application's profile (always prod) | java.lang.String | prod |
| application\_url | application's URL | java.lang.String | https://gazelle.ihe.net/CDAGenerator |
| application\_works\_without\_cas | cas configuration | java.lang.Boolean | false |
| application\_zone | application zone | java.lang.String | GMT+1 |
| assertion\_manager\_url | link to assertion manager | java.lang.String | https://gazelle.ihe.net/AssertionManagerGui |
| Cache-Control | Application should return caching directives instructing browsers not to store local copies of any sensitive data. | java.lang.String | private, no-cache, no-store, must-revalidate, max-age=0 |
| cas\_enabled | cas configuration | java.lang.Boolean | true |
| cas\_url | cas url | java.lang.String | https://gazelle.ihe.net/cas |
| cda\_result\_detail | link to cda stylesheet result | java.lang.String | https://gazelle.ihe.net/EVSClient/xsl/schematronResultStylesheet.xsl |
| cda\_xsd | path to schema | java.lang.String | /opt/CDAGenerator/xsd/ihe\_lab/infrastructure/cda/LabCDA.xsd |
## Compile
Before compiling, go to the directory CDAGenerator and edit the file pom.xml. Open this file and adapt the properties of profile prod to your case :
* jdbc.connection.url : jdbc:postgresql:cda-generator
* jdbc.connection.user / jdbc.connection.password : credentials for database access
Then, create the EAR archive with the command line:
```bash
cd CDAGenerator
mvn clean package
The archive (EAR) and the distribution file are created and placed into CDAGenerator /CDAGenerator-ear/target directory.
Copy the CDAGenerator.ear into the "server/gazelle/deploy" directory of your JBoss server. Finally, start your server.
When the application is deployed, open a browser and go to http://yourserver/CDAGenerator.
If the deployment and the database initialization are successful you should see the home page.
The administrator is able to configure the documentation of XDS/DSUB constraints and rules
First the user shall be logged in as an administrator.
Then, go to administration -> Constraints Management -> Constraints-admin
The user shall then upload the XML file, generated from the model of contraint, info the tool using he button add from the previous page.
After the upload is ended, click on the button "Delete and Generate". This button will delete all the constraints related to packages that are mentionned into the uploaded XML file. If there are some constraints related to other packages, there will not be deleted. All the information into the XML document are inserted in the database of the tool.
This part is for administrator of CDAGenerator.
To access to the BBR configuration page you need to go to menu -> Administration -> Building Block Repository
A BBR is the export coming from ART-DECOR in HL7 Templates format. This tool allows to generate validators based on this export, and using Gazelle ObjectsChecker technology. You can find in the paragraph references, some reference to the documentation of both Gazelle ObjectsChecker and ART-DECOR.
The main idea regarding the definition of the BBRs in CDA is to compile them and to deploy them. You are able to create a new BBR using the button "Create BBR" :
You need to specify the name of your validation tool, also you need to specify the link to the BBR. You can provide the xml export as a file, and upload it, or you can provide a html link to the BBR.
Example of HTML link : https://art-decor.ihe-europe.net/decor/services/RetrieveProject?prefix=IHE-EYE-SUM-&version=&mode=verbatim&language=en-US&download=true&format=xml
The check button "Is Active?" is to expose the BBR for the validation or not.
In the table we have six buttons in the column action :
View button : Allows to view the information related to the BBR
Edit button : Edit the BBR
Delete button : Delete the BBR from the database, it does not delete the validator from the server
download button : allows to download the BBR, not the validator
Compile button : allows to compile the BBR and to create
Deploy documentation button : allows to deploy the documentation in CDAGenerator. The documentation will be seen in Constraint Documentation
We can filter BBRs using the filter part of the page :
The parameter of filtering are :
Validator name
Version : version of the validator
Create date (of the validator)
URL : if the BBR is based URL, you can filter by it
Status : the status of the BBR (inital, deployed, etc)
Building Date
Active (or not)
When a BBR is added, its name is used in the validation service in EVSClient (if it is active). The filtering of the BBR in EVSClient is based on the same principle of filtering the other validator, if the name of the BBR contains a word coming from the referenced standard in EVSClient, it is proposed as a validator by CDAGenerator
Here is the process in the background for a user, how CDAGenerator works :
The workflow for the Administrator is described by this sequence diagram :
When you click on the button validate the application execute in the server the generation of the validation tool based on the BBR uploaded on the tool, and use for this the generation tool described in the application preference value 'bbr_folder'. As default this preference has the value /opt/CDAGenerator/BBR. The architecture of this folder is described like this :
BBR
├── generatedValidators
│ ├── archives
│ │ ├── 1
│ │ │ ├── iheeyegeecn-validator-app-0.0.1-SNAPSHOT-1.zip
│ │ ├── 2
│ │ └── ccdaadr11-validator-app-2.zip
│ ├── execs
│ ├── 1
│ ├── bin
│ │ ├── resources
│ │ ├── validator.bat
│ │ └── validator.sh
│ ├── documentation
│ │ └── iheeyegeecn-constraint.xml
│ └── repo
└── generator
├── hl7templates-packager-app
├── generateValidator.sh
├── packager
│ ├── bin
│ │ ├── generator.bat
│ │ └── generator.sh
│ └── repo
│ ├── list jars
└── version.txt
generatedValidators folder contains the list of generated validation tools. It contains two sub folder : exec and archive. The exec folder contains the current executable used for the validation. The archive folder contains the list of zip generated through the tool. Whe you click on the button compiling from the BBR page manager, you create a zip file archived in archive folder, and unzipped in exec folder. The folder generator contains the generator used to generate the validators based on the BBR URL. this generator can be used outside the CDAGenerator tool, also the generated validators can be used outside the CDAGenerator tool, as a standalone validation tool.
The generated validators contains three main folders : bin, repo and documentation. bin folder contains an executable : validator.sh and validator.bat. This executable is used by CDAGenerator during the validation of CDA documents. repo folder contains a list of jars used by the validator.sh, and documentation folder contains a the documentation that needs to be deployed in CDAGenerator, in XML format.
The validators describer is a link between the documentation and the validators. This allows to have an architecture of the validators.
To access to this page you need to go to menu -> Administration -> Validators Packages
This page is for the administrator of the tool. It represents an association between validators and packages of documentation. For each association we have and id, the validator name, the list of the validators parents, and the list of packages list related to the validator. The complete list of package related to a validator is the composition of the direct related packages list, and the sum of all the packages list related to the parent validators. You can create a new validator association by clicking on the button "Create Validator association".
The action column contains three button : view, edit and delete. The edit page looks like this :
The view page for the ValidatorDescriber looks like this :
The validatorDescriber is used by CDAGenerator for the scoring of the validation results.