Worklists plugin

Warning

This page documents the new Worklists plugin that supersedes the legacy Sample Modality Worklists plugin that is provided as a sample project with the Orthanc source code since 1.0.0.

The worklists plugin turns Orthanc into a server of DICOM worklists. General information about how Orthanc supports DICOM worklists through plugins is explained in the FAQ.

The plugin serves the worklists stored in some folder on the filesystem or directly in the Orthanc database. It also provides a REST API to create and manage worklists.

The source code of this plugin is available on GitHub (AGPLv3+ license).

Basic configuration

  1. First, generate the default configuration of Orthanc.

  2. Then, modify the Plugins option to point to the folder containing the shared library of the plugin.

  3. Finally, create a section “Worklists” in the configuration file to configure the worklist server.

A basic configuration would read as follows:

{
  [...]
  "Plugins" : [
    "."
  ],
  "Worklists" : {
    "Enable": true,

    "FilterIssuerAet": false, // Some modalities do not specify 'ScheduledStationAETitle (0040,0001)'
                              // in the C-Find and may receive worklists not related to them.  This option
                              // adds an extra filtering based on the AET of the modality issuing the C-Find.
    "LimitAnswers": 0,        // Maximum number of answers to be returned (new in release 1.7.3)

    "Directory": "./WorklistsDatabase",  // The folder from which worklists are read or in which they are created.


    "SaveInOrthancDatabase": false,      // If set to true and if the Orthanc Database supports Key-Value stores
                                         // (PostgreSQL or SQLite), the worklists must be created through the REST API
                                         // and are stored in the Orthanc DB.
    "SetStudyInstanceUidIfMissing": true,  // Add a StudyInstanceUID to the worklist if none is provided in the REST API call to create it
    "DeleteWorklistsOnStableStudy": true,   // Delete the worklist as soon as a a stable study is found with the StudyInstanceUID
                                            // provided in the worklist.
                                            // Note that this check is performed in the Worklist Housekeeper thread.  The plugin
                                            // does not react synchronously on the Stable Study event.
                                            // This process is only available if you are providing a StudyInstanceUID
                                            // or if you have set the 'SetStudyInstanceUIDIfMissing' configuration to true
    "HousekeepingInterval": 60,             // Interval [in seconds] between 2 execution of the Worklist Housekeeper thread.

    // New options only if SaveInOrthancDatabase is set to true.

    "DeleteWorklistsDelay": 24          // Delay [in hours] after which the worklist is deleted.
                                        // Note that this check is performed in the Worklist Housekeeper thread.
                                        // The plugin only deletes worklists that have been created through the REST API.
                                        // Set it to 0 if you don't want the plugin to delete worklists after a delay.
  }
}

Tutorial

  • Download DCMTK utilities.

  • Enable the Worklists plugin in your configuration file by adding this section:

    "Worklists" : {
  "Enable": true,
  "SaveInOrthancDatabase": true
},

  • Add the plugin to the list of plugins to load (this is an example for Microsoft Windows):

    "Plugins" : [
  "StoneWebViewer.dll",
  "OrthancExplorer2.dll",
  "OrthancWorklists.dll"   // On GNU/Linux, use libOrthancWorklists.so
],

  • The tests below will be done using the findscu command-line tool from the DCMTK utilities. Assuming findscu and Orthanc runs on the same computer (i.e. on the 127.0.0.1 localhost), declare the FINDSCU AET to the list of know modalities:

    "DicomModalities" : {
  "horos" : [ "HOROS", "192.168.0.8", 11112 ],
  "findscu" : [ "FINDSCU", "127.0.0.1", 1234 ]
},

  • Launch Orthanc as usual, making sure to give the proper configuration file (e.g. for Microsoft Windows):

    Orthanc.exe config.json

  • Open the Orthanc Explorer 2 User interface and create a worklist for a CT.

  • In another command-line prompt, launch a findscu request to ask Orthanc to return all worklists for CT modalities:

    findscu -W -k "ScheduledProcedureStepSequence[0].Modality=CT" 127.0.0.1 4242

    The -W option makes findscu issue a DICOM worklist query, the -k option specifies the query of interest, 127.0.0.1 corresponds to the localhost, and 4242 corresponds to the default DICOM TCP port of Orthanc.

  • findscu will display the matching worklists.

How to create a worklist using the REST API

The new worklsits plugin provides a REST API that can be used to create worklists. For example:

$ curl --request POST http://localhost:8042/worklists/create \
    --data '{
              "Tags" : {
                "PatientID": "PID-45",
                "PatientName": "Toto",
                "ScheduledProcedureStepSequence" : [
                  {
                    "Modality": "US",
                    "ScheduledProcedureStepStartDate": "20251014",
                    "ScheduledProcedureStepDescription": "Description"
                  }
                ]
              }
            }'

In response, you’ll get something like:

{
  "ID" : "5fdc7404-f9dc-4798-b6e1-8f715e2f9e71",
  "Path" : "/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71"
}

You can then check the content of the worklist by calling:

$ curl --request GET http://localhost:8042/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71

To delete it, call:

$ curl --request DELETE http://localhost:8042/worklists/5fdc7404-f9dc-4798-b6e1-8f715e2f9e71

To browse all worklists, call:

$ curl --request GET http://localhost:8042/worklists/?format=Simplify
$ curl --request GET http://localhost:8042/worklists/?format=Short
$ curl --request GET http://localhost:8042/worklists/?format=Full

Troubleshooting C-Find queries

When trying to retrieve worklists from a modality, one usually don’t get debugging capabilities from the modality itself. Therefore, it is usually convenient to mimic the modality with findscu (provided by DCMTK software).

  • First, you should make sure that you have configured the Worklist plugin correctly and that you have pushed at least a .wl file in the worklist database. For this, you should issue this kind of command:

    findscu -W 127.0.0.1 4242 -k 0008,0050="*"

    This is the most generic C-Find request and should return all AccessionNumber of all the worklists in your database.

    Note: you should make sure you have added a findscu DICOM modality in your configuration file.

    findscu should output something like this:

    W: ---------------------------
W: Find Response: 1 (Pending)
W:
W: # Dicom-Data-Set
W: # Used TransferSyntax: Little Endian Explicit
W: (0008,0005) CS [ISO_IR 100]                             #  10, 1 SpecificCharacterSet
W: (0008,0050) SH [**********]                             #  10, 1 AccessionNumber
W:

    If you don’t get any output, you may add -v -d options to the findscu command line to get additional details.

  • Everytime it receives a C-Find request, Orthanc displays the query parameters in its logs. With the previous C-Find command, you should expect this kind of output:

    I0422 17:16:03.512449 CommandDispatcher.cpp:490] Association Received from AET FINDSCU on IP 127.0.0.1
I0422 17:16:03.514433 CommandDispatcher.cpp:688] Association Acknowledged (Max Send PDV: 16372)
I0422 17:16:03.532062 main.cpp:118] No limit on the number of C-FIND results at the Patient, Study and Series levels
I0422 17:16:03.535986 main.cpp:128] No limit on the number of C-FIND results at the Instance level
I0422 17:16:03.536968 PluginsManager.cpp:171] Received worklist query from remote modality FINDSCU:
{
   "0008,0050" : "*"
}
I0422 17:16:03.559539 CommandDispatcher.cpp:891] DUL Peer Requested Release
I0422 17:16:03.560520 CommandDispatcher.cpp:898] Association Release

  • Now you may try to issue a C-Find request from your modality and check Orthanc logs. You should then have a better understanding of the query content and eventually understand why it does not match your worklists. You should also be able re-issue findscu requests with additional arguments to mimic the requests issued by your modality.

Common problems

  • C-FIND requests can be modified by implementing the IncomingWorklistRequestFilter Lua callback since Orthanc 1.4.2. This can be useful to fix/sanitize worklist queries.

  • According to the specification, modalities should not include their AET name in ScheduledStationAETitle on user initiated queries. Therefore, they do receive worklists that do not concern them. This may be handled by the FilterIssuerAet configuration option. Note that the default behavior might in some cases be intended.