Skip to main content

Sample DICOM Modality Worklist Production

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 sample production named Demo.DICOM.Production.WorkList demonstrates how to use a production to process DICOM worklists for modalities that support them. This production contains the business service EnsLib.DICOM.Service.TCPOpens in a new tab, the business process Demo.DICOM.Process.Storage, and the business operation EnsLib.DICOM.Operation.TCPOpens in a new tab.

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 the production.

  2. The C-FIND request specifies the need for a worklist.

  3. The production finds the information.

  4. The production creates a C-FIND response message for each patient in the list.

  5. The production sends the response message back to the modality.

This production includes business service EnsLib.DICOM.Service.TCPOpens in a new tab and the business process Demo.DICOM.Process.WorkList.

The business service, EnsLib.DICOM.Service.TCPOpens in a new tab, 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 Production Configuration page. See “Creating and Configuring a Production”.

  2. In Studio, modify the production definition to add both the StorageLocation property and the SETTINGS parameter. See Configuring a DICOM Production to Control the Storage Location for details on defining StorageLocation and SETTINGS. The SETTINGS parameter is required for the StorageLocation to work correctly. After defining StorageLocation and SETTINGS, compile the production.

  3. Add a DICOM duplex business service to the production using the EnsLib.DICOM.Service.TCPOpens in a new tab class.

  4. Configure the DICOM business service settings specifically for a modality worklist.

  5. Create a business process class that creates worklist entries from incoming DICOM C-FIND-RQ message documents.

  6. Add a DICOM business process using the custom class from the previous step.

  7. 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 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 the production. This corresponds to the Called AET you use when defining an association in an interoperability-enabled namespace.

When you run the Demo.DICOM.Production.WorkList production for the first time, it creates the DICOM association necessary for the production to connect to a test DICOM application for this demonstration production. You can view this association in the production’s namespace from the Interoperability > Interoperate > DICOM > 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.TCPOpens in a new tab service of the demo production uses JD-SCU for the value of RemoteAET.

Creating a Business Process Class for a DICOM Worklist Production

The 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 from a RIS system.

This custom class extends 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 instructions, see Developing Custom Business Processes in Developing 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.DocumentOpens in a new tab 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 DICOM production 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 displays a DICOM message document within the Message Browser:

Displayed are two tables, Command Set, and Data Set, each with columns for Tag, Name, and Contents.

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:

This excerpt of the Event Log shows the Method and Text columns for each event.

The following log from third-party DICOM testing software shows its communication with the 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
FeedbackOpens in a new tab