Populating observation field default values from HL7 data

💡 HL7-driven observation defaults are available only by request to customers using the Rad AI Reporting enhanced experience. Contact [e-mail] for access.

Learn how to configure observation fields to automatically populate their default values from incoming HL7 data. This article explains how to configure observation formulas, and how the populated values behave in the report workspace and outbound HL7 messages.

In this article:

1. Prerequisites
2. Overview
3. Configuring observation field default values
4. Referencing FHIR Observation resources in an observation
5. Using option select formulas in an observation
6. Using HL7-populated observations in the report workspace
7. Troubleshooting
8. Frequently asked questions

 

Prerequisites

Before you can populate observation field default values from HL7 data, make sure: 

1. The HL7-driven observation defaults feature has been enabled for your organization by Rad AI.

   💡 HL7-driven observation defaults are available only by request. Contact [e-mail] for access.
2. Your organization is using the Reporting enhanced experience, since this feature is not supported in the classic experience. 
    
3. The following permissions are enabled for your for your assigned role:
   • Admin Access
   • Read Observation

   • Manage Observation

     💡 The preconfigured “Admin” role comes with these permissions enabled by default. Learn more about roles and permissions.

3. Your integration stores inbound HL7 observation data as FHIR Observation resources (for example, in Medplum). Each FHIR Observation should have an observation code that you can reference in your observation formulas.

4. The observation fields you want to populate have been configured in Rad AI Reporting. Learn more about observations.

 

Overview

With this feature enabled, you can configure observation fields to populate their default values from inbound HL7 data using observation formulas.

At a high level, the process works as follows:

1. Your organization's integration converts relevant HL7 observation data into FHIR Observation resources (for example, in Medplum).
    
2. When a report is created, Rad AI Reporting retrieves the available FHIR Observations and evaluates any formulas configured for your observation fields.
    
3. If a formula references a matching FHIR Observation, the observation field's default value is populated automatically.
    
4. Report authors can review and edit populated values before signing the report.
    
5. When the report is signed, the final observation values can be included in outbound HL7 messages, depending on your observation field configuration.

This allows observation data to flow into the report automatically while still giving report authors the opportunity to review and update values before they're sent to downstream systems. 

 

Configuring observation field default values

1. Select Admin > Observations from the main navigation menu on the left-hand side. 
   
   
   
    
2. Do one of the following:
   • Click Add observation to create a new observation.
   • Double-click a listed observation to edit an existing observation.
      
3. Under the Details tab, in the Default Value section, verify that the correct Type is selected for your observation (Text or Select). 
    
4. Click Enable Formula. 
   
   
   
    
5. Type or paste the formula you want to use into the Enter Formula field. The formula determines how the observation's default value is calculated. 
   
   Depending on how you want to populate the observation field's default value, choose one of the following approaches:
    
   • Populate the observation field's default value from HL7 data using one of Reporting's built-in HL7 formulas, such as:
     • age() — Patient's age
     • reason() — Reason for study
     • studyDate() — Date the study was completed
       Learn more about available HL7 formulas.
        
   • Populate the observation field's default value from a FHIR Observation to use data from the “Measurements” tab in the report workspace. Learn how to reference FHIR Observation resources.
      
   • Populate the default value of a select-type observation by combining functions with the new option select formulas, such as selectOptionByIndex(INDEX), selectOptionByLabel("LABEL"), and selectOptionByValue("VALUE"). Learn more about using option select formulas in an observation.
      

6. Configure any additional settings for the observation. For example, enable Exported to include the observation value in outbound ORU messages when the report is signed.
    
7. Click Save.

8. To make the observation available in reports, do one of the following:
   • Associate the observation with a procedure code
   • Include the observation in a template

 

Referencing FHIR Observation resources in an observation formula

You can populate an observation field's default value using data from a matching FHIR Observation resource.

FHIR Observation resources typically originate from inbound HL7 messages that have been converted and stored in your organization's FHIR store (for example, Medplum). When a report is created, Rad AI Reporting retrieves those Observation resources and makes them available to observation formulas.

To reference a FHIR Observation in an observation formula, use the following syntax:

observationValue("OBSERVATION_CODE")

Replace OBSERVATION_CODE with the code of the FHIR Observation resource. For example:

observationValue("heart-size")

When a report is created, Rad AI Reporting evaluates the formula and populates the observation field's default value if a matching FHIR Observation is found. If no matching FHIR Observation is available, the observation field remains empty unless the formula specifies an alternative value.

💡 The Measurements tab in the report workspace displays data from FHIR Observation resources. Although these are shown under Measurements in the user interface, they are stored as standard FHIR Observation resources.

Report authors can review and edit populated values before signing the report. Any changes made become the final values used for downstream workflows and outbound HL7 messages.

 

Using option select formulas in an observation

You can use option select formulas to populate the default value of a select-type observation. Instead of returning plain text, these formulas return one of the observation's configured options. This allows incoming HL7 data or other formulas to automatically select the appropriate option.

Use the following formulas to return a configured option for a select-type observation:

• selectOptionByIndex(INDEX) — Returns the option at a specific position in the list. For example, selectOptionByIndex(1) returns the first option.
   
• selectOptionByLabel("LABEL") — Returns the option whose label matches the text you specify. For example, selectOptionByLabel("BIRADS 0") returns "BIRADS 0". 
   
• selectOptionByValue("VALUE") — Returns the option whose stored value matches the value you specify. For example, selectOptionByLabel("MRI") returns "MRI". 

You can combine option select formulas with other formula functions, such as if(), to return different options based on report data.

For example, the following formula selects the first option if the patient is older than 60, or the second option if the patient is 60 or younger:

if(ageInYears() > 60, selectOptionByIndex(1), selectOptionByIndex(2))

Option select formulas are particularly useful when you want to populate the default value of a select-type observation while still allowing report authors to review or change the selected option before signing the report.

Learn more about adding options for select-type observations.

 

Using HL7-populated observations in the report workspace

After an observation field has been configured to populate its default value from HL7 data, matching values are automatically populated when a report is created.

When a report author opens the report, any observation fields with matching data are already populated with their default values.

💡 If the underlying FHIR Observation changes after the report has been created, the observation field's default value is refreshed the next time the report is opened. Changes to the underlying FHIR Observation aren't reflected while the report remains open.

Report authors can:

• Review populated values before signing.
• Edit text-based observation fields by entering a new value.
• Select a different option for select-type observations.

HL7-populated values are only default values. If the report author edits a value before signing, the edited value—not the original default—is included in any outbound HL7 messages.

 

Troubleshooting

An observation field isn't populated

If an observation field isn't populated as expected, check the following:

• The inbound HL7 data has been converted into a matching FHIR Observation.
• The observation formula references the correct FHIR Observation code.
• The observation field is included in the report template or associated with the relevant procedure.
• The FHIR Observation was available when the report was created.

If the issue persists, contact your IT or integration team to verify the upstream HL7 and FHIR configuration.

 

An observation field contains an unexpected value

If an observation field is populated with an unexpected value, check the following:

• Verify that the corresponding FHIR Observation contains the expected value.
• Review the observation formula to ensure it returns the expected result.
• Confirm that the formula references the correct FHIR Observation code.

 

Changes aren't reflected in downstream systems

If changes made by a report author aren't reflected in downstream systems, check the following:

• The report was signed after the changes were made.
• The observation field is configured for export.
• The downstream system is processing the updated outbound HL7 message.

 

Frequently asked questions

Can I use this with observations associated with procedure codes?

Yes. As long as the observation field is associated with the relevant procedure and the observation formula references the correct FHIR Observation code, the observation field's default value is populated when a matching report is created. Learn more about associating observations with procedure codes.

 

Can I override an HL7-populated default value in a template?

Yes. Template-level default values take precedence over system-level default values. If a template specifies a default value for an observation field, that value is used instead of the system-level default configured for the observation.