Ensemble DICOM Development Guide
Ensemble Tasks for DICOM Productions
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

The following sections describe how to perform typical Ensemble tasks specifically for a DICOM production:

Adding a DICOM Duplex Business Service
Ensemble provides a built-in duplex business host that accepts DICOM documents from external sources over TCP connections.
To add an DICOM duplex business service to a production:
  1. Display the production in the [Ensemble] > [Production Configuration] page of the Management Portal. To access this page, click Ensemble, click Configure, click Production, and then click Go.
  2. In the Services column, click the Add button (a plus sign).
    Ensemble displays a dialog box.
  3. Select the EnsLib.DICOM.Service.TCP class from the Service Class list.
  4. 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.
  5. Click OK.
Adding a DICOM File Business Service
Ensemble provides a built-in file business service that accepts DICOM documents from external files.
To add a DICOM file business service to a production:
  1. Display the production in the [Ensemble] > [Production Configuration] page of the Management Portal. To access this page, click Ensemble, click Configure, click Production, and then click Go.
  2. In the Services column, click the Add button (a plus sign).
    Ensemble displays a dialog box.
  3. Select the EnsLib.DICOM.Service.File class from the Service Class list.
  4. 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.
  5. Click OK.
Creating a DICOM Business Process
To build an 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 Caché ObjectScript.
When you create your custom class, extend EnsLib.DICOM.Process 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 in Developing Ensemble Productions.
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.
Adding a DICOM Business Process
To add a DICOM business process to a production:
  1. Display the production in the [Ensemble] > [Production Configuration] page of the Management Portal. To access this page, click Ensemble, click Configure, click Production, and then click Go.
  2. In the Processes column, click the Add button (a plus sign).
    Ensemble displays a dialog box.
  3. Select your custom class from the Process Class list.
  4. 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.
  5. Click OK.
Integrating a DICOM Business Process
To integrate a new DICOM business process into an Ensemble 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
Ensemble 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:
  1. Display the production in the [Ensemble] > [Production Configuration] page of the Management Portal. To access this page, click Ensemble, click Configure, click Production, and then click Go.
  2. In the Operations column, click the Add button (a plus sign).
    Ensemble displays a dialog box.
  3. Select the EnsLib.DICOM.Operation.TCP class from the Operation Class list.
  4. 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.
  5. Click OK.
Configuring a DICOM Duplex Business Host
To configure a business host, click it in the diagram on the [Ensemble] > [Production Configuration] page, edit details on the Settings tab, and click Apply.
For a DICOM business host, you can configure the following settings:
Duplex Target Config Names
Specify the configuration item within the production to which the business host sends any DICOM documents that it receives.
LocalAET
The called Application Entity Title (AET) that the remote DICOM peer uses to communicate with Ensemble. This corresponds to the Called AET you use when defining an association in an Ensemble 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.
RemoteAET
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, Ensemble 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 Ensemble is connecting or be set to the * wildcard (see description of LocalAET property).
TraceVerbosity
Flag value for how much debug information to provide:
0 - No information
1 - Terse debug information
2 - Verbose debug information
ARTIM
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.
TXTIM
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.
Job Per Connection
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
IP port of the DICOM peer.
IP Address
IP address to connect to the DICOM peer. This property is null if it is in listening mode.
OS Accept Connection Queue Size
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).
Local Interface
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 Ensemble instance. This is done in the System Management Portal under System Administration > Configuration > Additional Settings > Startup, by editing the IPv6 setting.
SSL Configuration
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 the chapter Using SSL/TLS with Caché in the Caché Security Administration Guide. The first field on the Edit SSL/TLS Configuration form is Configuration Name. Use this string as the value for the SSLConfig setting.
If your SSL configuration requires a private key password, include that in the SSL Config setting. To do so, add a vertical bar character | after the configuration name, followed by the password. For example: MySSLItem|mypassword.
The remaining settings are either common to all business hosts or are determined by the type of adapter. For information, see the section “Reference for Settings” in each of the following books:
Also see Settings in All Productions in Configuring Ensemble Productions.
Setting the DICOM User ID Class and Version
The Ensemble 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 a Caché 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 Ensemble 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. Ensemble may delete data from the default temporary directory when it is restarted.
The StorageLocation property is defined in the ENSDEMO DICOM samples. To add this property to a new production, follow this procedure:
  1. Edit the production class in Studio.
  2. 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.
  3. Compile the production class.
  4. Open the production in the Ensemble Portal, the StorageLocation property appears in the Additonal Settings section.
Note:
The EnsLib DICOM components check for the storage location with the following call:
  Set tStorageLocation=..GetProductionSettingValue("StorageLocation",.tSC)