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.

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

To integrate with STOW RS Exporter of DCM4CHEE Archive 5.x, create an album and a token for it.
- Create an album
- Go to the album Settings and create a token for this album which shall be later used in STOW RS Exporter configuration.
  
  Note down the token secret as it is not available later

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.
View the exported study in KHEOPS album

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

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]