Tasks for DICOM Productions
This page describes how to perform typical production configuration specifically for a DICOM production:
Adding a DICOM Duplex Business Service
InterSystems provides a built-in duplex business host that accepts DICOM documents from external sources over TCP connections.
To add a DICOM duplex business service to a production:
-
Display the production in the Interoperability > Configure > Production page of the Management Portal.
-
In the Services column, click the Add button (a plus sign).
-
In the dialog box, select the EnsLib.DICOM.Service.TCPOpens in a new tab class from the Service Class list.
-
For Service Name, type the name of this business service. The name should be unique among the business services. Do not use periods or spaces.
The default is the name of the class on which this service is based.
-
Click OK.
Adding a DICOM File Business Service
InterSystems provides a built-in file business service that accepts DICOM documents from external files.
To add a DICOM file business service to a production:
-
Display the production in the Production Configuration page of the Management Portal.
-
In the Services column, click the Add button (a plus sign).
-
In the dialog box, select the EnsLib.DICOM.Service.FileOpens in a new tab class from the Service Class list.
-
For Service Name, type the name of this business service. The name should be unique among the business services. Do not use periods or spaces.
The default is the name of the class on which this service is based.
-
Click OK.
-
Optionally enable the UseStorageLocation setting of the new business host (EnsLib.DICOM.Service.FileOpens in a new tab).
When a EnsLib.DICOM.Service.FileOpens in a new tab reads a file, it creates a stream that it stores in the stream directory for the namespace (for example, mgr/name/stream). If UseStorageLocation is enabled, these streams will be stored in the StorageLocation, which is where the rest of the DICOM data is stored.
Creating a DICOM Business Process
To build a DICOM business process for use in a DICOM production, you must develop a custom business process class that performs the appropriate logic, create a business process that uses your custom class, configure it, and integrate it into the production. This topic explains each step:
Developing a DICOM Business Process Class
The bidirectional nature of DICOM means you cannot write business processes using BPL; you must create a custom business process using ObjectScript.
When you create your custom class, extend EnsLib.DICOM.ProcessOpens in a new tab which is the superclass for all user-defined DICOM business processes. See its entry in the Class Reference for detailed information. For information on creating a class, see Developing Custom Business Processes.
Because of the duplex nature of DICOM communication, the business process must keep track of what is happening outside of the process. You can accomplish this using a context variable for the state of the process and model your code after a event driven finite state machine.
About Sessions
The base class for DICOM business processes includes a StopPrivateSession method that can be called to ensure that each message gets its own session. For example, the OnMessage method of a business process could include the following code:
#; Send the reply back to the service ( don't want a response )
Set tSC=..SendRequestAsync(..ServiceDuplexName,tOutput,0)
f $$$ISERR(tSC) Quit
#; Stop the private session to ensure each message gets its own session
Set tSC=..StopPrivateSession(..ServiceDuplexName)
If $$$ISERR(tSC) Quit
However this approach can cause an asynch timing issue if the business service in the production receives a new document before it processes the request to stop the private session. If this scenario is possible, and each DICOM incoming message requires its own private session, the solution is to place the StopPrivateSession() call in a custom business service rather than the business process. For example, you could subclass EnsLib.DICOM.Service.TCP and override the SendDocument method with the following code:
Method SendDocument(pRequest As EnsLib.DICOM.Document, Output pResponse As %Library.Persistent) As %Status
{
Set tSC = ##super(pRequest)
If $$$ISOK(tSC)
{ If ..%InPrivateSession Set tSC=..StopPrivateSession() }
Quit tSC
}
When deciding whether to stop a private session, it is important to consider whether a single request can have multiple replies. For example, if there is a request that expects multiple replies that can come in fast and cause an issue, then it makes sense to wait until everything has been processed before stopping the session. If, on the other hand, there is a simple 1-to-1 operation like a single C-STORE and its response, then it is appropriate to have each request/response in a separate private session.
Adding a DICOM Business Process
To add a DICOM business process to a production:
-
Display the production in the Production Configuration page of the Management Portal.
-
In the Processes column, click the Add button (a plus sign).
-
In the dialog box, select your custom class from the Process Class list.
-
For Process Name, type the name of this business process. The name should be unique among the business processes. Do not use periods or spaces.
The default is the name of the class on which this process is based.
-
Click OK.
Integrating a DICOM Business Process
To integrate a new DICOM business process into a production, you must associate it with the business service that receives its incoming documents, and with the routing rule set that determines its actions based on those documents. To do this:
Select the DICOM business service in the configuration diagram. In the Duplex Target Config Names field enter the configured Name of the DICOM business process.
Adding a DICOM Duplex Business Operation
InterSystems provides built-in duplex business host that accepts DICOM document messages from external sources over TCP connections.
To add a DICOM business operation to a production:
-
Display the production in the Production Configuration page of the Management Portal.
-
In the Operations column, click the Add button (a plus sign).
-
In the dialog box, select the EnsLib.DICOM.Operation.TCPOpens in a new tab class from the Operation Class list.
-
For Operation Name, type the name of this business operation. The name should be unique among the business operations. Do not use periods or spaces.
The default is the name of the class on which this operation is based.
-
Click OK.
Configuring a DICOM Duplex Business Host
To configure a business host, click it in the diagram on the Production Configuration page, edit details on the Settings tab, and click Apply.
For a DICOM business host, you can configure the following settings:
Specify the configuration item within the production to which the business host sends any DICOM documents that it receives.
The called Application Entity Title (AET) that the remote DICOM peer uses to communicate with the production. This corresponds to the Called AET you use when defining an association in an interoperability-enabled namespace. For DICOM business services, you can set this property and the RemoteAET property to the * wildcard. If both of these properties are set to the * wildcard, the business service bypasses the usual checks on AET names, instead does a direct lookup on association contexts defined within the database. If the association context is defined then the connection is opened and the association is negotiated as usual, if not then the connection is rejected.
The calling Application Entity Title(s) of a remote DICOM peer.
When the adapter is in the role of Service Class Provider (SCP, server) it contains a comma-delimited list of names of the DICOM peers which are allowed to connect. A name can either be a literal string or a pattern/substitution specification of the form:
?Pattern/Substitution
For the pattern/substitution form, the production matches the calling AET against the pattern. If there is a match then it uses the substitution for association validation. For example, the following setting value:
?1"B".E/JD-SCU
Indicates that the pattern must match exactly one letter B followed by any number of any other character(s), so this entry matches any calling AET that starts with B and substitutes JD-SCU. To accept any AET use ?.E for a pattern.
When the adapter is in the role of Service Class User (SCU, client), it must contain the AET of the DICOM peer to which the prodcution is connecting or be set to the * wildcard (see description of LocalAET property).
Flag value for how much debug information to provide:
0 - No information 1 - Terse debug information 2 - Verbose debug information
The association request/reject/release timeout (in seconds). Adjust the value upwards if you find that a peer takes a long time to respond to association requests.
The data transfer timeout (in seconds). Adjust the value upwards if you find that a peer takes a long time to respond during data transfer.
True or False — Indicates whether or not to spawn a new process to handle each incoming TCP connection. A value of True allows simultaneous handling of multiple connections.
IP port of the DICOM peer.
IP address to connect to the DICOM peer. This property is null if it is in listening mode.
If in Listening mode, how many incoming connections should the OS hold open on our behalf until they can be processed. Set to 0 if only one connection at a time is expected; the operating system will refuse additional connection attempts. Set to a large number if many clients can connect rapidly (1000 is the maximum).
In a multi-homed system, specify which network interface the TCP connection should go through. An empty value means to use any interface. To be able to bind to IPv6 interfaces you may need to enable IPv6 in your instance. This is done in the System Management Portal under System Administration > Configuration > Additional Settings > Startup, by editing the IPv6 setting.
The name of an existing SSL/TLS configuration to use to authenticate this connection. Choose a client SSL/TLS configuration, because the adapter initiates the communication.
To create and manage SSL/TLS configurations, use the Management Portal. See Create or Edit a TLS Configuration. The first field on the Edit SSL/TLS Configuration form is Configuration Name. Use this string as the value for the SSLConfig setting.
The remaining settings are either common to all business hosts or are determined by the type of adapter. See
Setting the DICOM User ID Class and Version
The InterSystems DICOM implementation is identified by two items of information: the UIC and the VER. You can configure your own UIC or VER by setting the ^Ens.Config("DICOM","UIC") node and the ^Ens.Config("DICOM","VER") node respectively.
Configuring a DICOM Production to Control the Storage Location
Since the DICOM data is not stored in an InterSystems database, but is instead stored as an external file stream, you must configure DICOM productions to specify the location to use for these external files. You do this by defining a property named StorageLocation in your production. The DICOM business services, processes, and operations depend on the presence of this property˙. If the property specifies a directory, it is used as the storage location for the DICOM data. If the property has an empty string value, then the instance uses its default temporary directory to store the DICOM data.
If you add a DICOM component to a production, you must ensure that the StorageLocation property is defined in the production. If the StorageLocation property is not present, then the DICOM components can encounter an error when attempting to create DICOM data. We recommend that you specify a directory to use for DICOM data and not specify an empty string, which uses the default temporary directory. Restarting the InterSystems instance may delete data from the default temporary directory.
Also, by default, when a EnsLib.DICOM.Service.FileOpens in a new tab reads a file, it creates a stream that it stores in the stream directory for the namespace (for example mgr/name/stream). To instead store these streams in the StorageLocation, enable the UseStorageLocation setting of the EnsLib.DICOM.Service.FileOpens in a new tab.
The StorageLocation property is defined in the production definition. To add this property to a new production, follow this procedure:
-
Edit the production class in an IDE.
-
Insert the following lines in the production class definition after the XDATA that defines the production settings:
Parameter SETTINGS = "ShutdownTimeout,UpdateTimeout,StorageLocation"; /// This is the storage location for the DICOM streams to be stored Property StorageLocation As %String [ InitialExpression = "directory-location" ];
Replace directory-location with the directory where DICOM data is to be stored on the system, such as c:\InterSystems\DICOM.
-
Compile the production class.
-
Open the production in the Management Portal. The StorageLocation property appears in the Additional Settings section. Set the value of StorageLocation as needed (or keep the value specified by the InitialExpression as shown previously).
The EnsLib DICOM components check for the storage location with the following call:
Set tStorageLocation=..GetProductionSettingValue("StorageLocation",.tSC)