| Section | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||
|
1. Setup
...
application server
The software components are able to run on all Java application servers, we recommend you to install them at an Apache Tomcat instance.
...
To perform the installation of the server you may also follow this instructions: http://tomcat.apache.org/tomcat-7.0-doc/setup.html (For Apache Tomcat 7.0)
2. Obtain artifacts
In order to install OpenNCP, you must obtain the following artifacts (Please use the last versions for each component):
...
You need to define JNDI DataSources to the Apache Tomcat configuration. This is done to the conf/context.xml file. Here is an example file of Tomcat 6.0 context.xml.
For more background information and configuration tips on the JNDI please refer to this JIRA:
| Jira Legacy | ||||
|---|---|---|---|---|
|
2. Obtain artifacts
In order to install OpenNCP, you must obtain the following artifacts (Please use the last versions for each component):
- TRC-STS (War): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos.TRC-trc-STSsts/
- TSL-Sync (War): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-tslutils/epsos-tsl-sync/
- TSAM-Sync (Jar): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-tsam-sync/
- Server Side - NCP-A (War): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-protocol-terminators/epsos-ncp-server/epsos-ws-server/
- Client Side - NCP-B (War): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-protocol-terminators/epsos-ncp-client/epsos-client-connector/
- OpenATNA (JarWar): httphttps://codejoinup.ec.googleeuropa.comeu/nexus/p/epsos-common-components/source/checkout?repo=openatna (OpenNCP custom version)content/repositories/releases/eu/europa/ec/joinup/ecc/epsos-openatna/openatna-web/
- Portal (War): https://joinup.ec.europa.eu/nexus/content/repositories/releases/eu/europa/ec/joinup/ecc/openncp-portal/
3. Adjust configuration parameters
First, to hold all your configuration files, you can first start to create a folder and name it "epsos-configuration" for instance. (You can take a quick look at the last step of the guide to see a recommended folder structure for the NCP)
...
Next, you may download and unzip the content from the following file to the newly created folder.
| Attachments | ||||||
|---|---|---|---|---|---|---|
|
Folder content:
| Code Block |
|---|
/epsos-configuration |-- /audit-backup |-- /ATNA_resources |-- /EADC_resources |-- /TM_resources |-- configmanager.hibernate.xml |-- eadc-ds.xml |-- pn-oid.xml |-- ISO_3166-1.xml |-- tm.properties +-- tsam.properties |
| Tip |
|---|
All the provided files will be used and configured in this manual. At this step you need to add entries to your country at pn-oid.xml and ISO_3166-1.xml |
3.1 Configuration Manager Database
In order to hold the biggest part of your NCP configuration properties (i.e. countries endpoints, truststore locations, and others) you will need to create a database and an hibernate configuration file.
To do that, you may follow the "Setup" section, available at Configuration Manager.
(If you already have an existent setup with the old configuration files - epsos.properties and others - you can also follow the "How To Migrate" section. If you are doing a fresh install please ignore this line.)
3.2 NCP First-Time Configuration Utility
To help you on the process of setting up you NCP, you can use a special utility to populate your database with the basic required parameters, related to your scenario.
...
Once you have run the utility with success, you may delete the properties file, the jar and check if the database was correctly filled, using the appropriate database admin tool.
4. Install and setup components
...
3.3 Create Certificates
You can find more details on how to create and the epsos certificates here
4. Install and setup components
4.1 TRC-STS
The main purpose of this component it to generate and return security assertions on demand. It is a war application that will run also on your Application Server instance.
...
After that, you can check the property "secman.sts.url" at your ncp properties database to see if it matches the installed application URL.
4.2 TSL-Sync
This component will connect to the central services and fetch all the other countries configuration elements (such as endpoints) to your local properties database, together with all the certificates.
...
| Tip |
|---|
This tool will execute every 5 seconds, you can adjust this time by editing this file, present at the deploy dir: <application server root>/webapps/epsos-tsl-sync/WEB-INF/classes/quartz_data.xml |
From the 2.8.9 version the tsl-sync utility can be run also from the command line. You can see more here TSLSync Home
4.3 TSAM-Sync
The TSAM-Sync component will connect to HealthTerm repository to fetch your country terminologies and load them in your LTR database.
This application is a standalone jar that can be placed in custom location, together with a required group of folders.
For instance:
| Code Block |
|---|
tam-sync-custom-location |-- conf | |-- epsos.properties | |-- hibernate.cfg.xml | |-- log4j.xml | |-- logging.properties | +-- settings.properties |-- lib | +-- jdbc-connector.jar |-- tsam-sync.jar +-- sync.sh |
...
When you have set up the folder structure you should download the jar from the repository mentioned in step 2 and place it at the folder root - also you may adjust the sync.sh script to match the jar name.
| Tip |
|---|
If you do not have the LTR database already, you can just create it in the same way you create the properties database. Then adjust the TSAM-Sync configuration, present in the conf folder and run the jar. It will create your tables and fill the database with the terminologies. |
You can download the folder contents here:
| Attachments | ||||||
|---|---|---|---|---|---|---|
|
4.4 Transformation Syncronization Access Manager (TSAM)
In order to TSAM work properly, you should setup the tsam.properties file, already provided and located under your EPSOS_PROPS_PATH. You can find an example bellow:
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
########################################################################################### # # # # # TSAM configuration # # # # # ########################################################################################### ############################################################################### Languages # ##Code of a language, which country B uses for designations in pivot documents created in ##translation (local language of a country) translationLanguage=pt-PT ##Code of a language, which country A uses for designations in pivot documents created in ##transcoding (epSOS defines it as English) transcodingLanguage=en ########################################################################### Datbase Setup # ## MySQL DB URL ltr.dbhibernate.url=jdbc:mysql://hostaddress:3306/tsam?useUnicode=true&characterEncoding=UTF-8 ## DB Credentials ltr.db.user=username ltr.db.password=password ## Driver Setup ltr.hibernate.dialect=org.hibernate.dialect.MySQL5Dialect ltr.db.driverClass=com.mysql.jdbc.Driverdialect=org.hibernate.dialect.MySQL5Dialect ltr.hibernate.connection.datasource=java:comp/env/jdbc/TSAM |
Give special importance to:
...
Database Setup (you will need to fill these parameters according to the database you created in step 4.4)
- ltr.db.url: will hold the link to the database system, where the LTR database will be placed:
- ltr.db.user: the database username;
- ltr.db.password: the database password;
- ltr.hibernate.dialect: the dialect used for DB connections;ltr.db.driverClass: the driver class used to establish the connection;
| Note |
|---|
After setting up your config file for TSAM, please add the required library for DB connection, at server lib folder. |
4.5 Transformation Manager (TM)
Also for TM work properly, you should setup the tm.properties file, also provided and located under your EPSOS_PROPS_PATH.
...
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
########################################################################################### # # # # # TM configuration # # # # # ########################################################################################### ############################################################## Element List Configuration # ##Flag# indicatingcoded thatelement for identification of coded elements configurable list of ##elements should be used. tm.configurableelementidentification=false ## Coded Element Processing processing tm.configurableelementidentification=true tm.codedelementlist.enabled=falsetrue ### Actualactual path to coded_element_list.xml file tm.codedelementlistpathcodedelementlist.path=TM_resources/coded_element_list_epSOS2.xml ########################################################### Basic CDA Schema Configuration # ### Actualactual path to schema file tm.schemafilepath=TM_resources/schema/CDA_extended.xsd ### Schemaschema validation enabled tm.schema.validation.enabled=true ################################################################# Schematron Configuration # ### Actualactual path to patienSummary Schematron file tm.schematron.path.patientsummary=TM_resources/schematron/PatientSummary.sch ### Actualactual path to ePrescription Schematron file tm.schematron.path.eprescription=TM_resources/schematron/ePrescription.sch ### Actualactual path to eDispensation Schematron file tm.schematron.path.edispensation=TM_resources/schematron/eDispensation.sch ### Actualactual path to schematron XSL directory tm.schematron.path.xsldir=TM_resources/xsl ##### Schematron validation enabledNEW PROPERTIES # actual path to patientSummaryFriendly Schematron file tm.schematron.path.validationpatientsummary.enabled=false ################################################################ Document Type epSOS Codesfriendly=TM_resources/schematron/epSOS-PatientSummary-Friendly.sch # ##actual epSospath codeto forePrescriptionFriendly patientSchematron summary CDA document tm.documenttype.patientsummary=60591-5 ## epSos code for ePrescription CDA document tm.documenttype.eprescription=57833-6 ## epSos code for eDispensation CDA document tm.documenttype.edispensation=60593-1 ################################################################## Audit Trail Configuration # ## Audit Trail enabled/disabled tm.audittrail.enabled=false ## Audit Trail Event Log - The number of transaction including the epsos- prefix tm.audittrail.transactionnumber=epsos-94 ## Audit Trail Event Log - The IP Address of the target Gateway tm.audittrail.targetip= ## Audit Trail Audit Service - The facility number according to log4j tm.audittrail.facility=13 ## Audit Trail Audit Service - The severity of the message tm.audittrail.severity=2 |
4.6 Automatic Data Collector (eADC)
To setup and install the Automatic Data Collector you can follow the instructions present on the following page:
4.7 Audit Repository (OpenATNA)
In order to install and setup the OpenATNA you may download and build the OpenNCP custom version, following the link presented in step 2.
...
file
tm.schematron.path.eprescription.friendly=TM_resources/schematron/epSOS-ePrescription-Friendly.sch
# actual path to eDispensationFriendly Schematron file
tm.schematron.path.edispensation.friendly=TM_resources/schematron/epSOS-eDispensation-Friendly.sch
# actual path to patienSummaryPivot Schematron file
tm.schematron.path.patientsummary.pivot=TM_resources/schematron/epSOS-PatientSummary-Pivot.sch
# actual path to ePrescriptionPivot Schematron file
tm.schematron.path.eprescription.pivot=TM_resources/schematron/epSOS-ePrescription-Pivot.sch
# actual path to eDispensationPivot Schematron file
tm.schematron.path.edispensation.pivot=TM_resources/schematron/epSOS-eDispensation-Pivot.sch
tm.schematron.path.scannedDocument.friendly=.
tm.schematron.path.scannedDocument.pivot=.
tm.mda.validation.enabled=false
tm.mda.cda_xsd_path=TM_resources/validator_res/xsd/CDA.xsd
tm.mda.cda_epsos_xsd_path=TM_resources/validator_res/xsd/CDA_extended.xsd
tm.mda.cda_xsl_transformer_path=TM_resources/validator_res/mbvalidatorDetailedResult.xsl
tm.mda.value_set_repository_path=TM_resources/validator_res/valueSets/
### END NEW PROPERTIES
# schematron validation enabled
tm.schematron.validation.enabled=false
################################################################ Document Type epSOS Codes #
# epSos code for patient summary CDA document
tm.documenttype.patientsummary=60591-5
# epSos code for ePrescription CDA document
tm.documenttype.eprescription=57833-6
# epSos code for eDispensation CDA document
tm.documenttype.edispensation=60593-1
################################################################## Audit Trail Configuration #
# Audit Trail enabled/disabled
tm.audittrail.enabled=false
# Audit Trail Event Log - The number of transaction including the epsos- prefix
tm.audittrail.transactionnumber=epsos-94
# Audit Trail Event Log - The IP Address of the target Gateway
tm.audittrail.targetip=
# Audit Trail Audit Service - The facility number according to log4j
tm.audittrail.facility=13
# Audit Trail Audit Service - The severity of the message
tm.audittrail.severity=2
|
4.6 Automatic Data Collector (eADC)
To setup and install the Automatic Data Collector you can follow the instructions present on the following page:
4.7 Audit Repository (OpenATNA)
In order to install and setup the OpenATNA you may download and build the OpenNCP custom version, following the link presented in step 2.
Then to perform the installation of the generated artifacts, you may follow the official instructions, available at: https://www.projects.openhealthtools.org/sf/go/page1071
You can also this this tutorial OpenATNA Home
You should add this line to the TOMCAT startup.sh script:
| Code Block | ||
|---|---|---|
| ||
JAVA_OPTS="-DopenATNA.properties.path=file:$EPSOS_PROPS_PATH/ATNA_resources/openatna.properties $JAVA_OPTS" |
Tips for OpenNCP installation:
- TLS configuration: parameters in section arr-tls of file conf/ArrConnections.xml have to reflect the values of epsos.properties: HostName -> audit.repository.url and Port (default: 2862) -> audit.repository.port (default: 6514)
- Certificates: copy your ServiceProvider.jks and ServiceConsumer.jks certificates into conf/certs and refer to them in conf/ArrConnections.xml (KeyStore --> ServiceProvider.jks and TrustStore --> ServiceConsumer.jks)
- If you want to use the logviewer war, you have to add the openatna.properties files to atna.war/WEB-INF/classes
- If you want to use the logviewer war with MySQL, you have to add the jdbc-connector.jar to atna.war/WEB-INF/lib
- You also may need to extend the MaxPermSize of your Tomcat instance (adding -XX:MaxPermSize=256m to you CATALINA_OPTS)
4.8 Server Side (NCP-A)
At this moment you probably have all the configurations finished and correctly adjusted. So in order to install the Server Side (NCP-A) you will need to obtain the artifact named epsos-ws-server-X.X:X.war, as explained in Step 2.
It is advised to rename the file to simply epsos-ws-server.war, then you should deploy it on your Tomcat instance. (To deploy the application you may follow this instructions: http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html for Tomcat 7).
In case you change the default port, you have to modify the WEB-INF/conf/tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html for Tomcat 7axis2.xml file to reflect the change (default: port 8080 / 8443).
4.9 Client Side (NCP-B)
For client side it is used the same approach used in Server side. You should download the artifact named: epsos-client-connector-X.X.X.war, as explained in Step 2.
It is also advised to rename the file to just epsos-client-connector.war, then you should deploy it on your Tomcat instance. (To deploy the application you may follow this instructions: http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html for Tomcat 77).
In case you change the default port, you have to modify the WEB-INF/conf/axis2.xml file to reflect the change (default: port 8080 / 8443).
4.10 OpenNCP Portal or epSOS-Web
4.10.1 OpenNCP Portal
To install the OpenNCP portal, you may follow the provided instructions, available at:
Installing Liferay OpenNCP Portal
4.10.2 epSOS-Web
5. Database Logging
You can see how to setup database logging for several components in the following link: How to configure Database Appender for logging purposes to OpenNCP
6. Final Considerations
After performing the installation of all components you may end with this sample folder setup (considering that we placed all the files under the /opt folder)
| Code Block |
|---|
/opt |-- /apache-tomcat-7.X.XX | |-- /bin | |+-- /conf | |-- context.xml | |-- /logs | |-- /temp | |-- /work | +-- /webapps | |-- /epsos-client-connector | |-- /epsos-ws-server | |-- /epsos-tsl-sync | |-- /TRC-STS | +-- /atna |-- /tsam-sync | |-- /conf | | |-- epsos.properties | | |-- hibernate.cfg.xml | | |-- log4j.xml | | |-- logging.properties | | +-- settings.properties | |-- /lib | | +-- jdbc-connector.jar | |-- tsam-sync.jar | +-- sync.sh +-- /epsos-configuration |-- /EADCATNA_resources |-- /TMEADC_resources |-- configmanager.hibernate.xml/TM_resources |-- eadc-dsconfigmanager.hibernate.xml |-- pn-oid.xml |-- ISO_3166-1.xml |-- tm.properties +-- tsam.properties |
...