2 Installing and Configuring the Oracle DICOM Protocol Adapter
The Oracle DICOM protocol adapter is the core component of Oracle DICOM protocol adapter suite, acting as a bridge between standard DICOM clients (such as PACS and DICOM viewers) and WebCenter Content. This chapter discusses how to install and configure the adapter, the crawler and the proxy.
This documentation assumes that you are familiar with the process for deploying applications on WebLogic Server. For complete documentation about application deployment, see Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
This chapter contains the following sections:
2.1 About the Oracle DICOM Protocol Adapter
The Oracle DICOM protocol adapter is composed of three components. You can deploy all or just selected components on WebLogic Server.
The following sections provide a detailed overview of each component:
For details about deploying the components, see the following sections:
For details about configuring each component, see the following sections:
2.1.1 The Oracle DICOM Protocol Adapter
The DICOM adapter is deployed as a ResourceAdapter application in Oracle WebLogic Server. The adapter supports the following DICOM Protocol roles:
-
C-ECHO SCP
-
C-FIND SCP
-
C-MOVE SCP
-
C-STORE SCP
-
C-STORE SCU
See Section 2.1.1.1, "Protocol Message Handling" for more details about those protocol roles.
The following iillustration shows how the protocol adapter interacts with other DICOM clients, such as DICOM viewers and PACS, as well as with WebCenter Content. This example shows how a PACS might push an image to the DICOM adapter for checkin to Content Server. It also illustrates how a DICOM viewer might attempt to query and retrieve DICOM images from Content Server via the DICOM adapter.
Description of the illustration viewer_adapter.gif
2.1.1.1 Protocol Message Handling
The DICOM adapter supports the following operations of the DICOM network protocol (as specified in the DICOM standard). DICOM clients may issue these DICOM commands to the DICOM adapter to query and retrieve DICOM image content stored in Content Server:
-
C-ECHO: used to determine connectivity between the DICOM adapter and a DICOM client. Upon receipt of a C-ECHO request, the DICOM adapter issues a C-ECHO response indicating that the message was received and that the connection is good.
-
C-MOVE: used to query the DICOM adapter to retrieve images from the content server repository that match the given metadata attributes (wildcards are supported) defined in the C-MOVE request.
-
C-STORE: used to transfer an image to the DICOM adapter. When the DICOM adapter receives a C-STORE request, it takes the associated DICOM image and checks the image into Content Server.
-
C-FIND: used to query the DICOM adapter to retrieve image metadata in the content server repository that matches the given query. Wildcards are supported in the queries.
2.1.2 The Oracle DICOM Crawler
The Oracle DICOM crawler is a scheduled service of the DICOM adapter that periodically queries a set of PACS using the DICOM protocol to import new DICOM images and/or DICOM metadata into Content Server. It is deployed as a ResourceAdapter application in Oracle WebLogic Server.
The user can configure the DICOM crawler to periodically issue DICOM C-FIND requests to a PACS in order to identify DICOM images of interest according to user-specified search criteria. When the DICOM crawler identifies such images, it issues a C-MOVE request to the PACS in order to transfer these images to the DICOM adapter which will check in the images or the images' metadata to the content server repository. The following graphic depicts how these messages are exchanged between the DICOM crawler, PACS, and the DICOM adapter.
Description of the illustration crawler.gif
2.1.3 The Oracle DICOM WADO Proxy
The Oracle DICOM WADO proxy is a service that retrieves DICOM images via a WADO-formatted URL when the image metadata is in the Content Server and the images are in the PACS.
The WADO proxy is deployed as a JAX-RS Servlet application in Oracle WebLogic Server. The proxy listens for HTTP GET requests that correspond to the retrieval of a specific DICOM image from a specific PACS. Both the AE title of the PACS and the unique SOP instance UID of the image are encoded as part of the WADO URL. The format of the WADO URL is as follows:
http://hostname:port/dicom-net/resource/AE_TITLE /wado?requestType=WADO&studyUID=study_uid&seriesUID=series_uid &objectUID=instance_uid
When the proxy receives a WADO request like this, it issues a C-MOVE request to the corresponding PACS in order to retrieve the image. After the proxy receives the C-STORE request from the PACS with the DICOM image data corresponding to the C-MOVE it issued, the proxy passes the DICOM image data to the HTTP client that issued the WADO request.
The following figure depicts how the set of messages required to process a WADO request from a WADO client is exchanged between the various components. The figure also shows how this type of WADO URL is generated at checkin time for a DICOM image originating from a PACS.
Description of the illustration proxy.gif
2.2 Deploying the Oracle DICOM Protocol Adapter
Several steps must be followed in order to deploy the Oracle DICOM protocol adapter:
-
Install and deploy the OrdDicomLibrary.ear file, which contains the Java classes and Java libraries required to run the Oracle DICOM protocol adapter.
-
Also install and deploy the OrdDicomAdapter.ear archive file, which contains the files for each component in the Oracle DICOM protocol adapter. See Section 2.2.1, "Deploying the Archive Files" for details.
-
Perform a standard deployment (as described in Section 2.2.2, "Standard Deployment") or an advanced deployment to choose individual components for installation (as described in Section 2.2.3, "Advanced Deployment").
This documentation assumes that you are familiar with the process for deploying applications on WebLogic Server. For complete documentation about application deployment, see Oracle Fusion Middleware Deploying Applications to Oracle WebLogic Server.
2.2.1 Deploying the Archive Files
The Oracle DICOM protocol adapter is distributed as two WebLogic enterprise archive files.
The OrdDicomLibrary.ear archive contains all the Java classes and other Java libraries required to run the adapter.
The OrdDicomAdapter.ear archive references the OrdDicomLibrary.ear archive file and contains the XML descriptors and configuration files that are necessary to provide a bare-bones deployment configuration for the three components of the Oracle DICOM protocol adapter.
To deploy the OrdDicomLibrary.ear archive to WebLogic, use the weblogic.Deployer tool by issuing a command similar to the following:
java weblogic.Deployer -upload -name OrdDICOM -source OrdDicomLibrary.ear -targets [target_name] -adminurl [weblogic_admin_url] -user [weblogic_user] -deploy -library
To deploy the individual components of the Oracle DICOM protocol adapter, extract the contents of the OrdDicomAdapter.ear archive using the Java jar tool. Then modify the XML configuration files before deploying, as described in Section 2.3, "Configuring the Oracle DICOM Protocol Adapter."
If the archive is extracted to a directory named oracle-dicom, the file structure of the directory appears as follows:
oracle-dicom/META-INF/MANIFEST.MF oracle-dicom/META-INF/application.xml oracle-dicom/META-INF/weblogic-application.xml oracle-dicom/APP-INF/lib/dicom-net_adapter.jar oracle-dicom/APP-INF/lib/dicom-net_adapter.rar oracle-dicom/APP-INF/lib/dicom-net_crawler.jar oracle-dicom/APP-INF/lib/dicom-net_crawler.rar oracle-dicom/APP-INF/lib/dicom-net_wado.war oracle-dicom/APP-INF/classes/ordim_adapter_config.xml oracle-dicom/APP-INF/classes/ordim_crawler_config.xml oracle-dicom/APP-INF/classes/ordim_wado_config.xml
The XML files in the oracle-dicom/APP-INF/classes directory are the files used to configure each of the Oracle DICOM protocol adapter's components. See Section 2.3.1, "Configuring the DICOM Adapter," Section 2.3.2, "Configuring the DICOM Crawler," and Section 2.3.3, "Configuring the DICOM WADO Proxy."
The archive files in the oracle-dicom/APP-INF/lib/ directory correspond to the modules comprising the Oracle DICOM protocol adapter.
The XML files in the oracle-dicom/META-INF/ directory correspond to the WebLogic deployment descriptors describing all the modules and resources used in the application.
2.2.2 Standard Deployment
Important:
The OrdDicomLibrary.ear library must be deployed to WebLogic and the Oracle DICOM component for WebCenter installed to Content Server before deploying the Oracle DICOM protocol adapter. See Section 2.2.1, "Deploying the Archive Files" and Section 3.2, "Installing and Using the Oracle DICOM Component for WebCenter" for details.
To deploy a single instance of each of the three components of the Oracle DICOM protocol adapter, edit the XML files in the oracle-dicom/APP-INF/classes/ directory.
After the configuration files are modified, deploy the application to WebLogic by issuing a command similar to the following command. In this example, it is assumed that the user extracted the OrdDicomLibrary.ear archive to a directory named oracle-dicom.
java weblogic.Deployer -upload -name OracleDicomAdapterSuite -source 'oracle-dicom' -targets myserver -adminurl [weblogic_admin_url] -user [weblogic_user] -deploy
This command deploys the three components of the Oracle DICOM protocol adapter to WebLogic and starts them.
2.2.3 Advanced Deployment
Although the components of the Oracle DICOM protocol adapter are bundled together in a single enterprise archive, it is not necessary for all of the components to be deployed together at once. Multiple instances can be deployed of a particular component, or no instance at all can be deployed of a particular component.
The META-INF/application.xml file describes the modules that will be enabled at deployment time. The following is an example of this file:
<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/application_5.xsd"
version="5">
<!-- Oracle DICOM Protocol Adapter -->
<module>
<connector>/APP-INF/lib/dicom-net_adapter.rar</connector>
</module>
<module>
<ejb>/APP-INF/lib/dicom-net_adapter.jar</ejb>
</module>
<!-- Oracle DICOM Crawler -->
<module>
<connector>/APP-INF/lib/dicom-net_crawler.rar</connector>
</module>
<module>
<ejb>/APP-INF/lib/dicom-net_crawler.jar</ejb>
</module>
<!-- Oracle DICOM WADO Proxy -->
<module>
<web>
<web-uri>/APP-INF/lib/dicom-net_wado.war</web-uri>
<context-root>dicom-net</context-root>
</web>
</module>
</application>
In this example, all three components of the Oracle DICOM protocol adapter are enabled. To disable any of these components, delete (or comment out) the module references corresponding to the component to remove.
Both the DICOM adapter and the DICOM crawler components require at least two module definitions.
The *.rar archive is the ResourceAdapter archive for the component (there must be one of these for the component).
The *.jar is the MessageDrivenBean (MDB) archive for the component (there must be at least one of these for the component).
There is only a single module definition required per instance of the DICOM WADO proxy component (the *.war archive).
By default, there is an Oracle DICOM protocol adapter configuration file for each of the MDB archives and one for the WADO proxy archive, as shown in the following list:
-
dicom-net_adapter.jar and ordim_adapter_config.xml
-
dicom-net_crawler.jar and ordim_crawler_config.xml
-
dicom-new_wado.war and ordim_wado_config.xml
Follow these steps to deploy multiple instances of any of the three components of the Oracle DICOM protocol adapter:
-
Create a copy of the appropriate MDB (*.jar) archive or WADO (*.war) archive.
-
Modify the copy of the archive as described in Section 2.2.3.1, "Modifying the Individual Component Archives."
-
Place the modified archive alongside the original in the APP-INF/lib/ directory.
-
Place the new XML configuration file (modified in step 2) in the APP-INF/classes/ directory.
-
Add a
<module>entry in the META-INF/application.xml file for the new archive. -
Deploy the components using the weblogic.Deployer utility (see Section 2.2.2, "Standard Deployment").
2.2.3.1 Modifying the Individual Component Archives
This section describes the necessary modifications for the different Oracle DICOM protocol adapter components.
2.2.3.1.1 DICOM adapter
To modify the adapter .jar archive, rename the MDB and update the name of the XML configuration file to use. To do this, edit the META-INF/ejb-jar.xml file from the archive and change the following parameter values (marked in bold italics):
<message-driven>
<display-name>DICOM_ADAPTER</display-name>
<ejb-name>DICOM_ ADAPTER</ejb-name>
[…]
</message-driven>
<container-transaction>
<method>
<ejb-name>DICOM_ ADAPTER</ejb-name>
[…]
</method>
[…]
</container-transaction>
<activation-config-property>
<activation-config-property-name>adapterConfig</activation-config-property-name>
<activation-config-property-value>ordim_adapter_config.xml</activation-config-property-value>
</activation-config-property>
The META-INF/weblogic-ejb-jar.xml file from the archive must also be edited with changes to these additional parameter values (marked in bold italics):
<weblogic-enterprise-bean>
<ejb-name>DICOM_ ADAPTER</ejb-name>
[…]
</ weblogic-enterprise-bean>
2.2.3.1.2 DICOM crawler
In order to modify the *.jar archive to create a new instance of the Oracle DICOM crawler, the user must rename the MDB and update the name of the XML configuration file to use.
To do this, edit the META-INF/ejb-jar.xml file from the archive and change the following parameter values (marked in bold italics):
<message-driven>
<display-name>DICOM_CRAWLER</display-name>
<ejb-name>DICOM_CRAWLER</ejb-name>
[…]
</message-driven>
<container-transaction>
<method>
<ejb-name>DICOM_CRAWLER</ejb-name>
[…]
</method>
[…]
</container-transaction>
<activation-config-property>
<activation-config-property-name>crawlerConfig</activation-config-property-name>
<activation-config-property-value>ordim_crawler_config.xml</activation-config-property-value>
</activation-config-property>
You must also edit the META-INF/weblogic-ejb-jar.xml file from the archive and change these additional parameter values (marked in bold italics):
<weblogic-enterprise-bean>
<ejb-name>DICOM_CRAWLER</ejb-name>
[…]
</ weblogic-enterprise-bean>
2.2.3.1.3 Oracle DICOM WADO proxy
To create a new instance of the WADO proxy, first modify the WADO .war archive. To do this, rename the servlet and update the name of the XML configuration file to use by editing the WEB-INF/web.xml file from the archive and change the following values (marked in bold italics):
<context-param>
<param-name>wadoConfig</param-name>
<param-value>ordim_wado_config.xml</param-value>
</context-param>
<servlet>
<display-name>JAX-RS Servlet</display-name>
<servlet-name>jersey</servlet-name>
[…]
</servlet>
<servlet-mapping>
<servlet-name>jersey</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
2.3 Configuring the Oracle DICOM Protocol Adapter
This section describes how to configure the three components of the Oracle DICOM protocol adapter:
2.3.1 Configuring the DICOM Adapter
The DICOM adapter can be configured by creating an XML file that adheres to the ordim_adapter_config.xsd schema as detailed in Section A.1, "ordim_adapter_config.xsd."
This section describes the elements which are configurable in that schema.
2.3.1.1 adapter
Used to identify the DICOM host information for the DICOM adapter.
-
title: specifies the DICOM AE title for the host.
-
bind: specifies the port number the host will listen on for incoming DICOM assocations.
The following is an example of the adapter element.
<adapter useSSL="false">
<title>UCM</title>
<bind port="11112"/>
</adapter>
2.3.1.2 UCM
Used to identify how to connect to the WebCenter Content server with Content Server checkin properties.
-
connection: specifies the parameters required for the DICOM adapter to connect to WebCenter Content.
-
url: the URL used to connect to the WebCenter Content server.
-
login: the login credentials (user name and password) for the connection to the WebCenter Content server. If the password is not supplied, it will be retrieved via the credential map for the default WebLogic security realm associated with the resource adapter for the DICOM adapter.
-
-
properties: used to identify the Content Server checkin properties to use when checking in DICOM images using the DICOM adapter.
-
property: specifies the name and value of a Content Server checkin property. Valid properties include the following:
-
SECURITY_GROUP: a string value representing the name of the WebCenter Content security group to use for checkins.
-
DICOM_DOC_CHECKIN: a Boolean value representing whether or not to store an image representation of a DICOM image on checkin.
-
DICOM_DOC_TYPE: a string value representing the Content Server document type to use for DICOM image checkins.
-
DICOM_DOC_FOLDER: a string value representing the name of the Content Server folder where DICOM images should be stored.
-
DICOM_DOC_ORIGINAL: a Boolean value representing whether to retain the original DICOM image on checkin.
-
DICOM_DOC_PREVIEW: a Boolean value representing whether to generate an image preview of a DICOM image on checkin.
-
DICOM_XML_CHECKIN: a Boolean value representing whether to generate an XML-based representation of the metadata of a DICOM image on checkin.
-
DICOM_XML_TYPE: a string value representing the Content Server document type to use for DICOM XML metadata on checkin.
-
DICOM_XML_FOLDER: a string value representing the name of the Content Server folder where DICOM XML metadata will be stored.
-
DICOM_WADO_LINK_ENABLE: a Boolean value representing whether to generate a WADO URL on DICOM image checkin.
-
DICOM_WADO_LINK_PREFIX: a string value representing the base URL (the prefix string) for the WADO link generation.
-
-
The following is an example of the UCM element:
<UCM>
<connection>
<url location="http://hostname:16200/cs/idcplg"/>
<login username="user" password="pass"/>
</connection>
<properties>
<property name="SECURITY_GROUP" value="DICOMGroup"/>
<property name="DICOM_DOC_CHECKIN" value="true"/>
<property name="DICOM_DOC_TYPE" value="DICOM"/>
<property name="DICOM_DOC_FOLDER" value="/Contribution Folders/DICOM"/>
<property name="DICOM_DOC_ORIGINAL" value="true"/>
<property name="DICOM_DOC_PREVIEW" value="false"/>
<property name="DICOM_XML_CHECKIN" value="false"/>
<property name="DICOM_XML_TYPE" value="DICOMXML"/>
<property name="DICOM_XML_FOLDER" value="/Contribution Folders/DICOM"/>
<property name="DICOM_WADO_LINK_ENABLE" value="true"/>
<property name="DICOM_WADO_LINK_PREFIX" value="http://hostname:7001/dicom-net/resource"/>
</properties>
</UCM>
2.3.1.3 DICOM
Specifies DICOM-specific configurations such as AE title to IP address/port mapping.
-
hosts: specifies the set of DICOM clients which are permitted to connect to the adapter.
-
host: specifies the AE title, IP address, and port of a remote DICOM client to which the adapter can connect.
-
The following is an example of the DICOM element.
<DICOM>
<hosts>
<host title="TESTPACS" address="testpacs.hostname" port="11112"/>
<host title="WADO" address="127.0.0.1" port="12347"/>
</hosts>
</DICOM>
2.3.2 Configuring the DICOM Crawler
The Oracle DICOM crawler can be configured by creating an XML file that adheres to the ordim_crawler_config.xsd schema as detailed in Section A.2, "ordim_crawler_config.xsd." This section describes those elements in the schema that are configurable.
2.3.2.1 crawler
Specifies the DICOM host configuration for the DICOM crawler.
-
title: the DICOM AE title for the crawler.
The following is an example of the crawler element.
<crawler>
<title>UCM_CRAWLER</title>
</crawler>
2.3.2.2 jobs
Represents a single crawler job.
-
target: the AE title of the DICOM client to search.
-
dest: the AE title of the DICOM host where DICOM images should be sent.
-
period: the delay between job runs, including time units.
-
search: the list of queries to perform, in order, during the job invocation. Queries are chained such that the output of one query serves as the base dataset for the next query.
-
query: represents a single query, specifying the name of the dataset and the DICOM search root to use.
-
The following is an example of the jobs element.
<jobs>
<job>
<target title=" PACS "/>
<dest title="UCM"/>
<period duration="15" timeUnit="s"/>
<search>
<query searchRoot="study" dataset="Q1"/>
<query searchRoot="study" dataset="Q2"/>
<query searchRoot="study" dataset="Q3"/>
</search>
</job>
</jobs>
2.3.2.3 hosts
Specifies the set of DICOM clients to which the crawler is permitted to connect.
-
host: specifies the title, IP address, and port of a remote DICOM client to which the crawler can connect.
The following is an example of the hosts element.
<hosts>
<host title="UCM" address="localhost" port="12345"/>
<host title="PACS " address="pacs.hostname" port="11112"/>
</hosts>
2.3.2.4 datasets
Specifies the set of DICOM datasets to use as part of the queries for the crawler jobs. Each dataset is assigned a name that can be referenced in the query tag for a job.
-
dataset: specifies a single dataset.
-
value: a DICOM tag and its corresponding value, as a tag/value pair.
-
The following is an example of the datasets element.
<datasets>
<dataset name="Q1">
<value tag="00080052">STUDY</value>
<value tag="0020000D">*</value>
</dataset>
<dataset name="Q2">
<value tag="00080052">SERIES</value>
<value tag="0020000E">*</value>
</dataset>
<dataset name="Q3">
<value tag="00080052">IMAGE</value>
<value tag="00080018">*</value>
</dataset>
</datasets>
2.3.3 Configuring the DICOM WADO Proxy
The Oracle DICOM WADO proxy can be configured by creating an XML file that adheres to the ordim_wado_config.xsd schema as detailed in Section A.3, "ordim_wado_config.xsd." This section describes those elements in the schema that are configurable.
2.3.3.1 wado
Used to identify the DICOM host information for the Oracle DICOM WADO proxy.
-
wado: identifies the DICOM host information for the proxy.
-
title: specifies the DICOM AE title for the host.
-
bind: specifies the port number the host will listen on for incoming DICOM assocations.
-
The following is an example of the wado element.
<wado useSSL="false">
<title>WADO</title>
<bind port="12347"/>
</wado>
2.3.3.2 hosts
Specifies the set of DICOM clients to which the proxy is permitted to connect.
-
host: specifies the AE title, IP address, and port of a remote DICOM client to which the proxy can connect.
The following is an example of the hosts element.
<hosts>
<host title="UCM" address="localhost" port="12345"/>
<host title="PACS " address="pacs.hostname" port="11112"/>
</hosts>
2.4 Sample Configuration Scenarios
Two typical scenarios were discussed in Section 1.2, "Usage Scenarios". This section provides the details for configuring those scenarios.
In each scenario, the following steps must be taken:
-
Configure the Oracle DICOM crawler with the connection details of all PACS from which the user will import images. See Section 2.3.2, "Configuring the DICOM Crawler" for details.
-
Set up the DICOM query that serves as a filter restricting which images will be returned.
-
Configure the DICOM component by adding metadata mapping in the oracle_dicom_config.hda file UCM_DICOM_MAP ResultSet. Add a metadata mapping for each of the DICOM metadta elements the user wants to retain on image import. See Section 3.3.1, "Editing the oracle_dicom_config.hda File" for details.
2.4.1 Scenario 1: Importing Images and Image Metadata
This scenario assumes the user will consolidate all DICOM images and image metadata from PACS into Content Server.
To accomplish this, the following properties must be set in the DICOM adapter configuration:
<property name="DICOM_DOC_CHECKIN" value="true"/> <property name="DICOM_DOC_ORIGINAL" value="true"/>
These settings ensure that when an image is imported from a PACS, the metadata is extracted from the image and populated into Content Server metadata fields and the original image is retained in Content Server. After an image is imported, a user can search for the image based on its metadata and retrieve it directly from Content Server or via the DICOM adapter.
2.4.2 Scenario 2: Importing Only Image Metadata
This scenario assumes a user will consolidate only DICOM image metadata from PACS into Content Server.
The user must configure the WADO proxy so it has the connection details for all the PACS (that is, the same set as the DICOM crawler). Set the properties in the DICOM adapter configuration as follows, setting hostname:port to the hostname and port set for the WADO proxy:
<property name="DICOM_DOC_CHECKIN" value="true"/>
<property name="DICOM_DOC_ORIGINAL" value="false"/>
<property name="DICOM_WADO_LINK_ENABLE" value="true"/>
<property name="DICOM_WADO_LINK_PREFIX" value="http://hostname:port/dicom-net/resource"/>
The first two properties ensure that only the DICOM image metadata is retained by Content Server in the populated metadata fields even though the image is checked into Content Server on import.
The last two properties ensure that a WADO link is generated and added as one of the Content Server metadata fields. This link is a URL that points to the WADO proxy and includes all the information required by the proxy to retrieve the original image from the PACS where the image is stored. Thus the user can always access the original image by visiting the WADO link URL.
In this scenario, the user may still search for imported images based on metadata (the same as scenario 1), but the original images themselves are no longer available directly from Content Server. Instead, the user can search for an image and look up its corresponding WADO link in order to retrieve it (when searching for an image via Content Server directly).
Or the user can issue a DICOM query via the DICOM adapter to retrieve an image. The adapter will transparently retrieve the original image from the PACS via the WADO link and pass it on to the DICOM client that issued the request.