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.
Previous version of this manual are available here
Before proceeding with the installation of OpenNCP please refer to OpenNCP Installation Overview page for the basic information about OpenNCP installation and architecture.
This installation manual was based on an installation with the following software:
- Java 1.8.0 (Current version is 1.8.0_181 or newer).
- GNU/Linux x86_64
- MySQL 5.7.23
- Apache Tomcat 8.5.32
- Liferay 6.2.5 CE GA6
2. Setup application server
We strongly recommend using the version 1.8.0_131 of the JDK 8 (or newer, also tested with 1.8.0_181).
The software components are able to run on all Java application servers, but we recommend you to install them at an Apache Tomcat instance.
You can download it at http://tomcat.apache.org/ and you should use Tomcat version 8.5.
To perform the installation and fine tuning of the server you may also follow this instructions: Apache Tomcat official documentation.
Don't forget to give execution permission to the files in the bin folder. Also, add the JDBC connector (JAR file) of your database to your Tomcat's lib folder as the drivers are marked as provided by the container into the Maven pom files of the components.
You must check if you have some other service running in Tomcat's default ports (defined in its conf/server.xml file) and change them if you do.
2.1 JNDI Datasources
You need to define JNDI DataSources to the Apache Tomcat configuration. The OpenNCP default installation is using MySQL as a database and HikariCP as a connection Pool. The infrastructure manager is the responsible for the server configuration, and please take in consideration the maximum number of connections available on your database server if you are using connection pools.
There are different way to define JNDI Datasources with Tomcat. OpenNCP team has decided to share the pools between the web application deployed.
This is done in the conf/context.xml file. Here is an example file for Tomcat 8.5. Just add the definition of the JNDI data sources and change the connection string depending on the DBMS you're using (for MySQL there's no need to change). We'll configure each one of them as we progress through the installation (keep them commented and uncomment when you configure).
2.2 External dependencies
For scalability purpose between Apache Tomcat and MySql, some Java dependencies have to be added to the external lib directory instead of embedded to the WAR archive.
At least the two following dependencies must be added to your Apache Tomcat instance: /opt/apache-tomcat-server/lib/
MySQL JDBC drivers:
Depending of your database, you might choose your JDBC drivers version, default installation is using version 5.1.43 available from Maven repository or https://dev.mysql.com/downloads/connector/j/
Default installation has been tested with HikariCP and the JAR might be download from Maven repository or https://brettwooldridge.github.io/HikariCP/
Slf4j-api is required by HikariCP to work properly.
3. Adjust configuration parameters
First, you'll need to have a folder named "openncp-configuration" that will hold your configuration files (you can take a quick look at the last step of the guide to see a recommended folder structure for the NCP). The folder is provided hereafter as a zipped file:
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.
OIDs were defined within epSOS-I. It seems that the root used (2.16.17) is not officially assigned. Was it defined by IHE Services? Then we simply incremented the 8xx number for each country (22.214.171.1240.8xx.1000.990.1). At the end, at least for PRODUCTION, each country should get (buy) its own OID from HL7 or from their national OID authority (see list here http://www.oid-info.com/doc/country-OIDs.htm and click on the country OID for contact details, if available).
The sharing of International Search Masks (forms folder) is a manual process. Currently they're being shared by email between OpenNCP adopters. The central services could be used for that, using their public folder at: https://webgate.ec.europa.eu/ehealth/tsl/common_files/
Then set the EPSOS_PROPS_PATH environment variable to the path of configuration files folder. You can do this by executing the following command in the terminal window:
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.
3.1 Configuration Manager Database
The bulk of NCP configuration properties (i.e. countries endpoints, truststore locations, and others) is stored in the Configuration Manager database.
The "Setup" section of Configuration Manager explains how to create a database and a hibernate configuration file.
The openncp-property table structure has been updated as followed:
'name', 'varchar(255)', 'NO', 'PRI', NULL, ''
'value', 'varchar(255)', 'YES', '', NULL, ''
'is_smp', 'bit(1)', 'YES', '', 'b\'0\'', ''
3.2 Creation of certificates and configuring Tomcat
You can find more details on how to create epSOS certificates here.
After that, you need to add a new Connector to your Tomcat's conf/server.xml file, in order to configure SSL connections to use the generated keystores and certificates:
- port: should be the port that you want to use for SSL connections. It'll be the port where your web services (PatientIdentification, Consent, etc.) will be exposed;
- keyAlias: your service provider certificate alias;
- keystoreFile: the path to your service provider keystore. This means that your Tomcat will act as a service provider;
- keystorePass: your service provider keystore password;
- truststoreFile: the path to your truststore. This means that your Tomcat will only accept connections from your trusted third-parties;
- truststorePass: your truststore password.
If incoming SSL (TLS) connections are terminated in your environment at a load balancer (LB), you need to set up your LB to forward client certificate information to OpenNCP. The subject DN of the certificate needs to be placed in an HTTP header by the LB before the request is forwarded to OpenNCP. Set up properties
TLS_CLIENT_CERT_HEADER_NAME (more information on page OpenNCP properties). In addition, depending on the environment, you might need changes to the Tomcat connector, for example an additional connector without enabled SSL.
3.3 NCP First-Time Configuration Utility
To facilitate the process of setting up your NCP instance, 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, configure the database connection file and execute the utility JAR.
You must have the properties database (with no tables) already created, before using this utility.
Find the JAR file in section 3.1 of this manual. You can download the properties and database files here:
Once you have run the utility with success, you may delete both files and the JAR and check if the database was correctly filled, using the appropriate database administration tool.
Be aware that this configuration utility will ignore properties with no value set, so these ones should be added manually to your database.
Note: properties should not use environment variables like '$EPSOS_PROPS_PATH/...'. Instead, the full path should be used.
A full list of the OpenNCP properties can be found here: OpenNCP properties
The following table also provides some important information about the central services (for configurations and terminologies):
|TSAM||ACCEPTANCE / PPT||https://webgate.acceptance.ec.testa.eu/ehealth-term-server||Testa|
https://smp-ehealth-trn.acc.edelivery.tech.ec.europa.eu (DNS domain: ehealth-trn.acc.edelivery.tech.ec.europa.eu)
|SMP||ACCEPTANCE / PPT||https://smp-test.publisher.ehealth.testa.eu (DNS domain: ehealth.testa.eu)||Testa|
|SMP||PRODUCTION||Configuration will be provided in a restricted way for NCPeHs that successfully fulfilled the readiness criteria that enable them to GoLive||Testa|
4. Install and setup components
4.1 OpenNCP artifacts
In order to install OpenNCP, you must obtain the following artifacts (please use the latest versions for each component). All the components are available for download from the eHDSI CEF Nexus Repository Manager; after the authentication components and assets are available for download. All the relevant information are available at the following OpenNCP Reference Implementation - Artifacts Availability
The OpenNCP current version is the OpenNCP v2.5.3
OpenNCP main components:
- Server Side - NCP-A (WAR)
- Client Side - NCP-B (WAR)
- OpenATNA (WAR)
- TRC-STS (WAR)
- OpenNCP Gateway (WAR)
OpenNCP command line tools:
- TSAM-Sync (JAR)
- TSAM-Exporter (JAR)
- First-Time Configuration Utility
OpenNCP external tools:
- Portal (WAR)
- Web Portal (WAR)
- RichClient - eID Level 1 (JAR)
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 openncp-trc-sts-X.X.X.war, then it is advised to rename it to just TRC-STS.war (so the database property of the exposed service remains the same between different versions of TRC-STS).
Before the deploy, configure the jdbc/ConfMgr data source in your Tomcat conf/context.xml to connect to your OpenNCP properties database.
Next you can just deploy it in your Application Server instance. You can follow this instructions for Tomcat 8.5.
This will deploy the Secure Token Service at http://<hostname>:<port>/TRC-STS/STSServiceService , where <hostname> and <port> are the hostname or IP address of the machine Tomcat is running and the port Tomcat is using (you can check it in Tomcat's conf/server.xml file).
After that, you can add/update the property "secman.sts.url" at your NCP properties database with the aforementioned URL.
4.3 Service Metadata Provider and Locator (SMP/SML)
At the moment we are working on an updated version of this part of the user manual. This will be provided asap.
In the meanwhile this version can be used: SMP Editor user manual
The configuration of the SMP properties are managed by the OpenNCP Gateway component, which is an independent WAR file. From version 2.5.3, an authentication mechanism has been integrated.
Before deploying the Gateway component, you shall first update your openncp_properties database schema with the following 3 new tables:
In order to create the required tables, the following SQL script shall be executed (default username / password combination is admin / admin): openncp-gateway.sql
4.3.1 SMP Files
The configuration of your NCP-A should contain at least the following files:
International Search Mask (urn:ehealth:ISM::InternationalSearchMask##ehealth-107)
Your International Search Mask should respect the following format with the mandatory namespace xmlns="http://ec.europa.eu/sante/ehncp/ism".
Patient Identification and Authentication (urn:ehealth:PatientIdentificationAndAuthentication::XCPD::CrossGatewayPatientDiscovery##ITI-55)
Request of Data - Query (urn:ehealth:RequestOfData::XCA::CrossGatewayQuery##ITI-38)
Request of Data - Retrieve (urn:ehealth:RequestOfData::XCA::CrossGatewayRetrieve##ITI-39)
- XDR (Dispensation)
Provisioning of Data - Provide (urn:ehealth:ProvisioningOfData:Provide::XDR::ProvideandRegisterDocumentSet-b#ITI-41)
For the generation and signing of these files the SMP Editor is used.
4.3.2 SMP Editor
In the meanwhile this version can be used: SMP Editor user manual
The TSAM-Sync component is a standalone component able to retrieve the Terminologies from the eHealth Central Terminology Server according the credentials provided. The process will connect to the repository and load your terminologies into your Local Terminology Repository database.
This application is a standalone JAR that can be placed in custom location which only requires a configuration file detailed hereafter.
Before running the TSAM-Sync process, you should validate with your National Terminology responsible that all actions required into the central eHealth Terminology Portal have been achieved and validated (MVC published, Translations and/or Mappings uploaded and MTC nationally validated otherwise no data will be available for the synchronization).
If you need more details related to the eHealth Terminology Services, you could access the Terminology Server user guide
eHealth Terminology Services
Please, take in consideration the following information related to the eHealth Central Terminology Services:
eHealth DSI Terminology Server documentation: https://ec.europa.eu/cefdigital/wiki/x/yQLQAg
You should configure the application.yml file as follows, providing your country specific configurations:
For Oracle installations, use the same configuration for both openncp.ltrdb and spring.datasource and specify the connection using an URL. The following code block highlights the differences:
Before the deployment, please do not forget to configure the jdbc/TSAM data source in your Tomcat conf/context.xml and conf/server.xml related to the LTR database (ltrdb) connection.
If you do not have the LTR database already, you can just create the schema manually by using the following SQL script for MySQL:ltrdb-mysql.sql
Then run the JAR. It will create your tables and fill the database with the terminologies.
4.5 Transformation Synchronization Access Manager (TSAM)
In order for the TSAM to work properly, you should setup the tsam.properties file, already provided and located under your EPSOS_PROPS_PATH. You can find an example bellow:
Give special importance to:
- translationLanguage: here you will place your country language;
- transcodingLanguage: this property will hold the country A language, defined as "en-GB" 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.
You can find more on TSAM implementation here: epSOS_TM_TSAM_implementation_v7.
4.6 Transformation Manager (TM)
This component is used for data transformation from a national language to the epSOS Reference Terminology or for data transformation from the epSOS Reference Terminology to a national language.
In order for the TM to work properly, you should setup the tm.properties file, also provided and located under your EPSOS_PROPS_PATH.
It'll probably suit your needs with the default values, but you can always take a look at it.
You can find an example bellow:
4.7 Automatic Data Collector (eADC)
Automatic data collection is a feature requested to the NCP to provide information to evaluate the epSOS interoperability system performance and to collect statistics on the population using epSOS services.
To setup and install the Automatic Data Collector you can follow the instructions present on the following page: Setup eADC in OpenNCP
4.8 Audit Repository (OpenATNA)
You'll need to deploy the openatna-web WAR to your Tomcat, but before that you need to do the following configurations:
- TLS configuration: parameters in section arr-tls of file $EPSOS_PROPS_PATH/ATNA_resources/ArrConnections.xml have to reflect the values of epsos properties database:
- HostName -> audit.repository.url
- Port (default: 2862) -> audit.repository.port (default: 6514)
- copy your ServiceProvider.jks and ServiceConsumer.jks keystores into $EPSOS_PROPS_PATH/ATNA_resources/certs and refer to them in $EPSOS_PROPS_PATH/ATNA_resources/ArrConnections.xml (KeyStore --> ServiceProvider.jks and TrustStore --> ServiceConsumer.jks) OR:
- In ArrConnections.xml, point to the keystore and truststore (ServiceProvider.jks and ServiceConsumer.jks, respectively) in $EPSOS_PROPS_PATH/cert/PPT instead of copying those to $EPSOS_PROPS_PATH/ATNA_resources/certs folder and change the passwords (don't use environment variables, use full paths instead).
- Example configuration can be seen in step 4: OpenATNA Home
- Follow step 1 to set up the database: OpenATNA Home.
- In $EPSOS_PROPS_PATH/ATNA_resources/openatna.properties, you will need to change password of the DB and edit ihe.actors.dir to point to the ATNA_resources folder.
- 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 should add this line to the TOMCAT setenv.sh script:
- OpenATNA uses property with name scheduled.time.between.failed.logs.handling.minutes in ConfigurationManager database to define the interval in which OpenATNA checks if some audit log was not persisted. In case these logs are found, they will be attempted to re-persist. The default value is 60 (minutes).
- Configure epsos properties to write test audits (see step 5: OpenATNA Home)
Now you can deploy the WAR file in your Tomcat. If everything is OK your OpenATNA database structure should've been created and you should see the following lines at the end of the OpenATNA log file:
4.9 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 openncp-ws-server-X.X:X.war, as explained in step 3.1.
It is advised to rename the file to simply openncp-ws-server.war, then you should deploy it on your Tomcat instance (to deploy the application you may follow this instructions: Tomcat 8.5 deployment).
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). If not, and according to the configuration made in section 2.2, your web services will be exposed in the following URLs:
- And so on.
In order to implement a National Connector to connect OpenNCP to your National Infrastructure, you have to develop some services. OpenNCP Bitbucket provides a skeleton where you can start to work: epsos-nc-mock-it.
The following page provides some guidance on this task: National Connector Implementation.
4.10 Client Side (NCP-B)
For client side it is used the same approach used in Server side. You should download the artifact named: openncp-client-connector-X.X.X.war, as explained in Step 4.1.
It is also advised to rename the file to just openncp-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). If not, the following web service that allows the Portal to communicate with the OpenNCP will be exposed:
4.11 TSAM Exporter
Before running the TSAM-Exporter process, you should validate that you have successfully synchronize your Local Terminology Database with the Central Services. You should also ensure the ENVIRONMENT variable EPSOS_PROP_PATH is up to date and the user which is executing the TSAM Exporter process has enough privileges.
4.12 OpenNCP Gazelle Validation
The OpenNCP Gazelle Validation component is used to call the Gazelle validation services and to automatically validate the different messages and documents.
To activate the component, the following property has to be set in the property table of the ehealth_properties database:
To activate the remote validation using the gazelle services, you have to set the following property:
The validation results of the different remote service calls will be available in the validation subdirectory of the openncp-configuration folder. This folder has two possible subfolders, depending of the role of your country:
The generated files have the following structure:
So for example in the case of a successfully validated message you 'll get: 2018-08-27T14:04:19Z_AUDIT_EPSOS---SMP-SERVICE-CONSUMER---QUERY-[RFC3881-COMPATIBLE]_PASSED.xml
And in the case of a failed validated message you'll get: 2018-08-27T14:04:19Z_AUDIT_EPSOS---SMP-SERVICE-CONSUMER---QUERY-[RFC3881-COMPATIBLE]_FAILED.xml
4.13 OpenNCP Portal or epSOS-Web
At this point, you'll either install OpenNCP Portal or epSOS-Web. OpenNCP Portal is the reference implementation and should be your choice in case you're following this manual and want to use the eID capabilities. epSOS-Web requires a set of different properties in the database. CDA Display Tool shall be used in both cases.
4.13.1 OpenNCP Portal
To install the OpenNCP Portal, you may follow the provided instructions, available at:
To install epSOS-Web follow the instructions available at: epSOS-Web Get Started.
5. Database Logging
The current implementation of OpenNCP is using Logback framework for the logging management. Logging level and configuration are managed through the logback.xml configuration files embedded into the artefacts.
In addition to the Console and File logging appender, a database appender has been defined. The DBAppender inserts logging events into three database tables in a format independent of the Java programming language. These three tables are logging_event, logging_event_property and logging_event_exception. They must exist before DBAppender can be used.
Logback ships with SQL scripts that will create the tables. They can be found under the logback-classic/src/main/java/ch/qos/logback/classic/db/script folder. There is a specific script for each of the most popular database systems if required.
In order to complete the installation a dedicated database should be created according the MySQL SQL script provided hereafter.
If the logged information are not enough efficient, you will find some guidelines about the Logging configuration in the following link: Logging customization.
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):