Sample portal application

This document is designed to help the user understanding and use of the sample portal application that accompanies IBM(R) WebSphere(R) Business Integration for Healthcare industry solution.

The WebSphere Business Integration for Healthcare sample portal application is not a supported component of the WebSphere Business Integration for Healthcare industry solution. It is provided to serve two main purposes:

Sample portal architecture

The sample portal application is designed for the WebSphere Portal Server. Users logon through a browser, and the application communicates with the Healthcare industry solution components using a database and WebSphere MQ. The high-level architecture is shown in the following diagram:

Diagram showing sample portal architecture

WebSphere Portal Server

The sample application uses WebSphere Portal Server as an application framework. This framework provides the following benefits:

Sample portal functionality

The Healthcare sample portal application supports the EMR and Compliance Reporting use cases by implementing the following functionality:

Installing the sample portal application

Some of the following installation steps involving DB2(R) or WebSphere MQ will have been performed during installation of the WebSphere Business Integration for Healthcare industry solution. They are listed here for your reference, but do not need to be repeated.

Software prerequisites

This application has been tested only on WebSphere Portal Server installed on a Microsoft(R) Windows(R) 2000 system with Support Pack 3.

Software prerequisites include the following:

Browsers that have been tested include the following:

Configuring the database

Important: The database and tables required for the sample portal application are created during the DB2 configuration in the WebSphere Business Integration for Healthcare installation. If you have already completed those steps, you do not need to complete the steps below.

  1. Edit the Create_HLTHCARE_Database script so that the SQLLIB path information is correct for your system. (Be sure to leave the @ symbol in front of the file name.)
    Note: If your directory name contains a space (for example, Program Files) you must use a short name. View short names by entering dir /x
  2. Open a command prompt
  3. Change the directory to the location of the Create_ HLTHCARE _Database script
  4. Enter db2cmd to open a DB2 command window.
  5. In the new DB2 command window, enter the following:
    db2 < Create_ HLTHCARE _Database.txt
    db2 < Create_HLTHCARE_Tables.txt

Configuring the DB2 data source in WebSphere Application Server

The configured database can be on either the same machine as WebSphere Application Server or on a remote machine. If it is on a remote machine, use the DB2 Control Center on the WebSphere Application  machine to create a remote system, instance, and database definition. If the WebSphere Application Server machine will have both a local and remote database, you will need to give the remote database an alias. Only one WebSphere Application Server data source with the JNDI name provided below can be used at any one time.

To configure the data source in WebSphere Application Server, complete the following steps:

  1. Start the WebSphere Application Server Administrators Console
  2. Click Open a configuration file to edit with the console.
  3. Login as wpsadmin, if required.
  4. Click Resources > JDBC Drivers > wps40JDBC.
  5. Click DataSources, then click New.
  6. Enter the following information:
    Name
    : HLTHCARE (your name can vary)
    JNDI Name
    : jdbc/HLTHCARE (this name must be as shown, since it is referenced in the code)
    Custom Properties
    databaseName:
    HLTHCARE (or the alias name you have provided)
    user
    : your userId for DB2
    password
    : your password for DB2
  7. Click OK and save the configuration.
  8. To make this data source available, stop and restart both the WebSphere Application Server and WebSphere Portal Server.

Configuring WebSphere MQ

The WebSphere MQ queue manager and queue is created during the installation of WebSphere Business Integration for Healthcare. The sample portal application WebSphere MQ is configured using the portal application's System Settings page.

Installing the portal application

This sample includes a WBIHCSamples.war file that can be installed on WebSphere Portal Server V4.2 or V4.2.1. There are two ways to install the portlet application:

The most efficient method for installing is using the XMLAccess utility. If the requirements of the utility cannot be met, the manual process must be used.

Installing using XMLAccess

The XMLAccess utility is a component of WebSphere Portal Server. It is the means by which portal administration places and pages are installed. It can also be used to install user applications by importing an XML file that defines the application configuration. To install the sample portal application using XMLAccess complete the following steps:

  1. Ensure that WebSphere Application Server is running and that WebSphere Portal is started.
  2. Copy the WBIHCSamples.war file into your <portal_root>\install directory.
  3. Copy the import.xml file into your <portal_root>\bin directory.
    Note: The import.xml file contains access-right definitions for the wpsadmin ID. If your installation does not have this ID, you will have to either edit the import.xml file or use the manual installation process described below.
  4. Open a command prompt and switch to the <portal_root>\bin directory
  5. Run the following command, replacing <password> with the password for the wpsadmin ID and <hostname> with the full hostname and port (for example, machinename.mycompany.com:9080)
    xmlaccess import.xml wpsadmin:<password> <hostname>/wps/config 1> result.xml 
  6. When the command has completed, check the result.xml file to verify that there were no errors.

If there are errors or warnings in the result.xml file, it might be because your access rights are handled with an LDAP other than the default WebSphere Portal Server database authentication. You can edit the supplied import.xml using the process below:

Editing the import.xml file

This process below is required only if errors occurred when you imported the import.xml file. You can edit the subjectid= and owner= attributes so that the values will allow authentication for importing.

The values in the import.xml are as follows:

If you installed WebSphere Portal Server with an external LDAP, your subjectid= and owner= attributes would be specific to your system, as in the following example:

The exact form of your specification can be determined by exporting your current portal configuration. To export your portal configuration, complete the following steps:

  1. Make a copy of the import.xml file before editing. (Note that some editors can alter the format of the file and should not be used.) Ensure that the WebSphere Application Server is running and that WebSphere Portal is started.
  2. Determine your current user specification by exporting your configuration:
    1. Copy the export.xml file to your <portal_root>\bin directory. This file contains a generic export command and does not require editing.
    2. Open a command prompt, switch to the <portal_root>\bin directory and run the following command:
      xmlaccess export.xml wpsadmin:<password> <hostname>/wps/config 1>myimport.xml 

      This command will create a myimport.xml file that contains your current configuration. Check this file to determine your subjectid= and owner= attribute specifications.

  3. Edit your import.xml file's subjectid= and owner= attributes to include your specifications.
  4. Repeat the installation process using XMLAccess.

Installing manually

The only file needed for a manual installation is WBIHCSamples.war. To install this file to your WebSphere Portal Server V4.2 or V4.2.1, complete the following steps:

  1. Login to your WebSphere Portal Server as an administrator.
  2. Click the Portal Administration tab.
  3. Click Portlets > Install Portlets.
  4. Enter the location and filename of the WBIHCSamples.war file.
  5. Click Next, then click Install.
  6. Logout and stop and restart the Portal Server

Note: If you make changes to the WBIHCSamples.war file, you can update a previously installed application by clicking Portlets > Portlet Applications and doing an Update instead of repeating the installation. If you update rather than re-install, you will not need to redefine the places and pages.

When you have installed the application, you must create the associated place and pages and add the portlets to the pages. The place and page names below can vary due to NLS or other factors. The portlet names must remain as shown.

  1. On the Work with Pages, Manage Places and Pages page, create a place called WB Healthcare.
  2. Create eight pages in order in this place, then click Work with Pages > Edit Layout and add the portlets provided in the list below in the following form: page name (portlet name, portlet name, …).
    Portlets are shown as they are to be placed in the page. The Summary page has three rows of portlets. The bottom two rows have two columns as shown.

You can use the Manage Users and Access Control Lists pages to create and assign users access to your place, pages, and portlets.

Return to the Work with Pages, Manage Places and Pages page and select the WBI Healthcare place. Select the Science theme for the place. This allows all of the page tabs to be visible without scrolling through the tabs.

Using the sample portal application

The following section describes how to use the various functions of the sample portal application.

Logging in

The application is accessed using a browser. Point the browser to the WebSphere Portal Server instance, enter your ID and password, then click Log in:

Screen capture of the sample portal application's log-in page

After logging in, you should see a screen such as the one in the following image:

Screen capture of the sample portal application's task selection page

You can then click the WBI Healthcare tab to enter the various pages of application. Those pages are described in the following sections.

Patient Selection

After clicking the WBI Healthcare tab, you will see the Patient Selection page. From the list box, select a patient and then click Select Patient.  After selecting the patient, click the page in the menu that you want to open. (Note: The menu on the left of the screen also appears on subsequent pages, but is not included in the screen images that follow.)

Screen capture showing the sample portal application's Patient Selection page

Summary

The Summary page lists general Patient Information along with four separate tables:

These tables, and all subsequent tables, can be scrolled in both directions and the contents can be sorted by column. The column order can be varied by dragging the column header.

Screen capture showing the sample portal application's Summary page

Problems

The Problems page displays the Patient Information and Problems table. In a fully functioning application, you can use this page to add or edit patient problems.

Screen capture showing the sample portal application's Patient Information page with Problems table

Medications

The Medications page displays the medications table for the selected patient. Use the Refresh button to show any additional orders that might have been processed since opening the Medications page. Below the medication table is a form to enter an additional medication order, including doctor information and the order details. The doctor information is loaded from the default information supplied on the System Settings page.

Enter the appropriate information and click Order to place the order. The application builds the associated XML message and places it on the queue that was specified on the System Settings page.

After the order is placed, a status message appears next to the Order button indicating that the order was placed, or detailing any problems that might have been encountered.

Screen capture showing the sample portal application's Medications page

Flowsheet

The Flowsheet page displays the Patient Information and the Flowsheet table. In a fully functioning application, you can use this page to add and edit flowsheet information.

Screen capture showing the sample portal application's Flowsheet page

Documents

The Documents page displays the Patient Information and the Documents table. In a fully functioning application, you can use this page to add and edit document information.

Screen capture showing the sample portal application's Documents page

Report

The Report page displays the compliance report table. These entries are not associated with a particular patient, but rather are records kept to comply with government reporting requirements.

Screen capture showing the sample portal application's Report page

System Settings

Each user's application system settings are maintained in the DB2 database. There are two categories of settings:

The System Settings page displays the current system settings. The first time a user enters the application, the system displays default values. The user can edit and save the new values so that they are applied on each subsequent use.

Screen capture showing the sample portal application's System Settings page

Working with the sample source files

The WBIHCSamples.war file includes all of the source elements for the application. This file can be imported into a development environment such as WebSphere Studio Application Developer. To use WebSphere Studio Application Developer for portal development, install the WebSphere Portal Toolkit plug-in before importing the .war file.

The application's Javadoc files are also supplied in the WBIHCSamplesJavadoc.zip file. The Javadoc files provide a view of the various classes of the application.

Copyright IBM Corp. 2002, 2003