This installation manual was based on an installation with the following software:
- You should be using the latest version of Java 1.7 (version 1.8 is still not supported). You should also use Tomcat version 7 (version 8 is still not supported). S Issue with Java 1.7.0-25, we should recommend to use the latest JDK1.7.
- Don't forget to give execution permission to the files in the bin folder.
- Add the JDBC connector (JAR file) of your database to your Tomcat's lib folder.
- 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.
- Joao Cunha - Change TSL-Sync bullet to JAR: "TSL-Sync (JAR)"
S If the NCP uses an infrastructure with proxy, we need to add info related to the new proxy configuration setup included into the epsos-utility Jar.
- Joao Cunha - epsos-configuration.zip is missing 2 folders and 1 file (see attachments at the end of this page):
- Joao Cunha - How do PN's know their OID (used in pn-oid.xml)?
- Stéphane Spahni - 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 (2.16.17.710.8xx.1000.990.1). At the end, at least for PRODUCTION, each country should get (buy) its own OID from HL7.
- 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://ecrtsppt.conet-services.de:8445/common_files/
- In MySQL, the database name does not support dots ('.'), so the database should be named "epsos_properties".
- Joao Cunha - The hibernate file already exists in EPSOS_PROPS_PATH and should already have the configuration shown. In case you're using MySQL, to avoid a "portalb is temporarily unavailable" error message in the Portal due to MySQL's wait_timeout being exceeded (that is, no requests made during that time), you should use the following setup:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//EN" "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"> <hibernate-configuration> <session-factory> <property name="hibernate.dialect">org.hibernate.dialect.MySQLDialect</property> <property name="hibernate.connection.driver_class">com.mysql.jdbc.Driver</property> <property name="hibernate.connection.url">jdbc:mysql://databasehost:3306/epsos_properties?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false</property> <property name="hibernate.connection.username">username</property> <property name="hibernate.connection.password">password</property> <!-- Echo all executed SQL to stdout --> <property name="show_sql">yes</property> <property name="hibernate.hbm2ddl.auto">update</property> <property name="hibernate.connection.provider_class">org.hibernate.connection.C3P0ConnectionProvider</property> <property name="hibernate.c3p0.min_size">1</property> <property name="hibernate.c3p0.max_size">50</property> <property name="hibernate.c3p0.timeout">7200</property> <property name="hibernate.c3p0.max_statements">50</property> <property name="hibernate.c3p0.validate">true</property> <property name="hibernate.c3p0.idle_test_period">30</property> <property name="hibernate.c3p0.preferredTestQuery">SELECT 1 FROM DUAL</property> <mapping class="eu.epsos.configmanager.database.model.Property"/> </session-factory> </hibernate-configuration> |
- Joao Cunha - Add to the properties file the following properties (and fill them):
S Adding info related to proxy configuration if needed. And it could be also relevant to know which properties are required by components and what are their roles.
Stéphane Spahni Added several keys that were in my properties file! The problem is that I am not sure they are used! Should check the source code for determining which ones are really used and which ones are inherited from the Spirit config
This file will be used to initially populate the epsos-properties database.
## Keystores and truststore -- ask Stéphane Spahni ## This will call the XDStarClient online validator to validate messages ## IP address of the machine running OpenNCP ## Audit (used in old legacy epsos.properties files from different projects, no longer used) ## OpenATNA's TLS Server port ## OpenATNA's Server location ## Timeout value (milliseconds) for sending audit message ## Force AuditManager to write audit message ## Not used ## Determines if test audits should be written # Country code according to ISO 3166-1 alpha-2 (see e.g. Wikipedia for a list of possible values) # Name of country according to ISO 3166-1 alpha-2 (see e.g. Wikipedia for a list of possible values) # Language code according to ISO 639x # Local NCP infos (used for audit purposes) # Participating Nation OID (used in Portal for patient consent submission, Protocol Terminators and eADC) # ISO 3166-2 code for country subdivision (used in Portal, Protocol Terminators, TRC-STS and epSOS Web Portal for audit purposes) ## Path where test audits will be written ## TSL-Sync ## Path to folder where the other countries certificates will be stored ## Path of the truststore generated by TSL Sync ## ## SC - service consumer certificate ## SIG - signature certificate ## Javax Parameters ## Currently, only javax.net.ssl.keyStorePassword is needed (it should have the same value as NCP_SIG_KEYSTORE_PASSWORD property). It'll also be removed in the next release of OpenNCP. ## Algorithms (no longer used; SignatureManager replaced them by references to secman.{signature|digest}.algorithm.default properties) ################################################################################### TRC-STS # # Used in old legacy epsos.properties file from Gnomon Portal, no longer used ## You'll connect to the Central Services to fetch configuration and certificates from each one of these countries ## Location of the TSL file for each country |
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.
Joao Cunha - This table should also figure in the manual:
Service | Mode | URL | Port |
---|---|---|---|
SFTP | PPT | sftp://ecrtsppt.conet-services.de/swe/ | 22 |
SFTP | PROD | sftp://ecrts.conet-services.de/swe/ | 22 |
TSAM | PPT | https://ecrtsppt.conet-services.de/webservice/commonTerminologyService2.0 | 443 |
TSAM | PROD | https://ecrts.conet-services.de/webservice/commonTerminologyService2.0 | 443 |
TSL | PPT | https://ecrtsppt.conet-services.de | 8445 |
TSL | PROD | https://ecrts.conet-services.de | 8445 |
- Create the following directory structure:
$EPSOS_PROPS_PATH |-- /cert |-- /PPT |-- /conf |-- /pem |-- /private |-- /ROOT |-- /test_requests |
- You should create the CA certificate inside ROOT folder, by running the "ROOT Certificate Creation" script.
- Put the 3 configuration files inside conf folder, like this: Stéphane Spahni: we initially had 5 certs: Service Consumer, Service Provider, VPN client, VPN server, Digital signature. VPN client seems not to be used anymore. What about SP ?
- Joao Cunha - Creation of keystore and truststore in $EPSOS_PROPS_PATH/cert/PPT ## ask Stéphane Spahni: Has to be the in same directory as mentioned in the initial config script above
- The script for creating the self signed certificates should be put in $EPSOS_PROPS_PATH/cert/PPT
- In the script there is only one variable $password but it is used both for the keystore/truststore and CA private key. If they differ, it gives an error.
- Joao Cunha - Please, confirm this issue with the script:
cat $country-ncp-obj-self-sign.pem ROOT/$country-ca.pem > pem/$password-objsign.pem
The output file should be $country-objsign.pem, otherwise you get a "keytool error: java.io.FileNotFoundException: pem/pt-objsign.pem (No such file or directory)" when trying to import the certificate to the keystore.
S Into the old installation manual, the recommandation is to create 1 keystore per service/key, but we provide a script with only one keystore generated, we could modify the keystore creation script in order to follow our recommandation or just add a warning about this topic?
Stéphane Spahni VPNserver used by OpenSwan; Service provider = NCP server certificate ? Signature = NCP's signature? Service consumer = NCP's client signature?
These scripts are only available for Linux env, should we propose one for Windows also?
A summary about the role of the keystore and the trustore could also be added to this chapter, because I remembered that I was wondering for a long time what are the role of each keystore and trustore and also which component required which key etc. and also the link with the properties stored into the EPSOSProperties database (CfgManager).
- Before the deploy, configure the jdbc/ConfMgr data source in your Tomcat conf/context.xml to connect to your epsos properties database.
OpenNCP instances need to share their configurations (endpoints, certificates, etc) with each other. The current way to do this is by placing those configurations in the central services, providing a specific kind of file: the TSL file. Each country needs to create a TSL file with its configuration and upload it to the central services. This can be done with the help of the TSL-Editor. Each country can download these files from the central services and update their local installation by running the TSL-Sync.
The complete specification of the TSL files and its usage in the eHealth domain (the specific fields and values to be used) can be found in epSOS Deliverable 3.4.2 - section 4.4 "epSOS Trusted Service List" or in Fraunhofer's Wiki page on epSOS Trust Service List - ETSI TS 102 231 Binding.
Stéphane Spahni Put a link to the tutorial videos & manual. I think there were uploaded somewhere in the wiki? Joao Cunha: well remembered, they are attached in the installation manual page, I'm going to add some text about it (Alen Vrecko (Unlicensed) check this).
You can find a video tutorial on how to use the TSL-Editor in the following attachment: Webinar TSL-Editor & SyncApp (name of file: 3_Massi_webminar_TSL-Editor. It has to be run with Netviewer_NetPlayer, also provided in the folder). In this other attachment - TSL-Editor 2.3 -, you can find some old version of TSL-Editor which packages some documentation (namely /Doc/TSL_Creation_SbS.doc) as well as a properties file (/TslEditor2.3/tsleditor.properties) that may be useful.
Regarding the "Distribution point" field, it must point to the current central services provider (CONET):
In order to be able to upload the file to the central services, a pair of SSH keys must be generated, with the public key being sent to CONET, whom must also create the username and folder for the country. For more information about CONET's contact point on this topic, please leave a request to the OpenNCP Community (for now, use the comments section of this page). The upload path will vary: in PPT environment, it'll be /sftp/<CCC>/PPT ; in Production, it'll be /sftp/<CCC> , with <CCC> being the 3-letter country code, like "GRE" for Greece, "ITA" for Italy, and so on. The uploaded file can be retrieved using the URLs listed above (port: 8445).
The "Server" field in the upload dialog box of TSL-Editor has to contain "ecrtsppt.conet-services.de" for PPT and "ecrts.conet-services.de" for Production.
It is possible to override TSLEditor properties by having a "tsleditor.properties" file in the same folder as the JAR file (e.g. to extend the list of supported locales / countries for the Scheme Territory field).
S Providing info about how to execute the script and how it works (getting the countries codes into the DB).
- After this sentence "Then, according to you configuration. present in the properties database, it will fetch all the central services informations and sync them to your key stores and properties database." add:
- Insert this property in the database:
- TSL-Sync is also available as a standalone JAR file that should be placed and run in a custom location:
/tsl-sync-custom-location |-- tsl.sync.jar |
- You'll need to add the Conet certificate to your JVM's truststore (cacerts). See this link: http://stackoverflow.com/questions/6908948/java-sun-security-provider-certpath-suncertpathbuilderexception-unable-to-find
- Edit log4j reference in sync.sh to -Dlog4j.configuration=file:///$TSAM_DIR/conf/log4j.xml ($TSAM_DIR should be a script variable that references tsam-sync folder)
- Change the following property in the tsam-sync/conf/settings.properties
- Before the deploy, configure the jdbc/TSAM data source in your Tomcat conf/context.xml to connect to LTR database (ltrdb).
- This sync.sh script has to be run manually.
- OK
- 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 your epsos-configuration/tm.properties, add the following properties:
## epSos code for MRO CDA document ## epSos code for HCER CDA document ## Joao Cunha - This schematron doesn't exist in the folder, I don't know if this should also be provided and who can we ask for it |
- Joao Cunha - Also, the following files do not exist:
# actual path to ePrescriptionFriendly Schematron file |
- 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.
Joao Cunha - I think that this section needs to be better organized
- 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:
- Certificates:
- Follow step 1 to set up the database: https://openncp.atlassian.net/wiki/display/OP/OpenATNA+Home . Joao Cunha - confirm the last command (see comments in wiki)
- 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 also may need to extend the MaxPermSize of your Tomcat instance (adding -XX:MaxPermSize=256m to your CATALINA_OPTS)
- You should add this line to the TOMCAT setenv.sh script: JAVA_OPTS="-DopenATNA.properties.path=file:$EPSOS_PROPS_PATH/ATNA_resources/openatna.properties $JAVA_OPTS"
- 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: https://openncp.atlassian.net/wiki/display/OP/OpenATNA+Home)
- OK
S Providing info about how to modify the port of the server if the NCP doesn't use the default one for axis2.xml file, the proxy etc. Perhaps adding info related to the national implementation in order to connect natinal healthcare system, a kind of how to add national impl or how to work in a mock mode etc.
- OK
S Providing info about how to modify the port of the server if the NCP doesn't use the default one for axis2.xml file, the proxy etc.
- Be aware that you cannot use the same database for different versions of Liferay (you'll get a corrupted database if you try and there's no way to restore it unless you have a backup).
- Note that the database name in the scripts ('lportal') differs from the one shown in the properties file ('lp62'), but they refer to the same database. Choose the one you like the most.
- Change Liferay's Tomcat ports to others different than the ones you're using in your OpenNCP Tomcat (the chosen ports should be available too):
<Server port="XXXX" shutdown="SHUTDOWN"> <Connector port="YYYY" protocol="HTTP/1.1" <Connector port="WWWW" protocol="AJP/1.3" redirectPort="ZZZZ" URIEncoding="UTF-8" /> |
- Create portal-ext.properties under Liferay folder
- Add the following properties to your $EPSOS_PROPS_PATH/tsam.properties (connection to your TSAM/LTR database):
## Required for OpenNCP Portal |
- In your Liferay's Tomcat, add to /conf/context.xml the same JNDI resources that you defined in your OpenNCP's Tomcat
- (Trillium): Create "hcer" database (with the script below) and set the connection properties in your $EPSOS_PROPS_PATH/hcer.properties
CREATE TABLE IF NOT EXISTS `hcerdocs` ( `documentbody` text NOT NULL, `creationDate` datetime DEFAULT NULL, `creator` varchar(255) DEFAULT NULL, `patient` varchar(255) DEFAULT NULL, `fromcountry` varchar(20) DEFAULT NULL, `docid` bigint(20) NOT NULL AUTO_INCREMENT, PRIMARY KEY (`docid`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ; |
- In order to provide eID functionality in the Point-of-Care, add the jnlp folder to your Liferay's tomcat-X.Y.ZZ/webapps folder. This folder should have the following content:
/jnlp |-- /css |-- /img |-- /js |-- README.md |-- index.html |-- richclient-X.Y.Z.jar +-- openecard.jnlp |
In each new version of the eID artifacts, the JAR file and the JNLP file must be updated. The JAR file can be found in Joinup (section 2). The JNLP can only be found in OpenNCP Bitbucket. You can download the folder contents here:
Countries providing eID capabilities for their patients at the country of treatment must update their InternationalSearchMask file to add the storkAttrib attribute to the search fields (you can check the example file from Portugal, InternationalSearch_PT.xml, in epsos-configuration/forms folder). The complete list of values for this attribute is as follows (source code here):
cardType
healthInsuranceId
surname
givenName
dateOfBirth
gender
fiscalNumber
socialSecurityNumber
civilianIdNumber
issueDate
terminationDate
photo
Currently, eID only works for smart cards from the following countries: Portugal, Luxembourg, Italy, Greece and Spain. In order to electronically identify a patient from any other country, that country must provide sample cards to the community first, so that OpenNCP can be enhanced. |
- Start Liferay's Tomcat in order to create the deploy folder (zip file doesn't have it due to being an empty folder) and follow the setup wizard to create the default users and other data in the database
- Add some content to epsosportal/WEB-INF/classes/portlet.properties: http://liferay-hacks.blogspot.pt/2014/02/the-curse-of-empty-portletproperties.html
- Joao Cunha - Add this to the script: INSERT INTO PROPERTY VALUES ('PORTAL_CONSENT_ENABLED','true');
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): TSAM Exporter
This application is a standalone JAR file that can be placed in a custom location:
/tsam-exporter |-- epsos-tsamexporter.jar |-- logging.properties |-- run.sh +-- settings.properties |
- OK
/opt |-- /apache-tomcat-7.X.XX | |-- /bin | +-- /conf | |-- context.xml | |-- /logs | |-- /temp | |-- /work | +-- /webapps | |-- /epsos-client-connector | |-- /epsos-ws-server | |-- /TRC-STS | +-- /atna |-- /tsam-sync | |-- /conf | | |-- epsos.properties | | |-- hibernate.cfg.xml | | |-- log4j.xml | | |-- logging.properties | | +-- settings.properties | |-- /lib | | +-- jdbc-connector.jar | |-- tsam-sync.jar | +-- sync.sh |-- /tsl-sync | |-- epsos-tsl-sync.jar |-- /tsam-exporter | |-- epsos-tsamexporter.jar | |-- logging.properties | |-- run.sh | +-- settings.properties +-- /epsos-configuration |-- /ATNA_resources |-- /cert |-- /EADC_resources |-- /EpsosRepository |-- /forms |-- /TM_resources |-- configmanager.hibernate.xml |-- hcer.properties |-- pn-oid.xml |-- ISO_3166-1.xml |-- tm.properties +-- tsam.properties |