Data Coercion Guide

That guide will discuss the basics of DICOM data coercion, and how to use it on MedPlum.

What is data coercion?

Data coercion allows you to automatically make changes to order data when a new order arrives. You can inspect the order data, such as patient name, modality, body part, etc. You can then update fields as needed.

Consider some examples of how you might use data coercion:

How to use data coercion on MedPlum?

First, navigate to the device administration section. This area requires administrator access. If you do not have access, please talk to your account manager.

Next, click on the "Edit" link for the device. Data coercion rules are executed per sending device.

In the "Data Coercion" text box, enter your data coercion rules. Rules are written in Lua.

Let's look at some examples...

Example 1: Clean up modality strings

Groups often have strong preferences about orderType strings.

This becomes especially annoying if you receive orders from many different locations. It's virtually impossible to convince all of your providers to use the same modality tags.

Use data coercion to force the modality string to your preference.

Example 2: Convert patient names to upper case

It can also be distracting when you mix the case of patient names. "John Smith", "JOHN SMITH", "john smith"... It just creates extra cognitive burden.

This example forces all patient names to be all caps.

order.patientName = string.upper(order.patientName)

Example 3: Set Transcriptionist and Radiologist

As your team grows, you will inevitably need workflow automation and case assignment.

This example assigns Cody as the assistant and Reshma as the physician.

if == 0 then
    order.assistantUser = {id = 1, name = "Cody Ebberson"}

if == 0 then
    order.physicianUser = {id = 3, name = "Reshma Khilnani"}

Example 6: Export finalized reports to an HL7 destination

HL7 is a complicated and intimidating concept. MedPlum makes it as easy as possible.

This example sends an HL7 message over HTTPS when the order goes into Final status.

Exporting reports as HL7 to other systems is very useful if you want to (for example) integrate your EHR and your Lab Results.

if order.status == 'Final' then
    -- Type in the URL of the endpoint that you want to submit the HL7 message to, the report format and the protocol
    hl7Export("", "text", "https")

Example 7: Export finalized reports and pdfs to an secure FTP destination

Exporting reports to SFTP is easy. MedPlum makes it as easy as possible.

This example sends an HL7 message over secure when the order goes into Final status. You'll need to provide the URL to the box, the report format (choose pdf or hl7), username, password and the directory you want to write to.

if order.status == 'Final' then
    ftpExport("", "pdf", "reshma", "mypass5", "reports")

Order Fields

The following fields are available on the order and prev_order objects.

Note that some fields are "read only". If you make changes to these fields, the changes will be ignored.

Field NameTypeRead-onlyDICOM Field
accessionstringAccession Number (0008,0050)
bodyPartstringBody Part Examined (0018,0015)
descriptionstringOrder Description (0008,1030)
historystringPatient Comments (0010,4000)
institutionNamestringInstitution Name (0008,0080)
manufacturerstringManufacturer (0008,0070)
manufacturerModelstringManufacturer's Model Name (0008,1090)
modalitystringModality (0008,0060)
patientAgestringPatient's Age (0010,1010)
patientDateOfBirthdatePatient's Birth Date (0010,0030)
patientIdstringPatient ID (0010,0020)
patientMrnstringPatient MRN (0010,1090)
patientLocationstringCurrent Patient Location (0038,0300)
patientNamestringPatient's Name (0010,0010)
patientSexstringPatient's Sex (0010,0040)
performing_physicianstringPerforming Physician's Name (0008,1050)
physician_of_recordstringPhysician of Record (0008,1048)
prioritystringPriority (0000,0700)
referringUseruserRequesting Physician (0032,1032)
orderDateTimedate/timeRead-onlyOrder Date (0008,0020)
Order Time (0008,0030)
order_uidstringRead-onlyOrder Instance UID (0020,000D)

Date and Time Types

Data coercion uses a modified version of the Lua standard for date and time types.

In addition to the standard date and time fields (see table below), there is an extra "unixtime" field. As the name implies, this value is a unix time stamp (number of seconds since 1970-01-01 00:00:00).

To update a date/time table, you must set the unixtime property.

Warning! All dates and times are in UTC!
yeara full year
isdsta boolean, true if daylight saving

Learn more about Lua's date and time types:

User Type

User objects are simply a table with two properties.

idnumeric identifier
namedisplay name


In addition, the following functions are available to perform more complicated tasks.


sendEmail(to, subject, body)

Sends an HTML formatted email to the recipient.


  • to (string) - Email address of recipient. Currently, this must be a string specifying a single recipient.
  • subject (string) - Subject line for email.
  • body (string) - HTML string specifying the body content of the email.


sendSms(to, body)

Sends a text message (SMS) to the recipient.


  • to (string) - Phone number of recipient. Currently, this must be a string specifying a single recipient.
  • body (string) - String specifying the body of the text message/SMS.


sendFax(number, sendKeyImages, url, comments)

Faxes a report or other PDF attachment.


  • number (string) - Fax number to send to.
  • sendKeyImages (boolean) - If true, attach the key images for the order to the fax.
  • url (string) - If not nil, the PDF to be sent is retrieved from this location. Otherwise it will be generated from the order report.
  • comments (string) - Optional comments to be added to the cover page of the fax.


sendDicom(localAE, remoteAE, remoteHost, remotePort, remoteTLS)

Sends order via DICOM.


  • localAE (string) - Local AE title.
  • remoteAE (string) - Remote device AE title.
  • remoteHost (string) - Remote device host.
  • remotePort (string) - Remote device port.
  • remoteTLS (boolean) - If true, send over TLS.


hl7export(url, reportFormat, transportProtocol)

Sends a report using HL7 over HTTP(S).


  • url (string) - Url for the HL7 destination.
  • reportFormat (string) - report format.
  • transportProtocol (string) - transport protocol, e.g. https, mllp.


ftpExport(url, reportFormat, username, password, directory)

Sends a report using HL7 over SFTP.


  • url (string) - Url for the SFTP destination, prefix with https:// and include port if you like. For example
  • reportFormat (string) - Acceptable values are hl7, pdf, and athena
  • username (string)
  • password (string)
  • directory (string) - Make sure that the credentials have permissions to write to that directory

Learn more

MedPlum's data coercion system uses the Lua scripting language. To learn more, check out this Lua tutorial: Basic Lua.