DCM4CHEE: Updating the Modality Work List via HL7 / ORM^O01

Adding an item to dcm4chee’s modality work list (MWL) via an HL7 message is at first glance quite simple. For example sending the following ORM^O01 message:

MSH|^~\&|SendingApp|SendingFac|ReceivingApp|ReceivingFac|20160629095023||ORM^O01^ORM_O01|168715|P|2.5
PID||1|A-10001||DOE^JOHN
PV1||RAD|||||REF_PHYS_ID^REF_PHYS_FIRST^REF_PHYS_LAST|^ReferringPhysLast^ReferringPhysFirst
ORC|NW|1|||||^^^20150414120000
OBR|1|1|2|1100|||||||||||||||2|SPS_ID||||CT||||||||||PERFOMING_TECH
ZDS|1.2.4.0.13.1.432252867.1552647.1^AETitle^StationName

via the command-line using hl7snd from the dcm4che toolkit should work right out of the box w/ dcm4chee’s default config. Ie: Doing

$ cat orm_test_message.hl7 |  hl7snd -c localhost:2575  -

(where orm_test_message.hl7 contains the above sample message in plain text format) and querying the backend db like so:

dcm4chee=> select * from mwl_item;

should produce the following result, confirming the addition of a new MWL item corresponding to the above message:

pk | patient_fk | sps_status | sps_id |     start_datetime      | station_aet | station_name | ...
45 |         39 |          0 | SPS_ID | 2015-04-14 12:00:00     | UNKNOWN     | UNKNOWN       | ...

While this is a great first step, and may even be sufficient for your use case, not all of the information from the ORM is inserted into the MWL entry as expected.

For example, in the above message, notice that the ZDS segment has a component which specifies the AE Title and Station Name. However, in the above query result of the mwl_item table, these two fields continue to be blank.

After doing some digging I discovered that this is because the settings file which controls how dcm4chee parses and stores info from incoming ORM messages, conf/dcm4chee-hl7/orm2dcm.xls, is not setup to grab the AE Title and Station Name out-of-the box.

For my use case, it is a requirement that this information correctly be entered into dcm4chee’s db. Since getting it to do so required quite a few hours of playing with configs and poking around online, I decided it would be worthwhile to document the final result of this effort here.

(Moreover, the process of understanding how to get something like this working should prove insight in tackling other issues that may come up related to integrating HL7 with dcm4chee as it touches upon the core of how dcm4chee processes HL7 information.)

Note: In an upcoming companion article I will have a more general discussion on ORM^O01 and HL7 messages in general, including getting familiar with the official HL7 docs and how to use them when learning something new in HL7.

Note: The steps in this article have been tested on dcm4chee-2.18.x, no more no less :).

Configuring Dcm4chee to Parse the AE Title and Station Name

As alluded to above, getting dcm4chee to correctly parse and insert the AE Title and Station name from the above sample message requires modifying the config file:

PATH_TO_DCM4CHEE/server/default/conf/dcm4chee-hl7/orm2dcm.xls

Which controls how the information within an ORM HL7 message is mapped to DICOM which in turn is mapped to entries within dcm4chee’s database, in which there is a table which stores the modality work list.

The key is making the following adjustments to the aforementioned file.

First of all, we need to add entries defining the mapping of AE Title and Station name, respectively:

    <xsl:template match="ZDS" mode="sps">
        <!-- Station AE Title -->
        <xsl:call-template name="attr">
            <xsl:with-param name="tag" select="'00400010'"/>
            <xsl:with-param name="vr" select="'AE'"/>
            <xsl:with-param name="val" select="string(field[1]/component[2]/text())"/>
        </xsl:call-template>
        <!-- Scheduled Station Name (set to same field as AE Title)-->
        <xsl:call-template name="attr">
            <xsl:with-param name="tag" select="'00400001'"/>
            <xsl:with-param name="vr" select="'AE'"/>
            <xsl:with-param name="val" select="string(field[1]/component[1]/text())"/>
        </xsl:call-template>
    </xsl:template>

These sit apart from the entry defining how to extract the study_uid from the ZDS segment which in the default config already looks like this:

    <xsl:template match="ZDS">
        <!-- Study Instance UID -->
        <xsl:call-template name="attr">
            <xsl:with-param name="tag" select="'0020000D'"/>
            <xsl:with-param name="vr" select="'UI'"/>
            <xsl:with-param name="val" select="string(field[1]/text())"/>
        </xsl:call-template>
    </xsl:template>

The second and final step is to add an entry including the newly defined template referencing the AE Title and Station name into the ORC Scheduled Procedure Step sequence entry, like so:

    <xsl:template match="ORC" mode="sps">
            <item>
                <!-- Scheduled Procedure Step Start Date/Time -->
                <xsl:call-template name="attrDATM">
                    <xsl:with-param name="datag" select="'00400002'"/>
                    <xsl:with-param name="tmtag" select="'00400003'"/>
                    <xsl:with-param name="val" select="string(field[7]/component[3]/text())"/>
                </xsl:call-template>
                <xsl:apply-templates select="following-sibling::OBR[1]" mode="sps"/>
                <xsl:apply-templates select="following-sibling::ZDS" mode="sps"/>
            </item>

Notice this section is exactly the same as the default config, save for the extra line containing “following-sibling::ZDS.”

With these two modifications, re-sending the above sample ORM message to dcm4chee should add an item to your MWL with the correct AE Title and Station Name. A query to the db should yield a result looking like this:

pk | patient_fk | sps_status | sps_id |     start_datetime      | station_aet | station_name | ...
46 |         39 |          0 | 1      | 2016-06-11 12:22:02.249 | AETitle     | StationName  | ...

Download a Sample Version of orm2dcm.xsl

I am including a complete sample version of orm2dcm.xls here. However, if you’re going to try it out make sure you properly rename it, ie: remove the “_.txt” extension which I added for security-related reasons.

Other Resources Online

The most useful resource I found in figuring the above out was this thread in the old dcm4che group forum.

However, the suggestions in this thread from the same group did not work for me.


No fancy tricks or popups, simply an article like the above, which I write a few times a month - just for my subscribers.