The main goal of this page is to provide an installation manual for new OpenNCP adopters.

It tries to cover all possible setup and configuration operations and it can be used not only as a step-by-step guide but also as a supporting guide to install a certain component - you can check the table of contents on the right side of the page.

Please feel free to leave suggestions or expose your doubts at the bottom of the page.

Table of contents:

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.

You can download it at http://tomcat.apache.org/ and you may use the most recent version.

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)

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:

Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

2. Obtain artifacts

In order to install OpenNCP, you must obtain the following artifacts (Please use the last versions for each component):

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)

Then you will need to associate the folder location to a environment variable, called EPSOS_PROPS_PATH, you can do it with the following command:

export EPSOS_PROPS_PATH=/opt/epsos-configuration/

For more information about environment variables, you can check: https://help.ubuntu.com/community/EnvironmentVariables for Ubuntu, but that can be applicable to other distros.

Next, you may download and unzip the content from the following file to the newly created folder.

	File	Modified
Labels No labels Preview View	ZIP Archive epsos-configuration.zip	Sept 12, 2013 by Ivo Pinheiro

Folder content:

/epsos-configuration
|-- /audit-backup
|-- /ATNA_resources
|-- /EADC_resources
|-- /TM_resources
|-- configmanager.hibernate.xml
|-- pn-oid.xml
|-- ISO_3166-1.xml
|-- tm.properties
+-- tsam.properties

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.

To do that you just need to fill a provided unfilled properties file, according to your scenario and execute the utility Jar.

You must have your EPSOS_PROPS_PATH defined and the properties database (with no tables) already created, before using this utility.

You can download the utility, together with the properties file here:

	File	Modified
Labels No labels Preview View	ZIP Archive OpenNCP-configuration-utility.zip OpenNCP first-time configuration utility	Jan 30, 2013 by Marcelo Fonseca

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.

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.

In order to install it, you will need to obtain the artifact, named epsos-TRC-STS-X.X.X.war, then it is advised to rename it to just TRC-STS.war.

Next you can just deploy it in your Application Server instance. You can follow this instructions for Tomcat 7: http://tomcat.apache.org/tomcat-7.0-doc/deployer-howto.html

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.

Before running this component, make sure that you already have your trust store and key store already created (under your EPSOS_PROPS_PATH, i.e: $EPSOS_PROPS_PATH/cert), together with their passwords and alias.

In order to install this component, you need to download the war file, following the link in step 2 and deploy it to your server.

Then, according to you configuration. present in the properties database, it will fetch all the central services informations and sync them to your key stores and properties database.

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:

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

The conf folder will contain several configuration files that you need to adjust to your scenario. Please pay special attention to:

hibernate.cfg.xml: where you will place your database configuration
settings.properties: where you will define your credentials to access HealthTerm servers

The lib folder will contain your JDBC drivers.

In the root folder you will find sync.sh, which is a script to help you pass the required parameters to the jar execution.

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.

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:

	File	Modified
Labels No labels Preview View	ZIP Archive tsam-sync-folder.zip This file contains the folder content and structure for TSAM-Sync	Jan 30, 2013 by Marcelo Fonseca

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:

tsam.properties Configuration File

###########################################################################################
#                                                                              			  #
#                                                                              		  	  #
# 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 #
##
ltr.hibernate.dialect=org.hibernate.dialect.MySQL5Dialect
ltr.hibernate.connection.datasource=java:comp/env/jdbc/TSAM

Give special importance to:

Languages

translationLanguage: here you will place your country language;
transcodingLanguage: this property will hold the country A language, defined as "en" in epSOS;

Database Setup (you will need to fill these parameters according to the database you created in step 4.4)

ltr.hibernate.dialect: the dialect used for DB connections;

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.

It probably will suit your needs with the default values, but you can always take a look at it.

You can find an example bellow:

tm.properties

###########################################################################################
#                                                                              		      #
#                                                                              		      #
# TM configuration                                                           		      #
#                                                                              	  	      #
#                                                                              	          #
###########################################################################################
############################################################## Element List Configuration #
# coded element processing
tm.configurableelementidentification=true
tm.codedelementlist.enabled=true
# actual path to coded_element_list.xml file
tm.codedelementlist.path=TM_resources/coded_element_list_epSOS2.xml
########################################################### Basic CDA Schema Configuration #
# actual path to schema file
tm.schemafilepath=TM_resources/schema/CDA_extended.xsd
# schema validation enabled
tm.schema.validation.enabled=true
################################################################# Schematron Configuration #
# actual path to patienSummary Schematron file
tm.schematron.path.patientsummary=TM_resources/schematron/PatientSummary.sch
# actual path to ePrescription Schematron file
tm.schematron.path.eprescription=TM_resources/schematron/ePrescription.sch
# actual path to eDispensation Schematron file
tm.schematron.path.edispensation=TM_resources/schematron/eDispensation.sch
# actual path to schematron XSL directory
tm.schematron.path.xsldir=TM_resources/xsl
### NEW PROPERTIES
# actual path to patientSummaryFriendly Schematron file
tm.schematron.path.patientsummary.friendly=TM_resources/schematron/epSOS-PatientSummary-Friendly.sch 
# actual path to ePrescriptionFriendly Schematron 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:

Setup eADC in OpenNCP

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:

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/axis2.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 7).

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 OpenNCP Portal

Configuring portal

4.10.2 epSOS-Web

epSOS-Web Get Started

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)

/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
	|-- /ATNA_resources
	|-- /EADC_resources
	|-- /TM_resources
	|-- configmanager.hibernate.xml
	|-- pn-oid.xml
	|-- ISO_3166-1.xml
	|-- tm.properties
	+-- tsam.properties

Please do not forget to leave suggestions or expose your doubts at the comments section of this page.

https://openncp.atlassian.net/wiki/display/ncp/OpenNCP+Installation+Manual

OpenNCP Installation Manual (deprecated, since 2015-10-29)