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
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 integration solutions.

The DICOMInput node is contained in the Healthcare drawer of the message flow node palette, and is represented in the IBM® App Connect Enterprise 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.

By using a policy, you can configure the node with the presentation contexts and transfer syntax groups that are available to the SCU (see Configuring the presentation contexts that are accepted by a DICOMInput node). If no policy is set for the node, a default set of presentation contexts is used (see Default presentation contexts that are used by the 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) that is 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, you should also change the SOP instance so that the DICOM image is a different, and uniquely identified, DICOM image.

Storage commit: An SCU that sends 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 delivered successfully. 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 an IBM MQ 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 integration node. 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. Ensure that this directory has the required permissions to allow the user that starts the integration node or integration server to read and write files to the directory. The DICOM image that is stored on the file system is not encrypted. Therefore, you must decide whether to implement file system encryption.

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, 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 MQInput 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 describes 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 written successfully 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 integration node 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 integration node 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

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 retrieved successfully 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 retrieved successfully 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 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	This property specifies the port that listens for connection requests.
Application entity title (AET)	Yes	Yes	BROKERAE	This property specifies the name for this DICOM SCP endpoint. The value is a text string of up to 16 characters that allows application entities to be identified when they connect.
Processing directory	Yes	Yes	Input	This property specifies a file system directory that the node can use to process incoming DICOM images. This directory must be unique for this node. Ensure that this directory has the required permissions to allow the user that starts the integration node or integration server to read and write files to the directory. Note: If the node property is a relative directory name (for example, Output), it is appended to the IBM App Connect Enterprise work path to get an absolute directory. If the node property contains an absolute directory name (for example, C:\DICOM\Input), it is used directly as the file system location.
Archive DICOM images this many hours after they arrive	Yes	Yes	72	DICOM images are moved from the processing directory into a subdirectory that is named Archive after the number of hours specified by this property.
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.
Queue name	Yes	Yes	DICOM	This property specifies the name of the IBM MQ queue that this node can use for internal processing. This queue must not be used by any other node or application.

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

Property	M	C	Default	Description
Exclude DICOM attributes	No	Yes	7FE00010	This property provides 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 policy name	No	Yes		This property specifies an optional policy name. The policy contains the presentation contexts that the node makes available to an SCU. If the policy is not present, or is not a valid DICOM policy, an error is produced when the message flow starts. If no policy 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	This property specifies 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	This property specifies 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, a value must be entered for this property.

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

Property	M	C	Default	Description
Additional instances pool	No	Yes	Use pool associated with message flow	This property specifies the pool where additional instances are obtained. If you select Use pool associated with message flow, additional instances are obtained from the message flow value. If you select Use pool associated with node, additional instances are allocated from the additional instances of the node, based on the number that is specified in the Additional instances property.
Additional instances	No	Yes	0	This property specifies the number of additional instances that the node can start if the Additional instances pool property is set to Use pool associated with node. By default, no additional instances are given to the node.