KHEOPS Data Sharing Platform Integration - dcm4che/dcm4chee-arc-light GitHub Wiki

Overview

KHEOPS is a data sharing platform which internally uses DCM4CHEE Archive 5.x as its DICOMweb capable PACS. To send data / studies to KHEOPS, one may make use of STOW RS Exporter which requires DCM4CHEE Archive 5.x to be started separately and which is independent of the archive/PACS internally used by KHEOPS.

Configuration

KHEOPS Configuration / Basic Tests

  • Install KHEOPS
  • By default, KHEOPS uses following versions of containers used by DCM4CHEE archive 5.x internally :
  • Updating to newer versions (than the ones specified above) or to the latest version of archive / Keycloak containers does not work as expected i.e. for eg.
    • Importing of files is successful but Inbox doesn't show any studies
      • jboss/keycloak:11.0.3
      • dcm4che/slapd-dcm4chee:2.4.57-23.2
      • dcm4che/postgres-dcm4chee:13.1-23
      • dcm4che/dcm4chee-arc-psql:5.23.2
    • Importing files fails with 502 Bad Gateway
      • jboss/keycloak:11.0.2
      • dcm4che/slapd-dcm4chee:2.4.50-22.6
      • dcm4che/postgres-dcm4chee:12.2-22
      • dcm4che/dcm4chee-arc-psql:5.22.6 Hence we leave the default versions of Keycloak / Archive related containers used by KHEOPS as it is.
  • In $KHEOPS_HOME/kheops/docker-compose.env and $KHEOPS_HOME/kheops/docker-compose.yml files, replace 127.0.0.1 by the docker host where KHEOPS containers shall be started and running.
  • Additionally, in the $KHEOPS_HOME/kheops/docker-compose.yml file,
    • Add following extra_hosts to keycloak and kheops-reverse-proxy containers
      extra_hosts:
        - "your.domain.here:127.0.0.1"
      
    • Optionally, choose to map out the volumes to your host for each of the specified volumes.
    • Optionally, choose to map out keycloak container's standalaone/log for debugging purposes, which then requires the same to be added in volumes section.
  • To understand the differences, compare the KHEOPS docker-compose files : original downloaded and post changes mentioned above.
  • Access KHEOPS which is secured by Keycloak at http://<docker-host>. Replace <docker-host> with the host name or IP address where the KHEOPS containers are started and are running.
  • First time users need Register with an email ID / password and other details. For returning / existing users, login to KHEOPS console.

login_screen.png

  • Once logged in, for testing purpose or otherwise choose to Import Files (i.e. studies) into your Inbox.

import_files.png

view_study_inbox.png

  • To integrate with STOW RS Exporter of DCM4CHEE Archive 5.x, create an album and a token for it.
    • Create an album

      create_album.png

      view_created_album.png

    • Go to the album Settings and create a token for this album which shall be later used in STOW RS Exporter configuration.

      create_token.png

      Note down the token secret as it is not available later

      created_token.png

      view_created_token.png

Archive Configuration

  • Additionally, start DCM4CHEE Archive 5.x using Run minimum set of archive services on a single host. Ensure to change "8080:8080" in arc container (for eg. to "8880:8080") as Keycloak container in KHEOPS makes use of the same port mapping.
  • Access DCM4CHEE Archive 5.x at http[s]://<docker-host>:<port>/dcm4chee-arc/ui2. Replace <docker-host> with the host name or IP address where the archive containers are started and are running. Replace <port> with the changed port mapping value as done in the above point.
  • By default, archive is pre-configured with a stowrsd device which acts as a STOW-RS server. As KHEOPS shall be acting as a STOW-RS server, either
    • Clone the stowrsd device and rename it to kheops by going to Menu -> Configuration page -> Devices tab -> stowrsd -> Clone device or
    • Create a new device for kheops by going to Menu -> Configuration page -> Devices tab -> More functions -> Create device
  • Once kheops device is
    • Created : Edit device and go to its
      • Child Objects -> Network Connections -> Add new Network Connections : Specify appropriate Name. Values for Hostname and Port shall match with docker host where KHEOPS containers are running and 80 respectively. Next go to its Extensions -> Network Connection Extension -> (Add +) dcm4che proprietary network connection attributes; select Protocol as HTTP and Save. or
    • Cloned : Edit device and go to its
      • Child Objects -> Network Connections : Select the network connection and specify change values for Hostname and Port. These shall match with docker host where KHEOPS containers are running and 80 respectively.
    • Next go to its Extensions -> Device extension (Edit) -> Child Objects -> Web Applications and select stowrsd_CLONE from the list.
      • Rename the Web Application name for eg. to KHEOPS. Note : Ensure no spaces are used in the Web Application name as this is later used when configuring the URI in STOW RS Exporter.
      • Select the network connection created / updated in above step for Web Application Network Connection(s).
      • Specify an appropriate Web Application Description for eg. KHEOPS STOW-RS server
      • Specify Web Service Path as /api.
      • Select STOW_RS as Web Service Class.
      • Add following Property
        • allow-any-hostname=true
        • bearer-token=<album-token>. Replace <album-token> with the value of created token of the created KHEOPS album. and Save.
  • Create a STOW RS Exporter by going to Menu -> Configuration page -> Devices tab -> dcm4chee-arc -> Extensions -> Device extension (Edit) -> Extensions -> Archive Device (Edit) -> Child Objects -> Exporter descriptor -> Add new Exporter Descriptor (+).
    • Specify URI as stow:KHEOPS
    • Set Exporter ID and Exporter Description eg. STOW-RS Export to KHEOPS
    • Select appropriate Export Queue in Queue Name.
    • Select Archive Application Entity (AE) title as DCM4CHEE and Save.

Tests & Verification

  • Export studies to KHEOPS using archive UI by going to Menu -> Navigation page -> Studies tab. Select a Web App Service eg. DCM4CHEE and query for studies in archive.

  • Export Study using Synchronised DICOM STOW-RS exporter to KHEOPS web application configured in above steps acting as a STOW-RS server.

    export_study_kheops.png

  • View the exported study in KHEOPS album

    view_exported_study_kheops.png

Anonymize exported studies

  • Optionally, choose to anonymize studies when they are stored to KHEOPS. This requires an attribute coercion configuration in the archive (Navigation -> Devices -> dcm4chee-arc -> Device extension -> Archive Device extension -> Child Objects -> Attribute Coercion). Note : Replace <your.domain.here> with the host name or IP address where KHEOPS containers are running.

    version: 1
    
    dn: cn=De-identify objects on outgoing STOW,dicomDeviceName=dcm4chee-arc,cn=Devices,cn=DICOM Configuration,dc=dcm4che,dc=org
    objectClass: dcmArchiveAttributeCoercion
    cn: De-identify objects on outgoing STOW
    dcmDIMSE: C_STORE_RQ
    dicomTransferRole: SCP
    dcmDeIdentification: BasicApplicationConfidentialityProfile
    dcmProperty: ReceivingHostname=<your.domain.here>
    
  • Export a study from archive and view it in KHEOPS album

    deidentify_attribute_coercion.png

    export_study_anonymize_kheops.png

    export_study_anonymize_kheops_1.png

    Verify in archive server.log that configured attribute coercion is applied

    2021-03-31 12:16:56,801 INFO  [org.dcm4chee.arc.export.rs.ExporterRS] (default task-17) Process POST 
    /dcm4chee-arc/aets/DCM4CHEE/rs/studies/1.2.392.200036.9125.0.199302241758.16/export/stowrs:KHEOPS from [email protected]
    2021-03-31 12:16:57,233 INFO  [org.dcm4chee.arc.retrieve.impl.RetrieveServiceImpl] (default task-17) Coerce Attributes 
    from rule: ArchiveAttributeCoercion[cn=De-identify objects on outgoing STOW, priority=0, DIMSE=C_STORE_RQ, role=SCP, 
    cuids=[], conditions={ReceivingHostname=vrinda-pc}, retrieveAsReceived=false, deIdentification=[BasicApplicationConfidentialityProfile], 
    xslturi=null, noKeywords=false, leadingCFindSCP=null, mergeMWLMatchingKey=null, mergeMWLTemplateURI=null, attributeUpdatePolicy=MERGE, 
    trimISO2022CharacterSet=false, useCallingAETitleAs=null, nullifyTags=[], nullifyTags=[], nullifyIssuerOfPatientID=null, 
    issuerOfPatientIDs=[], issuerOfPatientIDFormat=null, supplementFromDeviceName=null]
    

    anonymized_study.png

⚠️ **GitHub.com Fallback** ⚠️