XDStarClient - Installation & Configuration

Here is a guide to help you installing XDStarClient.

Requirements

Debian squeeze or ubuntu 12.04/14.04 64bits with an Internet access.

Database : PostGresql 9.4
Java virtual machine : JDK 1.7
Application server : Jboss 7.2.0.Final

To install those requirements you need to follow instructions of installation of jboss7 : https://gazelle.ihe.net/content/general-considerations-jboss-7

Quick start

XDStarClient can be installed using gazelle user on your server:

wget https://gazelle.ihe.net/jenkins/job/XDStarClient/ws/install_xdstar_client.sh
wget https://gazelle.ihe.net/jenkins/job/Installer_script/ws/jboss7/common.sh
sudo chmod +x install_xdstar_client.sh
sudo chmod +x common.sh
sudo ./install_xdstar_client.sh $HOSTANDPORT

$HOSTANDPORT are the host and the port number to which your application will deployed, you may use the value localhost:8380 if you are testing locally and you have not changed the configuration of your jboss7 installed.

It will:

Backup the previous EAR
Get the latest released version of XDStarClient and deploy it in your jboss.
Create the database if it doesn’t exists.
Create /opt/XDStarClient folder (used for validation, samples storage) if this folder is not already there

All these steps are done by the script. The next paragraph are only details of how these steps are done (for developper who need more details).

Compile Sources

XDStarClient is an open source project under Apache2 licence. The sources are available on the IHE’s gitlab server:

git clone https://gitlab.inria.fr/gazelle/public/simulation/xdstar-modules
git clone https://gitlab.inria.fr/gazelle/public/simulation/xdstar-client

Before compiling, go to the directory XDStarClient and edit the file pom.xml. Open this file and adapt the properties of profile prod to your case :

jdbc.connection.url : jdbc:postgresql:xdstar-client jdbc.connection.user / jdbc.connection.password : credentials for database access

cd XDStar-modules/
mvn clean install
cd ../XDStarClient/
mvn clean package -U -Pproduction

The archive (EAR) and the distribution file are created and placed into XDStarClient /XDStarClient-ear/target directory. If maven cannot download dependencies checkout the maven configuration guide: https://gazelle.ihe.net/content/development-support-tools

Database creation

The names of the databases are defined in the pom.xml file. Use the following commands :

su postgresql
psql
postgres=\# CREATE DATABASE "xdstar-client" OWNER gazelle ENCODING UTF-8;
postgres=\# \\q
exit

Deployment

To deploy XDStar Client :

Paste the archive XDStarClient.ear in the JBoss deployment directory ${JBOSS7\_HOME}/standalone/deployments/
Display JBoss server logs, start JBoss and wait for ear deployment.
The application can be browsed at http://localhost:8080/XDStarClient. Port could also be different whether you have modified the JBoss configuration.
WARNING : From version 2.4.0, datasources have been extracted from the ear. The template file can be found in /src/main/application/datasource in the source or in the file XDStarClientDS-X.X.X-datasource.zip from the nexus. For more informations about how to manage that externalization, please refer to general considerations for JBoss7.

Datasource name : XDStarClientDS

Database name : xdstar-client

Insert configuration values

To insert values you can connect to the database:

psql -U gazelle xdstar-client

Then copy paste the folowing script:

INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'cda.xsl', 'cda_xsl_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'XDR Test Pratician', 'default_pratician_id');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'UTC+01', 'application_time_zone');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/jira/browse/XDSTAR', 'application_issue_tracker_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'XDStarClient', 'application_name');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/jira/browse/XDSTAR#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel', 'application_release_notes_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/content/xdstarclient', 'app_documentation');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/xsl/xdsDetailedResult.xsl', 'validation_result_xslt');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'NOVAK', 'family');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'JAN', 'given');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '19501201', 'birthdate');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'root');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'gender');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'extension');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'street');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'city');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'country');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'postalcode');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'maidenname');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '50000', 'connection_timeout');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/xsl/mbcdaDetailedResult.xsl', 'cda_mbv_xslt');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/usr/bin/', 'dicom3tools_validator');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/xsd/IHE/XDSI.b_ImagingDocumentSource.xsd', 'xds_xsd');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/xsd/DSUB/soap-envelope.xsd', 'dsub_xsd');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/', 'server_local_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'hra@kereval.com', 'application_admin_email');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'N/A', 'consent_template_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'N/A', 'dds_web_service');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'N/A', 'dispensation_template_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'N/A', 'epsosFolder');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/uploadedFiles', 'registered_files_directory');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/tmp', 'uploadFolder');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'N/A', 'xdstool_xca_query_wsdl');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'SAMEORIGIN', 'X-Frame-Options');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'private, no-cache, no-store, must-revalidate, max-age=0', 'Cache-Control');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'max-age=31536000 ; includeSubDomains', 'Strict-Transport-Security');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '', 'X-Content-Security-Policy');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'Use X-Content-Security-Policy values', 'X-WebKit-CSP');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'Use X-Content-Security-Policy-Report-Only values', 'X-WebKit-CSP-Report-Only');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'false', 'sql_injection_filter_switch');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'true', 'security-policies');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/china.jks', 'truststore_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'tomcat', 'key_alias');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'password', 'key_pass');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'password', 'keystore_pass');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'true', 'avoid_nist_validation_ihe');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/SchematronValidator-SchematronValidator-ejb/ScchematronValidatorWS?wsdl', 'schematron_validator');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'default-src ''self'' *.ihe.net *.ihe-europe.net *.ihe-c.org; script-src ''self'' ''unsafe-eval'' ''unsafe-inline''; style-src ''self'' ''unsafe-inline'';', 'X-Content-Security-Policy-Report-Only');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.1.', 'document_root_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.2', 'epsos_source_root_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.3', 'homeCommunityID');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.4', 'home_root_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.5', 'ihe_source_root_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '1.3.6.1.4.1.12559.11.13.2.6.', 'submission_set_root_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'Hilary Ramanantsalama', 'application_admin_name');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/AssertionManagerGui', 'assertion_manager_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'false', 'display_KSA_menu');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/attachments/', 'attachement_files_directory');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/CDAGenerator-CDAGenerator-ejb/CDAValidatorWS?wsdl', 'cda_mbv_wsdl');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/CDAGenerator-CDAGenerator-ejb/CDAValidatorWS?wsdl', 'cda_mbv_wsdl');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'http://localhost/XDStarClient-XDStarClient-ejb/DSUBRecipientWS?wsdl', 'xdstar_dsub_recipient_endpoint');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/XDStarClient/', 'gazelle_home_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '2.16.840.1.113883.3.3731.1.1.100.1', 'ksa_aa_oid');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'http://localhost/XDStarClient-XDStarClient-ejb/XDSDeletetWS?wsdl', 'xdstar_delete_doc_endpoint');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/home/aboufahj/Téléchargements/36667D66.dcm', 'ksa_manifest_file');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/SVSSimulator/rest/RetrieveValueSetForSimulator', 'svs_repository_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/XDStarClient/', 'application_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/EVSClient/', 'evs_client_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/xdstools2/', 'ksa_xdstools_url');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'false', 'display_IHE_RAD_menu');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'false', 'display_IHE_ITI_menu');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'false', 'ip_login');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'true', 'cas_enabled');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '.*', 'ip_login_admin');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '20', 'NUMBER_OF_ITEMS_PER_PAGE');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), '/opt/gazelle/cert/keystore.jks', 'keystore_path');
INSERT INTO app_configuration VALUES (nextval('app_configuration_id_seq'), 'https://gazelle.ihe.net/gazelle-documentation/XDStar-Client/user.html', 'documentation_url');

Finally When the application is deployed, open a browser and go to http://localhost:8080/XDStarClient. If the deployment and the database initialization are successful you should see the home page.

List of application preferences

Properties	Description	Default
app_documentation	official documentation	https://gazelle.ihe.net/content/xdstarclient
application_admin_email	email of the admin	hra@kereval.com
application_admin_name	Admin name	Hilary Ramanantsalama
application_issue_tracker_url	issues tracker’s url	https://gazelle.ihe.net/jira/browse/XDSTAR
application_name	application name	XDStarClient
application_release_notes_url	release notes’ url	https://gazelle.ihe.net/jira/browse/XDSTAR#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel
application_time_zone	time zone	UTC+01
application_url	the url of XDStarClient (too important as it is used by permanent links)	https://gazelle.ihe.net/XDStarClient/
assertion_manager_url	URL to the assertion manager used	https://gazelle.ihe.net/AssertionManagerGui
attachement_files_directory	file directory on the server, where documnent uploaded and downloaded will be saved	/opt/XDStarClient/attachments/
avoid_nist_validation_ihe	set to false when validation using the nist validator is performed	true
birthdate	used for initialization for XCPD request	19501201
Cache-Control	security parameter	private, no-cache, no-store, must-revalidate, max-age=0
cda_mbv_wsdl	link to the CDA MBV tool ws	https://gazelle.ihe.net/CDAGenerator-CDAGenerator-ejb/CDAValidatorWS?wsdl
cda_mbv_xslt	link to the stylesheet to render the result of validation of a CDA document	https://gazelle.ihe.net/xsl/mbcdaDetailedResult.xsl
cda_xsl_path	link to the stylesheet to render a cda document	cda.xsl
city	used for initialization for XCPD request	Valeur de la préférence
connection_timeout	When the client want to rich a responder, this represent the time in millisecond, that the client shall wait before closing the connection	50000
consent_template_path		N/A
country	used for initialization for XCPD request	Valeur de la préférence
dds_web_service	used to call DDS webservice	N/A
default_pratician_id	used for epSOS purpose	XDR Test Pratician
dicom3tools_validator	path where the dicom3tools is installed	/usr/bin/
dispensation_template_path	used for epSOS purpose	N/A
display_IHE_ITI_menu	display, or not, the IHE ITI transactions	false
display_IHE_RAD_menu	display, or not, the IHE RAD transactions	false
display_KSA_menu	display, or not, the KSA transactions	false
document_root_oid	unique identifier of documents	1.3.6.1.4.1.12559.11.13.2.1.
documentation_url	link to the documentation	https://gazelle.ihe.net/gazelle-documentation/XDStar-Client/user.html
dsub_xsd	path to the schema of DSUB	/opt/XDStarClient/xsd/DSUB/soap-envelope.xsd
epsosFolder	used for epSOS purpose	N/A
epsos_source_root_oid	used for epSOS purpose	1.3.6.1.4.1.12559.11.13.2.2
evs_client_url	link to evs client tool	https://gazelle.ihe.net/EVSClient/
extension	used for initialization for XCPD request	Valeur de la préférence
family	used for initialization for XCPD request	NOVAK
gazelle_home_path	path to a folder used by the tool	/opt/XDStarClient/
gender	used for initialization for XCPD request	Valeur de la préférence
given	used for initialization for XCPD request	JAN
homeCommunityID	used by the XSD.b requests	1.3.6.1.4.1.12559.11.13.2.3
home_root_oid	used by the XSD.b requests	1.3.6.1.4.1.12559.11.13.2.4
ihe_source_root_oid	used by the XSD.b requests	1.3.6.1.4.1.12559.11.13.2.5
key_alias	the alias of the keystore used for ssh connexion with responders	tomcat
key_pass	password of the key	password
keystore_pass	password of the keystore	password
keystore_path	the keystore location	opt/gazelle/cert/keystore.jks
ksa_aa_oid	assigning authority OID, for patients	2.16.840.1.113883.3.3731.1.1.100.1
ksa_manifest_file	Manifest used in test plan, only related to k-project	/../36667D66.dcm
ksa_xdstools_url	link to xdstools2 (only related to k-project)	https://gazelle.ihe.net/xdstools2/
maidenname	used for initialization of XCPD request	Valeur de la préférence
NUMBER_OF_ITEMS_PER_PAGE		20
postalcode	used for initialization of XCPD request	Valeur de la préférence
registered_files_directory	used by the ITI-41 transaction	/opt/XDStarClient/uploadedFiles
root	used for initialization of XCPD request	Valeur de la préférence
schematron_validator	path to the ws of schematronValidator	https://gazelle.ihe.net/SchematronValidator-SchematronValidator-ejb/SchematronValidatorWS?wsdl
security-policies	confirm if security is used	true
server_local_path	path to a folder on the server	/opt/XDStarClient/
sql_injection_filter_switch	security parameter	false
street	used for initialization of XCPD request	Valeur de la préférence
Strict-Transport-Security	security parameter	max-age=31536000 ; includeSubDomains
submission_set_root_oid	used by ITI-41 transaction	1.3.6.1.4.1.12559.11.13.2.6.
svs_repository_url	link to SVS rest service	https://gazelle.ihe.net:8180/SVSSimulator/rest/RetrieveValueSetForSimulator
truststore_path	path to the keystore	/opt/china.jks
uploadFolder	path to folder for uploading file	/opt/XDStarClient/tmp
validation_result_xslt	path to xds transformer of validation result	https://gazelle.ihe.net/xsl/xdsDetailedResult.xsl
X-Content-Security-Policy	security parameter	Valeur de la préférence
X-Content-Security-Policy-Report-Only	security parameter	default-src ‘self’ .ihe.net .ihe-europe.net *.ihe-c.org; script-src ‘self’ ‘unsafe-eval’ ‘unsafe-inline’; style-src ‘self’ ‘unsafe-inline’;
xdstar_delete_doc_endpoint	endpoint link to the delete webservice	http://127.0.0.1:8180/XDStarClient-XDStarClient-ejb/XDSDeletetWS?wsdl
xdstar_dsub_recipient_endpoint	endpoint link to the dsub recipient webservice	http://127.0.0.1:8180/XDStarClient-XDStarClient-ejb/DSUBRecipientWS?wsdl
xds_xsd	link to the schema of XDS-I.b	/opt/XDStarClient/xsd/IHE/XDSI.b_ImagingDocumentSource.xsd
xdstool_xca_query_wsdl		N/A
X-Frame-Options	security parameter	SAMEORIGIN
X-WebKit-CSP	security parameter	Use X-Content-Security-Policy values
X-WebKit-CSP-Report-Only	security parameter	Use X-Content-Security-Policy-Report-Only values

SSO Configuration

There are additional preferences to configure the SSO authentication.

Preference name	Description	Example of value
cas_enabled	Enable or disable the CAS authentication.	true
ip_login	Enable authentication by IP address matching `ip_login_admin` regex.	false
ip_login_admin	Regex to authorize ip authentication if CAS authentication is disabled.	.*

For more documentation about SSO configurations, follow the link here.

XDStar Client Administration guide 2.5.x Installation manual 3.X.X Release note 3.0.4 User manual 3.X.X