HDR implements the Cross-Enterprise Document Sharing-b (XDS.b) specification of the Information Technology Infrastructure (ITI) profile from Integrating the Healthcare Enterprise (IHE) standard.
IHE IT Infrastructure Integration Profiles, offer a common language that healthcare professionals and vendors can use to discuss integration needs of healthcare enterprises and the integration capabilities of information systems in precise terms. Integration Profiles specify implementations of standards that are designed to meet identified clinical needs. They enable users and vendors to state which IHE capabilities they require or provide, by reference to the detailed specifications of the IHE IT Infrastructure Technical Framework.
Integration profiles are defined in terms of IHE Actors and Transactions. Actors are information systems or components of information systems that produce, manage, or act on information associated with clinical and operational activities in the enterprise. Transactions are interactions between actors that communicate the required information through standards-based messages.
For a detailed description of the IHE standard and the various profiles in IHE standard, refer to http://www.ihe.net
.
Cross-Enterprise Document Sharing (XDS) enables a number of healthcare delivery organizations belonging to an XDS Affinity Domain (for example, a community of care) to co-operate in the care of a patient by sharing clinical records in the form of documents as they proceed with their patients' care delivery activities. Federated document repositories and a document registry create a longitudinal record of information about a patient within a given XDS Affinity Domain. This profile is based upon Electronic Business using eXtensible Markup Language (ebXML) Registry standards, Simple Object Access Protocol (SOAP), Hypertext Transfer Protocol (HTTP), and Simple Mail Transfer Protocol (SMTP). It describes the configuration of an ebXML Registry in sufficient detail to support Cross Enterprise Document Sharing.
As an XDS.b Document Repository actor, HDR is capable of storage and retrieval of electronic health record documents through web services.
The Web services implemented in HDR for supporting Document Repository actor are:
Provide and Register Document Set-b - ITI-41
Retrieve Document Set - ITI-43
Asynchronous Provide and Register Document Set-b
Asynchronous Retrieve Document Set
Configure Registry for Accepting Register Document Set-b Web Service Calls
User Creation in 'myrealm' WebLogic Server realm for IHE XDS.b Web Services
Configure ITI-42 Timeouts for IHE XDS Registry Web Service Call
Configure Registry for Accepting Delete Document Set ITI-62 Web Service Calls
Configure HDR To Accept Web Services Invocation Over http Protocol
Configure MTOM/ XOP for the ITI-43 Transaction (Retrieve Document Set)
HDR exposes a set of configuration APIs as EJB session beans, to configure the profile options used by HDR as a Document Repository actor. Use the IHEXDSConfigService
API and its following methods for this purpose:
configureRegistryServerDetails(String registryURL)
configureSyslogAuditServerDetails(String syslogServerHost, String syslogServerPort, String transportProtocol)
configureRepositoryUniqueId(String repositoryUniqueId)
configureRegistryAsyncURL(String registryAsyncURL)
The registry server URL has to be configured for enabling HDR to send Register Document Set-b request web service calls to external document registries.
The registry URL should be a valid web service endpoint URL implementing XDS.b Register Document Set-b specification.
The web service end point URL could be an http URL or secure https URL. In case of https connections to registry server, the necessary truststore and keystore files need to be generated and configured in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml under the REGISTRY_AUDIT_SERVER_SSL_CONFIG configuration name.
where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of WebLogic domain.
Refer to: http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html
to learn more about digital certificates and using jdk's keytool to generate keystore and truststore.
HDR generates the following Syslog audit event messages:
Actor Start Audit Event
Actor Stop Audit Event
Local user authentication success or failure audit event
Security Alert Audit Event for change in System configurations
Register Document Set Audit Event
Provide and Register Document Set Audit Event
Retrieve Document Audit Event
HDR can be configured to send audit messages to syslog audit server over UDP or TLS protocol. The Syslog audit messages are per RFC 5424 standard.
You must configure the Syslog audit server host, port number, and transport protocol (UDP or TLS) profile options to enable HDR to send audit messages to Syslog audit server. The Syslog server host and port number should be a valid server host and port number.
You must configure the HDR Document Repository's Unique Id. This id will be added to the Register Document Set-b requests sent out by HDR to external registry. The Repository Unique Id should be a valid OID.
Create the user IHE_XDS_USER in WebLogic default server realm'myrealm' for IHE XDS.b Web services.
Time synchronization is important for security and auditing purpose to provide a synchronized time trail in the logs. It is also important in Web service security where the client can send a timestamp. In this way, no one snooping the traffic on the wire can affect a replay of the packet being sent, as the server will report an error once the timestamp has expired.
The IHE Consistent Time Integration Profile provides a means to ensure that the system clocks and timestamps of many computers in a network are well synchronized. It specifically means the servers and clients in the system must have their system time synchronized with a Time Server. This can be achieved in a Linux server by setting up the Network Time Protocol (NTP) service to synchronize with the Time Server.
Once the machine starts, identify a Time Server with which you need to synchronize your machine, and perform the following steps:
Log in as root.
Change the time zone to your required location. For example, to change to a Central Time Zone, run the command:ln -sf /usr/share/zoneinfo/CST6CDT /etc/localtime
Edit /etc/ntp.conf by adding the following line, and save it:server 10.1.1.1
#Any Time Server you want to synchronize with
Check whether the ntpd service is running using the following command:service ntpd status
If the ntpd service is not stopped, run the command:service ntpd stop
Make the first-time synchronization using the following command:ntpdate 10.1.1.1
Make the second and subsequent synchronizations (if required) by using the same command above until the offset shows 0.xxxx or -0.xxxx.
Now start the ntpd service using the following command:service ntpd start
To enable the ntpd service to run all the time even after restart, run the following command:chkconfig --level 2345 ntpd on
To query the time synchronization status, issue the following command:ntpq -p -n
Perform the above steps both on the HDR host OS.
Shut down the WebLogic Managed Server on which HDR is deployed to, and bring it up after the setup.
Set HDR for TLS Communication with Document Source and Document Consumer
Set Up HDR for TLS Communication with Document Registry and Syslog Audit Server
A Secure Node is a system unit that validates the identity of any user as well as any other node, and determines whether this user is allowed to access the system and exchange information with other nodes or not.
A Secure Application provides security features only for the application features. HDR's IHE XDS.b is a Secure Application. The difference between the Secure Node and the Secure Application is the extent to which the underlying operating system and other environments are secured. A Secure Node includes all aspects of user authentication, file system protections, and operating environment security. The Secure Application is a product that does not include the operating environment.
HDR requires certificates to be loaded into the Keystore & Truststore of WebLogic Managed Server for TLS communication with Document Source actors and Document Consumer actors.
To configure the Identity and Trust for WebLogic Server, follow the steps provided in the link http://docs.oracle.com/middleware/1212/wls/SECMG/identity_trust.htm#i1196575
.
Enable SSL to secure communication between client and the HDR application. For configuring the SSL, follow the steps provided in the link http://docs.oracle.com/middleware/1212/wls/SECMG/ssl.htm#i1194343
. Under Advanced section of SSL configuration, set Hostname Verification to None, enable Use Server Cert’, and set Two Way Client Cert Behaviour option to Client Certs Requested and Enforced.
Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml
and enter the absolute paths to trustStore, keyStore and values for trustStorePassword, keyStorePassword, keyStoreType and cipherSuites that will be used for secure TLS communication with Document Registry and Syslog Audit Server under configuration item with name REGISTRY_AUDIT_SERVER_SSL_CONFIG. Enter comma seperated names of the cipher suites to be used for TLS communication for cipherSuites.
Configuration parameter netDebug can be set to any of the valid values application for JVM argument javax.net.debug
These configuration parameters will be used to set the java runtime arguments javax.net.ssl.trustStore, javax.net.ssl.keyStore, javax.net.ssl.trustStorePassword, javax.net.ssl.keyStorePassword, javax.net.ssl.keyStoreType, javax.net.debug and https.cipherSuites.
HDR provides the capability of logging OS Level Authentication Events to qualify as a Secure Node actor.
Perform the following steps on the remote machine where HDR is deployed:
Log in to the machine as root user and edit the file /etc/syslog.conf to add the following entry:authpriv.* |/var/log/syslog_auth.pipe
Create a named pipe 'syslog_auth.pipe' under the /var/log directory by using the mkfifo command, as follows:> cd /var/log > mkfifo syslog_auth.pipe
Change the owner and group of the pipe to <OS User>. Since the shell script that would read the content from this file will be somewhere in <OS User> home directory, change the owner and group of this file using the following commands:> chown <OS User> syslog_auth.pipe > chgrp <OS User> syslog_auth.pipe
Restart the syslog service using the following command:> service syslog restart
„Log in to the machine as <OS User>, and create a script, send_audit_event_for_user_authentication.sh. Copy the following content to that file. Also, ensure that Java 1.7 executable is in the path
#!/bin/sh #update the log file location logFile=/home/hiauser/atna.log #update the logging.properties file location log4JFile=/home/hiauser/logging.properties transportProtocol="" wlHost="" wlPort="" wlUserName="" wlPassword="" keystore="" keystore_password="" truststore="" truststore_password="" tmpPswd=somePswd tmpPswdCnfm=somePswd tmpInput="" function getPassword { read -s -p "Please enter $1: " tmpPswd echo read -s -p "Confirm password: " tmpPswdCnfm echo if [ "$tmpPswd" = "$tmpPswdCnfm" ] then echo else echo "Entered password did not match, exiting." tmpPswd="" tmpPswdCnfm="" exit 1; fi } function getInput { for i in {1..3} do read -p "Please enter $1:" tmpInput echo if [ "$tmpInput" != "" ] then break fi if [ "$i" -eq 3 ] then echo "Did not get the input, exiting." exit 1; fi done } #How do you want to send the audit messages to Audit Repository server, over TLS or UDP? getInput "TransportProtocol (UDP or TLS)" transportProtocol=$tmpInput # WebLogic Host getInput "Weblogic Managed Server Host" wlHost=$tmpInput # WebLogic Port getInput "Weblogic Managed Server Port" wlPort=$tmpInput # WebLogic Admin UserName getInput "Weblogic UserName" wlUserName=$tmpInput # WebLogic Adin User Password getPassword "Weblogic Password" wlPassword=$tmpPswd if [ "$transportProtocol" == "TLS" ]; then #The keystore file location. getInput "Absolute Path to Keystore File" keystore=$tmpInput #The keystore password getPassword "Keystore Password" keystore_password=$tmpPswd #The truststore file location. getInput "Absolute Path to Truststore File" truststore=$tmpInput #The truststore password getPassword "Truststore Password" truststore_password=$tmpPswd fi #<Weblogic home> - represents the WebLogic home and should be replaced with the actual file path where WebLogic is installed. #<HDR product install home> - represents the HDR product install home and should be replaced with the actual file where HDR product is installed. CLASSPATH=<Weblogic home>/oracle_common/modules/javax.ejb_3.2.0.jar:<HDR product install home>/weblogic/jars/hdrclnt.jar:<HDR product install home>/weblogic/jars/wlfullclient.jar if [ "$transportProtocol" == "UDP" ]; then JAVA_OPTIONS="-classpath $CLASSPATH -DLogFile=$logFile -Djava.util.logging.config.file=$log4Jfile -Dwl.user.name=$wlUserName -Dwl.user.pass=$wlPassword -Dwl.host.address=$wlHost -Dwl.listen.port=$wlPort" else JAVA_OPTIONS="-classpath $CLASSPATH -DLogFile=$logFile -Djava.util.logging.config.file=$log4Jfile -Dwl.user.name=$wlUserName -Dwl.user.pass=$wlPassword -Dwl.host.address=$wlHost -Dwl.listen.port=$wlPort -Dkeystore=$keystore -Dkeystore_password=$keystore_password -Dtruststore=$truststore -Dtruststore_password=$truststore_password" fi ( cat < /var/log/syslog_auth.pipe | while read entry do LoggedInUser=`echo $entry | grep 'Accepted' | awk '{print $9 }'` if [ "${LoggedInUser}" != "" ]; then java $JAVA_OPTIONS oracle.apps.ctb.ihe.xdsb.logger.audit.server.TLSSecureNodeAuditLogger $LoggedInUser Login fi LoggedOutUser=`echo $entry | grep 'session closed for user' | awk '{print $11 }'` if [ "${LoggedOutUser}" != "" ]; then java $JAVA_OPTIONS oracle.apps.ctb.ihe.xdsb.logger.audit.server.TLSSecureNodeAuditLogger $LoggedOutUser Logout fi done ) &
In the script, update the log4JFile and CLASSPATH variables with appropriate values, and then save it.
Change the permissions of the send_audit_event_for_user_authentication.sh file.> chmod 744 send_audit_event_for_user_authentication.sh
Start the following script and provide the input by following the prompts:> sh send_audit_event_for_user_authentication.sh
.
Note:
The script runs a set of commands in the background mode once you start the script. The script prompts for the following values:WebLogic Managed Server Host
WebLogic Managed Server Port
WebLogic Admin User Name
WebLogic Admin User Password
In case the user chooses tranportProtocol as TLS then the script prompts the following additional values:
Absolute Path to Keystore File
Keystore password
Absolute Path to Truststore File
Truststore password
The IHE XDS configuration file /user_projects/domains//config/hdr/ihe_xdsb_config.xml contains two timeout configurations specific to IHE XDS registry web service call.
The name of the configuration is "WS_CLIENT_CONFIG" which has two components as follows:
httpConnTimeout
httpReadTimeout
httpConnTimeout value is configured in milliseconds and this configuration controls how long the HDR will wait for the network connection to be made with the document registry. If a connection to the document registry cannot be established within this time, HDR will fail the entire PnR transaction and return a failure response to the client. The default value for this configuration is 3000 milliseconds. Set this value to a optimum value so that HDR can make a successful network connection with the document registry when available.
httpReadTimeout value is configured in milliseconds and this configuration controls how long the HDR will wait for the document registry to respond with a success or failure. If the document registry does not respond with a response within this time, HDR will fail the entire PnR transaction and return a failure response to the client. The default value for this configuration is 5000 milliseconds. Set this value to a value greater than the configured document registry transaction timeout value (or JTA timeout) and less than the HDR's JTA transaction timeout value.
Add the following configuration in the IHE XDS configuration file:
<config name="WS_CLIENT_CONFIG"> <component name="httpConnTimeout" value="3000" /> <component name="httpReadTimeout" value="5000" /> </config>
The registry update server URL has to be configured for enabling HDR to send ITI-62 Delete Document Set request web service calls to external document registries.
HDR uses this configuration to delete the ITI-41 document entries from registries if there is any failure in commiting the transaction in HDR after getting the SUCCESS response from registries. To do this, HDR uses the RegistryStoredQuery ITI-18 request to get all the registry objects associated with the XDSSubmissionSet uniqueId, and then HDR constructs the ITI-62 Delete Document Set request using all the registry objects received from ITI-18 response and call the registry for deleting them using the XDS registry update URL. Here HDR receives all the registry objects (associations, external identifiers, extrinsic objects, and so on) that are associated with the corresponding XDSSubmissionSet uniqueId using the ITI-18 call. This request will be sent from HDR only when there is a failure in committing the ITI-41 document after getting the SUCCESS call from the registry.
The web service end point URL could be an http URL or secure https URL. In case of https connections to registry server, the necessary truststore and keystore files need to be generated and configured in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml under the REGISTRY_AUDIT_SERVER_SSL_CONFIG configuration name.
where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of the WebLogic domain.
For information about digital certificates and using JDK's keytool to generate keystore and truststore, visit http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html
.
As in synchronous XDS.b web services, HDR exposes a set of configuration APIs to configure profile options. Use the ProfileOptionService EJB session bean to configure the profile options. Before deploying and running synchronous web services, configure the External Document Registry update server endpoint. To send Delete Document Set Transaction ITI-62 request to an external Document Registry actor, HDR should be configured with the Document Registry Update endpoint's URL. This URL must be a valid web service endpoint URL implementing XDS.b UpdateDocumentSet specification.
ProfileOptionService API: createProfileOption(ProfileOption profileOptionObject), setProfileOptionValue(ProfileOptionValue profileOptionValueObject)
ProfileOption Configuration Values: ProfileOptionCode: "CTB_XDS_B_REGISTRY_UPDATE_URL" ProfileOptionValue: "http://DOCUMENT_REGISTRY_HOST:PORT/UpdateServiceXYZ" ProfileOptionLevelCode: "SITE" ProfileOptionLevelValue: null
HDR provides support for the Asynchronous Web Services Exchange option of the IHE XDS.b specification, specifically for the Document Repository actor. The asynchronous XDS.b profile uses the same set of transactions specified in the XDS.b profile. However, any transaction between two XDS.b actors is now decoupled into two separate one-way transactions - one for request and another for response. Please note the difference that in the synchronous XDS.b profile, both request and response are exchanged between two XDS.b actors as part of a single transaction.
HDR implements the following Asynchronous XDS.b web services:
Asynchronous Provide and Register Document Set-b
Asynchronous Retrieve Document Set
Asynchronous Provide and Register Document Set-b
The following figure illustrates the Asynchronous Provide & Register Doc-b Web Service:
Asynchronous Retrieve Document Set
This section contains the following topics:
As in synchronous XDS.b web services, HDR exposes a set of configuration APIs, to configure profile options. Use the IHEXDSConfigService EJB session bean to configure the profile options. Before deploying and running Asynchronous web services, configure the Asynchronous External Document Registry endpoint: In order to send asynchronous Register Document Set-b request web service calls to an external Document Registry actor, HDR should be configured with the Document Registry endpoint's URL. This URL must be a valid web service endpoint URL implementing XDS.b Asynchronous Register Document Set-b specification.
API: configureRegistryAsyncURL(String registryAsyncURL)
Sample value: http://DOCUMENT_REGISTRY_HOST:PORT/ServiceXYZ
HDR leverages WLS JMS queues to implement Asynchronous XDS.b web services. The WL server where HDR is to be deployed must create the required JMS queues that are used by the asynchronous web services.
HDR's Asynchronous Provide and Register Document Set-b web service uses two JMS Queues:
AsyncXDS_PnRbRequestQueue: All inbound 'Asynchronous Provide and Register Document Set-b' requests are saved in this queue, before getting dequeued and processed.
AsyncXDS_PnRbResponseQueue: All outbound 'Asynchronous Provide and Register Document Set-b' responses are saved in this queue before getting dequeued and transmitted to callback endpoints of respective Document Sources.
HDR's Asynchronous Retrieve Document Set uses two JMS Queues:
AsyncXDS_RetrieveDocbRequestQueue: All inbound Asynchronous Retrieve Document Set requests are saved in this queue, before getting dequeued and processed.
AsyncXDS_RetrieveDocbResponseQueue: All outbound Asynchronous Retrieve Document Set responses are saved in this queue before getting dequeued and transmitted to callback endpoint of the client (An XDS.b Document Consumer).
Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the timeoutValue under configuration item with name JMS_MESSAGE_TIMEOUT. This timeoutValue represents how long the JMS Message Consumer will wait to receive response message from the AsyncXDS_PnRbResponseQueue or AsyncXDS_RetrieveDocbResponseQueue destinations before the timeout expires. The timeoutValue is in milliseconds, and default value is 180000 milliseconds.
By default, HDR installation enables client to invoke Web services over https protocol only. In case the user wants HDR to accept Web services invocation over http protocol, then a custom JVM argument EnableHTTPForWS=true has to be included to the value of the JAVA_OPTIONS variable in <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/bin/startManagedWebLogic.sh. where, <weblogic_install_dir> is the file path where the WebLogic server has been installed. <weblogic_domain_name> represents the name of the WebLogic domain.
The password of IHE_XDS_USER is stored in SecretStore of Oracle Wallet. IHE Service uses the IHE_XDS_USER credentials for user authentication. Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the absolute path to Oracle Wallet as a value for the credentialStore under configuration item with name CREDENTIAL_STORE_CONFIG.
This configuration controls how HDR returns the MTOM/XOP response for the ITI-43 transaction. Edit <weblogic_install_dir>/user_projects/domains/<weblogic_domain_name>/config/hdr/ihe_xdsb_config.xml and enter the optimizeMessage value under configuration item with name MTOM_XOP_CONFIG. Set optimizeMessage value to true to permit HDR to return optimized MTOM/XOP message. Else, set optimizeMessage value to false. For more information on optimized and non-optimized MTOM/XOP messages, refer to http://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_TF_Vol2b.pdf.