DICOM Integration with InterSystems IRIS for Health

dcm4che simulator · DICOM interoperability workshop

This repository provides hands-on examples of DICOM integration using InterSystems IRIS for Health and the dcm4che DICOM simulator.

You’ll find:

• A working IRIS production for handling DICOM messages
• Tools to simulate common DICOM workflows (store, query, retrieve)
• A sample WorkList scenario integrated with a MySQL database

Perfect for testing, learning, or building healthcare imaging integrations.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# What you’ll learn

DICOM vocabulary: An AE Title is a DICOM application’s name. An SCU sends a request and an SCP receives it. C-FIND searches for matching records, C-MOVE requests a transfer, Modality Worklist supplies scheduled imaging work, and STOW-RS stores DICOM objects over HTTP.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 🧰 Requirements

To run this project, you’ll need:

• Git
• Docker Desktop, including Docker Compose
  ⚠️ On Windows, make sure Docker is using Linux containers

Optional, for browsing and editing the ObjectScript source:

• Visual Studio Code with InterSystems ObjectScript Extension Pack

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 🚀 Getting Started

Once you’ve got Docker installed, build and start the lab with:

docker compose up -d --build

Confirm that the three services are running before starting a use case:

docker compose ps

You should see iris, tools, and mysql running. That’s it — you’re ready.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Explore the IRIS Production

Open the DICOM production interface in your browser:

DICOM.Production
Credentials: superuser / SYS

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 📥 Use Case 1: Receiving DICOM with Embedded PDF

A DICOM file containing a PDF report is received by IRIS. The system extracts metadata from the DICOM header (e.g. patient name, study ID) and stores both the PDF and metadata in another system (like an EHR or document store).

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# How to run it:

1. Open a shell in the tools container:

   docker exec -it tools bash
   

2. Generate a DICOM file with embedded PDF:

   ./pdf2dcm -f /shared/pdf/metadata.xml -- /shared/pdf/sample.pdf /shared/pdf/embeddedpdf.dcm
   

3. Send it to IRIS:

   ./storescu -b DCM_PDF_SCP -c IRIS_PDF_SCU@iris:2010 /shared/pdf/embeddedpdf.dcm
   

4. Check the messages in IRIS:
   Message Viewer

Expected outcome: A new inbound DICOM message appears in the IRIS Message Viewer.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 🔍 Use Case 2: Query / Retrieve (C-FIND / C-MOVE)

IRIS queries a PACS using a DICOM C-FIND to locate imaging studies, then uses C-MOVE to retrieve one of the matching documents.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Querying with C-FIND

1. Open the tools container:

   docker exec -it tools bash
   

2. Inspect a DICOM file:

   ./dcmdump /shared/dicom/d1I00001.dcm
   

3. Create the DICOMDIR database:

   ./dcmdir -c /shared/DICOMDIR --fs-id SAMPLEDICOMS --fs-desc /shared/dicom/descriptor /shared/dicom
   

4. Start the simulated archive:

   ./dcmqrscp --ae-config /shared/ae.properties -b DCM_QRY_SCP:3010 --dicomdir /shared/DICOMDIR
   

   This command keeps the terminal busy. Leave it running, then open a second terminal for the next steps.

5. In a second terminal, connect to IRIS:

   docker exec -it iris bash
   iris session iris
   

6. Run the C-FIND:

   do https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#class(DICOM.BS.QueryService).TestFind()
   

   View results in QueryService Messages

   Expected outcome: IRIS sends a C-FIND request and records matching study information in the Message Viewer.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Retrieving with C-MOVE

7. Request a study using C-MOVE:

   do https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#class(DICOM.BS.MoveService).TestMove()
   

   Track the transfer:
   MoveService | DICOM Store In

   Expected outcome: The selected study is transferred from the simulated archive to IRIS as DICOM C-STORE messages.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 📋 Use Case 3: WorkList Management (C-FIND + SQL)

Description: An imaging device sends a C-FIND request to IRIS to retrieve scheduled studies. IRIS queries an external MySQL database, builds the WorkList response, and sends it back.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Check the external MySQL WorkList DB

1. Enter the MySQL container:

   docker exec -it mysql bash
   mysql --host=localhost --user=testuser testdb -p  https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Password: testpassword
   

2. View WorkList data:

   SELECT * FROM WorkList;
   

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Request the WorkList using C-FIND

1. Open the tools container:

   docker exec -it tools bash
   

2. Send a WorkList query:

   ./findscu -b DCM_WL -c IRIS_WL@iris:1112 -M MWL -m ScheduledProcedureStepSequence.ScheduledProcedureStepStartDate=20250404
   

   This sends a real Modality Worklist C-FIND request using SOP class 1.2.840.10008.5.1.4.31.

   Expected outcome: The fixed demo date returns three scheduled entries: DEMO001, DEMO002, and DEMO003.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# See how IRIS handled it

Check DICOM WL Find In Messages

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# 🌐 Use Case 4: Store Document over the Web

An imaging device sends an image over HTTP using a STOW-RS (HTTP POST) request to IRIS, which receives, extracts, and processes the DICOM image.

1. Open the tools container:

   docker exec -it tools bash
   

2. Run a simulated listener for incoming C-STORE:

   ./storescp -b DCM_STORE_SCP:4010 --response-delay 5000
   

   This command keeps the terminal busy. Leave it running, then open a second terminal for the STOW-RS request.

3. In a second terminal, send DICOM images using STOW-RS:

   ./stowrs --url http://iris:52773/dicom/studies /shared/dicom/d1I00001.dcm /shared/dicom/d1I00002.dcm /shared/dicom/d1I00003.dcm
   

4. In IRIS, check the received message in the DICOM REST Service Messages

Expected outcome: IRIS receives the STOW-RS request, and the simulated listener receives the forwarded DICOM C-STORE messages.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# You’re All Set!

You now have a fully working, simulated DICOM integration lab using IRIS for Health and dcm4che. Use it to learn, test and build prototypes.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Stop the lab (optional)

docker compose down

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Securing DICOM with TLS

Want to add mutual TLS (mTLS) authentication to your DICOM communications?

Check out the TLS Setup Guide for step-by-step instructions on creating certificates and configuring secure connections between SCU clients and IRIS.

https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/#https://github.com/intersystems-ib/workshop-iris-dicom-interop/blob/master/# Learn More

• InterSystems Learning Portal
• 📦 dcm4che DICOM Tools
• 💡 IRIS for Health