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.
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.
Important:
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 Studio.
-
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).
Note:
The EnsLib DICOM components check for the storage location with the following call:
Set tStorageLocation=..GetProductionSettingValue("StorageLocation",.tSC)