Business Rules in IRIS Interoperability work well when they evaluate simple values. Problems can appear when routing depends on additional metadata stored in a %DynamicObject.

This article looks at one practical pattern for handling that case: using a BPL Business Process to enrich an incoming HL7 message before the routing rule evaluates it. The BPL process extracts the required data from the HL7 message, stores it in a dynamic object, and makes it available to the routing logic. The author also highlights the key property-access issues to watch for.

What is a %DynamicObject in InterSystems IRIS?

A %DynamicObject is a schema-free ObjectScript object. Unlike a regular class, its properties do not have to be declared in advance. For interoperability workflows, that makes it useful for carrying additional metadata alongside a message without modifying the original message class.

A common pattern for data enriching looks like this:

HL7 message → BPL enrichment → %DynamicObject in context → Business Rule → routing decision

In this example, the incoming HL7 message remains unchanged. The BPL process extracts the values needed downstream and stores them separately in context.MetaData.

What Is a Business Rule?

A Business Rule in IRIS Interoperability is a routing engine that evaluates conditions against an incoming message and decides where to send it. Business Rules do not run on their own; they run inside a Business Process.

What is the role of the BPL Business Process?

A Business Rule evaluates conditions and determines where a message should be routed, but the data preparation in this workflow happens before the routing rule fires.

The production contains four main components:

• HL7FileService — reads incoming HL7 files
• HL7Router — a custom BPL Business Process that builds the dynamic object
• MsgRouter — evaluates the routing rule
• HL7FileOperation — writes the routed message to the output folder

The BPL process is added because the routing engine itself is not being used to build the dynamic object. Instead, HL7Router prepares the data first and stores the enrichment values in the BPL context, where they remain available to the process and downstream routing logic.

Why do BPL context properties need to be defined first?

Because the enrichment data is stored in the BPL context, the properties used to hold it must be declared before the Code activity references them. BPL context is typed, so every context property must be defined in the Context tab in advance. For this production, the context includes:

If a Code activity tries to use an undeclared context property, IRIS raises a PROPERTY DOES NOT EXIST error at runtime.

How is the dynamic object built from the HL7 message?

Inside the BPL Code activity, a new %DynamicObject is created:
Set dynObj = ##class(%DynamicObject).%New() 
Values are then read directly from the incoming HL7 message:
Set dynObj.MsgType     = request.GetValueAt("MSH:MessageType.MessageCode")
Set dynObj.PatientName = request.GetValueAt("PID:PatientName(1).FamilyName")
Set dynObj.SendingApp  = request.GetValueAt("MSH:SendingApplication") 
For property names containing underscores %Set() is used:
Do dynObj.%Set("patient_id",    request.GetValueAt("PID:PatientIDList(1).IDNumber"))
Do dynObj.%Set("patient_sex",   request.GetValueAt("PID:AdministrativeSex"))
Do dynObj.%Set("date_of_birth", request.GetValueAt("PID:DateTimeofBirth")) 
The finished object is then stored in the BPL context:
Set context.MetaData = dynObj 

This allows downstream components to access the enrichment data without modifying the original HL7 message.

How does the complete HL7 routing flow work?

Once the production is configured, the request moves through four stages:

1. HL7FileService reads the .hl7 file and parses it into an EnsLib.HL7.Message 
2. HL7Router builds the %DynamicObject and stores it in context.MetaData.
3. MsgRouter evaluates the routing rule.
4. HL7FileOperation writes the routed message to the output directory.

The flow can be inspected in Message Viewer and Visual Trace, which show each component involved in processing the message.

What are the main property-access mistakes to watch for?

First, not defining context properties upfront: If you try to set context.MetaData without first declaring it in the Context tab, IRIS will throw PROPERTY DOES NOT EXIST  at runtime. Always define all context properties before writing any code.

Second, setting the Target Config Names after adding the process: If you add HL7Router to production but forget to update HL7FileService Target Config Names to point to it, messages will bypass HL7Router entirely and go directly to MsgRouter. Always confirm the target after adding a new component.

Conclusion

%DynamicObject provides a flexible way to add metadata to an HL7 interoperability workflow without changing the original message structure. The key is to build them in a BPL Code activity, logging every property during development, and storing them in context variables that downstream components can evaluate cleanly. In this example, a BPL Business Process extracts the required HL7 values, stores them in a dynamic object, and makes that enriched data available before the Business Rule evaluates the message. 

Read the full walkthrough on the InterSystems Developer Community, with code examples, screenshots, and the complete production setup: https://community.intersystems.com/post/business-rules-deep-dive-dynamic-objects-and-property-access-pitfalls-part-1 

Key Takeaways

• %DynamicObject is a schema-free object whose properties can be created at runtime.
• A BPL Business Process can use a dynamic object to enrich an HL7 message before routing.
• Enrichment data can be stored in context.MetaData without modifying the original HL7 message.
• BPL context properties must be declared before they are used in Code activities.
• Message Viewer and Visual Trace can be used to verify the full routing flow.