Integrating the Healthcare Enterprise (IHE) Accelerator Reference

Transcription

1 IBM Initiate Master Data Serice Integrating the Healthcare Enterprise (IHE) Accelerator Reference Version9Release7 SC

2

3 IBM Initiate Master Data Serice Integrating the Healthcare Enterprise (IHE) Accelerator Reference Version9Release7 SC

4 Note Before using this information and the product that it supports, read the information in Notices and trademarks on page 41. Copyright IBM Corporation 1995, US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Introduction to IHE Accelerator..... Chapter 1. IHE Oeriew XDS.b profile ATNA logging profile PIX profile PDQ profile Chapter 2. IHE Accelerator Project... 5 Prerequisites Project components Master Data Engine enironment and IBM Initiate Workbench project Viewing IHE Accelerator relationships in IBM Initiate Inspector Chapter 3. IBM Initiate IHE Web Serice 9 proxy.config.xml proxy.config.xsd IBM-Initiate-IHE.war Status page IHE web serice installation IHE web serice installation on Tomcat IHE web serice installation on IBM WebSphere 17 IHE web serice installation on Oracle WebLogic Serer Editing paths and ariables in your configuration files Enabling SSL for broker to hub communication 27 Enabling HTTP communication Enabling ATNA Logging Troubleshooting your IHE installation Chapter 4. Configuration Files XML and XPath Inbound broker configuration files Query broker configuration files ATNA logging configuration file Query error responses XDS stored query configuration Patient erification identifier Testing Legal Statement Notices and trademarks Index Contacting IBM Copyright IBM Corp. 1995, 2011 iii

6 i Integrating the Healthcare Enterprise (IHE) Accelerator Reference

7 Introduction to IHE Accelerator The IBM Initiate Integrating the Healthcare Enterprise (IHE) Accelerator Reference proides an oeriew of selected profiles established by Integrating the Healthcare Enterprise (IHE) for arious Connectathon eents and the solutions to meet the profiles using the Message Broker Suite. The content in this document is intended to proide the serices team with information that can assist in the implementation of healthcare-related projects. The IHE profile descriptions do not attempt to proide a full definition of the specifications, rather they offer a high-leel oeriew. Copyright IBM Corp. 1995, 2011

8 i Integrating the Healthcare Enterprise (IHE) Accelerator Reference

9 Chapter 1. IHE Oeriew XDS.b profile Through forums and eents, such as the Connectathon, Integrating the Healthcare Enterprise (IHE) defines a technical framework for implementing messaging standards. Connectathon eents encourage participants to deelop solutions and engage in rigorous testing to meet the technical requirements. IBM Initiate Integrating the Healthcare Enterprise (IHE) Accelerator Reference presents a high-leel oeriew of the IHE profiles and the transactions that were met using the IBM Initiate Master Data Serice and Message Broker Suite. Because IHE specifications are fluid, this document is not meant to describe the full specifications for the supported profiles. For detailed requirements, see the IHE IT Infrastructure (ITI) Technical Framework ( Cross Enterprise Document Sharing (XDS) registers and shares electronic health record documents between healthcare enterprises, ranging from physician offices to clinics to acute care in-patient facilities. XDS.b support permits healthcare organizations that belong to an XDS Affinity Domain to cooperate in sharing clinical records (documents). The 9.7 release supports XDS.b. XDS actors While the IBM Initiate Master Data Serice participates in only a portion of the XDS profile, the full profile requirement includes the following actors: Document Repository - is responsible for storing documents and assigning the Uniform Resource Identifier (URI), which is used by the consumer during requests. Document Registry - stores information about the documents. The IBM Initiate Master Data Serice Hub seres as a Document Registry. Document Source - is the creator and publisher of the document. Document Consumer - this is the source requesting the document from the repository. Patient Identity Source - is the proider of a unique patient identifier and maintains patient identity demographics. Integrated Document Source/Repository - combines the functions of a document source and document repository. XDS transactions The IHE Accelerator supports the following required IHE transactions: Registry stored query. Registry stored queries are predefined queries that return folders or documents, or both. Register document set.b. Using SOAP, this transaction moes document metadata from the document repository to the registry. Successful processing of the following transactions is optional; howeer, the IHE Accelerator supports these transactions. Copyright IBM Corp. 1995,

10 ATNA logging profile Multiple document submission - the document source includes multiple documents in a single submission set request. Document life cycle management - the source submits an addendum to another document existing in the registry and repository. It also submits a document transformation of another document existing in the registry and repository. Folder management - the source creates a folder and adds one or more documents to the folder. Consumer systems can then query the registry for the folder. XDS messages For a basic understanding of XDS messages, it is helpful to understand the metadata objects and the IDs contained within the messages. See the IHE standards and profiles at the IHE website for information about message format and content. XDS.b use case A doctor (general practitioner) wants to pull up records for a patient who recently isited the emergency room (ER) for a broken leg. An x-ray of the leg was taken when the patient was admitted to the ER. The ER stored the x-ray in their x-ray document repository. The doctor pulls up the patient record from the office system. Linked to the patient profile is the patient x-ray results. The doctor clicks on the link in the patient record. The office system is the registry. The registry determines where the x -rays are stored across the enterprise based on document location information stored as part of the patient profile. The doctor iews the x-rays, pulled from the correct enterprise repository. The doctor then ealuates the patient, makes notes about the isit, and dispenses additional medications and treatment recommendations. The records from the patient isits are later scanned. The new record is submitted to the local repository and registered with the patient profile in the document registry for future user iewing. The Audit Trail and Node Authentication (ATNA) profile assists the implementation of confidentiality policies through user authentication and tracking. The IHE Accelerator solution uses SSL to authenticate users. Audit logging can be used to produce ATNA logs for the following actions. ATNA messages are written to the IBM-Initiate-IHE-ATNA.log file. RegisterDocument-b RegistryStoredQuery PRPA_IN201301UV02 - Patient Registry Record Added PRPA_IN201302UV02 - Patient Registry Record Reised PRPA_IN201304UV02 - Patient Registry Record Merged PRPA_IN201305UV02 - Patient Registry Find Candidates Query PRPA_IN201309UV02 - Patient Registry Get Identifiers Query Note: Specifications for HL73 ATNA logging were unaailable at the time this document was published, howeer ATNA logging for RegisterDocument-b and RegistryStoredQuery are fully implemented in the IBM Initiate Integrating the Healthcare (IHE) Accelerator project. 2 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

11 PIX profile PIX (Patient Identifier Cross-reference) profile supports the cross-referencing of patient identifiers from multiple Patient Identifier Domains (for example, hospitals, clinics, and physician offices). These cross-referenced patient identifiers are used by identity consumer systems to relate patient information from sources that know a gien patient by different identifiers. PIX actors While the IBM Initiate Master Data Serice participates in only a portion of the PIX profile, the full profile requirement includes the following actors: Patient Identity Source - A single source system responsible for assigning the unique Patient Identifier. Patient Identifier Cross-reference Consumer - A consuming system that requests information about a patient. Patient Identifier Cross-reference Manager - A system responsible for creating, maintaining, and proiding lists of identifiers. PIX transactions Successful completion of the following transactions is required for IHE-compliance. Patient Identity Feed - Is used by a Patient Identity Source actor to notify a Patient Identity Cross-Referencing actor of all eents related to patient identification (creation, update, merge, and other eents). A Patient Identity Feed triggers on Admit/Register or Update messages. PIX Query - Is used by a Patient Identity Consumer to find out the identification of a patient in different Patient Identification Domains. The serices of a Patient Identity Cross-reference Manager actor are used. PIX Update Notification - Is used by a Patient Identity Cross-reference Manager to notify a Patient Identity Consumer of patient identification changes. The Document Registry does not participate in PIX Update Notifications. PDQ profile PDQ (Patient Demographics Query) profile supports queries for a lists of patients (based on user-defined search criteria) It also supports retrieal of patient demographic data into the consuming application. PDQ actors The Patient Demographics Supplier and the Patient Demographics Consumer are the two actors directly inoled with PDQ. Patient Demographics Supplier - supplies patient information to the requesting consumer. The IBM Initiate Master Data Serice acts as the supplier in this profile. Patient Demographics Consumer - is the requesting system. PDQ transactions The Patient Demographics Query transaction is required for both the Patient Demographics Supplier and Consumer. Patient Demographics and Visit Query is an optional transaction for both actors. Chapter 1. IHE Oeriew 3

12 The Patient Demographics Supplier receies patient registration and update messages from sources and responds with the required information. The Supplier receies either a Patient Demographics or Patient Demographics and Visit query from the Consumer, and returns the demographics from multiple or single domains. 4 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

13 Chapter 2. IHE Accelerator Project Prerequisites The IHE Accelerator project proides a basic framework from which you can build an XDS.b registry deployment. An IBM Initiate Workbench project is included to assist in defining the basic objects in the registry, and the relationships between these objects. Initialization files for the IHE Web Serice Broker are also proided, and match the framework configuration. Additionally, IHE-configured Inbound Message Broker and Query Broker configuration files are proided. The IHE Accelerator solution supports: The subset of the XDS.b specification known as the document registry HL73 XML formatted messages SOAP 1.1 and 1.2 (synchronous communication) The IHE Accelerator project further supports two key features: 1) improed Broker search capabilities and 2) parent-child relationships. To meet the search requirements for XDS, three search filters are implemented in the brokers. Date range filter for documents, folders and submission sets based on a specified range of dates. This search works exactly like normal date range searches found in components like IBM Initiate Inspector. For example, request/return documents created (submitted) between June 12, 2009 and July 12, Deterministic filter that uses AND logic that returns documents, submission sets, and folders based on an exact specified search criteria. For example, request and return a specific document or folder. Wildcard character filter permits the use of certain characters to search for documents, submission sets, and folders. For example, request and return all documents matching E* Jones. The search parameters used for documents, folders or submission sets is controlled by the IHE specification. Taking adantage of the relationship logic in the Master Data Engine and the isual representation of these relationships in IBM Initiate Inspector is one unique feature of the IHE Accelerator. Patient records can be associated to documents and submission sets, documents associated to folders, and folders associated to submission sets. Relationships are built upon the Patient ID attribute of the document, folder, or submission set. The relationship rules are created when the Patient ID attribute matches an existing Patient MemIdnum. You must install and configure certain IBM Initiate Master Data Serice components in order to use the IHE Accelerator project. Begin by installing: Master Data Engine Copyright IBM Corp. 1995,

14 Message Broker Suite which includes the following: IHE Accelerator project - XDS Reference Web Serice Inbound broker Query broker IBM Initiate Workbench IBM Initiate Inspector (optional) See the following resources for information about installing and configuring the arious components: IBM Initiate Master Data Serice Engine Installation Guide Project components IBM Initiate Master Data Serice Message Broker Suite Reference (for information about installing the brokers and standard configuration file details) HL7 Query Adapter Reference (for information about query instance creation and configuration files) IBM Initiate Workbench User's Guide (includes IBM Initiate Inspector configuration information) IBM Initiate Workbench Installation Guide IBM Initiate Inspector Installation and Configuration Guide Components of the IBMInitiate IHE Accelerator project include the pre-configured hub, web serice files, and Message Broker Suite configuration files. The IBM Initiate Workbench project (pre-configured hub) file is called the xdsreference.zip and is located in your broker installation directory, for example, install_dir/ibm/initiate/brokers9.x.x/config/xdsreference Web serices files are located in the /proxy directory within your broker installation directory, for example, install_dir/ibm/initiate/brokers9.x.x/ proxy. Chapter 3, IBM Initiate IHE Web Serice, on page 9 Broker configuration files are located in the /config/ihe directory within your broker installation directory, for example, install_dir/ibm/initiate/ Brokers9.x.x/config/IHE. Master Data Engine enironment and IBM Initiate Workbench project Since eery implementation is different, you can customize the framework proided by the IBM Initiate Workbench project to use additional attributes, member types, or relationships as needed. The four objects included in the IHE Accelerator are; Person, Submission Set, Folder, and Document. Each of these objects has been defined with the minimum attributes necessary to support an XDS.b registry. The XDS-only member types hae been configured with a minimal algorithm, from which the system can process keyed searches against these objects in support of XDS.b required functions. The Person object has a more traditional comparison algorithm that can be used to not only search the registry for XDS queries, but proide EMPI capabilities beyond standard XDS functions. The patient ID is the key into the XDS.b objects. All metadata objects (folders, documents, and subsets) hae patient IDs associated to them. 6 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

15 The IHE Accelerator includes a set of relationship rules and IBM Initiate Inspector configuration (inspector.arm) for all of the registry objects. This information can be used to query and iew the registry contents through IBM Initiate Inspector if you want. The project includes: Member type/entity types Assoc/Assoc (Associations) Person/id Document/doc Folder/Folder Subset/Subset (submission set) Relationship types: FOLDERTODOC (folder-to-document) PATTODOC (patient-to-document) PATTOSUB (patient-to-submission set) SUBTODOC (submission set-to-document) SUBTOFOLDER (submission set-to-folder) In IBM Initiate Inspector, these relationships are represented as: - Has Documents (folder-to-document and patient-to-document) - Has Submissions (patient-to-submission set) - Has Folders (submission set-to-folder) Attribute types: In addition to some of the standard attribute types, are the following types. These attribute types hae associated implementation-defined segments). ASSOCIATION (defines document associations) EXTERNALID (defines external object IDs) MEMAUTHOR (originating author of document, folder or submission set contents) NODECLASS (defines the document classification object [metadata]) OBJECTCLASS (defines the object - document, folder, and other objects) XDSFILTER (used to define the search filters) Accessing the IHE Accelerator project You can access the IBM Initiate IHE Accelerator project in IBM Initiate Workbench. Procedure 1. Extract the xds_reference.zip file to your xdsreference directory. 2. From the Naigator iew in IBM Initiate Workbench, right click and select Import. Browse to the xdsreference directory and select the xds.imm file. See IBM Initiate Workbench User's Guide for additional details. Viewing IHE Accelerator relationships in IBM Initiate Inspector The relationships between a patient and associated documents, folders, and submission sets can be iewed in IBM Initiate Inspector. About this task Use this procedure to iew XDS relationships. See IBM Initiate Inspector User's Guide for detailed instructions. Chapter 2. IHE Accelerator Project 7

16 Procedure 1. Search for a member, typically by patient ID or name. 2. Select the preferred record from the returned results. 3. Click the Relationship tab. 8 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

17 Chapter 3. IBM Initiate IHE Web Serice The design of the IHE web serice is unique in that it does not require specific broker instances. Preiously, the web-enabled broker used socket connections to connect the web serer to the broker, at which turn the broker opened MPINET connections with the hub. This method meant that each broker was installed as a separate serice and each serice required multiple connections with the hub. Through the implementation of Jaa Natie Interface (JNI), the need for brokers as separately installed serices/daemons is eliminated (with exception of the ATNA logger that is still installed as a serice). Running the brokers with the IHE web serice means that when you install the brokers with the intent of creating an XDS registry, you do not hae to create broker instances. With this configuration the brokers, libraries, and associated Engine libraries are packaged such that a single, direct line of communication is created between the hub and IHE web serice. proxy.config.xml The IHE web serice uses three main files to manage processing: proxy.config.xml, proxy.config.xsd and IBM-Initiate-IHE.war. These files are located in your broker installation path /proxy directory. Another added feature of the IHE web serice is the status page, which is used to monitor message processing. Currently, the web serice is only supported on Tomcat. See IBM Initiate Master Data Serice System Requirements for details on supported Tomcat ersions. The proxy.config.xml file controls the web serice and enironment configuration, and proides processing directies for using broker function to complete IHE transactions. Users familiar with the serices.ini file will recognize the ariables contained in the first part of the file. Copyright IBM Corp. 1995,

18 When you first open the proxy.config.xml file, you see a number of REPLACE_ME_WITH... entries. Each of these entries must be updated with the specifics of your installation. The examples here show an edited file. The easiest way to handle this edit is to do a search for REPLACE_ME_WITH. Enironment ariable use, such as ${MAD_ROOTDIR}, is not supported inside of configuration files running under web serices. You must enter the full path. Important: Regardless of the operating system on which you are installing, the proxy.config.xml file only accepts forward slashes (/). For example, if you are installing on a Microsoft Windows platform your home directory path might be D:\Program Files\IBM\Initiate\brokerx.x.x. Howeer, it must be entered as D:Program Files/IBM/Initiate/brokerx.x.x in the proxy.config.xml file. <proxy.config xmlns:xsi=" xsi:nonamespaceschemalocation="proxy.config.xsd"> <global.config mad.log_dir="" mad.log_name="d:/ibm/initiate/brokers/log/proxy_log.mlg" mad.root_dir="d:/ibm/initiate/brokers/win32-debug" mad.home_dir="d:/ibm/initiate/brokers/win32-debug" mad.broker_dir="d:/ibm/initiate/brokers/win32-debug" mad.so_timeout="30" mad.conn.str="localhost 16000" mad.login="system" mad.password="system" mad.password.scheme="plain" mad.dtd.dir="d:/ibm/initiate/brokers/dtd" ihe.home.community.id="ihe:homecommunityid" > In this example, the ihe.home.community.id="ihe:homecommunityid" attribute is used in ATNA logging. The second part of the file, the body, is where the actual transactions (serices) are defined. There are two types of serices: IHE serices and generic serices. The IHE handler.config portion of the body contains the name of the serice (for example, "XDS_b_DocumentRegistry" or "PIX Manager") and the serice action (for example, RegisterDocumentSet-b", RegistryStored Query or PRPA_IN201301UV02 ). The serice name identifies an associated IHE web serice (which contains a grouping of IHE actions or profiles). The action name or element is the action (profile) to be performed, followed by the type of broker (for example, broker.inbound or broker.query) that processes the profile. The associated configuration file (for example, RegisterDocumentSetB.ini) used for the action is also identified. The broker.inbound processes requests to register or record information in the document registry. The broker.query processes serice requests for information from the registry. All supported IHE profiles are automatically listed in the proxy.config.xml file. The profiles defined are XDS.b Document Registry, PIX Manager, and PDQ Supplier. Unless you hae a reason to deiate from the IHE standards, you not hae to edit this section. The next example shows an optional attribute that can be added to the handler.config sections to turn on ATNA logging: atnalogger=" :8087". 10 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

19 <handler.config sericename="xds_b_documentregistry" atnalogger=" :8087"> <action actionname="registerdocumentset-b"> <broker.inbound> <config.file.request>d:/ibm/initiate/brokers/config/ihe/msgbr oker/registerdocumentsetb.ini</config.file.request> <config.file.reject.response>d:/ibm/initiate/brokers/config/i HE/msgBroker/MsgReaderFailureXDS.ini</config.file.reject.response> <config.file.success.response>d:/ibm/initiate/brokers/config/ IHE/msgBroker/MsgReaderSuccessXDS.ini</config.file.success.respons e> <config.file.path>d:/ibm/initiate/brokers/config/ihe/msgbroke r</config.file.path> <queue.dir>d:/ibm/initiate/brokers/inbound</queue.dir> <queue.success.name>success</queue.success.name> <queue.reject.name>reject</queue.reject.name> <attribute.update.queue.dir></attribute.update.queue.dir> <attribute.update.queue.name></attribute.update.queue.name> <attribute.update.filter></attribute.update.filter> <attribute.update></attribute.update> <manage.duplicates></manage.duplicates> <application.name></application.name> <parser.handler.lib>parser_xds.dll</parser.handler.lib> </broker.inbound> <message.type.xml> <xml.doc.handler.lib>document_handler_xds.dll</xml.doc.handler. lib> <xml.doc.name></xml.doc.name> <xml.doc.public.id></xml.doc.public.id> <xml.doc.system.id></xml.doc.system.id> <message.type.xml> </action> <action actionname="registrystoredquery"> <broker.query> <config.file>d:/ibm/initiate/brokers/config/ihe/querybroke r/registrystoredquery.ini</config.file> <config.file.path>d:/ibm/initiate/brokers/config/ihe/query Broker</config.file.path> <queue.dir>d:/ibm/initiate/brokers/query</queue.dir> <queue.request.name>req</queue.request.name> <queue.response.name>resp</queue.response.name> </broker.query> </action> In the example aboe, the parser.handler.lib is operating-system-specific. This example shows a Microsoft Windows library extension of.dll (parser_xds.dll). Other operating system (OS) libraries hae the OS-specific extension and follow the conention set by all of our natie libraries. The libraries are named in the lib folder of the proxy installation directory. Following the IHE-specific actions, there is a section for generic broker serices that is used for custom serices and actions. Serices can be define to process the addition of patient records to the Hub using XML, delimited, fixed-length, or HL72 messages. The message type is defined by the <message.type.*> tag (for example, <message.type.xml>). The next example shows the XML message configuration portion. Chapter 3. IBM Initiate IHE Web Serice 11

20 <!--handler.config.generic sericename="genericbrokerserice"> <action rootelement="xmlwrapped"> <broker.inbound> <config.file.request>d:/ibm/initiate/brokers/config/ihe/ms gbroker/cust_addpatient.ini</config.file.request> <config.file.reject.response>d:/ibm/initiate/brokers/confi g/msgbroker/msgreaderfailurexml.ini</config.file.reject.respons e> <config.file.success.response>d:/ibm/initiate/brokers/conf ig/msgbroker/msgreadersuccessxml.ini</config.file.success.respo nse> <config.file.path>d:/ibm/initiate/brokers/config/ihe/msgbr oker</config.file.path> <queue.dir>d:/ibm/initiate/brokers/inbound</queue.dir> <queue.success.name>success</queue.success.name> <queue.reject.name>reject</queue.reject.name> <attribute.update.filter></attribute.update.filter> <manage.duplicates></manage.duplicates> <application.name></application.name> <manage.attribute.update></manage.attribute.update> <attribute.update.queue.dir></attribute.update.queue.dir> <attribute.update.queue.name></attribute.update.queue.name> </broker.inbound> <message.type.xml> <xml.doc.handler.lib></xml.doc.handler.lib> <xml.doc.name></xml.doc.name> <xml.doc.public.id></xml.doc.public.id> <xml.doc.system.id></xml.doc.system.id> </message.type.xml> </action> proxy.config.xsd IBM-Initiate-IHE.war The proxy.config.xsd file is an XML schema that is used to help alidate the XML element alues before starting the web serice. The.xsd file defines (goerns) the proxy.config.xml file and not be augmented. If you must change the proxy.config.xml file (for example, deiate from the IHE standards), contact IBM Software Support. The IBM-Initiate-IHE.war file is a jar used to distribute the collection of files and libraries that make up the web application. Deployment of the war file is further discussed in the web serice installation topics. Status page The web serice status page proides a static iew of the web serice actions, such as RegisterDocumentSet-b, that are being run. The Total column represents the total number of messages processed for this action. The min and max fields show the minimum and maximum amount of time (in milliseconds) it takes to process each message. If the message cannot be processed because of an error condition, the number of errors is shown. 12 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

21 IHE web serice installation The first message to run, per action, has a maximum time of 0. This number is due to the spin-up of serices that take place for the initial request. The minimum time for the first message is the actual time it took to process. The true reflections of min/max time per serice begin with the second message. Failure to process a message constitutes an error. For example, if a request comes in and the broker does not respond, that is considered an error. If a requested document or patient is not in the hub, that is not considered an error because the broker processed the request. An error count other than 0 indicates that there is a problem in either the broker.ini files or the web serice portion of the product. Consult the logs for information about the errors. The IHE web serice can be installed on Tomcat, IBM WebSphere, or Oracle WebLogic Serer. The web serices files are located in the proxy directory within your broker install directory (for example, C:/Program Files/IBM/Initiate/Brokers/proxy These instructions assume that you hae already installed the Message Broker Suite and deployed the IHE Accelerator project to a hub. IHE web serice installation on Tomcat Installing the IHE web serice on Tomcat is supported. Before beginning installation, there are some prerequisites that must be met. In these instructions, the following alues must be replaced with alues specific to your configuration. These settings can be added to the TOMCAT_HOME/bin/startup.*: TOMCAT_HOST is the serer name on which Tomcat is running TOMCAT_PORT is the port number used by TOMCAT TOMCAT_HOME is the directory in which TOMCAT is installed, also called CATALINA_HOME Verify that the following tasks hae been completed. You hae already installed the Message Broker Suite (see the IBM Initiate Master Data Serice Message Broker Suite Reference ) and deployed the XDS Reference.zip file (see Project components on page 6). You hae the JAVA_HOME path set in your system enironment ariables, for example: Variable = JAVA_HOME Value = C:/Program Files/Jaa/jre1.6.0_02 You hae installed Tomcat 6.0. Verify that the path to the Tomcat libraries is set in your system ariables. (You can also add the ariables directly in the Tomcat startup script (TOMCAT_HOME/bin/startup.*). On the Apache Tomcat Properties dialog, under the Jaa tab, erify that the Jaa library is set. For example: Jaa Virtual Machine: C:/Program Files/Jaa/jre1.6.0_02/bin/client/ jm.dll or C:/Program Files/Jaa/jre6/bin/serer/jm.dll Jaa Classpath: C:/Program Files/IBM/Initiate/Tomcat 6.0/bin/ bootstrap.jar Jaa Options: Chapter 3. IBM Initiate IHE Web Serice 13

22 -Dcatalina.home=TOMCAT_HOME/Tomcat 6.0 -Dcatalina.base=TOMCAT_HOME/Tomcat 6.0 -Djaa.endorsed.dirs=TOMCAT_HOME/Tomcat 6.0/endorsed -Djaa.io.tmpdir=TOMCAT_HOME/Tomcat 6.0/temp -Djaa.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djaa.util.logging.config.file=TOMCAT_HOME/Tomcat 6.0/conf/logging.properties -Djaa.library.path=TOMCAT_HOME/Tomcat 6.0/shared/lib You must reboot your system after adding any ariables. Storing the proxy.config.xml and shared libraries - Tomcat installation For IBM Initiate IHE web serice installation on Tomcat, the proxy.config.xml and shared libraries must be stored in the shared libraries path. Procedure 1. Shut down the Tomcat serer. 2. Install Tomcat. For Tomcat 6.x or later, modify the YOUR_TOMCAT_HOME/conf/ catalina.properties file so that the shared classloader mechanism works the same as Tomcat 5.x. Verify that the entry beginning with shared.loader= reads: shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/ lib/*.jar. 3. If it does not exist, create a shared/classes directory under the YOUR_TOMCAT_HOME directory. 4. Copy your proxy.config.xml and proxyconfig.xsd files file into YOUR_TOMCAT_HOME/shared/classes directory. 5. Copy the schemas folder from.../proxy to YOUR_TOMCAT_HOME/shared/classes. 6. All of the libraries in the proxy/lib folder must be copied to YOUR_TOMCAT_HOME/shared/lib. In order for the natie Tomcat library loader to see the shared libraries during run time, the YOUR_TOMCAT_HOME/shared/lib must be added to the jaa.library.path. Set an enironment ariable JAVA_OPT as such: JAVA_OPT=-Djaa.library.path=YOUR_TOMCAT_HOME/shared/lib 7. Depending upon your operating system, make sure that you add the following information: Microsoft Windows: The YOUR_TOMCAT_HOME/shared/lib; also must be added to the system's PATH. Linux or Solaris: Add the YOUR_TOMCAT_HOME/shared/lib to the enironment's LD_LIBRARY_PATH. AIX : Add the YOUR_TOMCAT_HOME/shared/lib to the enironment's LIBPATH. HP-UX: Add the YOUR_TOMCAT_HOME/shared/lib to the enironments SHLIB_PATH. 8. IBM AIX, Linux, Solaris, or HP-UX only, add these lines to the.bash_profile: export JAVA_OPTS=-Djaa.library.path=$CATALINA_HOME/shared/lib export CATALINA_OPTS="-Xms128m -Xmx1024m" Make sure that you do not include any statements related to MAD_DBTYPE or MAD_CTXLIB. Doing so results in a data source name not found error. 9. Due to the large memory footprint of the IHE schemas, the default memory limits in Tomcat are not sufficient. You should allow 1G for the Tomcat instance running this serice. This increase can be done by using the CATALINA_OPTS enironment ariable. For example: CATALINA_OPTS=-Xms128m -Xmx1024m instructs Tomcat to start the heap size at 128 megabytes and grow it to the maximum of 1 gigabyte. 14 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

23 Installing the IHE web application on Tomcat After storing the proxy.config.xml and shared libraries, you can begin to install the IBM Initiate IHE web application on Tomcat. Procedure 1. Restart Tomcat. 2. In a web browser, enter You should see the The Apache Jakarta Project" page with links for Tomcat Administration and Tomcat Manager. 3. Click the link for the Tomcat Manager and log in with the name and password of a Tomcat administrator account. 4. In the Install section, click Browse in the WAR file to deploy area and go to the IBM-Initiate-IHE.war file. Click Deploy. Results The IBM Initiate IHE web application is deployed. When the Apache Jakarta Project page refreshes, you should see an IBM-Initiate-IHE row in the Applications section with a Display Name of IBM-Initiate-IHE. As an alternatie, Tomcat can be configured by default to auto-deploy any war file dropped into the YOUR_TOMCAT_HOME/webapps directory. Enabling XDS.b Serice on Tomcat The XDS.b serice is disabled by default when you install the IBM Initiate IHE web application. Use this procedure to enable the XDS.b serice on Tomcat. Procedure 1. After installing the IHE web application, shut down the Tomcat serer. 2. Extract the IBM-Initiate-IHE.aar file located in the expanded IHE web application serices directory. For example, TOMCAT_HOME/webapps/IBM- Initiate-IHE/WEB-INF/serices. 3. Open the serices.xml file located in the extracted /META-INF directory. Remoe the comments surrounding the XDS.b serice. 4. Compress the IBM-Initiate-IHE.aar file. 5. Go to the TOMCAT_HOME/shared/classes directory and open the proxy.config.xml file. Remoe the comment surrounding the XDS.b serice. 6. Restart the Tomcat serer. Updating an existing installation on Tomcat There are specific steps you must take to update an existing IBM Initiate IHE web serice installation on Tomcat. Updates are patch releases within a major ersion. For example, updating build to build , where 9.0 is the major ersion number. Procedure 1. Remoe the IHE web serice application from the Tomcat Manager page. In some cases, a shutdown of the Tomcat serer and remoal of the YOUR_TOMCAT_HOME/webapps/IBM-Initiate-IHE and YOUR_TOMCAT_HOME/webapps/ IBM-Initiate-IHE.war files are required. This happens because Tomcat places a lock on one of the jars in the IBM-Initiate-IHE.war and preents the serice from being remoed while Tomcat is running. Chapter 3. IBM Initiate IHE Web Serice 15

24 2. Follow the installation steps from Storing the proxy.config.xml and shared libraries - Tomcat installation on page 14). a. Replace the shared libraries in YOUR_TOMCAT_HOME/shared/lib. b. If the layout of the proxy.config.xml has changed (see IBM Initiate Master Data Serice Release Notes), port your settings from the existing proxy.config.xml to the new format and replace the YOUR_TOMCAT_HOME/ shared/classes/proxy.config.xml and proxy.config.xsd with the new ersion. c. In the proxy.config.xml file, do a search for REPLACE_ME_WITH and in each instance, replace the text with the specifics for your installation. Enironment ariable use, such as ${MAD_ROOTDIR}, is not supported inside of configuration files running under web serices. You must enter the full path. 3. Follow the instructions for deployment of the IBM-Initiate-IHE.war (see Installing the IHE web application on Tomcat on page 15). Upgrading an existing installation on Tomcat There are specific steps you must take to upgrade an IBM Initiate IHE web serice on Tomcat from a major ersion to a new major ersion (for example, 9.0 to 9.2 or later). Procedure 1. Remoe the IHE web serice application from the Tomcat Manager page. In some cases, a shutdown of the Tomcat serer and remoal of the YOUR_TOMCAT_HOME/webapps/brokerproxy and YOUR_TOMCAT_HOME/webapps/ brokerproxy.war files is required. This happens because Tomcat places a lock on one of the jars in the brokerproxy.war and preents the serice from being remoed while Tomcat is running. 2. Follow the installation steps from Storing the proxy.config.xml and shared libraries - Tomcat installation on page 14): a. Replace the shared libraries. b. If the layout of the proxy.config.xml has changed (see IBM Initiate Master Data Serice Release Notes), port your settings from the existing proxy.config.xml file to the new format and replace the YOUR_TOMCAT_HOME/shared/classes/proxy.config.xml with the new ersion. 3. Follow the instructions for deployment of the IBM-Initiate-IHE.war (see Installing the IHE web application on Tomcat on page 15). Related tasks Editing paths and ariables in your configuration files on page 26 The proxy.config.xml file and some of the broker.ini files contain "REPLACE_ME_WITH_" text which must be customized with path information specific to your install. Changing the logging configuration on Tomcat You hae the option of changing the default IBM Initiate IHE web serice logging configuration on Tomcat. Procedure 1. The logging configuration is controlled by the log4j.properties file located in the expanded web application classes directory. See YOUR_TOMCAT_HOME/webapps/ brokerproxy/web-inf/classes. 2. Find the section "# Initiate Systems Logging." Edit the line: log4j.logger.com.initiatesystems=your_al, ISwhere your_al is one of the 16 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

25 following: TRACE, DEBUG, INFO, WARN, FATAL. You get less logging as you moe further to the right in the list. The default setting is WARN. TRACE logs eery message to and from the JNI layer, so use it with caution. (The logs can contain personal health information [PHI] information in some cases.) TRACE and DEBUG settings are meant to be used during the deelopment and testing phases. In this section, you can also change the location of the IBM-Initiate-IHE.log and other log4j properties. 3. Restart Tomcat. IHE web serice installation on IBM WebSphere Installing the IHE web serice on IBM WebSphere is supported. Before beginning installation, there are some prerequisites that must be met. Verify that the following tasks hae been completed. The proxy.config.xml file has been modified to match your installation configuration. The proxy.config.xml, proxy.config.xsd, and the schemas folder has been copied to the WebSphere/AppSerer/properties folder. The contents of the BROKER_ROOTDIR/proxy/lib directory has been copied to WebSphere/AppSerer/bin. Storing the proxy.config.xml and shared libraries - IBM WebSphere installation For IBM Initiate IHE web serice installation on IBM WebSphere, the proxy.config.xml and shared libraries must be stored in the shared libraries path. Procedure 1. Shut down the WebSphere serer. 2. Place the proxy.config.xml and the proxy.config.xsd files along with the schemas folder into the YOUR_WEBSHPERE_DIR/AppSerer/properties directory. 3. Place the contents of the YOUR_BROKER_INSTALL_DIR/proxy/lib directory in to the YOUR_WEBSHPERE_DIR/AppSerer/bin directory. Installing the IHE web application on IBM WebSphere After storing the proxy.config.xml and shared libraries, you can begin to install the IBM Initiate IHE web application on IBM WebSphere. Procedure 1. Access the Integrated Solutions Console. The default address is: 2. Select Applications > New Applications > New Enterprise Application. 3. Under Path to the new application, go to the IBM-Initiate-IHE.war file and select Open. Then select Next. 4. Under "How do you want to install the application", select Detailed - Show all installation options and parameters. Select Next. a. On the Application Security Warnings page, select Continue. b. For the Select installation options step, leae all defaults and select Next. c. For the Map modules to serers step, leae all defaults (options cleared) and select Next. Chapter 3. IBM Initiate IHE Web Serice 17

26 d. For the Proide JSP reloading options for Web modules step, leae all defaults and select Next. e. For the Map shared libraries step, leae all defaults and select Next. f. For the Map shared library relationshipsstep, leae all defaults and select Next. g. For the Map irtual hosts for Web modules step, leae all defaults and select Next. h. For the Map context roots for Web modules step, type IBM-Initiate-IHE in the Context Root field. Select Next. i. For the Summary step, select Finish. 5. At the end of the installation process, select Sae to sae the changes directly to the master configuration. 6. Under the Applications > Application Types menu on the left of the admin console, select WebSphere enterprise applications. 7. Examine the status of IBM-Initiate-IHE_war. A red X indicates the application is stopped. Check the box next to IBM-Initiate-IHE_war, and then select Start. Results The message "Application IBM-Initiate-IHE_war on serer serer name and node node name started successfully" is displayed. The application status for IBM-Initiate-IHE_war has a green arrow indicating that the application has started. What to do next Continue with "Turning off web serices scanning and setting maximum heap size". Turning off web serices scanning and setting maximum heap size on IBM WepSphere You can turn off web serices scanning and to set your maximum heap size for your web serice application. Procedure 1. From the Integrated Solutions Console, select Serers > Serer Types > WebSphere Application Serers. 2. Under Application serers, select the link associated with your serer (for example, serer1). 3. Under Serer Infrastructure, select Jaa and Process Management > Process Definition. 4. Under Additional Properties, select the link for the Jaa Virtual Machine. 5. Set the Generic JVM arguments parameter to: -Dcom.ibm.WebSphere.webserices.DisableIBMJAXWSEngine=true 6. Set the Maximum heap size to Select Apply and Sae your changes. What to do next Continue with setting your class loader order. 18 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

27 Setting the class loader order on IBM WebSphere You can set the class loader order on your IBM Initiate IHE web application installation. Procedure 1. From the Integrated Solutions Console, select Applications > Application Types > WebSphere enterprise applications > IBM-Initiate-IHE_war > Manage Modules > IBM-Initiate-IHE. 2. Set the Class loader order to Classes loaded with local class loader first (parent last). 3. Select Apply and Sae your changes. 4. Go to the WebSphere/AppSerer/profiles/AppSr/installedApps/yourNode/IBM- Initiate-IHE_war.ear/IBM-Initiate-IHE.war/WEB-INF/ directory. Open the ibm-web-ext.xmi file and add the following lines. <jspattributes xmi:id="jspattribute_n" name="jdksourceleel" alue="16"/> <jspattributes xmi:id="jspattribute_n" name="disablejspruntimecompilation" alue="false"/> 5. Go to the WebSphere/AppSerer/profiles/AppSr/installedApps/yourNode/IBM- Initiate-IHE_war.ear/IBM-Initiate-IHE.war/WEB-INF/lib/ directory. Make a copy of the wsdl4j jar file and place the copy in the WebSphere/AppSerer/jaa/jre/lib/ext/ directory. 6. Go to the WebSphere/AppSerer/profiles/AppSr/installedApps/yourNode/IBM- Initiate-IHE_war.ear/IBM-Initiate-IHE.war/WEB-INF/classes/ directory. Open the log4j.properties file and find this line: log4j.appender.is.file=${catalina.base}/logs/ibm-initiate-ihe.log Change the line to: log4j.appender.is.file=websphere/appserer/profiles/appsr/logs/ IBM-Initiate-IHE.log Find the line: log4j.appender.isatna.file=${catalina.base}/logs/ IBM-Initiate-IHE-ATNA.log Change the line to: log4j.appender.isatna.file=websphere/appserer/profiles/appsr/ logs/ibm-initiate-ihe-atna.log 7. Restart the serer. What to do next The IBM Initiate IHE application is located at: Initiate-IHE. Access this URL to erify that the application is installed correctly. If the WebSphere port is different from 9080, replace it with the correct port number. Completing the IHE web serice installation on IBM WebSphere After performing the initial installation steps, there are a few additional steps you need to take to complete the process. About this task This task assumes that you hae already completed the following: Storing the proxy.config.xml and shared libraries - IBM WebSphere installation on page 17 Chapter 3. IBM Initiate IHE Web Serice 19

28 Installing the IHE web application on IBM WebSphere on page 17 Turning off web serices scanning and setting maximum heap size on IBM WepSphere on page 18 Setting the class loader order on IBM WebSphere on page 19 Procedure 1. Verify that WebSphere is off. 2. Go to the YOUR_WEBSPHERE_DIR/AppSerer/profiles/YOUR_APPSRV/ installedapps/your_node/ibm-initiate-ihe_war.ear/ibm-initiate-ihe.war/ WEB-INF/ directory. Open the ibm-web-ext.xmi file and add the following lines. <jspattributes xmi:id="jspattribute_n" name="jdksourceleel" alue="16"/> <jspattributes xmi:id="jspattribute_n" name="disablejspruntimecompilation" alue="false"/> 3. Go to the YOUR_WEBSPHERE_DIR/AppSerer/profiles/YOUR_APPSRV/ installedapps/your_node/ibm-initiate-ihe_war.ear/ibm-initiate-ihe.war/ WEB-INF/lib/ directory. Make a copy of the wsdl4j jar file and place the copy in the WebSphere/AppSerer/jaa/jre/lib/ext/ directory. 4. Go to the YOUR_WEBSPHERE_DIR/AppSerer/profiles/YOUR_APPSRV/ installedapps/your_node/ibm-initiate-ihe_war.ear/ibm-initiate-ihe.war/ WEB-INF/classes/ directory. Open the log4j.properties file and find this line: log4j.appender.is.file=${catalina.base}/logs/ibm-initiate-ihe.log Change the line to: log4j.appender.is.file=your_websphere_dir/appserer/ profiles/your_appsrv/logs/ibm-initiate-ihe.log Find the line: log4j.appender.isatna.file=${catalina.base}/logs/ibm-initiate-ihe-atna.log Change the line to: log4j.appender.isatna.file=your_websphere_dir/appserer /profiles/your_appsrv/logs/ibm-initiate-ihe-atna.log 5. Restart the IBM WebSphere serer. What to do next The IBM Initiate IHE application is located at: Initiate-IHE. Access this URL to erify that the application is installed correctly. If the IBM WebSphere port is different from 9080, replace it with the correct port number. Enabling XDS.b Serice on IBM WebSphere The XDS.b serice is disabled by default when you install the IBM Initiate IHE web application. Use this procedure to enable the XDS.b serice on IBM WebSphere. Procedure 1. After installing the IHE web application, shut down the IBM WebSphere serer. 2. Extract the IBM-Initiate-IHE.aar file located in the expanded IHE web application serices directory. For example, YOUR_WEBSPHERE_DIR/AppSerer/ profiles/your_appserver/installapps/node_cell/ibm-initiate-ihe_war.ear/ IBM-Initiate-IHE.war/WEB-INF/serices. 20 Integrating the Healthcare Enterprise (IHE) Accelerator Reference

29 3. Open the serices.xml file located in the extracted /META-INF directory. Remoe the comments surrounding the XDS.b serice. 4. Compress the IBM-Initiate-IHE.aar file. 5. Go to the YOUR_WEBSPHERE_DIR/AppSerer/profiles/ directory and open theproxy.config.xml file. Remoe the comment surrounding the XDS.b serice. 6. Restart the IBM WebSphere serer. Updating an existing installation on IBM WebSphere There are specific steps you must take to update an existing IBM Initiate IHE installation in IBM WebSphere with a patch release. Patch releases are updates within a major ersion. For example, updating build to build , where 9.0 is the major ersion number. Procedure 1. Verify that WebSphere is turned off. 2. Replace the shared libraries. a. Copy the schemas folder to the YOUR_WEBSPHERE_DIR/AppSerer/properties directory. b. Copy the contents of the YOUR_BROKER_INSTALL_DIR/proxy/lib directory to YOUR_WEBSPHERE_DIR/AppSerer/bin directory. 3. If the layout of the proxy.config.xml has changed (see IBM Initiate Master Data Serice Release Notes), port your settings from the existing proxy.config.xml to the new format and replace the proxy.config.xml and proxy.config.xsd inside YOUR_WEBSPHERE_DIR/AppSerer/properties with the new ersion. 4. Restart IBM WebSphere. 5. Access the Integrated Solutions Console. The default address is 6. Select Applications > Application Types > Websphere Enterprise Application. 7. Select the IBM-Initiate-IHE_war check box and click Uninstall. 8. Select OK. 9. Sae your changes. 10. Follow the steps in these topics: a. Turning off web serices scanning and setting maximum heap size on IBM WepSphere on page 18 b. Setting the class loader order on IBM WebSphere on page 19 c. Completing the IHE web serice installation on IBM WebSphere on page Restart IBM WebSphere. Upgrading an existing installation on IBM WebSphere There are specific steps you must take to upgrade an IBM Initiate IHE web serice on IBM WebSphere from a major ersion to a new major ersion (for example, 9.0 to 9.2 or later). Procedure 1. Verify that WebSphere is turned off. 2. Replace the shared libraries. a. Copy the schemas folder to the YOUR_WEBSPHERE_DIR/AppSerer/properties directory. Chapter 3. IBM Initiate IHE Web Serice 21