Housekeeper plugin

This page describes the official sample plugin that performs housekeeping in the Database and Storage.

When changing some configuration or when upgrading Orthanc, it might be usefull to perform housekeeping operations to optmize the DB or clean/compress/uncompress the storage. This can happen e.g:

• when changing the list of indexed MainDicomTags

• when changing the StorageCompression configuration

• when changing the IngestTranscoding configuration

• to remove unnecessary attachments like the dicom-as-json that were used in Orthanc prior to 1.9.1.

• when upgrading the DICOMweb plugin from 1.14 to a later version.

Note that these housekeeping operations are not mandatory. Orthanc will continue to work without these cleanups. However, running the plugin might improve performances and storage usage.

The plugin detects any configuration changes that can trigger a cleanup and will start process the studies one by one (in the order they have been ingested in Orthanc). If Orthanc is stopped and restarted, the plugin will resume where it stopped.

Configuration

Here’s a sample configuration section for this plugin with its default values:

{
  "Housekeeper": {

    // Enables/disables the plugin
    "Enable": false,

    // the Global Prooperty ID in which the plugin progress
    // is stored.  Must be > 1024 and must not be used by
    // another plugin
    "GlobalPropertyId": 1025,

    // Forces execution even if the plugin did not detect
    // any changes in configuration
    "Force": false,

    // Delay (in seconds) between reconstruction of 2 studies
    // This avoids overloading Orthanc with the housekeeping
    // process and leaves room for other operations.
    "ThrottleDelay": 5,

    // Runs the plugin only at certain period of time.
    // If not specified, the plugin runs all the time
    // Examples:
    // to run between 0AM and 6AM everyday + every night
    // from 8PM to 12PM and 24h a day on the weekend:
    // "Schedule": {
    //   "Monday": ["0-6", "20-24"],
    //   "Tuesday": ["0-6", "20-24"],
    //   "Wednesday": ["0-6", "20-24"],
    //   "Thursday": ["0-6", "20-24"],
    //   "Friday": ["0-6", "20-24"],
    //   "Saturday": ["0-24"],
    //   "Sunday": ["0-24"]
    // },

    // configure events that can trigger a housekeeping processing
    "Triggers" : {
      "StorageCompressionChange": true,
      "MainDicomTagsChange": true,
      "UnnecessaryDicomAsJsonFiles": true,
      "IngestTranscodingChange": true,
      "DicomWebCacheChange": true   // new in 1.12.2
    },

    // When rebuilding MainDicomTags, limit to a single level of resource
    // which can greatly improve performances e.g. if you have only updated
    // the Study level ExtraMainDicomTags.
    // Allowed values: "Patient", "Study", "Series", "Instance", "All"
    "LimitMainDicomTagsReconstructLevel": "All"

  }
}

Scheduling/throttling

Processing a whole database/storage might take a very long time (days, weeks or even months) and can be I/O & CPU intensive. Therefore, the configuration offers options to schedule and/or throttle the housekeeping operations. E.g, you can run only the plugin during the night and week-end and, you can introduce a delay between each processed study.

Triggers & internals

By default, all triggers are enabled. Depending on the detected change, various operations will happen:

• if MainDicomTagsChange or UnnecessaryDicomAsJsonFiles is triggered, the plugin will call the /studies/.../reconstruct route on every study one by one. Orthanc will read the DICOM tags from the DICOM files again and update their value in the DB.

• if DicomWebCacheChange is triggered (this happens when upgrading from the DICOMweb plugin from 1.14 to a later version), the plugin will call the /studies/../update-dicomweb-cache route on every study one by one.

• if any other change is detected, the plugin will again call the reconstruct route but, this time, with the ReconstructFiles option enabled. Orthanc will then, read the DICOM file from the storage, compress/uncompress/transcode it and it will save it again to disk. The new file will be stored using the new Storage settings (StorageCompression and IngestTranscoding). Note that, Orthanc will create a new Attachment that will be saved at a different place as the previous one.

Status

You can get a progress status of the plugin by calling the /housekeeper/status API route.

Tips

• The housekeeper plugin saves its state in the Orthanc SQL database in the ServerProperties table. When running the Housekeeper plugin in a Docker environment, it is mandatory to set the DatabaseServerIdentifier configuration to make sure that an Orthanc container keeps the same identifier over multiple runs which should prevent the Housekeeper plugin to start again from scratch when Orthanc is restarted. If not set explicitly in the configuration, the DatabaseServerIdentifier might change from one run to the other.

Compilation

This plugin is part of the Orthanc core repository and is included in the Orthanc makefile. It is compiled with Orthanc itself and is distributed together with Orthanc binaries.