Page tree
Skip to end of metadata
Go to start of metadata

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

Table of contents:

1. Recommendations

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_191 or newer).
  • GNU/Linux x86_64
  • MySQL 5.7.XX
  • Apache Tomcat 8.5.XX
  • Liferay  6.2.5 CE GA6

2. Setup application server

We strongly recommend using the latest version of the JDK 8 available.

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 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.

  • /opt/apache-tomcat-server/conf/server.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    <Server port="8005" shutdown="SHUTDOWN">
       <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
       <!-- Security listener. Documentation at /docs/config/listeners.html
          <Listener className="" />
       <!--APR library loader. Documentation at /docs/apr.html -->
       <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
       <!-- Prevent memory leaks due to use of particular java/javax APIs-->
       <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
       <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
       <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />
       <!-- Global JNDI resources Documentation at /docs/jndi-resources-howto.html -->
          <!-- Editable user database that can also be used by
             UserDatabaseRealm to authenticate users
       <Resource name="UserDatabase" auth="Container" type="org.apache.catalina.UserDatabase" description="User database that can be updated and saved" 
                 factory="org.apache.catalina.users.MemoryUserDatabaseFactory" pathname="conf/tomcat-users.xml" />
          <!--Define hereafter your OpenNCP Connection Pools: jdbc/ConfMgr, jdbc/TSAM, jdbc/EADC_XCPD, jdbc/EADC_XCA, jdbc/EADC_XDR, jdbc/LOGS --> 
          <Resource name="jdbc/ConfMgr" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_properties" dataSource.user="openncp_user"
          <Resource name="jdbc/OPEN_ATNA" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_atna" dataSource.user="openncp_user" 
          <Resource name="jdbc/TSAM" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_ltrdb" dataSource.user="openncp_user"
          <Resource name="jdbc/EADC_XCPD" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_eadc" dataSource.user="openncp_user"
          <Resource name="jdbc/EADC_XDR" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_eadc" dataSource.user="openncp_user"
          <Resource name="jdbc/EADC_XCA" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_eadc" dataSource.user="openncp_user"
          <Resource name="jdbc/LOGS" auth="Container" factory="com.zaxxer.hikari.HikariJNDIFactory" type="javax.sql.DataSource" singleton="true" 
                    minimumIdle="2" maximumPoolSize="5" connectionTimeout="300000" dataSourceClassName="com.mysql.jdbc.jdbc2.optional.MysqlDataSource"
                    dataSource.serverName="" dataSource.port="3306" dataSource.databaseName="ehealth_logs" dataSource.user="openncp_user"
       <!-- A "Service" is a collection of one or more "Connectors" that share
            a single "Container" Note:  A "Service" is not itself a "Container",
            so you may not define subcomponents such as "Valves" at this level.
            Documentation at /docs/config/service.html
       <Service name="Catalina">
          <!--Tomcat configuration -->

  • /opt/apache-tomcat-server/conf/context.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- The contents of this file will be loaded for each web application -->
       <!-- Default set of monitored resources. If one of these changes, the    -->
       <!-- web application will be reloaded.                                   -->
       <ResourceLink global="jdbc/ConfMgr" name="jdbc/ConfMgr" type="javax.sql.DataSource"/>
       <ResourceLink global="jdbc/TSAM" name="jdbc/TSAM" type="javax.sql.DataSource"/>
       <ResourceLink global="jdbc/OPEN_ATNA" name="jdbc/OPEN_ATNA" type="javax.sql.DataSource"/>
       <ResourceLink global="jdbc/EADC_XCPD" name="jdbc/EADC_XCPD" type="javax.sql.DataSource"/>
       <ResourceLink global="jdbc/EADC_XCA" name="jdbc/EADC_XCA" type="javax.sql.DataSource"/>
       <ResourceLink global="jdbc/EADC_XDR" name="jdbc/EADC_XDR" type="javax.sql.DataSource"/>    
       <ResourceLink global="jdbc/LOGS" name="jdbc/LOGS" type="javax.sql.DataSource"/>

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.XX available from Maven repository or

  • HikariCP:
    Default installation has been tested with HikariCP and the JAR might be download from Maven repository or

    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:

  File Modified
ZIP Archive Enabling audit messages for pivot transformation (epsos-94). Resource tm.audittrail.enabled=true [OpenNCP 2.5.5] Nov 09, 2018 by Jerome SUBIGER

Folder content:

|-- /ATNA_resources
|-- /audit-backup
|-- /EADC_resources
|-- /forms
|-- /TM_resources
|-- configmanager.cfg.xml (this configuration file has been renamed)
|-- pn-oid.xml

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 (

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 and click on the country OID for contact details, if available).

The sharing of International Search Masks (forms folder) is a command line client process (before improving to an automatic process). The central services (Service Metadata Locator) are used  for this purpose (SMP profile ehealth-107: urn:ehealth:ISM::InternationalSearchMask##ehealth-107).

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:

export EPSOS_PROPS_PATH=/opt/openncp-configuration/

For more information about environment variables, you can check: for Ubuntu, but that can be applicable to other distribution.

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.

Table openncp-property

The OpenNCP EHNCP_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 hereFor testing and development purposes eHDSI Gazelle Security Suite tool has to be used:

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:

<Connector port="PORT" protocol="HTTP/1.1" SSLEnabled="true"
           maxThreads="150" scheme="https" secure="true"
           clientAuth="true" sslProtocol="TLS"
  • 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_TERMINATION_AT_LOAD_BALANCER and 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 schema already created (with no tables), before using this utility.

Find the JAR file in section 3.1 of this manual. You can download the properties and database files here:

  File Modified
ZIP Archive Removed deprecated* property (OpenNCP 2.4.0) Apr 08, 2016 by João GONÇALVES

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):





SMPPRODUCTIONConfiguration will be provided in a restricted way for NCPeHs that successfully fulfilled the readiness criteria that enable them to GoLiveTesta

4. Install and setup components

4.1 OpenNCP artifacts

OpenNCP version

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.5

OpenNCP main components:

  • Server Side - NCP-A (WAR)
  • Client Side - NCP-B (WAR)
  • OpenATNA (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)

Important notice

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:


OpenNCP Gateway configuration

Please note that from OpenNCP Release 2.5.5, the datatbase schema OPENNCP_PROPERTIES has been updated.

In order to create the required tables, the following SQL script shall be executed (default username / password combination is  admin / admin)create-openncp-gateway-2.5.5.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="".

    <?xml version="1.0" encoding="UTF-8"?>
    <patientSearch xmlns="">
       <country code="EU">
             <id domain="" label="ID Card Number" max="-1" min="-1"></id>
             <textField dtoIndex="1" friendlyName="surname" label="" max="-1" min="3"></textField>
  • XCPD

    Patient Identification and Authentication (urn:ehealth:PatientIdentificationAndAuthentication::XCPD::CrossGatewayPatientDiscovery##ITI-55)

  • XCA
    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

Important notice

In the meanwhile this version can be used: SMP Editor user manual

4.4 TSAM-Sync

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.

|-- ...
|-- openncp-tsam-sync
|	|-- application.yml
|	+-- openncp-tsam-sync-x.x.x.jar
+-- ...

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:

You should configure the application.yml file as follows, providing your country specific configurations:

debug: false
    username: tsam_user
    password: password
     org.hibernate: ERROR
     org.springframework.web.client: DEBUG
    port: 3306
    username: openncp_ltrdb_user
    password: LTRDB_PASSWORD
    database-name: openncp_ltrdb
      use: true
      port: 9999
      use-authentication: true
      username: proxy_user
      password: proxy_password
    url: jdbc:mysql://
    username: openncp_user
    password: password
    driver-class-name: com.mysql.jdbc.Driver
    active: mysql

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:

    url: jdbc:oracle:thin:@//
    username: openncp_user
    password: password
    driver-class-name: oracle.jdbc.OracleDriver
    url: jdbc:oracle:thin:@//
    username: openncp_user
    password: password
    driver-class-name: oracle.jdbc.OracleDriver
    active: oracle

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:


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 file, already provided and located under your EPSOS_PROPS_PATH. You can find an example bellow: 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)


##Code of a language, which country A uses for designations in pivot documents created in
##transcoding (epSOS defines it as English)


########################################################################### Database Setup #

## Hibernate configuration

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 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:
#                                                                              		      #
#                                                                              		      #
# TM configuration                                                           		      #
#                                                                              	  	      #
#                                                                              	          #
############################################################## Element List Configuration #
# coded element processing
# actual path to coded_element_list.xml file
########################################################### Basic CDA Schema Configuration #
# actual path to schema file
# schema validation enabled
################################################################# Schematron Configuration #
# actual path to patienSummary Schematron file
# actual path to ePrescription Schematron file
# actual path to eDispensation Schematron file
# actual path to schematron XSL directory
# actual path to patientSummaryFriendly Schematron file
# actual path to ePrescriptionFriendly Schematron file
# actual path to eDispensationFriendly Schematron file
# actual path to patienSummaryPivot Schematron file
# actual path to ePrescriptionPivot Schematron file
# actual path to eDispensationPivot Schematron file
# schematron validation enabled
################################################################ Document Type epSOS Codes #
# epSos code for patient summary CDA document 
# epSos code for ePrescription CDA document 
# epSos code for eDispensation CDA document 
################################################################## Audit Trail Configuration #
# Audit Trail enabled/disabled
# Audit Trail Event Log - The number of transaction including the epsos- prefix
# Audit Trail Event Log - The IP Address of the target Gateway
# Audit Trail Audit Service - The facility number according to log4j
# Audit Trail Audit Service - The severity of the message 

You can find information on TM specifications in TM_specs_v0.7 and on the implementation (helpful to understand the previous properties) in epSOS_TM_TSAM_implementation_v7.

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)
  • Certificates:
    1. 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:
    2. 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).
    3. 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/, 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 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 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:

Starting OpenATNA service..
TLS Server running on port:2862
UDP server started on port 2861

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:

  • https://<hostname>:<SSLport>/openncp-ws-server/services/XCPD_Service
  • https://<hostname>:<SSLport>/openncp-ws-server/services/XCA_Service
  • https://<hostname>:<SSLport>/openncp-ws-server/services/XDR_Service
  • 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: 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:

  • http://<hostname>:<port>/openncp-client-connector/services/ClientConnectorService

4.11 TSAM Exporter

The TSAM Exporter tool is used to extract code translations from the LTR database into XML files that will be used by CDA Display Tool.

In order to correctly translate the CDA, you must run the TSAM-Exporter (make sure you have fetched your country terminologies into your LTR database through the TSAM Sync process).

This application is a standalone JAR that can be placed in custom location which only requires a configuration file detailed hereafter.

|-- ...
|-- openncp-tsam-exporter
|	|-- application.yml
|	+-- openncp-tsam-exporter-x.x.x.jar
+-- ...

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.

If you need more details related to the eHealth Terminology Services, you could access the Terminology Server user guide.

You should configure the application.yml file as follows, providing your LTRDB specific configuration:

debug: false
    url: jdbc:mysql://
    username: openncp_ltrdb_user
    password: openncp_ltrdb_password
    driver-class-name: com.mysql.jdbc.Driver

Then run the JAR and it will create your files with the terminologies definition.

When finished you will have under your OpenNCP configuration folder ($EPSOS_PROPS_PATH) a new folder named EpsosRepository in which you will find the produced exported XML files.

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:

|-- /validation
|   |-- /NCP-A
|   |-- /NCP-B

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:

  1. Installing OpenNCP Portal
  2. Configuring portal

4.13.2 epSOS-Web

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):

|-- /apache-tomcat-8.5.XX
|   |-- /bin
|   +-- /conf
|       |-- context.xml
|		|-- server.xml
|   |-- /logs
|   |-- /temp
|   |-- /work
|   +-- /webapps
|       |-- /openncp-client-connector
|       |-- /openncp-ws-server
|       |-- /openatna-web.war
|       |-- /openncp-gateway
|       +-- /TRC-STS
|-- /openncp-tsam-sync
|   |-- application.yml
|   +-- openncp-tsam-sync.jar
|-- /openncp-tsam-exporter
|	|-- application.yml
|	+-- openncp-tsamexporter.jar
+-- /openncp-configuration
    |-- /ATNA_resources
    |-- /cert
    |-- /EADC_resources
    |-- /EpsosRepository
    |-- /forms
    |-- /TM_resources
    |-- configmanager.cfg.xml
    |-- pn-oid.xml

  • No labels


  1. Jerome SUBIGER, can you clarify your last change:

    If you are using self-signed certificates, you have to set the property clientAuth to false into the Tomcat Connector node defined just above in order to bypass the security restriction related to the certificate issuer.

    As far as I recall this is related to the fact that TSL-Sync does not import self-signed CA certificates into the OpenNCP truststore, but we discussed in a tcon that it's supposed to be like that. You need to share the CA certificate in some other way (FTP, email, whatever). But the clientAuth must be set to true, otherwise systems will not pass the Audit messages validations in Gazelle (the message may be valid but IHE judges will invalidate due to "Client certificate not found" warning message).

    1. Hello, yes you're right linked to the Gazelle test tool; but the point is with the self-signed certificates we cannot have a valid certificate chain accepted by the browser (since the latest browser's releases). So in the situation where even without taking into account that we exchange TSL files and only when we try to use the NCP installed as NCP-A and B with the generated certificates, we received a BAD CERT error and I'm not sure that is link to the fact when the CA is not imported through the TSL-Sync into the TrustStore. I will keep in mind this point in order to have a clear answer, and add this to the next technical committee if it's ok for you?

      1. That is another issue. It's due to the fact that the CA certificate that issued the NCP server certificate is not in the browser's truststore (cacerts). But why do you need to add it to cacerts? To open the WSDL of the epSOS services in the browser? If so, then disabling clientAuth is by no means the correct approach (and should not be encouraged). You can use a curl command for that:

        curl --cert pt-ihe-epsos-service-consumer.pem:PASSWORD --key pt-ncp-sc.key --cacert pt-ihe-root-ca.pem -H "Content-Type:text/xml;Charset='UTF-8'" --verbose
        1. Yes, you're absolutely right according the security recommendations and warnings. My idea with the "Note" is not to disable the 2 ways ssl by disabling the client authentication. This is more in order to help the system administrator to better understand OpenNCP installation and configuration (also because is a MS use the self signed, this is most probably because the NCP node is a mock); perhaps we could add your comment with the curl function into the installation manual? And also the part when we must import manually the self-signed CA because this is not the role of the TSL-Sync to import the trusted issuer. Let's discuss this point during the Tconf. Many thanks for the advices Joao.

          1. I don't agree that using self-signed certificates means that the NCP is a mock, because changing it into an operational NCP is just a matter of replacing the certificates. So I'd feel more comfortable if instead of your note, we could put the curl command and explain its purpose (and I mean, a sysadmin is supposed to know curl, otherwise he's not qualified as such (smile)). Remember that it's very easy for a country to read that note, disable clientAuth and forget to enable it again, we've had some similar experiences in past CATs.

            I agree that we could add a note about the self-signed CA and TSL-Sync.

            1. Ok perfect, let's do it in this way, thanks.

              1. Jerome, please do this change as we discussed.

  2. Hi !

    I have some questions regarding the installation of OpenNCP:

    1. In the I'm missing the tsam-sync.jar, so that I can't execute this file.
      Can you please include this JAR-file into the ZIP-file? (I see only jdbc-connector.jar_.jar)
    2. For the installation of OpenNCP do I need an account for PPT and who can create it for me?
    3. What is the current status of the term repository or maybe is there a new term repository?

    Thanks in advance


    Kind regards,


    1. Hello Maid,

      1. You should download the JAR from the repository mentioned in step 3.1.
      2. Yes, you should ask DG-SANTE. I think Yacoubou WAOLANY is the guy whom you should contact. → Only for the TSL part and not the TSAM.
      3. AFAIK, DG-SANTE is working on the new term repository. The old one is no longer working.
    2. Dear Maid EROVIC,

      I'll try to answer your question regarding the TSAM sync; for information this component is not up and running for the time-being because there is no Terminology Services available.

      • tsam-sync folder does not contain the tsam-sync.jar because as an official OpenNCP component, it's available at the following url.
      • In order to use the Terminology Services, each MS should have an account (but not yet available since the Terminology Services is not running).
      • The Terminology Services implementation is ongoing also linked with the Semantic Task force which is responsible of the content of the Master ValueSet Catalog. More detailed information will be provided soon about the release date of the different components. At least the Terminology Services should be included into the release 2.6.0. For the time-being, in order to install you OpenNCP node, you need to use the backup file of your local authority (LTRDB). If you don't have a back-up, please feel free to contact us for using a default one.

      I hope this information will help you.



  3. Hello guys,

    we're trying to install OpenNCP Portal following this installation manual.

    In step 2. of the installation manual from the folder "create" of downloaded ZIP-file we run the script "create-mysql.sql". This script creates different tables and also many indexes. Some of the tables have fields which are very long, e.g. in table "SCProductVersion" the filed "directDownloadURL" has a length of VARCHAR(2000) and the character set of these field is utf8 (utf8_general_ci). And this is the problem, why some of indexes can't be created.

    When we run the script, we get the following error message from MySQL: ERROR 1071 (42000) at line 4038: Specified key was too long; max key length is 767 bytes

    As required from the installation manuel of OpenNCP we are using MySQL 5.6.25.

    If innodb_large_prefix is enabled, the index key prefix limit is 3072 bytes for InnoDB tables that use DYNAMIC or COMPRESSED row format. If innodb_large_prefix is disabled, the index key prefix limit is 767 bytes for tables of any row format.
    (Please see the maximums and minimums on InnoDB tables:

    The problem is in the character encoding of the fields: utf8. For storing of a character utf8 needs 3 bytes (latin1 only 1 byte). If we have a field which length is 2000 characters and we use utf8, then for the creation of an index we need 6002 bytes (2 bytes reserved space for holding the length of string). And this length is more then the allowed limits of 3072 or 767.

    When we limit the length of index to store just 255 characters of the string at the affected line 4038 in the script "create-mysql.sql":

    create index IX_7020130F on SCProductVersion (directDownloadURL(255));

    then it works fine.

    My question is, is it acceptable for the full funcionallity of OpenNCP Server to short the length of the index and to save only 255 characters insted of 2000?

    Do we have any disadvantage or restrictions thereby?

    Why we don't use latin1 as charachter encoding or do we expect any special characters which are not supported with latin1?


    Thank you for your support in advance.


    Kind Regards,


    1. Dear Maid EROVIC,

      Many thanks for your comment, I'have just created an issue related to this topic EHNCP-1078 - Getting issue details... STATUS .

      As a first draft of answer, the create-mysql.sql is provided with the Liferay Portal CE official release, so this is complicated to modify the content of the script. I suppose this could be an issue linked to the MySQL server version. From our side we never had this issue but we use a RedHat server which "impose" a quite old version of packages (MySQL 5.1.73).

      I'll do a quick test on Ubuntu with an up to date MySQL server and provide you feedback.

      In the meantime, the encoding selected through the portal is finally a NCP decision according the language/characters that you should support (that's why by default we recommend UTF-8), but only in a NCP-B client point of view.

      I hope it helps you. Kind regards


  4. Looking at the various WAR generated, I can see 3 different log configurations:

    • log4j.xml
    • logback.xml

    → Does anyone know exactly which one(s) are used by which components ?


    1. Hello Stephane SPAHNI, the Logging framework is now Logback so the logback.xml file is now the configuration one for logging, I didn't remove yet all the or log4j.xml files but anyway there are deprecated and the dependencies are not present anymore with the artefacts.



  5. OK I took the "easy path" and just slighlty adapted the "DB" logger to logback (changing the class)... but that too simple!

    LOGBACK is (by default) using 3 DB tables for storing logs → if we want to customize the log, we have to replace the Dabase Appender of logback.

    → What do we do? Use the standard DB logger and create a new database for logback or rewrite the appender (or was it already rewritten?)

    → It has a strong impact on what I will present in Day 2 of the boot camp!

  6. Hi, 

    Someone mentioned tsl-editor.3.0.0 in replys, link to download  is dead.Should we use 3.0 version or 2.4.2 is ok too ?

    I am trying to create NCP_Service_Status_List fail with openncp-tsl-editor-2.4.2.jar.

    Managed to get all info configured, but when trying to sign with self-signed CA I get error:
     XML Signature of TSL Failed. Is there some log or smth that I could debug?


  7. Anonymous

    For signing the TSL file, tsl editor version 2.3 works fine with Java 6.

    For signing the SMP file, tsl editor version 3.1.5 works fine with Java 8.

    Let me know if you have problems finding one or another jar (smile)


  8. (sorry that was Stephane SPAHNI)

    Note that you cannot sign the TSL file with 3.1.5, and you cannot sign the SMP file with 2.3 (sad) Signing library is not the same and both are incompatible.

  9. Anonymous

    Hello to all,

    We are trying to deploy a full in-lab installation of openNCP for developing purposes (we are involved in an H2020 project focused in adding security to eHealth and we should rely on openNCP). Is it possible to have a working installation of an openNCP node, and an in-lab communication between two openNCP nodes deployed on a local network, without relying on the central services? If this is not possible, should we define a custom country, and connect with the central services? And in this case, who can provide us with the credentials to connect to the central services?

    Thank you in advice.

    Writing in behalf of the University of Naples "Parthenope", Italy

    1. Dear "Naples",

      As explained by Stephane SPAHNI, you currently need the central services in order to configure the NCP nodes and a Local Terminology Repository DB.

      As there is no terminology services up and running for the time being, we could provide some dump files with different languages. You will also have to prepare 2 TSL files for your 2 mock countries (NCP-IT-1 and NCP-IT-2) then you just need an Apache server to mock the central services.

      If you want more details regarding this installation topic, please feel free to contact us and we will be so glad to answer your question or organize a meeting if needed.

      Please, do not hesitate to create a EU-Login account in order to have access to more functionalities of the workspace

      I wish you a nice afternoon.

      Kind regards


      1. Anonymous

        Dear Jerome SUBIGER,

        Thanks to you and to Stephane SPAHNI for your timely answer. We are going forward with the in-lab deployment, and I guess that now we need a dump of the terminology database; where can we find them?

        We are also experiencing problems with the signature of the TSL file. We are trying to sign the TSL file for our installation of openNCP with the NCP signature certificate, employing self-signed certificates. But the TSL-Editor always returns " XML Signature of TSL Failed". We tried different versions of the TSL-Editor with different versions of Java, namely:

        • TSL-Editor 2.3 with Oracle Java 6
        • TSL-Editor 2.4.3 with Oracle Java 7 and OpenJDK 8 (it does not work at all with Oracle Java 7)

        In all cases, we got the mentioned error.

        Thanks to all

        1. (sorry, that was Raffaele MARTINO) A correction: TSL-Editor 2.4.3 works with Oracle Java 7, even if we was not able to sign the TSL due to the mentioned error. TSL-Editor 2.4.3 does not work at all with Oracle Java 6.

  10. Hello Naples,

    You currently need "central" services for 2 purposes:

    1) Retrieving endpoints of the other NCPs (TSL file): this is the tsl.location.<country> url in epsos-configuration database → you may well have your own internal web server serving this file

    2) Retrieving the terminology database (LTRDB) → in the absence of central services, you may use a dump and import it into the LTRDB database

    → answer is definitely: yes (smile)

  11. One question about 2 properties in


    ##Code of a language, which country B uses for designations in pivot documents created in translation (local language of a country)


     → what does it mean exactly ? the language to be used by NCP-B for the B-Friendly document sent to portal when creating it from the A-Pivot (e.g. for a PS) ? Or the language used by B-Friendly when creating the B-Pivot to be sent to NCP-A (e.g. for eD) ?


    ##Code of a language, which country A uses for designations in pivot documents created in transcoding (epSOS defines it as English)


     → means the language of the A-Pivot document sent to NCP-B ?


    Btw I did not find any reference to these two properties in the source code... (I am currently clarifying our strategy for working with 3 different languages → possibly 3 portals, 3 NCP-B but 1 NCP-A returning PS which PS-A-Friendly being in any of the 3 languages...)



    1. Dear Stephane SPAHNI,

      References to this property are in different place:

      • oppenncp-portal (file ctx_tsam.xml) because of the Helper method of the portal.
      • openncp-xca-ws-client (file ctx_tsam.xml)
      • openncp-xca-ws-server-impl ((file ctx_tsam.xml)

      translationLanguage is the parameter used for the local language of the NCP-B as you describer (Friendly-B format)

      transcodingLanguage is the parameter to transform NCP-A friendly to NCP-A pivot which are then translated into the NCP-B friendly format with the previous language parameter.

      Reference: openncp-transformation-manager component: method toEpsosPivot() and translate();

      Please do not hesitate if you need more info.



      1. Does this means that transcodingLanguage must always be en-GB ?

        1. Yes Locale "en-GB" Locale is the preferred language for all the eHDSI Pivot CDA (but it affects only the display name of the coded elements).

  12. Tomcat v7.0.75 does not work with openATNA but Tomcat v7.0.73 is OK. Here is a part of the error : 

    org.apache.jasper.JasperException: Unable to compile class for JSP:

    An error occurred at line: [95] in the generated java file: [/local/opt/openncp/2.4.3/ncp-a/work/Catalina/localhost/openatna/org/apache/jsp/WEB_002dINF/jsp/]
    The code of method _jspService(HttpServletRequest, HttpServletResponse) is exceeding the 65535 bytes limit

    at org.apache.jasper.compiler.DefaultErrorHandler.javacError(
    at org.apache.jasper.compiler.ErrorDispatcher.javacError(
    at org.apache.jasper.compiler.JDTCompiler.generateClass(

  13. Anonymous

    While trying to do tsam-sync with(openncp-tsam-sync-2.5.1.jar):

    I have configured application.yml:


    Error I get:

    2017-06-27 12:24:47.145 DEBUG 16508 --- [ main] o.s.web.client.RestTemplate : GET request for "" resulted in 400 (Bad Request); invoking error handler
    Exception in thread "main" java.lang.reflect.InvocationTargetException
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    at java.lang.reflect.Method.invoke(
    at org.springframework.boot.loader.Launcher.launch(
    at org.springframework.boot.loader.Launcher.launch(
    at org.springframework.boot.loader.JarLauncher.main(
    Caused by: org.springframework.web.client.HttpClientErrorException: 400 Bad Request
    at org.springframework.web.client.DefaultResponseErrorHandler.handleError(
    at org.springframework.web.client.RestTemplate.handleResponse(
    at org.springframework.web.client.RestTemplate.doExecute(
    at org.springframework.web.client.RestTemplate.execute(
    at org.springframework.web.client.RestTemplate.getForEntity(
    at org.springframework.cglib.proxy.MethodProxy.invoke(
    at org.springframework.aop.framework.CglibAopProxy$CglibMethodInvocation.invokeJoinpoint(
    at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(
    at org.springframework.transaction.interceptor.TransactionInterceptor$1.proceedWithInvocation(
    at org.springframework.transaction.interceptor.TransactionAspectSupport.invokeWithinTransaction(
    at org.springframework.transaction.interceptor.TransactionInterceptor.invoke(
    at org.springframework.aop.framework.ReflectiveMethodInvocation.proceed(
    at org.springframework.aop.framework.CglibAopProxy$DynamicAdvisedInterceptor.intercept(
    ... 8 more

    1. Dear Anonymous,

      Thanks for your question, in order to provide you information to the current situation may I kindly provide you the link of the Terminology Services documentation in order to enable your MVC. It will explain you in few steps how to handle your MTC according the MVC published: eHealth DSI Terminology Server documentation:

      Related to your issue, the stack trace is quite horrible because the exception is not handled correctly byt the TSAM-Sync, but as explained by the result code 400, you didn't add an agreement (ready for download status) to your National MTC so it means that you are not able to fetch locally the catalog.

      If you still have issues, please do not hesitate to open a ticket to

      I wish you a pleasant day.

      Kind regards

  14. Anonymous

    Hello, everybody

    We are trying to deploy a full in-lab installation of openNCP for developing purposes (we are involved in an H2020 project focused in adding security to eHealth and we should rely on openNCP). But We have a problem with openncp-portal deployment in liferay-porttal-6.2 . 

    Error I get:

    09:24:21,803 ERROR [localhost-startStop-2][HotDeployImpl:233] Error registering servlet context listeners for epsosportalepsosportal Error registering servlet context listeners for epsosportalepsosportal
    at com.liferay.portal.kernel.servlet.PluginContextListener.fireDeployEvent(
    at com.liferay.portal.kernel.servlet.PluginContextListener.doPortalInit(
    at com.liferay.portal.kernel.util.BasePortalLifecycle.portalInit(
    at com.liferay.portal.kernel.util.PortalLifecycleUtil.register(
    at com.liferay.portal.kernel.util.PortalLifecycleUtil.register(
    at com.liferay.portal.kernel.util.BasePortalLifecycle.registerPortalLifecycle(
    at com.liferay.portal.kernel.servlet.PluginContextListener.contextInitialized(
    at com.liferay.portal.kernel.servlet.SecurePluginContextListener.contextInitialized(
    at org.apache.catalina.core.StandardContext.listenerStart(
    at org.apache.catalina.core.StandardContext.startInternal(
    at org.apache.catalina.util.LifecycleBase.start(
    at org.apache.catalina.core.ContainerBase.addChildInternal(
    at org.apache.catalina.core.ContainerBase.addChild(
    at org.apache.catalina.core.StandardHost.addChild(
    at org.apache.catalina.startup.HostConfig.deployDirectory(
    at org.apache.catalina.startup.HostConfig$
    at java.util.concurrent.Executors$
    at java.util.concurrent.ThreadPoolExecutor.runWorker(
    at java.util.concurrent.ThreadPoolExecutor$
    Caused by: java.lang.reflect.InvocationTargetException
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    at java.lang.reflect.Method.invoke(
    ... 24 more
    Caused by: java.lang.ExceptionInInitializerError
    at com.gnomon.epsos.MyServletContextListener.contextInitialized(
    at com.liferay.portal.kernel.servlet.SecurePluginContextListener.instantiatingListener(
    at com.liferay.portal.kernel.servlet.SecurePluginContextListener.instantiatingListeners(
    ... 30 more
    Caused by: java.lang.RuntimeException: The key to be selected in SMP has a length which is not allowed
    at epsos.ccd.gnomon.configmanager.ConfigurationManagerSMP.query(
    at epsos.ccd.gnomon.configmanager.ConfigurationManagerSMP.getProperty(
    at epsos.ccd.gnomon.configmanager.ConfigurationManagerService.getProperty(
    ... 33 more
    09:24:21,828 INFO [localhost-startStop-2][PortletHotDeployListener:344] Registering portlets for epsosportal
    09:24:22,161 INFO [localhost-startStop-2][PortletHotDeployListener:497] 5 portlets for epsosportal are available for use
    09:24:22,177 ERROR [liferay/hot_deploy-1][SerialDestination:70] Unable to process message {destinationName=liferay/hot_deploy, response=null, responseDestinationName=null, responseId=null, payload=null, values={companyId=0, groupId=0, command=deploy, servletContextName=epsosportal}}
    com.liferay.portal.kernel.messaging.MessageListenerException: java.lang.NullPointerException
    at com.liferay.portal.kernel.messaging.BaseMessageListener.receive(
    at com.liferay.portal.kernel.messaging.InvokerMessageListener.receive(
    at com.liferay.portal.kernel.messaging.SerialDestination$
    at com.liferay.portal.kernel.concurrent.ThreadPoolExecutor$WorkerTask._runTask(
    at com.liferay.portal.kernel.concurrent.ThreadPoolExecutor$
    Caused by: java.lang.NullPointerException
    at com.liferay.resourcesimporter.util.PluginPackageProperties.<init>(
    at com.liferay.resourcesimporter.messaging.ResourcesImporterHotDeployMessageListener.initialize(
    at com.liferay.resourcesimporter.messaging.ResourcesImporterHotDeployMessageListener.onDeploy(
    at com.liferay.portal.kernel.messaging.HotDeployMessageListener.doReceive(
    at com.liferay.portal.kernel.messaging.BaseMessageListener.receive(
    ... 5 more

    1. Jerome SUBIGER, would you be so kind to give a look?

  15. Hi All!

    This is my first time with an OpenNCP installation and I'm facing some problems, according to the recommendations I've used:
    Ubuntu server 16.04 x64

    • Java 1.8.0_144 (also update-lternatives is pointing java to jdk instead of jre: /usr/lib/jvm/java-8-oracle/bin/java)
    • Tomcat 8.5.20 (8.5.15 was not available)
    • Mysql (server: 5.7.19 client: 5.1.43)
    • Applied JNDI configuration to apache config and created mysql databases (openncp_properties, ehealth_properties, ehealth_ltrdb, ehealth_eadc, ehealth_logs), granted permissions, and tested that mysql is OK.
    • Created all certificades and obtaining the same result as 2.2 section with country "es" instead of "pt", I've used self-cert options.

    However, when I check tomcat catalina.out, it shows the following error:

    (Alias name does not identify a key entry... by where?, when I generate certificates, Should be a real host? do I have to add to /etc/hosts somehow?

    Thank you in advance,

    26-Sep-2017 15:42:42.740 SEVERE [main] org.apache.coyote.AbstractProtocol.init Failed to initialize end point associated with ProtocolHandler ["https-jsse-nio-auto-1-4$
    java.lang.IllegalArgumentException: Alias name [] does not identify a key entry
            at org.apache.coyote.AbstractProtocol.init(
            at org.apache.coyote.http11.AbstractHttp11Protocol.init(
            at org.apache.catalina.connector.Connector.initInternal(
            at org.apache.catalina.util.LifecycleBase.init(
            at org.apache.catalina.core.StandardService.initInternal(
            at org.apache.catalina.util.LifecycleBase.init(
           at org.apache.catalina.core.StandardServer.initInternal(
            at org.apache.catalina.util.LifecycleBase.init(
            at org.apache.catalina.startup.Catalina.load(
  16. Ok I discovered myself the error, according to keytool alias it seems that I mistyped the alias in the config.xml connector: instead of for service provider

    oo@ubuntu:~$ keytool -list -keystore /opt/openncp-configuration/cert/PPT/keystore/es-service-provider-keystore.jks

    Enter keystore password:

    Keystore type: JKS
    Keystore provider: SUN

    Your keystore contains 2 entries, Sep 26, 2017, PrivateKeyEntry,
    Certificate fingerprint (SHA1): 10:20:8C:FE:50:E6:8D:C8:15:9B:30:86:3C:49:FA:D9:B6:BF:55:B7, Sep 26, 2017, trustedCertEntry,
    Certificate fingerprint (SHA1): 29:71:1F:5A:2D:C7:44:DA:95:45:8E:17:6C:04:A6:0C:8E:06:39:A4

  17. Dear David MARTIN, thanks for your message, I'm glad to see that you have found the solution.

    Do not hesitate to use our JIRA is you need support

    Please note that the certificates you are using are self signed and only for Testing purpose, we are currently using Gazelle IHE eHDSI certificates.

    Best regards

    1. Dear Jerome, all,

      I'm back with this certificates issue, and as we already have installed the rest of the artifacts, tools, etc, for us it's time to take this issue into consideration.

      You mentioned in your last comment that you were using Gazelle IHE eHDSI certicicates, Would be possible to have them?

      Thank you in advance,

      Best Regards,


  18. Anonymous

    Hi all,

    In the JNDI datasource configuration shouldn't jdbc/OPEN_ATNA datasource point to the jdbc/OPEN_ATNA?

       <ResourceLink global="jdbc/TSAM" name="jdbc/TSAM" type="javax.sql.DataSource"/>

       <ResourceLink global="jdbc/OPEN_ATNA" name="jdbc/TSAM" type="javax.sql.DataSource"/>


       <ResourceLink global="jdbc/OPEN_ATNA" name="jdbc/OPEN_ATNA" type="javax.sql.DataSource"/>

  19. Dear all,

    After deploying all the components and following all the steps I got an error while trying to access epsos-web-portal test patients (I tried with every country test patients). The output log from catalina.out: (using last version 2.5.2.RC3 for all wars: client connector, ws-server and gateway):

    2017-10-23 18:35:07,757 [http-nio-8080-exec-16] INFO - queryForPatient called for country: ES
    2017-10-23 18:35:07,758 [http-nio-8080-exec-16] INFO - Patient ids: '[ label: domain: 2.16.724.4.41 value: 1199925 max: null min: null, label: domain: 2.16.724.4.42 value: 803409 max: null min: null]
    2017-10-23 18:35:07,766 [http-nio-8080-exec-16] ERROR - Failed to query for patient, Webservice is not initialized Webservice is not initialized
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(
    at java.lang.reflect.Method.invoke(
    at org.apache.wicket.proxy.LazyInitProxyFactory$JdkHandler.invoke(
    at org.apache.wicket.proxy.$Proxy117.queryForPatient(Unknown Source)
    at org.apache.wicket.ajax.markup.html.form.AjaxButton$1.onSubmit(
    at org.apache.wicket.ajax.form.AjaxFormSubmitBehavior.onEvent(
    at org.apache.wicket.ajax.AjaxEventBehavior.respond(
    at org.apache.wicket.ajax.AbstractDefaultAjaxBehavior.onRequest(

    So I looked for the class inside and inside, and it seems as it is missing a kind of initization (shelobConnector var seems to be null):
        QueryPatientRequest queryPatientRequest = createQueryPatientRequest(patientList, country);
    List<Person> personList = new ArrayList<Person>();
        if (shelobConnector != null) {
    try {
    List<PatientDemographics> queryPatient = shelobConnector.queryPatient(queryPatientRequest);
    for(PatientDemographics dem : queryPatient) {
    } catch (Exception e) {
    throw new NcpServiceException(e.getMessage(), e);
    } else {
    throw new NcpServiceException("Webservice is not initialized", new Exception());

    So, I'm not sure if there is missing some configuration or some component...

    Thank you in advance,

    1. Dear David MARTIN, have you checked for the additional instructions for configuring epSOS-web? They are available here: epSOS-Web/Get Started. It looks like you are missing the -Dclient-connector-wsdl-url address in your Tomcat. As a second possibility, the NCP's client connector might be not running or not initialized properly.

  20. Thank you Konstantin HYPPÖNEN,

    Yes, I've already followed the steps, and my JAVA_OPTS is like:


    • I tried to use NcpServiceFacadeMock instead of NcpServiceFacadeImpl, and at least I can see the next page, so the problem must be in the call to the web service.

    • On the other hand I tried to make a raw call to the connector web service using one of the unit tests, and got an initialization error on

    <S:Envelope xmlns:S="">
    xmlns:wsse="" />
    <arg0>anybody there?</arg0>


    22:39:27.248+02:00 [http-nio-8080-exec-3] ERROR o.a.axis2.transport.http.AxisServlet.error(90) - Could not initialize class
    java.lang.NoClassDefFoundError: Could not initialize class
    at org.apache.axis2.engine.Phase.invokeHandler(
    at org.apache.axis2.engine.Phase.invoke(
    at org.apache.axis2.engine.AxisEngine.invoke(
    at org.apache.axis2.engine.AxisEngine.receive(
    at org.apache.axis2.transport.http.HTTPTransportUtils.processHTTPPostRequest(
    at org.apache.axis2.transport.http.AxisServlet.doPost(
    at javax.servlet.http.HttpServlet.service(
    at javax.servlet.http.HttpServlet.service(
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(

    By looking deeper, as far as I can, wrong initialization could be because ConfigurationManagerService is not working. I have even three different config files for hibernate, all three have similar database config:

       -rwxrwxrwx 1 tomcat tomcat 1182 Oct 23 19:54 configmanager.cfg.xml
       -rwxrwxrwx 1 tomcat tomcat 1693 Oct 18 17:25 configmanager.hibernate.xml
       -rwxrwxrwx 1 tomcat tomcat 1406 Oct 3 13:36 database.config.xml

    I'm getting a bit desperate because jar dependencies seem to be in the right place.

    Did anyone of you faced similar problems?

    Best Regards,


    1. Hi,

      I finally found the answer. It was an issue with the missing dependencies of jaxb at openncp-web-portal. I suggest including such libraries in newer war versions.

      Best regards,

  21. Dear all,

    Following the steps of this manual, I have to populate ehelath_ltr database from TSAM services:

    Also check:

     However I don’t have a user / pass yet. How could I get one?




        username: tsam_user

        password: password

    Thank you in advance,

    1. Dear David MARTIN,

      A user has been created for you in the training environment. The problem is that your base-url refers to the production environment. Please change it to: and use the credentials that have been created for you.

      1. Thank you Mathias, after agreeing the value set catalog, the TSAM ltrdb is sync now (smile)

      2. I am having trouble with this. Maybe I need a user. How can it be created?

        1. Dear Abel Tenera , thank for your message and sorry if I misunderstood but as I don't know you as a "power user" of the eHDSI CEF project, could you please send an email to the eHDSI support service with a short introduction and also if you need credentials, could you please create a ticket for this with detailed information. Best regards. Thanks in advance.

          1. I am recent on this. I am assembling open ncp for Portugal, for healtheid project. How do I contact them?

            1. Dear Abel Tenera , you can contact them by email: . They will follow up your request.

  22. Dear all,

    I have a general question about using any of the two choices

    • OpenNCP Portal (deployed on Liferay Community Server)
    • epSOS-Web (deployed on Tomcat)

    We are testing OpenNCP from SHIELD project at Ibermatica, so we installed the two options to test them. We are currently using the second one (epSOS-Web portal) as we managed to test all modules properly while we had some trouble with the Liferay portal which only works partially.

    I have not clear which option has a higher level of maturity, as I can see clearly that Liferay provides more reliable membership features. On epSOS Web users are stored on a unsecure users.xml.

    My questions are:

    ¿In epSOS Web would be possible to change the authentication provider to a custom membership feature?
    ¿Would you recommend to use Liferay site instead of epSOS portal?

    Thank you in advance,

    1. Dear David MARTIN,

      The OpenNCP Reference Implementation is providing as extra components 2 different clients inherited from previous Pilots.

      These 2 clients are provided for testing purpose only as the client is a National responsibility. Changes on the Portal might be addressed to the Technical Committee (could you please provide more details on "Custom Membership feature"?

      I will also recommend you to use the OpenNCP Liferay Portal as this is the one on which the Service Provider is doing technical support.

      Please let us know if you have any other question?

      Best Regards.

  23. Is the configuration file "" still used? Because it appears in the documentation and in but I did'nt use it

  24. It's look like and are not used anymore can we removed them from the documentation and from the ?

    1. is used. is not. You'll see an exception in the Portal log during its deploy complaining that it couldn't find this file, but the deploy will progress nevertheless.

      1. Well seen João GONÇALVES (smile) ! We already use the database "ehealth_properties" to recover some properties. As an improvement, can we delete this file and pass the properties in the database (if necessary)?

  25. What is the OpenNCP Gateway purpose?

    1. Dear Boromé Colombi

      As you will know, the eDelivery Service Metadata Publishing (SMP) building block is used for publishing service metadata of the different deploying countries. This can be seen as a central storage of service metadata files of all the different deploying countries. If a Country-B wants to communicate with a Country-A, it first requests the service metadata of Country-B on the SMP server in order to know for example the IP address of the service.

      The OpenNCP Gateway is a web application that allows the different deploying countries to create such service metadata files, to sign them using there signature certificate and to manage them on the SMP server (load/edit/delete). The OpenNCP Gateway is deployed at the deploying country level and just permits the management of the service metadata files on the central configuration service (SMP).

      1. Thank you for your answer,

        Are these metadata requested at each request? Or is these some sync/poll/cache mechanism involved?

  26. Section 4.3.1 of this installation manual mentions two SMP file. Which one is XCPD in the gateway select menu?

    1. Patient Identification and Authentication corresponds with the XCPD profile.

      I added the info in the relevant paragraph.

  27. I didnt find script to create the openncp-gateway security tables. I end up writting it for mysql:

      `id` bigint(20) NOT NULL AUTO_INCREMENT,
      `role` varchar(50) NOT NULL,
      `description` varchar(255) NOT NULL,
      PRIMARY KEY (`id`),
      UNIQUE KEY `role` (`role`)

      `id` bigint(20) NOT NULL AUTO_INCREMENT,
      `username` varchar(50) NOT NULL,
      `password` varchar(255) NOT NULL,
      PRIMARY KEY (`id`)

    CREATE TABLE IF NOT EXISTS `user_role` (
      `user_id` bigint(20) NOT NULL,
      `role_id` bigint(20) NOT NULL,
      KEY `FK__user` (`user_id`),
      KEY `FK__role` (`role_id`),
      CONSTRAINT `FK__role` FOREIGN KEY (`role_id`) REFERENCES `role` (`id`),
      CONSTRAINT `FK__user` FOREIGN KEY (`user_id`) REFERENCES `user` (`id`)
    1. Dear Boromé Colombi , you are currently trying to install the DEVELOP branch which is not yet released, that's why some information are currently missing with this SNAPSHOT version of 2.5.3.

  28. Jerome SUBIGER, what were the changes on the openncp configuration file?

    Thank you

    1. Dear Abel Tenera , latest update on file has been related to the activation of Audit Trails messages when the Pivot Transformation are processed.

      It was set to false by default and now the value is true by default (tm.audittrail.enabled=true for Event Type: epsos-94).

      1. Hi Jerome SUBIGER , please add release notes everytime a new version of the same file is uploaded (there's a textbox for that), otherwise it's impossible to know all the changes and we might be missing something on our installations (and completely replacing openncp-configuration in our environments everytime there's an update is not an option).