DICOMInput node

Use a DICOMInput node to receive DICOM images from an SCU, store the DICOM images on the file system, and propagate metadata from the DICOM images into the message flow as XML messages.

Purpose
Using this node in a message flow
Activity log entries
Configuring the DICOMInput node
Terminals and properties

Purpose

The DICOMInput node is a Service Class Provider (SCP) node for the Verification and Storage service classes. The node receives DICOM images from a Service Class User (SCU) by accepting DICOM C-STORE commands. You can then manage the storage of the scanned images (pixel data) and extract metadata from the DICOM images to use in message flow applications.

The DICOMInput node is contained in the Healthcare drawer of the message flow node palette, and is represented in the IBM® Integration Toolkit by the following icon:

Using this node in a message flow

The DICOMInput node supports the verification SOP class so that diagnostic ECHO requests can be made to the node to validate network connectivity.

Using a configurable service, you can configure the node with the presentation contexts and transfer syntax groups that are available to the SCU. For details on creating a configurable service for a DICOMInput node, see Configuring the presentation contexts accepted by a DICOMInput node. If no configurable service is set for the node, then a default set of presentation contexts is used. For details of the default set of presentation contexts, see Default presentation contexts used by DICOMInput node.

The metadata from the DICOM images is copied and propagated through the containing message flow as an XML message. The DICOM XML message contains a reference to the scanned image (pixel data) stored in the file system. The metadata in the DICOM XML message can be transformed in the message flow however, if two images contain the same SOP instance, then, according to the DICOM standard, they must be identical in every respect. If you configure a message flow to change some metadata in a DICOM XML message, then you should also change the SOP instance so that the DICOM image is a different, and uniquely identified, DICOM image.

Storage commit: An SCU sending DICOM images to the DICOMInput node might request storage commit response messages. The purpose of a storage commit response is to confirm that a DICOM image was successfully delivered. The DICOMInput node writes the DICOM image to the file system before it sends the storage commit response message. Storage commit responses are sent asynchronously to the SCU from the DICOMInput node, over a separate connection. You must therefore configure the DICOMInput node with a port to which it can send the storage commit response messages.

Message queue: The DICOMInput node manages the transition of the metadata from the DICOM images into the message flow by using a Integration Explorer message queue. You must give each instance of the DICOMInput node a unique message queue name because queue names cannot be shared between multiple instances of the node.

Processing directory: You configure the DICOMInput node with a directory on the file system, which is used for storing DICOM images. This directory cannot be used by any other node unless you are using a multi-instance configuration. In a multi-instance configuration, the same message flow is configured on both the active and passive broker. Only one message flow is active at any time and the shared file system directory provides the state for the DICOMInput node when the message flow is activated.

Message schema: A single schema is used to describe all the DICOM XML messages that are sent by the DICOM nodes. However, only one of the complex types that are defined in the schema is used to structure each type of DICOM XML message. The DICOM complex type is used to define the DICOM XML messages that are sent from the DICOMInput node output terminal.; For more information about the schema, see DICOM message schema.

DICOM transactions: The DICOMInput node stores the DICOM images on the file system. The metadata in each DICOM image is used to create an XML message that is written to an MQ queue. The DICOMInput node uses an MQOutput node to read the XML messages from the queue and propagate them to the containing message flow. Each DICOM image therefore has two distinct transactions, one where the XML message is written to the queue, and one where the XML message is read from the queue and propagated to the containing message flow. These transactions can be monitored through the activity log entries and service trace.

Activity log entries

The following table details the activity log entries that are written by the DICOMInput node, where the following names are used in the examples:

BROKERAE is the name of the DICOMInput application entity
SOURCEAE is the name of the application entity that sent the DICOM image
hostname:1111 is the host name and port number of the receiving DICOMInput node
hostname:1112 is the host name and port number of the remote application entity

Condition	Description	Type	Example	Recommendations
Start receive	A DICOM image arrived at the DICOMInput node. Note: This activity log entry does not indicate that the DICOM image was committed to the file system.	Information BIP12068	`Received DICOM instance (BROKERAE,SOURCEAE,hostname:1111)` The DICOM image Object Identifier (OID) is logged in the `FILENAME` field in the activity log	No action is required.
End receive	A DICOM image was stored on the file system. The metadata from the DICOM image was extracted. Note: This activity log entry does not indicate that the metadata from the DICOM image was processed by the containing message flow.	Information BIP12068	`Finished processing DICOM instance (BROKERAE,SOURCEAE,hostname:1111)` The DICOM image OID is logged in the `FILENAME` field in the activity log	No action is required.
Start store queue	A DICOM image was received and is being stored on the file system.	Information BIP12068	`Storing received DICOM instance on queue (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log.	No action is required.
End queue store	A DICOM image was received and stored on the file system. The metadata from the DICOM image was successfully written to the message queue as an XML message.	Information BIP12068	`Finished storing DICOM instance on queue (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log	No action is required.
Store queue failed	A DICOM image was received and stored on the file system. The metadata from the DICOM image cannot be written to the message queue.	Error BIP12070	`Failed to store the DICOM instance on the queue (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log	Check that the queue exists. Check that the queue is write-enabled Check that the broker has write permissions to the queue.
Start send storage commit response	The DICOMInput node is sending a storage commit response message to the remote SCU	Information BIP12068	`Sending storage commit response message (BROKERAE,SOURCEAE,hostname:1112)`	No action is required.
End send storage commit response	The storage commit response message was successfully sent to the remote SCU	Information BIP12068	`Finished sending storage commit response message (BROKERAE,SOURCEAE,hostname:1112)`	No action is required.
Send storage commit response failed	The DICOMInput node cannot send a storage commit response message to the remote SCU	Warning BIP12069	`Failed to send storage commit response message (BROKERAE,SOURCEAE,hostname:1112)`	Check network connectivity between the broker and the remote SCP. Check the application entity names and port numbers match exactly with the remote SCU. Check the remote SCU is online and ready to accept storage commit connections. Check the exception details for more information about the error.
Archive DICOM image	A DICOM image is being archived by the DICOMInput node	Information BIP12068	`Archiving DICOM instance from DICOMInput node (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log.	No action is required.
Delete DICOM image	A DICOM image is being deleted from the DICOMInput archive	Information BIP12068	`Deleting DICOM instance from DICOMInput node archive (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log	No action is required.
Process DICOM image failed	The DICOM image was not processed by the DICOMInput node because the metadata in theDICOM image is larger than 4 MB	Error BIP12070	`Failed to process DICOM instance because it is larger than 4MB (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log	Exclude DICOM attributes from the message by using the Exclude DICOM Attributes property on the DICOMInput node
Process DICOM image failed	The DICOM image was not processed by the DICOMInput node	Error BIP12070	`Failed to process DICOM instance in the DICOMInput node (BROKERAE)` The DICOM image OID is logged in the `FILENAME` field in the activity log	Check the message that is propagated to the Failure terminal of the DICOMInput node for more information

Configuring the DICOMInput node

When you have added an instance of a DICOMInput node into a message flow, you can configure it.

All mandatory properties for which you must enter a value (properties that do not have a default value defined) are marked with an asterisk in the user interface.

Terminals and properties

The DICOMInput node terminals are described in the following table.

Terminal	Description
Failure	The output terminal to which a message is routed if an error occurs. The DICOMInput node propagates a failure message when an error occurs in the message flow. This error can happen if the Catch terminal on the DICOMInput node is not connected, or if an error occurs within the catch-handling logic of the message flow. The original DICOM XML message is propagated to the Failure terminal. A message is also propagated to the Failure terminal if an internal processing error occurs before a DICOM XML message is propagated to the Out terminal. An activity log entry is also written. The DICOM image that is associated with the failure message is not processed again by the DICOMInput node but it can be archived. An internal processing error can occur as a result of a restriction on the size of a DICOM XML message that can be propagated by the DICOMInput node. The node does not propagate DICOM XML messages that are larger than 4 MB. The size of a DICOM XML message can be limited by excluding attributes on the node (see the Exclude DICOM Attributes property on the Advanced tab of the DICOMInput node).
Out	The output terminal to which the DICOM XML message is routed if it is successfully retrieved from the DICOM SCU.
Catch	The output terminal to which the DICOM XML message is routed if an error occurs downstream and is caught by this node. Errors are only caught if this terminal is attached.

Terminal

Description

Failure

The output terminal to which a message is routed if an error occurs.

The DICOMInput node propagates a failure message when an error occurs in the message flow. This error can happen if the Catch terminal on the DICOMInput node is not connected, or if an error occurs within the catch-handling logic of the message flow. The original DICOM XML message is propagated to the Failure terminal.

A message is also propagated to the Failure terminal if an internal processing error occurs before a DICOM XML message is propagated to the Out terminal. An activity log entry is also written. The DICOM image that is associated with the failure message is not processed again by the DICOMInput node but it can be archived.

An internal processing error can occur as a result of a restriction on the size of a DICOM XML message that can be propagated by the DICOMInput node. The node does not propagate DICOM XML messages that are larger than 4 MB. The size of a DICOM XML message can be limited by excluding attributes on the node (see the Exclude DICOM Attributes property on the Advanced tab of the DICOMInput node).

Out

The output terminal to which the DICOM XML message is routed if it is successfully retrieved from the DICOM SCU.

Catch

The output terminal to which the DICOM XML message is routed if an error occurs downstream and is caught by this node. Errors are only caught if this terminal is attached.

The following table describes the elements in a failure message.

Element	Description
SOPInstanceUID	The unique identifier of the failed DICOM image
FailureReason	An explanation of why the DICOM image was not processed successfully
ErrorComment	Additional information, if available, that explains why the failure occurred.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the broker archive (BAR) file to deploy it).

The Description properties for the DICOMInput node are described in the following table.

Property	M	C	Default	Description
Node name	Yes	No	DICOMInput	The name of the node.
Short description	No	No		A brief description of the node.
Long description	No	No		Text that describes the purpose of the node in the message flow.

The Basic properties for the DICOMInput node are described in the following table.

Property	M	C	Default	Description
Connection details	Yes	Yes	1111	The port that listens for connection requests.
Application entity title (AET)	Yes	Yes	BROKERAE	The name for this DICOM SCP endpoint. A text string of up to 16 characters that allows application entities to be identified when they connect.
Processing directory	Yes	Yes	Input	A file system directory that the node can use to process incoming DICOM images. This directory must be unique for this node. Note: If the node property is a relative directory name, for example, Output, then it is appended to the IBM Integration Bus work path to get an absolute directory. If the node property contains an absolute directory name, for example, C:\DICOM\Input), then it is used directly as the file system location.
Queue name	Yes	Yes	DICOM	The name of the Integration Explorer queue that this node can use for internal processing. This queue must not be used by any other node or application.
Archive DICOM images this many hours after they arrive	Yes	Yes	72	DICOM images are moved from the processing directory into a subdirectory named Archive after this many hours.
Delete DICOM images this many hours after they are archived	Yes	Yes	72	DICOM images are deleted from the Archive subdirectory this many hours after they are archived.

The Advanced properties for the DICOMInput node are described in the following table.

Property	M	C	Default	Description
Exclude DICOM attributes	No	Yes	7FE00010	A comma-separated list of DICOM tags. These tags are not passed through the message flow in the DICOM XML messages. The default value of 7FE00010 is the standard DICOM tag for pixel data. Note: Other DICOM tags can be added to this list, for example 00420011, which is the DICOM tag for the encapsulated data in a DICOM Structured Report (SR).
DICOM configurable service name	No	Yes		An optional configurable service name. The configurable service contains the presentation contexts that the node makes available to an SCU. If the configurable service is not present, or is not a valid DICOM configurable service, then an error is produced when the message flow starts. If no configurable service is set for the node, then a default set of presentation contexts is used.

The Storage Commit properties for the DICOMInput node are described in the following table.

Property	M	C	Default	Description
Send storage commit responses to port	No	Yes	1112	An optional port number that is used to deliver storage commit response messages to the SCU that sent the DICOM images. If this field is blank, the node does not accept storage commit requests or send storage commit response messages.
Connection timeout (seconds)	No	Yes	60	The length of time, in seconds, that a node waits for a connection to the SCU. Note: If a port number is configured to deliver storage commit response messages, then a value must be entered for this property.

Last updated : 2015-12-07 16:17:39

Reference topic | Version 3.0.0.1 | ha05010