Ensemble DICOM Development Guide
Sample DICOM Modality Worklist Production
[Back] [Next]
Go to:

A common DICOM SOP class is the Modality Worklist (MWL), which enables primary imaging equipment (modalities) to query for patient demographics and study details from the MWL Service Class Provider (SCP), normally part of a radiology information system (RIS). The modality asks for a list of patients with chosen criteria via a standard C-FIND operation and the Modality Worklist service responds accordingly.

The ENSDEMO namespace contains a production named Demo.DICOM.Production.WorkList. This production demonstrates how to use Ensemble to process DICOM worklists for modalities that support them.
The scenario for this production is such that at the beginning of the day a modality needs a list of work to process. The production does the following:
  1. The modality sends a C-FIND request message to Ensemble.
  2. The C-FIND request specifies the need for a worklist.
  3. Ensemble finds the information.
  4. Ensemble creates a C-FIND response message for each patient in the list.
  5. Ensemble sends the response message back to the modality.
The business service, EnsLib.DICOM.Service.TCP, connects to a DICOM imaging device. The Demo.DICOM.Process.WorkList business process class demonstrates how to handle DICOM C-FIND-RQ messages and respond with worklist entries.
This is the only way that the modality worklist SOP class (MWL) works, namely the modality querying data from the service provider (SCP); there is no means for the SCP to broadcast the data out to modality equipment. Likewise, the MWL protocol itself provides no means for the modality to inform the RIS of which patient has been chosen from the list of matches returned, though this can be communicated using the Modality Performed Procedure Step (MPPS) service when it is supported by both pieces of equipment.
The following steps outline the procedure to add this type of interface to a production:
  1. Create a generic production by clicking Create New Production on the [Ensemble] > [Production Configuration] page. See Creating and Configuring a Production in Configuring Ensemble.
  2. In Studio, modify the production definition to add the StorageLocation property and compile the production. See Configuring a DICOM Production to Control the Storage Location for details.
  3. Configure the DICOM business service settings specifically for a modality worklist.
  4. Create a business process class that creates worklist entries from incoming DICOM C-FIND-RQ message documents.
  5. Add a DICOM business process using the custom class from the previous step.
  6. Test the production to verify that it receives a request message for a worklist and sends the appropriate response message documents back.
You can view the class code of Demo.DICOM.Production.WorkList.cls using Studio to see the production details.
Configuring the DICOM Worklist Business Service
You can configure a DICOM business service by clicking it in the diagram on the [Ensemble] > [Production Configuration] page. Configuring a DICOM Duplex Business Host describes the details. This section describes the settings specific to the business service in the demonstration worklist production.
Duplex Target Config Names
Specify the configuration item within the production to which the business service should send any DICOM documents that it receives.
The Demo.DICOM.ProductionStorage production uses the business process based on the class, Demo.DICOM.Process.WorkList, which is described in Creating a Business Process for a DICOM Worklist Production.” This is a custom process that contains the logic for processing DICOM messages from the modality.
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.
When you run the Demo.DICOM.Production.WorkList production for the first time, it creates the DICOM association necessary for Ensemble to connect to a test DICOM application for this demonstration production. You can view this association in the ENSDEMO namespace from the [Ensemble] > [DICOM Settings] page.
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.
The EnsLib.DICOM.Service.TCP service of the demo production uses JD-SCU for the value of RemoteAET.
Creating a Business Process Class for a DICOM Worklist Production
The ENSDEMO Demo.DICOM.Production.WorkList production uses a sample custom business process class, Demo.DICOM.Process.WorkList, which demonstrates how to handle DICOM C-FIND request messages and respond with worklist entries. This demonstration class mimics retrieving patient information form a RIS system.
This custom class extends 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 instructions, see Developing Custom Business Processes in Developing Ensemble Productions.
The Demo.DICOM.Process.WorkList class uses the parameter SETTINGS to expose a new property, NumberOfWorkListEntries, for configuration. This setting influences the number of worklist entries returned as a result of a C-FIND request.
See the following sections for an overview of the contents of the custom class:
You can view the class code for Demo.DICOM.Process.WorkList.cls using Studio to see the processing details.
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.
DICOM Worklist Process Properties
The custom class adds the following properties it needs to read in the requests and format responses:
The incoming message from the business service (a EnsLib.DICOM.Document object).
Configurable number of worklist entries; defaults to 1.
Keeps track of the ID of the originating message.
Keeps track of the number of replies sent to the worklist request.
DICOM Worklist Process Methods
The custom class adds the following methods it needs to process the requests and create responses:
This method handles the C-FIND request and C-CANCEL request messages. The find request asks for a query to be performed using the criteria specified in the dataset of the request. The query may take significant time and produce many results so individual matches are reported in one or more messages. This demonstration method does not expect any other types of DICOM messages.
The OnMessage() method has the following signature:
Method OnMessage(pSourceConfigName As %String,
                 pInput As %Library.Persistent)
                 As %Status
This method is called when any error occurs. Returning the same error causes the business process to set its status to error and close down.
The OnError() method has the following signature:
Method OnError(request As %Library.Persistent, ByRef response As %Library.Persistent,
               callrequest As %Library.Persistent,
               pErrorStatus As %Status,
               pCompletionKey As %String)
               As %Status
This method creates an intermediate instance of a message for the C-FIND response, filling in the mandatory DICOM fields. The protocol requires that all messages but the last one have their status set to Pending. This indicates to the client that there is more data coming. The last message has a status of Success, which means that the query has finished. This example ignores the selection criteria and returns dummy patient records. Your production implementation will be necessarily more complex.
The CreateIntermediateFindResponse() method has the following signature:
Method CreateIntermediateFindResponse(pDocIn As EnsLib.DICOM.Document,
                                      Output pDocOut As EnsLib.DICOM.Document)
                                      As %Status
This method creates an instance of a message to indicate that the final process is complete, setting the command field to C-FIND-RSP to indicate that this is a find response message.
The CreateFinalFindResponse() method has the following signature:
Method CreateFinalFindResponse(pDocIn As EnsLib.DICOM.Document,
                               Output pDocOut As EnsLib.DICOM.Document)
                               As %Status
Testing the DICOM Worklist Production
Once you have working associations and created a production, you can attempt to process valid DICOM message documents through the worklist production. The demonstration production included with Ensemble was developed using third-party software specifically developed for testing DICOM processing. You can use any of the many available software products, or test with your actual DICOM modality data.
This section shows portions of the Event Log, Message Browser, Message Details, and Message Contents pages in the Management Portal of the Demo.DICOM.Production.WorkList production running and accepting DICOM messages from a modality that supports worklists.
The following display the contents of a DICOM message document in Ensemble using the Message Browser:
You can see the structure of a DICOM message that contains metadata in the command set and the physical data in the data set.
The following portion of the Event Log page shows (from the bottom up) the events of running the production communicating with a modality and processing three worklist items as configured in the business process:
The following log from third-party DICOM testing software shows its communication with the Ensemble production:
test: #3:ENS-SCP << C-FIND-RQ Modality Worklist Information Model - FIND SOP Class
test: #3:ENS-SCP << Dataset
test: #3:ENS-SCP >> C-FIND-RSP Modality Worklist Information Model-FIND SOP Class, status #ff01H[StatusEntry.PENDING]
test: #3:ENS-SCP >> Dataset
test: #3:ENS-SCP >> C-FIND-RSP Modality Worklist Information Model-FIND SOP Class, status #ff01H[StatusEntry.PENDING]
test: #3:ENS-SCP >> Dataset
test: #3:ENS-SCP >> C-FIND-RSP Modality Worklist Information Model-FIND SOP Class, status #ff01H[StatusEntry.PENDING]
test: #3:ENS-SCP >> Dataset
test: #3:ENS-SCP >> C-FIND-RSP Modality Worklist Information Model-FIND SOP Class, status #0000H[Success]
test: #3:ENS-SCP closing socket