T2.2: Creates Routing Rules

Overview

The routing rule editor in InterSystems HealthConnect provides a powerful interface for creating complex message routing logic.

RuleSet Structure

• RuleSet: Container for all routing rules associated with a particular Message Router Business Process
• For each message, the RuleSet evaluates each rule in sequential order
• Critical concept: All rules are evaluated for every message unless a return action stops evaluation

Exam Editor Note

As of April 2025, the exam still uses the older ZEN-based rule editor interface:

• Access the old editor by clicking the button in the upper right corner
• Be familiar with the old editor's appearance and functionality for exam preparation
• Underlying rule logic remains the same

RuleSet Properties

• effectiveBegin/effectiveEnd dates: Control when the RuleSet becomes active
• Allows multiple RuleSets for the same Message Router with transition dates
• Useful for planned upgrades or migrations
• Only the RuleSet whose effective dates include current date/time will be evaluated

Rule Components

Individual rules consist of three main components:

• Constraints: Act as filters to determine if the rule should be evaluated
• When conditions: Define specific criteria that must be met
• Actions: Specify what to do when conditions are met

Overview

Routing rules need to access the content of HL7 messages to make intelligent routing decisions based on patient information, message type, or any other data in the message.

Two Syntaxes for Field Access

The expression editor provides two primary syntaxes:

• HL7.{PropertyPath}: Older, traditional approach commonly seen in exam questions
• Document.{PropertyPath}: Newer alternative
• Both syntaxes provide equivalent functionality for accessing message fields

Required Constraints

Before using either syntax to access message content in when conditions:

• docCategory constraint: Specifies the HL7 version (like "2.5")
• docName constraint: Specifies the message structure (like "ADT_A01")
• These constraints are prerequisites that tell the rule editor what message structure to expect
• Enables field access and code completion in the expression editor

Field Picker Interface

The expression editor includes a field picker interface:

• Visually navigate the message structure
• Select the specific field you want to access
• Example: Navigate through PIDgrp, select PID segment, then patient name field
• The picker generates appropriate virtual property path syntax automatically

Virtual Property Paths

Use dot notation to navigate the hierarchical structure:

• PIDgrp.PID:18: Accesses field 18 of the PID segment within the PID group
• PIDgrp.PV1grp.PV1:18: Navigates through nested segment groups
• Understanding message structure is essential for constructing correct property paths

Overview

The relationship between rule constraints and the expression editor's code completion capability is a critical concept that appears frequently on the certification exam.

Dual Purpose of Constraints

Constraints in routing rules serve dual purposes:

• Filter: Determine which messages the rule applies to
• Enable code completion: Allow expression editor to understand message structure

How Constraints Enable Code Completion

• docCategory constraint: Tells the rule editor which HL7 version (2.3.1, 2.5, 2.7, etc.)
• docName constraint: Specifies the exact message structure (ADT_A01, ORM_O01, ORU_R01, etc.)
• With both defined, the expression editor knows:
• What fields, segments, and segment groups are available
• Can provide appropriate code completion suggestions
• Can validate your field access syntax

Without Constraints

If you attempt to use HL7.{} syntax without docCategory and docName:

• Expression editor doesn't know what message structure to expect
• Cannot provide code completion or validation
• Can lead to runtime errors when accessing fields
• Constraints provide context for field picker interface and correct virtual property paths

Exam Relevance

• Frequently appears in exam questions with specific constraint combinations
• docCategory and docName are prerequisites for HL7 message field syntax
• If field access isn't working, check whether appropriate constraints are defined

Overview

The HL7.{} syntax with curly braces is designed for accessing single, specific field values in routing rule conditions.

Single Field Access

This syntax returns the value of one particular field occurrence:

• Allows direct comparisons using standard operators: equals (=), not equals (!=), greater than (>), less than (<)
• Example: `HL7.{MSH:MessageType.TriggerEvent} = "A01"` checks if the trigger event equals "A01"

Repeating Fields and Segments

When working with repeating elements, specify which occurrence you want:

• Example: `HL7.{NK1(1):Name(1).familylastname.familyname} = "Kennedy"`
• Accesses first occurrence of NK1 (Next of Kin) segment
• Then first occurrence of Name field within that segment
• Finally the family last name component
• Occurrence numbers in parentheses are required for repeating elements

Navigation Syntax

• Colon syntax: Field number follows a colon (e.g., :18 for field 18)
• Dot notation: Component numbers or field names follow dots
• Understanding HL7 schema is essential for constructing correct property paths
• Schema tells you which segments/fields can repeat and what components each field contains

Use Cases

Most appropriate when checking a specific value in a specific location:

• Patient class: `PV1:2 = "I"` for inpatient
• Receiving facility: `MSH:6` matches a specific facility code
• Direct comparison capabilities make this syntax efficient and readable

Overview

The HL7.() syntax with parentheses is designed specifically for working with repeating segments and repeating fields where you want to search across all occurrences rather than accessing a specific instance.

When to Use This Syntax

Particularly powerful when:

• You don't know which occurrence contains the value you're looking for
• You want to match against any occurrence that meets your criteria

Return Value Format

When you use the HL7.() syntax:

• Return value is a collection of all matching values concatenated together
• Each value wrapped in angle brackets
• Example: Patient has three Next of Kin with family names "Kennedy", "Smith", and "Jones"
• Expression `HL7.(NK1():Name().familylastname.familyname)` returns ``

Using Contains Operator

Because the return value is a delimited string with angle brackets:

• Cannot use the simple equals (=) operator
• Must use the Contains operator
• Example: `HL7.(NK1():Name().familylastname.familyname) Contains ""`
• Returns true if any Next of Kin has "Kennedy" as family name
• Regardless of which occurrence or how many total are present

Common Use Cases

Essential for scenarios with repeating elements:

• Multiple OBX: Observation results
• Multiple NK1: Next of kin
• Multiple insurance segments: IN1/IN2
• Repeating fields: Multiple patient identifiers, phone numbers
• Efficiently search across all occurrences in a single condition

Overview

The foreach action in routing rules provides sophisticated iteration capabilities over repeating segments within HL7 messages.

Use Cases

Particularly valuable when processing:

• Laboratory results (ORU messages with multiple OBX segments)
• Message types where you need different routing logic for different occurrences of the same segment type

How foreach Works

• Creates a loop that iterates over each occurrence of a specified repeating segment
• Example: `foreach OBX` executes once for each OBX segment in the message
• Within the loop, define conditions that examine each segment individually
• Perform different actions based on what's found in that particular occurrence

Critical Syntax Difference

Within foreach loops, use different field access syntax:

• Use Segment.{field} instead of HL7.{field}
• Loop context is focused on the current segment occurrence
• Segment reference refers to that specific iteration's segment
• Example: Inside `foreach OBX`, use `Segment.{3}` to access field 3 (Observation Identifier)

Practical Applications

• Split ORU messages: Multiple OBX segments into separate messages for different departments
• Route test results: Specific results to specialized systems, others to general EMR
• Apply transformations: Different transformations to different observation types
• Significantly enhances routing flexibility beyond traditional syntax

Overview

The send action is the fundamental routing mechanism in routing rules, directing messages from the Business Service through the Message Router to target Business Processes or Business Operations.

How Send Works

• Each send action specifies one or more target components by their production configuration names
• When executed, creates a copy of the message and forwards it to each specified target
• Enables message distribution to multiple systems or processing paths

Multiple Targets

A single send action can specify multiple targets separated by commas:

• Efficient when sending the same message to several destinations
• Example: Send ADT admission message to both billing system and bed management system
• All targets receive identical message content
• Suitable for broadcast scenarios where multiple systems need the same information

Transform Integration

The send action can optionally include a transform parameter:

• Specifies a DTL (Data Transformation Language) class to apply before sending
• DTL executes and creates a transformed version of the message
• Transformed version is what gets sent to the target(s)
• Allows modifying message structure based on routing decisions without separate transformation Business Processes

Different Transforms to Different Targets

When different transformed versions are needed:

• Use multiple send actions within the same rule (or in different rules)
• Example: One send transforms to version 2.3.1 for legacy system, another transforms to version 2.5 for modern system
• Each send action executes independently with its specified transformation and targets
• Provides maximum routing flexibility

Overview

Understanding rule evaluation flow and the return action is critical for creating efficient routing rules and avoiding unintended routing behavior.

Default Rule Evaluation

• When a message enters a Message Router, the RuleSet evaluates each rule in sequential order
• By default, all rules will execute unless explicitly stopped
• The return action provides the mechanism to stop rule evaluation

When to Use Return

Particularly important when you have rules that should be mutually exclusive:

• Separate rules for routing different message types to different destinations
• Use return after successfully routing an ADT message
• Ensures rules designed for ORU messages don't also process it
• Without return, both ADT-specific rule and subsequent rules would execute
• Could cause duplicate sends or unwanted routing

Return vs Continue

• Continue action: Allows rule evaluation to proceed to the next rule
• Appropriate when multiple rules should potentially process the same message
• Absence of any flow control action has the same effect
• Return action: Immediately stops all rule evaluation for the current message
• Even if there are more rules in the RuleSet

When Clause Behavior

Within a single rule with multiple when clauses:

• Only the first matching when clause executes
• If when1 matches and executes, when2 and otherwise are skipped
• Even if when2's condition would also be true
• This is independent of the return action
• Return controls whether evaluation continues to the next rule
• When clause matching controls which actions execute within the current rule

Overview

Troubleshooting routing rule problems requires systematic analysis of how constraints, conditions, and actions interact.

Constraint Mismatch Issues

One of the most common issues - rule's constraints don't match incoming message properties:

• Source constraint: Verify it matches the actual Business Service name sending the message
• docCategory constraint: Must match Message Schema Category configured in Business Service
• docName constraint: Must match actual message structure being processed
• If any constraint doesn't match, the rule is skipped entirely

Testing Service Gotcha

A particularly tricky exam scenario:

• When you test using the built-in test interface, message comes from virtual "Testing Service"
• Not from your actual Business Service
• If rule has Source constraint specifying actual Business Service name, rule won't match during testing
• Even though it would match in production
• Can cause confusion when rule appears not to work during testing

Field Access Problems

Often stem from missing or incorrect constraints:

• HL7.{} syntax requires both docCategory and docName constraints
• Without them, expression editor cannot determine message structure
• If docName doesn't match actual message structure, field access fails at runtime
• Message structure doesn't match what the rule expects

Rule Order and Return Placement

Significantly affects routing behavior:

• If earlier rule matches and executes return, all subsequent rules are skipped
• Regardless of whether they would have matched
• When messages aren't routing as expected, check for earlier rules with return
• Review order of rules in RuleSet
• Verify return action placement ensures evaluation flow matches intent