XDSdemo Configuration Instructions

XDSdemo is a stand-alone program for distributing DICOM images and documents for the XDS demo.

1 Directory Structure

The program's directory contains the following files and directories: The ROOT directory is the base directory for the HTTP server and the root of the servlet paths. It contains the following files and directories:

2 XDSdemo.jar

The program can be run on a Windows system by double-clicking this file.

If it is desired to monitor any possible error log entries (for example, by the DICOM library), the program should be run from a command window using the command:

If memory problems are experienced during operation, it may be necessary to increase the heap space available for Java. This can be accomplished by adding the mx and ms parameters to the command: On a Windows system, these parameters can be added to the default start parameters for the jar file type so they will be applied when the program is started by double-clicking the jar file.

3 config.xml

When the program starts, it loads the config.xml file. If the file is not present, it copies the example-config.xml file into config.xml and then loads the configuration. This allows upgrades to be done without overwriting existing configuration files.

The configuration file contains all the information necessary to define the demonstration. It is an XML file which can be edited with any text editor. Special care must be taken that the file be well-formed. Note that the assigning authority attributes in the file contain ampersands which must be escaped in the file as shown below. After editing the file, it is wise to open it in a program that will parse the file and report errors. One such program is Internet Explorer. The configuration file has the following structure: 

<config
	askOnClose="no"
	uidRoot="1.2.3.4.5.6.7"
	logDepth="100"
	serverPort="80"
	globalAssigningAuthority="RSNA_GLOBAL&amp;1.2.6.1.4.1.21367.2005.1.1&amp;ISO"
	localAssigningAuthority="RSNA_LOCAL&amp;1.2.6.1.4.1.21367.2005.1.2&amp;ISO">

	<registry id="Registry1"
		hl7URL="http://localhost:3900"
		receivingApplication="Registry1"
		receivingFacility="facility"
		acceptsITI8withGlobalID="yes"
		acceptsITI8withLocalID="no"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"/>

	<pixmgr id="PIXMgr1"
		hl7URL="http://localhost:3900"
		receivingApplication="PIXMgr1"
		receivingFacility="facility"
		acceptsITI8withGlobalID="yes"
		acceptsITI8withLocalID="no"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"/>

	<pdqmgr id="PDQMgr1"
		hl7URL="http://localhost:3900"
		receivingApplication="PDQMgr1"
		receivingFacility="facility"
		acceptsITI8withGlobalID="yes"
		acceptsITI8withLocalID="no"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"/>

	<repository id="Repository1"
		soapURL="http://localhost:3901"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"
		docsetDelay="10000"/>

	<ehrsystem id="EHRSystem1"
		hl7URL="http://localhost:3900"
		receivingApplication="EHRSystem1"
		receivingFacility="facility"
		acceptsITI8withGlobalID="no"
		acceptsITI8withLocalID="no"
		sendsITI8withLocalID="no"
		acceptsRAD1="no"
		acceptsMessages="no"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"
		localAssigningAuthority="RSNA_LOCAL1&amp;1.2.6.1.4.1.21367.2005.1.2&amp;ISO">
			<hl7 msg="ITI8" segment="PV1" seq="7" value="PV1-7 value"/>
			<hl7 msg="ITI8" segment="PV1" seq="9" value="PV1-9 value"/>
	</ehrsystem>

	<dcmsystem id="DCMSystem1"
		hl7URL="http://localhost:3900"
		receivingApplication="DCMSystem1"
		receivingFacility="facility"
		acceptsITI8withGlobalID="no"
		acceptsITI8withLocalID="no"
		sendsITI8withLocalID="no"
		acceptsRAD1="yes"
		acceptsRAD4="yes"
		dcmURL="dicom://TCE:XDSDEMO@localhost:104"
		sendsKOS="yes"
		repositoryID="Repository1"
		retrieveAET="RetrieveAETitle"
		institutionName="Hospital 1">
		pointOfCare="WestTower"
		globalAssigningAuthority="RSNA_GLOBAL&1.2.6.1.4.1.21367.2005.1.1&amp;ISO"
		localAssigningAuthority="RSNA_LOCAL2&amp;1.2.6.1.4.1.21367.2005.1.3&amp;ISO">
			<hl7 msg="RAD1" segment="PV1" seq="7" value="PV1-7 value"/>
			<hl7 msg="RAD1" segment="PV1" seq="9" value="PV1-9 value"/>
			<hl7 msg="RAD4" segment="PV1" seq="6" value="PV1-6 value"/>
	</dcmsystem>

	<study id="Study1"
		dcmsystemID="DCMSystem1"
		directory="studies/study1"
		date="20000101"
		description="..."
		placerOrderAuthority="XDSDEMO_ORDPLC"
		fillerOrderAuthority="XDSDEMO_ORDFIL"
		enteringOrganization="922229-10^IHE-RAD^IHE-CODE-231"
		procedureCode="P1^Procedure 1^XDSDEMO"
		localProcedureCode="X1_A1^SP Action Item X1_A1^DSS_XDSDEMO" />

	<docset	id="DocSet1"
		repositoryID="Repository1"
		directory="docsets/docset1"
		document="document1.xml"
		template="xmlToFO.xsl"
		metadata="metadata1.xml"
		title="Document Title"
		date="20000101"
		institutionName="Hospital 1"/>

	<docset	id="DocSet2"
		repositoryID="Repository1"
		directory="docsets/docset2"
		title="ECG Study"
		date="*"
		institutionName="Hospital 2"/>

	<message id="Message1"
		ehrsystemID="EHRSystem1"
		file="messages/message1"/>
</config>
Notes:

4 addresses.xml

The addresses.xm file contains a set of addresses to be supplied to registrants. The set is treated as a circular buffer. Each registration is given the next address in line, wrapping back to the beginning when the end of the list is reached. As the demonstration progresses, therefore, the distribution of addresses will be the same as the distribution in the set. The format of the file is: 
<addresses>

	<address
		sex="M" or "F"
		street="Elm St."
		city="Smallville"
		state="KA"
		zip="55555"
		country="US" />

	<address
		street="State St."
		city="Hampshire"
		state="IL"
		zip="60104"
		country="US" />

	...etc...

</addresses>
If a sex attribute is present with a value of "M" or "F", it applies only to registrations of the corresponding sex. If a sex attribute is not present or if it has any other value, it applies to registrations of either sex.

The country attribute is optional. The default is US.

Street addresses should not include house numbers. When the addresses.xml file is parsed, the street addresses are separated from the rest of the addresses, and any non-blank street addresses are added to a list. When a registration is received, a random selection of street, with a randomly generated house number, is applied to the next city/state/zip/country. Thus, not all address elements must include a street attribute, but at least one street attribute must be present somewhere in the file.

5 DICOM Studies

The studies directory contains one subdirectory for each DICOM study. Each subdirectory must contain only the DICOM instances to be processed and transmitted. Note that a studies subdirectory can be referenced by multiple study elements in the config.xml file.

6 Document Sets

The docsets directory contains one subdirectory for each document. A docsets subdirectory can be referenced by multiple docset elements in the config.xml file. Each subdirectory contains the following files: Each of the source files can contain special elements which insert information from the configuration or the registration into the constructed document, allowing different documents to be created from the same instructions.

7 Messages

The messages directory contains one XML file for each message to be constructed. A message file can be referenced by multiple message elements in the config.xml file. A message file defines a single HL7 message as in this example: 
<a03>
	<msh>
		<seq n="9">ADT^A03^ADT_A01</seq>
	<msh>
	<evn>
		<seq n="1">A03</seq>
		<seq n="2">@dateTime</seq>
		<seq n="6">@dateTime</seq>
	</evn>
	<pid/>
</a03>
Message and segment names are converted to upper case when they are inserted into the HL7 structure. The most common segments are populated by default from the EHRSystem's configuration parameters or from the registration. If any seq elements appear in the segment, they override the prepopulated values. The @dateTime reference generates the current date and time string. The value of a field is trimmed before being inserted into its segment.

8 HTTP Server

The ROOT directory is the base directory of the HTTP server. The server returns files in this directory in response to HTTP GETs. The server supports sub-paths from this directory (for example, http://localhost/xyz/abc.html). The server attempts to assign a proper content type for all files as defined below. It always suppresses caching.

8.1 Path Evaluation

When the HTTP server receives a request, it evaluates the path to identify the servlet which will handle the request. The servlets are:

8.2 Content Types

The HTTP Server's default servlet returns files with content types that correspond to their file extensions. It knows only the following extensions:

ExtensionContent-Type
 html  text/html;charset=UTF-8 
 htm  text/html;charset=UTF-8 
 xml  text/xml;charset=UTF-8 
 txt  text/plain;charset=UTF-8 
 gif  image/gif 
 jpeg  image/jpeg 
 jpg  image/jpeg 
 zip  application/zip 

8.3 Index files

When the program starts, it initializes each servlet by calling its static init method. This method looks in the base directory of the servlet for its index.html file. If the file is not present and there does exist an example-index.html file in the same directory, then it copies that file into the index.html file. Since the index.html files are not included in the software release, this allows the administrator of the demonstration to change those files (to include, for instance, demonstration logos and better graphics) without losing their contents during an upgrade.

9 Batch Registration Processing

The Batch Registration tab allows processing lists of registrations formatted either as an XML file using the schema of the registrations.xml file (the registratioin database) or as a CSV file. For CVS files, the column names of each of the fields must be specified in the columns.properties file. The defaultCountry property must also be included in the columns.properties file. An example file is included in the release. This file is overwritten on an upgrade, so it is important to backup the file before an upgrade. When registrations are processed, many subordinate threads are launched. To prevent the system from being flooded with threads, an interval field is provided in the header of the Batch Registration page. The default is 10 seconds. This field can be adjusted to see if shorter intervals will work.

10 Source Software Overview

Almost all the classes are in the org.rsna.xds package. The exceptions are classes provided by external libraries. The following notes are intended to provide basic guidance to the key classes for programmers wishing to modify the code.
XDSDemo
The main class of the program. This class loads the configuration, initializes the UI, initializes the servlets, and instantiates and starts the HTTP Server.
Configuration
This class contains all the configuration information, including the config.xml file, the registration database, and the event log object. An instance of this class is passed to the constructors of key objects in the system.
XDSEventLog
This class keeps a circular buffer of the last 'n' XDSEvent objects generated and appended by other objects (typically servlets) during operation of the program.
HttpServer
This class is a Thread that creates a ServerSocket, waits for connections on it, and instantiate an HttpHandler objects to service the connections.
HttpHandler
This class is a Thread that services an individual connection. It instantiates HttpRequest and HttpResponse objects for the connection and calls the static Servlet.getInstance(HttpRequest) method to obtain an instance of the Servlet to handle the request. It then calls the servlet's doGet or doPost method, depending on the request type.
HttpRequest
This class encapsulates a request. It provides access to the path, the content type, and the parameters (obtained either from the query string on a GET or the form parameters on a POST).
HttpResponse
This class encapsulates a response. It allows a servlet to send both text and files to the client in the connection's output stream. Files are written without having to be loaded completely into memory in order to minimize the footprint when returning large images. This class provides the mapping of file extensions to Content-Types in the setContentType(File) and setContentType(String) methods. To extend the known content types, add to the static ContentTypes class which is contained within the HttpResponse class.
Servlet
This is the base class for all servlets. It includes the static getInstance(HttpRequest) method which returns the appropriate subclass to service the request. The Servlet class also includes the default file server for handling GET requests that correspond to files. Thus, the getInstance method returns an instance of the Servlet class when it cannot find a subclass that corresponds to the requested path. To add new servlets to the system, create a new subclass of this class and update the getInstance method to return an instance of it in reponse to the base path that defines it. The base path for any servlet is defined by the first path element (eg "registration" for the RegistrationServlet). Each servlet handles all requests whose first path element matches its base path. The base path is defined in a servlet's static servletPath field.
ConfigurationServlet
This class is the Servlet subclass that returns a page containing the contents of the config.xml file in tabular form.
DashboardServlet
This class is the Servlet subclass that returns a page displaying the current status of the system.
RegistrationServlet
This class is the Servlet subclass that handles registrations. On a GET, it returns the index.html file from its base directory (/registration/index.html). On a POST, it returns a page displaying the request and then processes it. To process a request, it starts separate processing threads for all systems. Each system processes the request in accordance with its configuration.
PDQServlet
This class is the Servlet subclass that handles patient demographic queries. On a GET, it returns the index.html file from its base directory (/pdq/index.html). On a POST, it returns a page displaying the result of the registration database search.
MessagesServlet
This class is the Servlet subclass that provides access to collections of HL7 messages that have been captured using the program's Special tab. If called with no path, it returns a page containing a list of zip files in the base directory of the servlet. If called with a path to a file, it returns the file.
RegistrationDatabase
This class stores Registration objects in a Hashtable and allows the table to be updated and searched. It also provides persistence by saving the contents of the table as an XML file.
Registration
This class encapsulates a single registration, including the patient demographics, global ID, and the local IDs corresponding to each EHR system and DICOM system.
XDSElement
This class is the base class for all systems and datasets in the demo.
XDSSystem
This class is the XDSElement subclass for all systems in the demo.
DataSystem
This class is the XDSSystem subclass that represents systems that accept HL7 messages (PIXMgr, PDQMgr, and EHRSystem).
PIXMgr
This class is the DataSystem subclass that represents a PIX Manager.
PDQMgr
This class is the DataSystem subclass that represents a PDQ Manager.
Registry
This class is the PIXMgr subclass that represents a Registry. It behaves exactly as a PIXMgr but has a different name to avoid confusion.
Repository
This class is the XDSSystem subclass that represents a Repository.
EHRSystem
This class is the DataSystem subclass that represents an EHR System.
DCMSystem
This class is the EHRSystem subclass that represents a DICOM System.
HL7Message
This class encapsulates a simple HL7 message, providing management of its segments. It also provides methods to save the message to a file and transmit the message to an HL7 system.
HL7Segment
This class encapsulates an HL7 message segment, providing methods for getting and setting fields.
HL7A04
This class is an abstract class to encapsulate an HL7 A04 message. It instantiates the required segments in the proper order and provides methods for populating the required fields.
HL7ITI8
This class extends HL7A04 to create an ITI8 transaction.
HL7RAD1
This class extends HL7A04 to create a RAD1 transaction.
HL7RAD4
This class implements the RAD4 transaction.
HL7Field
This class encapsulates a field in an HL7 message. It is used only to store the contents of hl7 elements in the config.xml file, as shown in the ehrsystem and dcmsystem examples in the config.xml section, above. These fields allow messages to be configured individually for each system when necessary.
KOS
This class encapsulates a DICOM Key Object Selection object. It is created during the processing of a study for a DicomSystem and transmitted (when enabled by the configuration of the DicomSystem) to the Repository.
XDSSoapRequest
This class provides transport for a metadata file and its associated XML object. This is used by the Repository class to send a CDA to a repository.
Study
This class is the XDSElement subclass that encapsulates a DICOM study. It points to the DicomSystem to which it will be sent.
DocSet
This class is the XDSElement subclass that encapsulates a collection of documents. It points to the Repository to which it will be sent.
SimpleInstaller
This class is the base class for the program's installer.
Installer
This class is the SimpleInstaller subclass that provides the parameters required for installation of XDSdemo.