DEV Community: InterSystems

Business Rules Deep Dive: Dynamic Objects and Property Access Pitfalls - Part (2)

InterSystems Developer — Thu, 24 Sep 2026 15:46:30 +0000

Hi, Community!

In Part 1 of this series, we built a production using the HL7 Messaging type and created a BPL Business Process that enriches an incoming HL7 message with a %DynamicObject before passing it to the routing engine. If you have not read Part 1 yet, start there. It fully covers the production setup, context properties, and the Build Dynamic Object Code activity.

This article focuses on what happens after you start using %DynamicObject in production. Seven specific property-access pitfalls catch every developer sooner or later. They all share the same frustrating characteristic: no error, no warning in the Event Log, just an empty value that causes your routing rule to fall through to the default action with no clue why.

To fix that, we added a second Code activity to the same Demo.HL7Router BPL from Part 1. Then we demonstrated all seven pitfalls with working code and verified the results in the Event Log and Visual Trace.

TL;DR

All seven common %DynamicObject pitfalls produce the same symptom: empty value, no error, no warning.
Underscore in property names, wrong case, and nested object access are the top three; use %Get() for all of them.
Use %IsDefined() to check if a property exists, %GetIterator() to loop over properties, and %GetTypeOf() to distinguish null from an empty string.
Numeric JSON values require numeric comparison; string comparison with a number silently fails to match.

Who This Article Is For

This guide is for IRIS Interoperability developers who work with %DynamicObject in BPL Business Processes and have experienced unexpected empty values or routing rule fall-throughs that are difficult to diagnose.

Prerequisites

Complete Part 1 of this series first. You should have a running Demo.HL7RulesDemo production with the following:

HL7FileService configured and pointing to HL7Router
Demo.HL7Router BPL with the Build Dynamic Object Code activity verified in the Event Log and working
MsgRouter and HL7FileOperation configured and running

Adding the Property Pitfalls Code Activity

Open Demo.HL7Router in the Business Process Designer.

Click Add Activity and select Code. Drag it between Build Dynamic Object and the Call activity.

Reconnect the arrows:

Remove the arrow from Build Dynamic Object to the Call activity.
Connect Build Dynamic Object to the new Code activity.
Connect the new Code activity to the Call activity.

Label it Property Pitfalls.

Click on the Code activity to select it. In the right-side panel, find the Code field and click the magnifier icon. Enter the following code; each pitfall is clearly labelled in the comments:

// -------------------------------------------------------
// PITFALL 1: Underscore in property name
// _ is string concatenation in ObjectScript
// context.MetaData.patient_id reads as (context.MetaData.patient) _ (id)
// -------------------------------------------------------
Try {
    Set wrongValue = context.MetaData.patient_id
} Catch ex {
    Set wrongValue = ""
}
$$$LOGINFO("Pitfall 1 - Wrong (underscore)  : [" _ wrongValue _ "]")

// CORRECT: use %Get() for underscore-named properties
Set context.PatientId = context.MetaData.%Get("patient_id")
$$$LOGINFO("Pitfall 1 - Correct            : " _ context.PatientId)

// -------------------------------------------------------
// PITFALL 2: Case sensitivity
// Patient_Id and patient_id are different properties
// -------------------------------------------------------
Set wrongCase = context.MetaData.%Get("Patient_Id")
$$$LOGINFO("Pitfall 2 - Wrong case         : [" _ wrongCase _ "]")

Set correctCase = context.MetaData.%Get("patient_id")
$$$LOGINFO("Pitfall 2 - Correct case       : " _ correctCase)

// -------------------------------------------------------
// PITFALL 3: Nested object access
// Cannot chain dot notation for nested %DynamicObject
// -------------------------------------------------------
Set addressObj = ##class(%DynamicObject).%New()
Set addressObj.city    = "Lahore"
Set addressObj.country = "PK"
Do context.MetaData.%Set("address", addressObj)

// Wrong way - fails silently
Set wrongNested = context.MetaData.address.city
$$$LOGINFO("Pitfall 3 - Wrong nested access: [" _ wrongNested _ "]")

// CORRECT: get nested object first then access its property
Set addr = context.MetaData.%Get("address")
Set city = addr.%Get("city")
$$$LOGINFO("Pitfall 3 - Correct nested     : " _ city)

// -------------------------------------------------------
// PITFALL 4: Checking if a property exists
// %Get() returns empty for both missing and empty properties
// Use %IsDefined() to check existence reliably
// -------------------------------------------------------
If context.MetaData.%IsDefined("patient_id") {
    $$$LOGINFO("Pitfall 4 - patient_id exists  : " _ context.MetaData.%Get("patient_id"))
} Else {
    $$$LOGINFO("Pitfall 4 - patient_id does not exist")
}

If context.MetaData.%IsDefined("ward_code") {
    $$$LOGINFO("Pitfall 4 - ward_code exists   : " _ context.MetaData.%Get("ward_code"))
} Else {
    $$$LOGINFO("Pitfall 4 - ward_code does not exist - use default")
}

// -------------------------------------------------------
// PITFALL 5: Iterating over properties
// For loops do not work on %DynamicObject
// Use %GetIterator() instead
// -------------------------------------------------------
$$$LOGINFO("Pitfall 5 - Iterating properties:")
Set iter = context.MetaData.%GetIterator()
While iter.%GetNext(.key, .val) {
    If $IsObject(val) {
        $$$LOGINFO("  Key: " _ key _ " = [object]")
    } Else {
        $$$LOGINFO("  Key: " _ key _ " = " _ val)
    }
}

// -------------------------------------------------------
// PITFALL 6: Null vs Empty String
// Both return empty from %Get() but are different types
// Use %GetTypeOf() to distinguish
// -------------------------------------------------------
Set nullJson = ##class(%DynamicObject).%FromJSON("{""nullProp"":null,""emptyProp"":""""}")
$$$LOGINFO("Pitfall 6 - emptyProp value    : [" _ nullJson.%Get("emptyProp") _ "]")
$$$LOGINFO("Pitfall 6 - nullProp value     : [" _ nullJson.%Get("nullProp") _ "]")
$$$LOGINFO("Pitfall 6 - emptyProp type     : " _ nullJson.%GetTypeOf("emptyProp"))
$$$LOGINFO("Pitfall 6 - nullProp type      : " _ nullJson.%GetTypeOf("nullProp"))

// -------------------------------------------------------
// PITFALL 7: Number type handling
// Numeric values in JSON are stored as numbers not strings
// Use numeric comparison or unary + for conversion
// -------------------------------------------------------
Set numObj = ##class(%DynamicObject).%FromJSON("{""age"":25}")

If numObj.%Get("age") = "25" {
    $$$LOGINFO("Pitfall 7 - String comparison  : matched (unexpected)")
} Else {
    $$$LOGINFO("Pitfall 7 - String comparison  : [no match - wrong approach]")
}

If numObj.%Get("age") = 25 {
    $$$LOGINFO("Pitfall 7 - Numeric comparison : matched correctly")
}

If +numObj.%Get("age") = 25 {
    $$$LOGINFO("Pitfall 7 - Unary + conversion : matched correctly")
}

// Store context values
Set context.PatientSex = context.MetaData.%Get("patient_sex")

// Send message to MsgRouter for routing decision
Set sc = ..%Process.SendRequestAsync("MsgRouter", request)

Click OK to close the editor, then click Save and Compile. Confirm that no errors appear before testing.

Test and Verify

Drop a new test file into your incoming folder. Go to Management Portal > Interoperability > View > Messages and click the message to open the Visual Trace.

Mark the Show Events checkbox at the top. This makes the $$$LOGINFO entries from your Code activities visible in line in the trace. Click on any event entry to expand it and see the full log message.

Go to Management Portal > Interoperability > View > Event Log. All the log entries from both Code activities appear here. Look for the pitfall entries to confirm the results match what you expect:

Understanding the Seven Pitfalls

All seven pitfalls share the same symptom: an empty value or an unexpected result with no error in the Event Log. That is what makes them hard to debug without knowing what to look for.

Pitfall 1: Underscore in Property Name

This is the most common silent failure when consuming REST APIs that use snake_case naming. When you write the following:

Set val = dynObj.patient_id

ObjectScript does not read patient_id as a single property name. The underscore _ is the string concatenation operator, so this line is read as the value of dynObj.patient concatenated with the string id. Since dynObj.patient does not exist, the result is empty, with no error or warning.

// Wrong - returns empty silently
Try {
    Set val = dynObj.patient_id
} Catch ex {
    Set val = ""
}

// Correct - use %Get() for underscore-named properties
Set val = dynObj.%Get("patient_id")

Pitfall 2: Case Sensitivity

%DynamicObject property names are fully case-sensitive. PATIENT_ID, patient_id, and Patient_Id are three completely different properties. This comes up when you consume third-party APIs with inconsistent casing or when you type the property name slightly differently in two places.

// Wrong - wrong case returns empty silently
Set val = dynObj.%Get("Patient_Id")

// Correct - exact case must match what was set
Set val = dynObj.%Get("patient_id")

Always check the raw JSON to confirm the exact casing before writing your access code. Log the property value immediately after setting it during development to confirm it is there.

Pitfall 3: Nested Object Access

Modern REST APIs almost always return nested JSON structures. When IRIS parses nested JSON, each nested object becomes its own %DynamicObject instance. Dot notation does not automatically traverse nested objects.

// Wrong - fails silently
Set city = dynObj.address.city

// Correct - get the nested object first, then access its property
Set addr = dynObj.%Get("address")
Set city = addr.%Get("city")

This pattern applies at every level of nesting:

Set patientObj = dynObj.%Get("patient")
Set contactObj = patientObj.%Get("contact")
Set phone      = contactObj.%Get("phone")

Pitfall 4: Checking If a Property Exists

Many developers use %Get() and check if the result is empty to determine whether a property exists. However, this is unreliable because a property can exist with an empty value, and both cases return empty from %Get(). The correct method is %IsDefined():

// Wrong - cannot distinguish missing property from empty value
If dynObj.%Get("patient_id") = "" {
    // Is it missing or just empty?
}

// Correct - explicitly checks if property exists
If dynObj.%IsDefined("patient_id") {
    Set val = dynObj.%Get("patient_id")
} Else {
    $$$LOGINFO("patient_id does not exist - using default")
    Set val = "UNKNOWN"
}

In the Event Log, you will see ward_code logged as "does not exist" because we never set it, while patient_id is correctly found and returned.

Pitfall 5: Iterating Over Properties

ObjectScript For loops do not work on %DynamicObject. The correct way is %GetIterator():

// Wrong - does not work on %DynamicObject
For i = 1:1:dynObj.%Size() {
    Write dynObj.%Get(i), !
}

// Correct - use %GetIterator()
Set iter = dynObj.%GetIterator()
While iter.%GetNext(.key, .val) {
    If $IsObject(val) {
        $$$LOGINFO("Key: " _ key _ " = [object]")
    } Else {
        $$$LOGINFO("Key: " _ key _ " = " _ val)
    }
}

In the Event Log, you will see all properties listed in order, confirming that %GetIterator() traverses all of them correctly, including the nested address object.

Pitfall 6: Null vs. Empty String

%DynamicObject distinguishes between a property set to JSON null and a property set to an empty string "". Both return empty from %Get(), but they are different types. Use %GetTypeOf() to distinguish between them:

Set testObj = ##class(%DynamicObject).%FromJSON("{""nullProp"":null,""emptyProp"":""""}")

// Both return empty from %Get()
Write testObj.%Get("emptyProp"), !   // empty
Write testObj.%Get("nullProp"), !    // empty

// Use %GetTypeOf() to distinguish
Write testObj.%GetTypeOf("emptyProp"), !  // string
Write testObj.%GetTypeOf("nullProp"), !   // null

This matters when you need to know whether a field was intentionally left empty or was absent from the JSON payload entirely.

Pitfall 7: Number Type Handling

When JSON contains numeric values, %DynamicObject stores them as numbers, not strings. Comparing a numeric property with a string value silently fails to match:

Set numObj = ##class(%DynamicObject).%FromJSON("{""age"":25}")

// Wrong - string comparison does not match a numeric value
If numObj.%Get("age") = "25" { ... }

// Correct - use numeric comparison
If numObj.%Get("age") = 25 { ... }

// Also correct - force numeric conversion with unary +
If +numObj.%Get("age") = 25 { ... }

Common Mistakes

Using dot notation for anything other than simple property names: If the property name has an underscore, has inconsistent casing, or could be nested, always use %Get(). Making it your default for all %DynamicObject access prevents pitfalls 1, 2, and 3 with one habit.

Not logging values during development: All seven pitfalls return empty silently. Without $$$LOGINFO statements around your property access code, you will have no idea which pitfall you hit. Log every value you read from a %DynamicObject during development, then clean up before going to production.

Trusting the routing rule to tell you what went wrong: The routing rule does not throw an error when a condition evaluates to empty. It simply moves to the next rule or the default. If you are debugging a routing fall-through, always check the Event Log first to confirm what values your Code activity produced before looking at the routing rule.

Practical Recommendations

Make %Get() your default for all %DynamicObject property access, not just for underscores.
Use %Set() when setting any property with special characters, including underscores.
Exploit %IsDefined() before %Get() whenever a property might be missing.
Utilize %GetTypeOf() when you need to distinguish null from an empty string.
Employ numeric comparison (= 25, not = "25") when working with JSON numeric values.
Log every dynamic object property during development and verify them in the Event Log before testing the routing rule.
Remove debug $$$LOGINFO statements before going to production; they write to the Event Log database and consume storage over time.

FAQ

Q: Why does my routing rule fall through even though the condition looks correct?

A: The most likely cause is a silent empty value on the left side of the condition. Check the Event Log for the $$$LOGINFO entries from your Code activity. If the value you are routing on is empty, trace it back through the seven pitfalls starting with an underscore in the property name.

Q: Is there a safe way to read any %DynamicObject property regardless of what it is called?

A: Yes. Always use %Get("propertyName"). It handles underscore names, case-sensitive names, and works as the entry point for nested object traversal. Dot notation works reliably only for simple property names with no special characters.

Q: How do I know if a property name has the wrong case?

A: Log the raw JSON string before parsing it and compare it against your %Get() calls. In development, log every value immediately after setting it and check the Event Log to confirm the value is there before the routing rule evaluates it.

Q: Can I iterate over a %DynamicArray the same way?

A: Yes. %GetIterator() works on both %DynamicObject and %DynamicArray. For an array, the iterator returns numeric indices starting from 0 instead of property names. The %GetNext(.key, .val) pattern functions in an identical manner.

Q: What does %GetTypeOf() return for different value types?

A: It returns a string describing the type: "string", "number", "boolean", "null", "object", or "array". Use it whenever you need to make a decision based on what type of value a property holds rather than just whether it is empty or not.

Q: Should I remove the $$$LOGINFO statements after testing?

A: Yes, for production. $$$LOGINFO entries write to the Event Log database and consume storage over time. Keep only those entries that are genuinely useful for monitoring and remove the debug-level ones used during development.

Conclusion

All seven pitfalls covered in this article share one characteristic: they fail silently. That is what makes them so frustrating to debug. The routing rule falls through, the message lands on the default action, and there is nothing in the Event Log to point you in the right direction unless you already know what to log.

The fix for most of them, however, is a single habit: use %Get() for all %DynamicObject property access and log every value during development. Once you know the seven patterns, spotting them in code will take you seconds rather than hours.

Thanks for reading!

Business Rules Deep Dive: Dynamic Objects and Property Access Pitfalls - Part (1)

InterSystems Developer — Thu, 24 Sep 2026 15:43:21 +0000

Hi, Community!

Business Rules in IRIS Interoperability are one of those features that work smoothly until they suddenly do not anymore. You build a rule, the condition looks correct, the routing target is right, but the message keeps falling through to the default action. There is no error in the Event Log and no obvious clue in the Visual Trace.

One of the most common causes is a dynamic object whose properties are not accessible the way you expect. This two-part series covers the full picture. Part 1 walks us through setting up a production using the HL7 Messaging type and building a BPL Business Process that enriches an incoming HL7 message with a dynamic object. Part 2 uses the same production and demonstrates seven real-world property-access pitfalls that cause silent failures in production integrations.

TL;DR

A %DynamicObject in IRIS is a schema-free object you create on the fly without defining a class.
Use it inside a BPL Business Process to carry enrichment data alongside an HL7 message before the routing rule evaluates it.
Exploit %Set() to set properties with special characters like underscores and %Get() to read them back.
Part 2 of this series covers seven property-access pitfalls that all silently return empty with no error.

Who This Article Is For

This guide is for IRIS Interoperability developers working with BPL Business Processes and HL7 routing who want to understand how to enrich messages with dynamic objects before routing decisions are made.

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.

In this article, all the data preparation work happens in a BPL Business Process before the routing rule fires. The routing rule then evaluates clean, simple values and makes the decision.

What Is a Dynamic Object?

A %DynamicObject in IRIS is a schema-free object. Unlike a regular ObjectScript class where you define properties upfront, a %DynamicObject lets you create any property on the fly at runtime without a class definition. This makes it extremely useful in integration scenarios where you need to carry extra data alongside a message as it moves through production.

A common real-world pattern is enriching an incoming HL7 message with additional metadata before the routing rule evaluates it. Instead of modifying the original HL7 message class, you create a %DynamicObject, set whatever properties you need, store it in the BPL context, and read from it downstream.

In our example, we read the message type, patient name, and sending application from the incoming HL7 message and store them in a dynamic object. That object then travels with the message through production, and anything downstream can read from it without touching the original HL7 structure.

The Production We Will Build

The production uses standard auto-created components plus one new BPL Business Process:

HL7FileService: Scans a folder for incoming HL7 files.
HL7Router: Our new BPL Business Process that builds the dynamic object.
MsgRouter: Evaluates the routing rule.
HL7FileOperation: Writes the routed message to an output folder.

Step 1: Create the Production

Go to Management Portal > Interoperability > List > Production and click New.

Fill in the form with the following data:

Package: Demo
Name: HL7RulesDemo
Description: Demonstrates dynamic objects and property access pitfalls using a BPL process alongside the HL7 routing engine.
Production Type: HL7 Messaging

Click OK.

When you select HL7 Messaging, IRIS automatically creates a set of standard components:

HL7FileService: A Business Service that monitors a folder for incoming HL7 files.
MsgRouter: An EnsLib.HL7.MsgRouter.RoutingEngine that evaluates routing rules.
HL7FileOperation: A Business Operation that writes routed messages to an output folder.
BadMessageHandler, EMailAlert, PagerAlert: Alert components you can configure later.

It saves significant setup time, so we will simply reuse these components and add only one new BPL Business Process.

Step 2: Configure the Auto-Created Components

Configure HL7FileService

Click on HL7FileService in the canvas to open its settings panel. Set up the following information:

File Path: Your incoming folder (e.g., C:\hl7\in)
File Spec: *.hl7
Message Schema Category: 2.5

Click Apply.

Configure HL7FileOperation

Click on HL7FileOperation in the canvas and set the following:

File Path: Your outgoing folder (e.g., C:\hl7\out)

Click Apply.

Step 3: Build the BPL Business Process

The MsgRouter routing engine evaluates simple conditions but does not support Code activities for building dynamic objects. We add a BPL Business Process between HL7FileService and MsgRouter to handle all data preparation.

3A. Create the Process

Go to Management Portal > Interoperability > List > Business Processes and click New. In the General tab, set Language to ObjectScript. Then save it as Demo.HL7Router.

3B. Define Context Properties

In BPL, context is a typed class, and every property you want to use must be declared upfront in the Context tab before you write any code. If you skip this and try to set a property inside a Code activity, IRIS will throw a PROPERTY DOES NOT EXIST error at runtime. So, before touching the canvas, let us define all the properties this process will need.

In the right-side panel, click the Context tab, then click + to add each property:

Property Name	Property Type
MetaData	%DynamicObject
PatientId	%String(MAXLEN=50)
PatientSex	%String(MAXLEN=50)

3C. Add the Code Activity

Click Add Activity and select Code. Drag it between <start> and <end>. Label it Build Dynamic Object.

Connect the arrows:

<start> to Build Dynamic Object
Build Dynamic Object to <end>

Click on the Code activity to select it. In the right-side panel, find the Code field and click the magnifier icon next to it. It will open a larger editor where you can enter the code below:

$$$LOGINFO("Request class: " _ $classname(request))
Set dynObj = ##class(%DynamicObject).%New()

// Read values from the actual 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")

// Use %Set() for underscore-named properties
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"))

// Log each value for testing purposes
$$$LOGINFO("Dynamic Object built:")
$$$LOGINFO("  MsgType    : " _ dynObj.MsgType)
$$$LOGINFO("  PatientName: " _ dynObj.PatientName)
$$$LOGINFO("  SendingApp : " _ dynObj.SendingApp)
$$$LOGINFO("  patient_id : " _ dynObj.%Get("patient_id"))

// Store in context
Set context.MetaData = dynObj

Click OK to close the editor, then click Save and Compile. Ensure that no errors appear before moving forward.

3D. Add the Process to Production

Go back to the production canvas. Click Add in the Processes section:

Process Class: Demo.HL7Router
Process Name: HL7Router
Description: BPL process that builds dynamic objects before routing
Enable Now: Checked

Click OK.

Before starting the production, make sure that the following steps are complete:

1. Set Business Service Target
Click on HL7FileService in the production canvas. Confirm Target Config Names is set to HL7Router. If not, type HL7Router and click Apply.

2. Enable All Components
Confirm the Enabled checkbox is marked off for the following:

HL7FileService
HL7Router
MsgRouter
HL7FileOperation

How It All Fits Together

It is worth pausing here to understand the full flow before we start testing:

HL7FileService picks up the .hl7 file from the incoming folder and parses it into an EnsLib.HL7.Message. It forwards the message to HL7Router based on the Target Config Names setting.
HL7Router runs the Build Dynamic Object Code activity, stores the enriched object in context.MetaData, and then calls MsgRouter using SendRequestAsync. MsgRouter evaluates the routing rule and sends the message to HL7FileOperation.
HL7FileOperation writes the routed message to the outgoing folder.

Step 4: Start the Production and Test

Start the production. All components should show green status indicators.

The Sample HL7 Message

Create the test file using the IRIS terminal to ensure correct segment separators:

Set file = ##class(%File).%New("C:\hl7\in\test1.hl7")
Do file.Open("NWS")
Set content = "MSH|^~\&|SENDING_APP|SENDING_FAC|RECEIVING_APP|RECEIVING_FAC|20250315143022||ADT^A01|MSG00001|P|2.5" _ $Char(13)
Set content = content _ "EVN|A01|20250315143022" _ $Char(13)
Set content = content _ "PID|1||MRN001^^^HOSP||Smith^John^M||19850101|M|||123 Main Street^^Lahore^Punjab^54000^PK||03001234567" _ $Char(13)
Set content = content _ "PV1|1|I|WARD-A^Room101^Bed1|E|||DOC001^Smith^James|||SUR|||||||V01|ACC001" _ $Char(13)
Do file.Write(content)
Do file.Close()
Write "File created", !

(Remember to replace C:\hl7\in\ with your actual incoming folder path.)

Verify in Message Viewer and Visual Trace

Within 5 seconds, the adapter picks up the file. Go to Management Portal > Interoperability > View > Messages.

Click the message to open the Visual Trace. You will see the complete flow:

HL7FileService reads the file.
HL7Router processes it and builds the dynamic object.
MsgRouter evaluates the routing rule.
HL7FileOperation writes the output file.

Common Mistakes

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.

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.

Practical Recommendations

Always define all context properties in the Context tab before writing any Code activity logic.
Log every dynamic object property immediately after setting it during development; this is the fastest way to confirm values are correct before testing the routing rule.
Keep the dynamic object lean by only storing values you actually need downstream.

FAQ

Q: Do I need a dynamic object if I can pass the HL7 message directly to the routing rule?

A: Simple property names (e.g., context.MetaData.MsgType = "ADT") work well and get evaluated correctly. However, properties with underscores in their names do not work reliably in the rule expression editor. Extract those values into typed context variables in the Code activity and evaluate them in the rule instead.

Q: Why does my Code activity compile but fail at runtime with PROPERTY DOES NOT EXIST?

A: This happens when you reference a context property that was not declared in the Context tab. Go to the Context tab, add the missing property, and recompile.

Q: Can I use %DynamicObject properties directly in a routing rule condition?

A: Simple property names work context.MetaData.MsgType = "ADT" evaluates correctly. Properties with underscores in their names do not work reliably in the rule expression editor. Extract those values into typed context variables in the Code activity and evaluate those in the rule instead.

Q: What happens if I forget to call Compile after editing the BPL?

A: The production will run the previous compiled version of the class. Your changes will not take effect until you compile. Always compile after every code change and confirm there are no errors before testing.

Q: Can I store a nested object inside a %DynamicObject?

A: Yes. You can set a nested %DynamicObject as a property value using %Set(). However, to access nested properties, you should get the nested object first. (It will be covered in detail in Part 2.)

What Is Coming in Part 2

Part 1 covered building and using a %DynamicObject inside a BPL Business Process. Part 2 will use the same production but add a second Code activity that will demonstrate seven real-world property-access pitfalls.

Conclusion

Dynamic objects are a practical tool that enriches HL7 messages with metadata before routing decisions are made. 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.

The production we built in this article gives you a working foundation to experiment with. Try adding more properties to the dynamic object, or update the routing rule condition to evaluate context.MetaData.MsgType directly and see how it behaves. In the next article in this series, we will take this exact production and break down seven real-world property-access pitfalls every developer encounters when working with %DynamicObject in production integrations.

Thanks for reading!

Exposing IRIS data through MCP with AI Hub: a practical toolkit with access controls

InterSystems Developer — Sat, 19 Sep 2026 16:03:24 +0000

Connecting an AI agent to a database is useful, but it immediately raises another question: what should that agent be allowed to read?

For this project, I wanted to make that decision in the application code. An agent can search patient records using a few filters, inspect an approved global, and retrieve basic information about an IRIS namespace. It cannot submit its own SQL query or select another namespace.

What is this project?

I built the MCP Data Exposure Toolkit for the InterSystems Community Bounty Program “Idea to Application” — Round 2, in response to the MCP Data Exposure Toolkit idea (DPI-I-985). My contribution is a runnable ObjectScript example covering SQL, globals, and namespace monitoring.

The source is available on GitHub. In this article, we'll run it and look at the code behind the examples.

What the example exposes

I chose synthetic healthcare records because they provide useful search criteria without putting real patient information in the repository. The project imports 500 records from the Synthetic Healthcare Patient Records Dataset by dnation on Kaggle. The persistent class MCPData.Data.Patient stores those records.

There are five tools:

ListResources: Describe approved data sources and operations
SearchPatients: Filter synthetic patient records (at most 50 rows)
ReadGlobalData: Read nodes of global ^ERRORS
LargestGlobals: Report estimated global sizes
RecentApplicationErrors: Return recent error summaries

These tools help an agent discover what data is available and provide controlled ways to access it without exposing every underlying table or global.

How AI Hub fits into the project

You can obtain the AI Hub through the Early Access Program: InterSystems AI Hub Early Access Program repository.

That repository also contains the documentation and samples I used as a starting point. This project depends on that early-access software; it is not an example for a standard IRIS image without AI Hub.

Application Architecture

The application consists of two Docker containers, each with a distinct responsibility:

iris hosts the InterSystems IRIS database, the ObjectScript tool implementations, and the native MCP service.
mcp runs the EAP iris-mcp-server binary, which exposes the MCP service to external clients using the Streamable HTTP transport.

Together, these containers separate the external MCP transport layer from the database and tool execution environment.

A request from an MCP client follows this path:

When a client sends an MCP request, Docker first forwards traffic from port 8280 on the host to port 8080 in the mcp container. The iris-mcp-server then communicates with IRIS over the Docker Compose network using the native connection on iris:1972.

Within the MCP_EXAMPLE namespace, the request passes through three ObjectScript layers. MCPData.Service.HealthExample determines which toolset is available, MCPData.ToolSet.HealthExample associates the tools with the appropriate authorization and auditing policies, and MCPData.Tools.HealthExample contains the ObjectScript methods that perform the actual operations.

This design keeps the public MCP endpoint separate from the underlying database implementation while giving clients a controlled set of tools through which they can interact with IRIS.

Running the toolkit

Clone the project and follow the repository instructions to prepare the required configuration. Once everything is configured, start the containers. After the services have finished initializing, you should be able to connect your AI agent to the MCP servers and begin using the available tools.

VS Code

Create .vscode/mcp.json in the workspace with the authorization header included:

{ 

  "servers": { 

    "health-example": { 

      "type": "http", 

      "url": "http://localhost:8280/mcp/health-example", 

      "headers": { 

        "Authorization": "Basic <generated key>" 

      } 

    } 

  } 

}

Mistral or other CLI AI agents

For Mistral Vibe, add this server to the project file .vibe/config.toml or the user file ~/.vibe/config.toml:

[[mcp_servers]] 

name = "care_data" 

transport = "streamable-http" 

url = "http://localhost:8280/mcp/health-example" 

headers = { Authorization = "Basic <generated key>" }

Start Vibe and use /mcp to inspect the connection.

A connected MCP client should discover all five tools. Here is the list in Mistral Vibe:

Python smoke test

If you don't have access to an AI agent, the repository also includes a Python smoke test. It connects directly to the MCP endpoint, verifies that all five expected tools are available, and calls each one with a small set of test inputs:

uv venv --python 3.12

source .venv/bin/activate

uv pip install -r requirements.txt

set -a

source .env

set +a

python test_mcp.py

From an ObjectScript method to an MCP tool

Now that the client is connected, let's look at the most important part of the project: how an ObjectScript method becomes an MCP tool, and how the application controls what the agent is allowed to do.

The project does not rely on a single security check. Instead, access is controlled at several layers:

the IRIS user and database role;
the authorization policy;
the tool implementation;
the ToolSet configuration; and
the audit policy.

Each layer has a different responsibility. Together, they ensure that the agent receives only the capabilities that the application explicitly exposes.

Step 1: Define the database user and role

The first layer is the IRIS security model. The endpoint user receives only the MCPDataReader role. That role grants SELECT permission on the patient table, MCPData_Data.Patient, but does not grant unrestricted access to the database. The tool still executes under an IRIS user, and that user must have permission to perform the requested operation.

In this example, the role does not give the agent permission to query arbitrary tables, and it does not turn the MCP connection into an administrator connection.

Step 2: Write the tools in ObjectScript

The actual operations are implemented in MCPData.Tools.HealthExample, which extends %AI.Tool. Its methods that should become MCP tools are declared as ClassMethods with the WebMethod keyword.

For example, ListResources starts like this:

Class MCPData.Tools.HealthExample Extends %AI.Tool

{

ClassMethod ListResources() As %DynamicObject [ WebMethod ]

{

    ...

}

}

This class contains the application logic:

SearchPatients searches the synthetic patient table;
ReadGlobalData reads the approved global;
LargestGlobals reports estimated global sizes;
RecentApplicationErrors returns recent error summaries; and
ListResources describes the available data sources and operations.

The methods are deliberately narrow. They accept filters, paths, and limits defined by the application rather than arbitrary SQL statements or arbitrary global names. For example, ReadGlobalData contains its own validation:

If path'="^ERRORS" Quit {"error":"Only ^ERRORS global is allowed"}

This prevents the method from reading a different global even if it is called with an unexpected value.

Step 3: Apply authorization before execution

The project defines MCPData.Policy.Authorization, which implements the authorization logic shared by the ToolSet.

The policy defines the tools that may be called:

Set allowlist=$LISTBUILD(


    "ListResources",


    "SearchPatients",


    "ReadGlobalData",


    "LargestGlobals",


    "RecentApplicationErrors"


)

If $LISTFIND(allowlist,name)=0 {


    Quit ..Deny(name,call,"Tool is not allowlisted: "_name)


}

This is a server-side decision in IRIS. The AI model is not trusted to decide which tools are safe, and a prompt cannot add a new capability.

The policy then validates the arguments of permitted tools. For example, it can verify that ReadGlobalData is limited to ^ERRORS or that monitoring requests remain inside the MCP_EXAMPLE namespace.

The result is a layered validation flow:

Authorization policy


    ↓


Is this tool allowed?


    ↓


Are its arguments within the approved scope?


    ↓


Tool implementation


    ↓


Are the inputs still valid before accessing data?


    ↓


IRIS database privileges


    ↓


Can the connected user perform the operation?

Step 4: Record successful and failed executions

Authorization answers the question “may this operation run?”. Auditing answers a different question: “what happened when the request was processed?”.

The project defines a second policy, MCPData.Policy.Audit, which implements %LogExecution and stores audit records in the persistent MCPData.Data.Audit class.

The policy records bounded metadata rather than copying the complete response returned to the agent.

Depending on the tool, an audit record can include:

the tool name;
the execution timestamp;
the execution status;
the duration;
the filters used for a patient search;
an error message when execution fails.

The audit policy also records failed executions. In the example below, SearchPatients received an invalid value for the diabetic filter, the request failed validation and the error was stored in StatusText field.

Step 5: Attach the policies to a ToolSet

We now have separate components for:

MCPData.Tools.HealthExample: application operations
MCPData.Policy.Authorization: permission and argument checks
MCPData.Policy.Audit: execution and result metadata

How to connect these elements now? That is the responsibility of the ToolSet MCPData.ToolSet.HealthExample.

Its definition is:

<ToolSet Name="CareOutreachData"> 


    <Description> Read-only namespace monitoring and error inspection. </Description> 


    <Policies> 


        <Authorization Class="MCPData.Policy.Authorization"/> 


        <Audit Class="MCPData.Policy.Audit"/> </Policies> 


    <Include Class="MCPData.Tools.HealthExample"/> 


</ToolSet>

We can observe this definition and see that:

The <Include> element identifies the class containing the tools.
The <Policies> section attaches the authorization and audit behavior.

The ToolSet is therefore the point where the application declares which tools that are exposed and what are the policies that govern their execution.

Step 6: Expose the ToolSet through an MCP service

The ToolSet defines what is available and which policies apply, but an MCP service still needs to expose it to clients.

In this project, that service is MCPData.Service.HealthExample:

Class MCPData.Service.HealthExample Extends %AI.MCP.Service


{


    Parameter SPECIFICATION As STRING = "MCPData.ToolSet.HealthExample";


}

The service main responsibility is to point AI Hub to the ToolSet that should be exposed through the registered MCP endpoint.

The complete structure is:

MCPData.Service.HealthExample


        ↓


selects


        ↓


MCPData.ToolSet.HealthExample


        ↓


        ├── Authorization → MCPData.Policy.Authorization


        ├── Audit         → MCPData.Policy.Audit


        └── Tools         → MCPData.Tools.HealthExample

Adding a method to the tool class does not automatically give an AI agent unrestricted access to IRIS. The method must be included in the ToolSet, the ToolSet must be exposed by the service, the authorization policy must allow the call and its arguments, and the connected IRIS user must have the required database privileges.

Security model in practice

Sensitive access is so controlled at several layers:

The endpoint user receives only the MCPDataReader role.
That role receives SELECT only on MCPData_Data.Patient. Access to a database resource does not bypass IRIS SQL privileges.
The authorization policy permits only five named tools.
The tools accept filters and approved paths, not arbitrary SQL statements or global names.
Query results, traversal depth, and monitoring results have hard limits.
Monitoring remains inside the MCP_EXAMPLE namespace and cannot inspect the full IRIS instance.
The audit policy records the tool name, status, duration, and bounded result metadata.

Testing and examples

Once connected, you can test the MCP server and verify that its access policies are enforced by sending a series of requests.

Try asking:

List all available resources and tools from the MCP server.

Find diabetic patients aged 60 or older with a Diabetes diagnosis. Return at most 10 records.

Show me the 5 largest globals in the MCP_EXAMPLE namespace.

Let's try with a few requests outside the approved scope:

Execute SELECT * FROM MCPData_Data.Patient

As expected, this request is rejected because the agent has no tool that allows it to execute arbitrary SQL queries against the database.

The same restriction applies to globals. In the following example, attempting to read a global outside the approved scope results in an access-denied error:

Conclusion

Connecting an AI agent to IRIS does not have to mean giving it general access to the database.

The approach I explored in this project is to expose a small set of operations that make sense for the application and keep the boundaries around them in code. The agent can search the patient data, inspect the resources that have been explicitly made available, and retrieve some namespace information, but it cannot turn that access into arbitrary SQL queries or unrestricted global reads.

AI Hub provides the pieces to structure this cleanly: ObjectScript methods implement the tools, the ToolSet groups them and attaches policies, authorization decides which calls and arguments are acceptable, and auditing records what actually happened. Underneath that, the normal IRIS security model still applies.

The project is available on GitHub, and I hope it provides a useful starting point for experimenting with AI Hub and building more controlled MCP interfaces on top of InterSystems IRIS.

My First Agent Studio: building and testing native IRIS agents with AI Hub and Ollama

InterSystems Developer — Wed, 16 Sep 2026 17:54:29 +0000

What does it take to go from an ObjectScript class to an agent that can call tools, use skills, and delegate part of a task?

I built My First Agent Studio to make that process easier to explore. It includes small native %AI.Agent examples, terminal demos, a dataset, and a browser UI for testing the same agents interactively. Everything except the local model service is packaged in a Docker Compose project.

The project is my contribution to the InterSystems Community Bounty Program — Round 2. It brings together two ideas:

My First Agent (End-To-End Starter): learn the SDK through a small task involving tools, skills, an external MCP server, and sub-agents.
Generic Agent Test UI for %AI.Agent: select an existing agent class and chat with it, using the behavior defined in that class.

The source is available in the My First Agent Studio repository, that contains the full setup instructions and examples

This article focuses on how the pieces work together.

What the project runs

The agents run inside InterSystems IRIS using the AI Hub while Ollama supplies the LLM. I chose Ollama so developers can try these features without a paid model API or a cloud-provider API key. You still need enough local resources to run your chosen model, in particular, use a tool-capable model for the tool and delegation examples like Qwen 3.8.

Configure an agent, skills and tools through AI HUB

An agent in AI Hub is more than a connection to an LLM. It is the point where we define which model will do the reasoning, which instructions it should follow, and which capabilities it can use while processing a request.

These capabilities are separated into two main concepts: tools and skills:

Tools give the agent something it can do, for example, query data stored in IRIS, perform a calculation, or invoke functionality exposed by an MCP server.
Skills give the agent additional instructions for how to approach a particular type of task.

The agent brings these pieces together, as in the following example:

Class Test.Agent Extends %AI.Agent

{

Parameter TOOLSETS = "Test.ToolSet.Local";

Parameter SKILLS = "Test.Skill.Poet,Test.Skill.Echo";


}

There is an important architectural distinction here: the LLM itself does not automatically have access to our IRIS data or application logic. By declaring the toolsets on the agent, we explicitly define the operations that AI Hub can make available to the model. Likewise, declaring a skill does not add another executable operation; it makes a reusable set of instructions available to the agent.

This gives us a useful separation of responsibilities:

Agent → who is reasoning and what capabilities are available
Tools → what the agent can do
Skills → how the agent should approach a task

Defining a skill

A skill is a reusable set of instructions that an agent can load when it needs to perform a particular kind of task. In AI Hub, we can define one by extending %AI.Skill.

For example, the project contains a simple Poet skill:

Class Test.Skill.Poet Extends %AI.Agent.Skill { XData SUMMARY [ MimeType="text/yaml" ] { name: talk-like-a-poet description: Transform responses into poetic verse. parameters: name: request description: The user's request to be answered in poetic form type: string required: true tags: poetry creative-writing literary-style verse rhyme } XData INSTRUCTIONS [ MimeType="text/markdown" ] { You are a poet. Respond to every request with the grace and precision of verse. }

}

There are three pieces worth noticing here:

NAME is the identifier AI Hub uses for the skill
DESCRIPTION tells the agent what the skill is intended for.
INSTRUCTIONS contains the actual instructions that are added when the skill is activated.

Defining a simple tool and a toolset

A tool gives the agent an operation it can actually execute.

A native IRIS tool can be implemented by extending %AI.Tool and exposing methods as tools. A deliberately simple example would look like this:

Class Test.Tools.Calculator Extends %AI.Tool 


{ 

Method Add( a As %Numeric, b As %Numeric ) As %Numeric [ WebMethod ] 

{ 

    Return a + b 

} 

}

However, defining the %AI.Tool class is only the first step. Tools are made available to an agent through a ToolSet.

A ToolSet acts as the container that groups related tools and gives AI Hub a unit that can be attached to an agent. For our calculator, we could define a small ToolSet such as:

Class Test.ToolSet.Local Extends %AI.ToolSet 


{ 

XData ToolSet 

{ 

<ToolSet Name="Local"> 

    <Tool Name="Calculator" 

        Class="Test.Tools.Calculator"/> 

    </ToolSet> 

} 

}

This gives us a simple hierarchy:

Agent


  │


  └── ToolSet


        │


        └── Tool


              │


              └── WebMethod

The distinction is useful as an application grows. A %AI.Tool class contains the implementation of one or more related operations, while a %AI.ToolSet describes the collection of tools that should be exposed together. The agent can then reference the ToolSet rather than having to know about every individual tool implementation:

If the model receives a question such as "What is 15 + 18?", it does not execute ObjectScript itself. AI Hub exposes the tool definition to the model, the model can decide to request Add with the appropriate arguments, AI Hub executes the ObjectScript method, and the result is returned to the model so it can continue generating its answer.

Defining an agent

Beyond tools and skills, an agent also needs to know which model it will use and how AI Hub should access it. AI Hub represents this connection through a provider.

A provider defines how AI Hub communicates with a model service. In this project we use Ollama, running locally, through its OpenAI-compatible API. This allows us to use local models while keeping the interaction with the model behind the AI Hub provider abstraction.

For example, the agent can initialize its provider as follows:

Method %OnInit() As %Status


{


  Set sc=##super()


  If $$$ISERR(sc) Quit sc

If '$ISOBJECT(..Provider) {

    Set base=$SYSTEM.Util.GetEnviron("OLLAMA_BASE_URL")

    Set ..Provider=##class(%AI.Provider).Create("openai",{"api_key":"ollama","base_url":(base)})

    Set ..Model=$SYSTEM.Util.GetEnviron("OLLAMA_MODEL")

    If ..Model="" Quit $$$ERROR($$$GeneralError,"OLLAMA_MODEL is required")

  }

If $$$ISERR(sc) Quit sc


  Quit $$$OK


}

Bringing all pieces together, we can define an agent as follows:

Class Test.Agent Extends %AI.Agent


{


Parameter TOOLSETS = "Test.ToolSet.Local";

Parameter SKILLS = "Test.Skill.Poet,Test.Skill.Echo";

Method %OnInit() As %Status

{

  Set sc=##super()

  If $$$ISERR(sc) Quit sc

If '$ISOBJECT(..Provider) {

    Set base=$SYSTEM.Util.GetEnviron("OLLAMA_BASE_URL")

    Set ..Provider=##class(%AI.Provider).Create("openai",{"api_key":"ollama","base_url":(base)})

    Set ..Model=$SYSTEM.Util.GetEnviron("OLLAMA_MODEL")

    If ..Model="" Quit $$$ERROR($$$GeneralError,"OLLAMA_MODEL is required")

  }

If $$$ISERR(sc) Quit sc

  Quit $$$OK

}

}

Connecting an external MCP server

Not every tool available to an agent has to be implemented in ObjectScript.

AI Hub can also use tools provided by an external Model Context Protocol (MCP) server. In this project I included a small Python MCP server (mcp-python-server.py), which uses FastMCP to expose Python functions through the MCP, so that the complete integration can be tested locally.

If you want to learn more about MCP servers, check my latest article: Model Context Protocol (MCP) with InterSystems IRIS - From Zero to Hero.

For example, the MCP server can expose simple arithmetic operations:

from fastmcp import FastMCP

mcp = FastMCP("HealthcareStatistics")

@mcp.tool()


def add_numbers(first: float, second: float) -> float:


    """Add two numbers."""


    return first + second

On the IRIS side, because this example uses an MCP server over stdio, the Python script must be available in the same runtime environment as IRIS. In this project, mcp-python-server.py is copied into the IRIS container, where AI Hub can start it using the IRIS Python interpreter. We then connect that MCP server to AI Hub through a %AI.ToolSet.

/// External Python MCP toolset for deterministic arithmetic and synthetic-data statistics..


Class Test.ToolSet.StatisticsMCP Extends %AI.ToolSet


{


XData Definition [ MimeType=application/xml ]


{


<ToolSet Name="StatisticsMCP">


  <Description>Deterministic arithmetic and synthetic-data statistics from an external Python MCP process.</Description>


  <MCP Name="Statistics">


    <Stdio Executable="/usr/irissys/bin/irispython"


           Args="/home/irisowner/dev/mcp-python-server.py"/>


  </MCP>


</ToolSet>


}


}

This is still a normal %AI.ToolSet, so it can be attached to an agent in the same way as the other ToolSets. The only difference is that, instead of declaring a native ObjectScript tool implementation, the ToolSet contains an <MCP> definition, while Executable points to the Python interpreter available inside the IRIS container and Args identifies the Python MCP server that should be executed.

Starting a conversation: sessions, monitoring and chat

Once the agent has been configured, the next step is to actually use it. AI Hub separates the definition of an agent from an individual conversation with that agent.

First we create and initialize the agent:

Set agent = ##class(Test.Agent).%New()


Set sc = agent.%Init()

The Test.Agent class tells AI Hub which model, instructions, skills and ToolSets are available. It does not, however, represent a particular conversation. For that we create a session:

Set session = agent.CreateSession()

A session represents the state of one conversation with the agent. This distinction becomes important as soon as we want to send more than one message.

For example:

Set response = agent.Run(session,"Find the diabetic patients",10)


Do ##class(%AI.System).RenderMarkdown(response)

Run() starts the agent loop for the supplied prompt. AI Hub sends the conversation and available capabilities to the model and processes the response. If the model requests a tool, AI Hub executes it, adds the tool result to the conversation and lets the model continue.

The result is therefore not necessarily produced by a single LLM request:

User prompt


    │


    ▼


   LLM


    │


    ├── requests a tool


    │         │


    │         ▼


    │      AI Hub


    │         │


    │         ▼


    │    tool executes


    │         │


    ◄─────────┘


    │


    ▼


   LLM


    │


    ▼


Final response

This loop is one of the reasons for passing a maximum number of iterations to Run(). In the example above, 10 gives the agent enough room to make intermediate tool calls without allowing the execution loop to continue indefinitely.

Continuing the same conversation

The session becomes particularly useful when we call the agent again.

Set response = agent.Run(session,"Now summarize their main characteristics",10)

Because we pass the same session, this is a continuation of the previous conversation. The model can work with the context already accumulated in that session rather than treating the second prompt as an unrelated request.

If instead we create another session:

Set anotherSession = agent.CreateSession()

we have started a new conversation, even though both sessions use the same Test.Agent.

The distinction can therefore be summarized as:

Test.Agent


    │


    ├── Session A


    │     ├── User message


    │     ├── Tool call


    │     ├── Tool result


    │     └── Assistant response


    │


    └── Session B


          └── Independent conversation

So, we can say that the agent defines the capabilities; the session holds the conversation using those capabilities.

Seeing what the agent is doing with a monitor

When developing an agent, looking only at the final response tells us only part of the story. We also want to understand how the agent arrived at that response: how many iterations were required, whether tools were called, and how much work was performed before the final answer was produced.

In this project I defined a specific monitor class:

Class Test.DemoMonitor Extends %RegisteredObject


{


Method OnIterationStart(iteration As %Integer, maxIterations As %Integer, session As %AI.Agent.Session)


{


  Write !,"[agent iteration ",iteration,"/",maxIterations,"]",!


}

Method OnIterationComplete(iteration As %Integer, response As %AI.LLM.Response, session As %AI.Agent.Session)

{

  Set stats=session.GetStats()

  Set totalToolCalls=stats.%Get("total_tool_calls",0)

  Set totalToolDuration=stats.%Get("total_tool_duration_ms",0)

  Write "Token usage: ",response.Usage.%ToJSON(),!

  Write "Total tool calls: ",totalToolCalls," | Total tool duration (ms): ",totalToolDuration,!

}

}

This use it we can create a monitor and pass it to Run():

Set monitor = ##class(%AI.Agent.Monitor).%New()


Set response = agent.Run(session,"Find diabetic patients and summarize the cohort",10,monitor)

The monitor lets us observe the execution of the agent loop instead of seeing only the final response, for example:

[agent iteration 1/5] 


Token usage: {"completion_tokens":81,"prompt_tokens":1267} 


Total tool calls: 2

Monitoring the execution helps us distinguish between these cases.

Inspecting the session statistics

The monitor shows what is happening during execution. AI Hub also gives us a second view through the statistics stored on the session:

Write "Parent stats: ",session.GetStats().%ToJSON(),!

Because the same session is reused for several prompts, GetStats() gives us the accumulated statistics for that conversation rather than only information about the last prompt.

Delegating work to sub-agents

So far our agent has handled a request by interacting with the model and calling tools. AI Hub also allows an agent to delegate part of its work to another agent.

This is useful when a task benefits from a separate role, set of instructions, or context. Instead of asking the main agent to perform every step itself, it can create a sub-agent, give it a specific task, wait for its response, and then continue its own execution.

In this project I use two forms of delegation:

Predefined sub-agents, where the specialist role and instructions are defined in advance.
Generic delegation, where the parent creates a specialist dynamically for a task.

In both cases, I use the same pattern as for the rest of the project: delegation is exposed as a tool (agent as a tool pattern). The parent agent sees a normal tool call, while the implementation behind that tool creates and runs a %AI.Agent.SubAgent.

Defining a predefined sub-agent

A predefined sub-agent is useful when we already know that part of our workflow should be handled by a specialist. For example, we may want a reviewer, validator, summarizer, or domain-specific analyst whose role and instructions are controlled by the application rather than generated dynamically by the parent agent.

A simplified delegation tool looks like this:

Class MyApp.SubAgents.Reviewer Extends %AI.Tool


{


Parameter DESCRIPTION = "Delegate content to a specialized child agent for review.";

Property ParentAgent As %AI.Agent;

Method %OnNew(parentAgent As %AI.Agent = "") As %Status [ Private ]

{

  If $ISOBJECT(parentAgent) {

    Set ..ParentAgent=parentAgent

  }

  Quit $$$OK

}

/// Review a task from the parent agent.


///


/// Args:


///     task: task to be reviwed


Method Review(task As %String) As %String [ WebMethod ]


{


  Set output = ""


  Try {


    If '$ISOBJECT(..ParentAgent) {


      $$$ThrowStatus($$$ERROR($$$AICoreIncompleteInitialization,$CLASSNAME(),"ParentAgent"))


    }


    Write "["..%ClassName()"] called as tool",!


    Set prompt = "You are a specialist reviewer. Review only the supplied content and provide a concise assessment."


    Set subagent=##class(%AI.Agent.SubAgent).Create(..ParentAgent,prompt,"")


    Set subagent.ToolManager=##class(%AI.ToolMgr).%New()


    Set session=subagent.CreateSession()


    Set response=subagent.Run(session,task)


    Set output = response.Content


  } Catch exception {


    Set sc = exception.AsStatus()


    Set output = "Review failed: "_$SYSTEM.Status.GetErrorText(sc)


  }


  Return output


}


}

From AI Hub's point of view, Review() is still simply a tool operation because it is exposed as a [ WebMethod ].

The child agent must be created in the context of the parent agent. For this reason, the delegation tool keeps a reference to its parent:

Property ParentAgent As %AI.Agent;

Generic Delegation

Predefined delegation works well when we already know which specialist we want to call. In other cases, however, the required specialist depends on the current task.

For this reason, the project also includes a generic delegation tool (that can be found in the EAP GitHub as well). The parent agent does not call a fixed reviewer or validator. Instead, it asks the delegation tool to create a child agent for a role described at runtime:

/// Delegate Task Tool - Demonstrates Recursive Language Model (RLM) pattern


/// This tool creates a sub-agent to handle a delegated task


Class Test.Tools.DelegateTasks Extends %AI.Tool


{

/// Tool description for LLM

Parameter DESCRIPTION = "Delegate a task to a specialized sub-agent. Use this when the current task has distinct subtasks that would benefit from focused attention.";

/// Parent agent reference (set by the agent using this tool)

Property ParentAgent As %AI.Agent;

/// Create the delegation tool already bound to its parent agent.

Method %OnNew(parentAgent As %AI.Agent = "") As %Status [ Private ]

{

    If $ISOBJECT(parentAgent) {

        Set ..ParentAgent = parentAgent

    }

    Quit $$$OK

}

/// Delegate a task to a specialized sub-agent

///

/// Use this when the current task has distinct subtasks that would benefit from focused attention.

/// The sub-agent will have its own conversation context and can use the same tools as the parent.

///

/// Parameters:

/// - task: The task to delegate to the sub-agent (required)

/// - specialistRole: The role/expertise of the sub-agent (e.g., "code reviewer", "writer", "data analyst")

/// - context: Additional context to pass to the sub-agent

Method Execute(task As %String, specialistRole As %String = "", context As %String = "") As %String [ WebMethod ]

{

    Try {

        If '$ISOBJECT(..ParentAgent) {

            $$$ThrowStatus($$$ERROR($$$AICoreIncompleteInitialization, $CLASSNAME(), "ParentAgent"))

        }

    Write !, "[Delegation] Creating sub-agent with role '"_specialistRole_"' for task: ", $EXTRACT(task, 1, 50), "...", !

    // Build system prompt for sub-agent
    Set systemPrompt = "You are a helpful assistant"
    If specialistRole '= "" {
        Set systemPrompt = "You are a " _ specialistRole _ " assistant"
    }
    If context '= "" {
        Set systemPrompt = systemPrompt _ ". Context: " _ context
    }

    Write "[Delegation] Sub-agent role: ", systemPrompt, !

    // Create sub-agent using CreateSubAgent API
    // This will use safe_block_on internally to handle nested runtime contexts
    Set subagent = ##class(%AI.Agent.SubAgent).Create(
        ..ParentAgent,
        systemPrompt,
        "" // No additional config for now
    )

    Write "[Delegation] Sub-agent created, executing task...", !

    // Run the sub-agent on the delegated task
    Set session = subagent.CreateSession()
    Set response = subagent.Run(session, task)

    Write "[Delegation] Sub-agent completed", !
    Write "[Delegation] Response length: ", $LENGTH(response.Content), " characters", !

    Return response.Content

} Catch ex {
    Return "Error in delegation: " _ ex.DisplayString()
}


}

}

From the parent model's perspective, Execute() is simply another tool. The interesting part is that specialistRole is not fixed when the application is written.

For example, the parent could request:

specialistRole = "mental-math teacher"


task = "Explain why multiplication by zero always returns zero."

In another conversation, the same tool could be called with:

specialistRole = "technical editor"


task = "Review this explanation for clarity."

Both calls use the same delegation implementation, but they create child agents with different responsibilities.

Registering a generic delegation tool without a Toolset

If we do not want to create a specific Toolset containing sub-agents or delegation tool, we can register a single generic tool directly when the parent agent is initialized:

Method %OnInit() As %Status


{


  ......


  Do things


  ......


  Set sc=..RegisterGenericDelegateTool()


  If $$$ISERR(sc) Quit sc


  Quit $$$OK


}

Method RegisterGenericDelegateTool()


{


  Set delegateTool=##class(Test.Tools.DelegateTasks).%New($THIS)


  Do ..ToolManager.AddTool(delegateTool)


}

Start the environment

Now that we have covered the main building blocks, it is time to run the project and see them working together.

A first conversation in ObjectScript

Before opening the browser, it is useful to run one conversation directly. This makes the distinction between the agent and its session explicit.

Open IRIS terminal and create a bundled simple chat agent:

Set agent=##class(Test.Agents.SimpleAgent).%New()


Set sc=agent.%Init()


Do $SYSTEM.Status.DisplayError(sc)

%Init() prepares the agent configuration and, in this project, also registers the generic and predefined delegation tools with the current agent instance.

Set session=agent.CreateSession()


Set maxIterations=5


Set monitor=##class(Test.DemoMonitor).%New()

CreateSession() creates the conversation context.

We can run the first request:

Set prompt="I have three tasks to finish today. Can you help me decide which one to do first?"


Set response=agent.Run(session,prompt,maxIterations,monitor)


Do ##class(%AI.System).RenderMarkdown(response.Content)

Run() submits a prompt, with an iteration limit and the demo monitor.

The returned response exposes its text through Content.

Keep the same session for a follow-up:

Set prompt="One task has a deadline today; the other two can wait until Friday."


Set response=agent.Run(session,prompt,maxIterations,monitor)


Do ##class(%AI.System).RenderMarkdown(response.Content)

You can also register a skill from the terminal:

Set sc=agent.UseSkill("Test.Skill.Caveman")


Set prompt="Load the Caveman skill and explain your previous answer briefly."


Set response=agent.Run(session,prompt,maxIterations,monitor)


Write session.ActiveSkills.%ToJSON(),!

UseSkill() makes the skill available to the agent programmatically, while session.ActiveSkills lets us inspect which skills are active in the current conversation. This is useful when we want the application, rather than the model, to decide that a particular behavior should be applied.

We can inspect the tools exposed to the model at any time:

Write agent.ToolManager.%Discover().%ToJSON(),!

The next step is to use delegation. Suppose we want a sub-agent to review the previous response:

Set prompt="Call Execute to delegate review of this result to a concise technical reviewer. Use specialistRole='technical reviewer'. Task: "_response.Content


Set response=agent.Run(session,prompt,maxIterations,monitor)


Do ##class(%AI.System).RenderMarkdown(response.Content)

After these interactions, we can inspect the sub-agents created by the parent:

Write "Spawned sub-agents: ",agent.SubAgents.Count(),!

For i=1:1:agent.SubAgents.Count() {


    Write !,agent.SubAgents.GetAt(i).SystemPrompt,!


}

This is particularly useful with generic delegation because the system prompt shows the role that was assigned to each dynamically created specialist.

Testing agents in the browser

Once the terminal flow is clear, the browser UI gives us a more convenient way to repeat the same experiments interactively.

The important point is that the browser does not define another kind of agent. The agent classes still live in ObjectScript, run inside IRIS, and use the same tools, skills, sessions, and delegation logic described earlier.

Opening the Agent Studio

Run the docker compose and open UI at http://localhost:5174

The initial workspace is divided into two main areas:

Sidebar
- Recent chats
- Configuration
- Selected Agent
Main chat

Selecting an existing `%AI.Agent`

The agent selector is populated from the agent classes installed in IRIS. The frontend receives from the backend the concrete %AI.Agent subclasses and their metadata such as description, example prompt, ToolSets and skills.

Choosing the model

The model selector follows a similar approach. Instead of maintaining a predefined list of model names, the UI queries the configured Ollama instance and presents the models that are currently installed.

The agent logic remains unchanged while only the model performing the reasoning changes.

Starting a conversation

Once the agent and model are selected, we can send a prompt exactly as we did from the terminal.

The browser sends the request to IRIS, where the selected agent is instantiated and the normal AI Hub execution loop runs, and finally it displays the result of the same agent execution we could inspect from ObjectScript.

Loading a skill from the UI

Skills can also be controlled directly from the browser. New conversations start without active skills. Selecting a skill and clicking Load sends an explicit request to IRIS to activate that skill for the conversation.

The UI then marks the skill as active and changes the available action to Unload.

An example of a skill usage

After the skill has been loaded, we can use it:

Reopening conversations

The UI stores conversations and their AI Hub session state in IRIS. The Recent chats panel lets us reopen a previous conversation instead of starting over.

Conclusion

The goal of this project is to make the different pieces of AI Hub easier to explore together rather than as isolated features.

Starting from a native %AI.Agent class, we can configure a model provider, expose ObjectScript and MCP tools, add reusable skills, maintain conversations through sessions, inspect execution statistics, and delegate work to specialized sub-agents.

The project is intentionally a playground rather than a production architecture. The AI Hub APIs used here are part of the Early Access preview and may evolve, but the examples provide a practical starting point for experimenting with the SDK and understanding how its main building blocks relate to one another.

If you are exploring AI Hub, clone the repository, try the bundled agents, inspect their available tools, change a skill, experiment with delegation, and then add your own %AI.Agent class. That is where the project becomes most useful: not as a finished application, but as a small environment for learning what you can build next.

Working with Dynamic Objects in IRIS: doubts that only come up when you need to deploy by tomorrow morning and it's 11 P.M.

InterSystems Developer — Sun, 30 Aug 2026 07:37:14 +0000

If you have spent any time on the Developer Community, you have seen the many questions return in different costumes: How do I turn a persistent object into JSON? How do I loop over a JSON payload whose shape I don't know? Why does Required do nothing on my %DynamicArray property? Why is my date coming back as 31390?

Noticing that, we decided to write an article summarizing all the questions that come with something that the documentation alone couldn't provide: practice.

Let's start with the foundation

InterSystems IRIS gives you two classes for schema-less data: %DynamicObject and %DynamicArray. Both inherit from %DynamicAbstractObject, and instances of either are called dynamic entities. They map cleanly onto JSON: an object is a set of key/value pairs, an array is an ordered list. Unlike a persistent or registered class, a dynamic object keeps no predefined list of valid property names — every string key is legal, and you add or remove members at runtime.

The most pleasant part is the literal syntax, which will look familiar to anyone coming from JavaScript:

Set person = {"name":"Ada","active":true,"roles":["admin","dev"]}
Set scores = [90, 85, 77]

You can also build them field by field. %Set() returns the entity it modified, so calls chain:

Set obj = {}.%Set("a",1).%Set("b",2) // now obj is {"a":1,"b":2}

Do scores.%Push(100)                 // now scores is [90, 85, 77, 100]

Set last = scores.%Pop()             // now scores is [90, 85, 77] and last is 100

%Push() and %Pop() exist only on arrays, but everything else works on both. To turn text into an entity, use %FromJSON() and to serialize back, use %ToJSON():

Set jsonString = "{""field"": ""value""}"
Set obj = {}.%FromJSON(jsonString) // now obj is {"field": "value"}

Write obj.%ToJSON()                // this outputs "{""field"": ""value""}"

%FromJSON() also accepts a stream, and %FromJSONFile() reads straight from a filename (note: a filename string, rather than a %File object — a common trip-up).

Iterating over structure you don't control

When a payload arrives from another system, you often don't know how many elements it has or what they're called. Don't reach for a for loop by index. Dynamic arrays can be sparse, which means that an element can exist positionally without ever having been assigned, and a for loop will happily hand you those empty slots. The correct tool is %GetIterator(), which returns a %Iterator.Object or %Iterator.Array, driven by %GetNext():

Set iter = obj.%GetIterator()

While iter.%GetNext(.key, .value, .type) 
{
    Write !, key, " = ", value, " (", type, ")"
}

%GetNext() skips unassigned elements automatically, which is exactly why it is preferred. For an object, key is the property name. For an array, key is the index. To walk a nested structure, recurse whenever $IsObject(value) is true, as that will return true for both sub-objects and sub-arrays.

That third argument, .type, is easy to ignore, but worth understanding. When present it does two useful things. First, it returns the element's original JSON datatype as a string. Second — and this is the practical part — it changes the conversion rules so you avoid <MAXSTRING> errors: a very long JSON string is handed back as a read-only stream object instead of being force-fit into an ObjectScript string, and JSON numbers are returned in their original textual form rather than being coerced. If you're processing arbitrary external JSON, passing .type is cheap insurance.

Type discovery inside a dynamic entity

Because dynamic entities are untyped containers, IRIS gives you tools to interrogate them. %GetTypeOf(key) reports what a value actually is: number, string, boolean, object, array, null, oref, or unassigned:

Set a = [1, "test", true, {"v":1}, [1,2,3]]

// the indexes are:

//       0,      1,    2,       3,       4

Write a.%GetTypeOf(2)   // true: boolean


Write a.%GetTypeOf(3)   // {"v":1}: object


Write a.%GetTypeOf(9)   // unassigned - it finishes at index 4

This matters because ObjectScript flattens JSON's richer type system on the way in. JSON true, false, and null all become ObjectScript-friendly values 1, 0, and "" when you read them with dot syntax or %Get(). If you need to tell a genuine null apart from an empty string apart from a key that was never set, %GetTypeOf() is the reliable discriminator. There is also %IsDefined(), but it returns false for unassigned members and true for both "" and null.

The date gotcha

Type flattening is behind one of the community's recurring puzzles. Export a persistent object whose DOB is 1926-12-11 and you may see "DOB":31390 in the result — that 31390 is the internal $HOROLOG day count, not a corrupted value. The same logic bites the other direction in dynamic SQL: if you pass a query a literal like '1926-12-11' and get zero rows, it's usually because the column expects $HOROLOG internal format. The fix is to convert on the way in with $ZDATEH("1926-12-11", 3). Whenever a date crosses the boundary between JSON, SQL, and stored objects, ask which representation each side expects.

Two things both called "array"

Here is a distinction that quietly causes bugs. %DynamicArray is a positional list, indexed from 0. But ObjectScript also has typed collection properties, and the array of collection is not a positional array at all — it's a dictionary (a keyed map). Compare:

Property Tags As array of %String;   // a dictionary: key -> value

Property Notes As list of %String;   // an ordered, positional list

You access an array of collection by key, not by position:

Do obj.Tags.SetAt("high", "priority")

Write obj.Tags.GetAt("priority")     // high

Set key = ""


For 


{ 


    Set value = obj.Tags.GetNext(.key)  Quit:key=""


    Write !, key, ": ", value 


}

When a class using %JSON.Adapter serializes an array of property, it comes out as a JSON object{"priority":"high"}, whereas a list of comes out as a JSON array ["high"]. So "typed array" can mean two very different shapes on the wire depending on which collection you chose. If you want positional JSON, use list of (or a %DynamicArray); if you genuinely want a keyed lookup, array of is your dictionary.

Bridging persistent objects and dynamic objects

A frequent need is converting a stored object into a free-form dynamic one — for instance, to trim fields before returning them from a REST method. If your class extends %JSON.Adapter, the clean, non-deprecated path is a two-step that fits on one line:

Set sc = person.%JSONExportToString(.json)


Set dynObj = {}.%FromJSON(json)

(For large objects, swap in %JSONExportToStream() so you never hit the string length limit.) Two alternatives are worth knowing. Embedded SQL's JSON_OBJECT() lets you cherry-pick and rename columns when you only want a subset:

&sql(SELECT JSON_OBJECT('name':Name,'dob':DOB) INTO :json WHERE ID = 1)


Set dynObj = {}.%FromJSON(json)

And going the other way, %JSONImport() populates a persistent object from a dynamic one.

Where dynamic freedom ends: validation

Finally, the caveat that surprises people building JSON request validators. The Required property keyword works for literals, collections, streams, and object-valued properties — but it is silently ignored for %DynamicArray and %DynamicObject properties. The reason is mechanical: the generated getter defaults these to [] and {}, so even assigning "" gets overwritten with a non-empty default, and %ValidateObject() never sees a missing value. If you need to enforce presence or shape on dynamic properties, don't rely on Required — implement a %OnValidateObject() callback and check them yourself:

Method %OnValidateObject() As %Status


{


    If ..fieldOptions.%Size() = 0 


    {


        Return $$ERROR($$GeneralError, "fieldOptions is required")


    }

Return $$OK


}

Choosing well

Dynamic entities are the right tool when structure is unknown, external, or genuinely fluid — parsing payloads, assembling responses, staging data. Typed persistent classes remain the right tool when you want the database, indexes, and validation to enforce a contract. Most real systems use both, meeting at the %JSON.Adapter boundary. Keep three habits and you'll avoid the classic pitfalls: iterate with %GetNext() rather than by index, reach for %GetTypeOf() whenever a value's type actually matters, and remember that array of is a dictionary, not a list.

Disclaimer: this article has been written by human hands, but reviewed with Claude AI for (1) enhancing my English (not my first language) and (2) reminding me of topics I hadn't covered in the initial versions. The search and studies for sources and practice were all made by a human (me :D), and the agent used to review is trained only on my own articles, so that it copies my tone without plagiarism, with respect to my fellow community members. The final revision was done completely without AI.

InterSystems for dummies – IRIS Vector Search (Part II)

InterSystems Developer — Sun, 30 Aug 2026 07:30:53 +0000

After an extensive math lesson, we are going to put our new knowledge into practice and create one of the best context-related databases.

Get your magnifying glasses and hats ready, because Vector Holmes is back.

Vector Calculation

To calculate the vector associated with a text, image, or sound, we will use a Python library called sentence-transformers, which allows us to transform content into a vector.
To implement this, we should create the following function:

ClassMethod Embedding(Text) [ Language = python ]
{
    from sentence_transformers import SentenceTransformer

    model_name = 'sentence-transformers/all-MiniLM-L6-v2'

    # Cache in global variables of the embedded Python module (persistent per process).
    global _cached_embedding_model
    if '_cached_embedding_model' not in globals():
        _cached_embedding_model = SentenceTransformer(model_name)

    vector = _cached_embedding_model.encode(
        [Text],
        normalize_embeddings=True,
        convert_to_numpy=True,
        show_progress_bar=False
    )

    return str(vector[0].tolist())
}

This method "vectorizes" the content of our text using a pre-trained library called "all-MiniLM-L6-v2". However, if you wish, you can modify it and utilize your own trained library.

First Steps

Note: To access the terminal of our Docker instance, use the following command:
Docker-compose exec iris iris session iris

Let's use an example of a vectorized search. For this, we will utilize a table called St.vectorsearch.Feeling that has the following fields:

Field	Type	Description
Text	%String	Text about how I feel
Value	%Integer	Identifier of my feeling (See attached table)
Vector	%Vector	Text vector value

You can create the data by running the following command:

Do ##class(St.vectorsearch.Data).Init()

Next, we are going to load the sentiment data from the /opt/irisbuild/data/training.csv directory, using the Populate command from the St.vectorsearch.Data class.

USER>do ##class(St.vectorsearch.Data).Populate()
Truncating table St_vectorsearch.Feeling
Preparing to load data from file training.csv
Loading data from file training.csv
Total records loaded: 2000
Calculating vectors for records...
Processing 496 of 2000

Be patient, since it will create a vector for each record, and it might take quite a while.

Note: Populate will initialize a data model of 2000 records. There is another file with 5410 records if you want more information in the data model. If you wish to work with that one, use the PopulateFull() command instead.

The values of feelings are as follows:

Feeling	Value
sadness	0
joy	1
love	2
anger	3
fear	4

For example:

“I left with my bouquet of red and yellow tulips under my arm, feeling slightly more optimistic than when I arrived.” It has a value of 1 (Joy).

“I can’t walk into a shop anywhere where I do not feel comfortable.” It has a value of 4 (Fear).

If we use this function to create vectors, the first text we pass will return the next vector:

.034666668623685836791, .012147962115705013276, .020678628236055374146, 
.043785430490970611572, .030321707949042320251, -.0081106657162308692932, 
-.028869708999991416931, -.059950094670057296752, .067945346236228942871, 
-.070874534547328948974, -.060159780085086822509, .016239311546087265014, 
-.034665744751691818237, -.011642633005976676941, .080176420509815216064, 
………
.0099751437082886695861, .0098187308758497238159, .00016082286310847848653, .013545278459787368774, -.0049553057178854942321, .054155148565769195556, .025806473568081855773, -.038503900170326232911, .039657127112150192261, 
-.073851920664310455322, -.070615962147712707519, .066068030893802642822, 
-.082378372550010681152, -.043505564332008361816, -.0054294602014124393463

Note: The vector value has been reduced to keep the text from being too long; the vector actually has 384 values.

If we look for another cheerful text when creating the vector, it will give us the following value.

Example:

“Today, I’m very happy.”

[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 0.08268272876739502, 0.004975424613803625, -0.062008269131183624, 
……
0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]

This data does not make sense right now because we are not going to make a value-by-value comparison. That means we are not going to look for a record with exactly the same value as the vector because each vector is different. For that, we will use the formulas explained in the first part.

We are going to use the following SQL commands to see which vectors are the closest to the vector we have calculated.

Dot Product Search

As we indicated in the first part, the dot product search tells us how aligned two different vectors are. That means the closer it is to 1, the closer, or rather more similar, two vectors are.

To perform our search, we will use the condition “VECTOR_DOT_PRODUCT” that compares two vectors to determine their alignment:

SELECT TOP 5 Text, Value
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

This search gives us the following results:

So… “Today, I’m very happy” returns most results with a value of 1, joy.

But… what is the percentage of proximity our text has regarding the rest of the retrieved values?

We can find that out by comparing it with the current vector and displaying the value in a percentage format.

SELECT TOP 5 Text, Value, TO_CHAR(VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
 -0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) * 100 , '990.99%') AS Percentage
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_DOT_PRODUCT(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

This search gives us the following results:

The percentage of similarity to the most matching text is 65%. Our mind knows that, among all the texts, the meaning of “Today, I’m very happy” is a feeling of joy, meaning it should be closer to 100% comparing to the text “I am feeling so happy”

Cosine Similarity Search

The cosine similarity search is performed using the cosine of the angle between the vectors being compared.

If we want to perform vector search with cosine similarity, we would have to utilize the condition “VECTOR_COSINE”, just as we have previously done it:

SELECT TOP 5 Text, Value, TO_CHAR(VECTOR_COSINE(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
 -0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) * 100 , '990.99%') AS Percentage
 FROM St_vectorsearch.Feeling
ORDER BY VECTOR_COSINE(Vector, TO_VECTOR('[-0.007015716750174761, 0.05171322077512741, 0.0045058708637952805, -0.04008815810084343, 0.009171668440103531, -0.04867621883749962, 
......
-0.036987580358982086, 0.027985544875264168, 0.05382953956723213, 0.031146947294473648, -0.011256292462348938, 0.005441852379590273]', float)) DESC

Oh… surprise!! It gave us back the same results:

As mentioned in the first part, this type of search is more advisable for comparing more than one parameter, such as movie genre, lead actor, etc. In other words, this is how the movie recommendation system of Netflix or HBO works.

Does it Support Multiple Languages?

What will happen if, instead of using the text “Today, I’m very happy,” we do it in Spanish?

“Hoy, estoy muy feliz.”

The created vector (reducing the text for obvious reasons) will resemble the following:

[-0.020053215324878693, 0.08766797184944153, 0.04118209332227707, 0.027171766385436058, -0.026769554242491722, -0.045022152364254,
…..
 0.038541924208402634, 0.018977241590619087, 0.03448185324668884, 0.10012426972389221, 0.08426760882139206, -0.09713190793991089]

And if we use it to perform the search as we did previously, we will get the result below:

We got a combination of love (2), fear (4), and joy (1), when the meaning is identical to the English text.

This rather diverse result appeared because the word "feliz" is closer to "feel" than "happy".

As you have noticed, the creation of vectors is closer to the phonetics of the texts than to their meanings.

I recommend testing the same text in different languages.

Here you have the result of searching for it in French “Aujourd'hui, je suis très heureux”:

Therefore, if we want to use this system to search for text in a document that we have fully "tokenized", it can be solved in a very simple way.

In a nutshell, we are going to change the model we used to create the token to the model paraphrase-multilingual-MiniLM-L12-v2:

model_name = 'sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2'

Therefore, if we modify this line in the Embedding method, we can use multilingual support in data retrieval.

This is the result of using this model with the search in Spanish:

Now, if you create a language-based token, why does it internally "translate" "Feliz" to "Happy"? Yes, I have used double quotation marks around "translate" because it is not a context-based translation like in any other online dictionary. It interprets the word by creating a token, which can cause some confusion when similar words are used.

For example, in Spanish, the word "tiempo" is the same word for the meaning of the word "time" or "weather", so the token for this word could be confusing. Fortunately, the token is not based on a single word, but on a set of words that make up the phrase. It means that the rest of the phrase's context helps us create a token much closer to the final one. Therefore, our vector seems to have translated the text we want to search for.

Case Study

Very important note: I encountered some difficulties developing these practical examples. When trying to create a vector from an IRIS production environment, the process would completely freeze.

The solution to using the St.Vectorsearch.Vector.Embedding method without any issues was to download the model locally instead of querying the online model for each request. When using the model locally, invoking this class from production did not require an Internet connection to download the model, making the vector creation process much faster.

I have created a small demo to show how a text, entered from a form, is "tokenized" and searched in the database to find the five closest results.

http://localhost:52773/csp/user/feeling.html

Note: Make sure production is running. To do this, log in to the Management Portal and start production if it was stopped.

The first time you ask about a feeling, it may take a little while, because it caches the model for future queries.

This website invokes an API running on IRIS that converts the text into a vector. Then it invokes the SQL search as I mentioned previously.

It performs a search for the 5 closest phrases to the calculated vector. Then the website displays those results and indicates which sentiment is repeated more often, showing the arithmetic mean of the most repeated results.

Can We Have More Than One Element to Create a Vector?

In the sentiment example, the phrase included information we used to create a search vector. However, what do we need if we have more than one column to perform the search?

If we want someone to recommend a similar movie to the one we have already seen, the result will depend on many factors. It could be related to the movie release year (because you like older films) or the genre (comedy, drama, science fiction), etc.

In this case, we will create a vector based on the text that includes the fields we want to index. This way, we will have all the fields we wish to use for our query:

Note: The order of the data is important because if we are interested in films from the same year and genre, those columns will have the most weight in the index.

If we are looking for recommendations based on the plot, genre, director, and actors, that would be the order:

“Overview: [Overview]. Genre: [Genre]. Directed by [Director] and starring by [Star1], [Star2], [Star3] and [Star4]. Movie year [Year]. Ranking: [Rating]."

To understand the age classifications better, I will show you the meaning of those values:

Certificate	Description	Comment
A	A is Adults (equivalent to the USA R).	Rating in the UK
UA	UA is for ages 12 and up with parental supervision.	Rating in the UK
U	U is Universal (for everyone).	Rating in the UK
PG-13	PG-13 (Parents Strongly Cautioned): Strong warning for parents. Some materials may be inappropriate for children under the age of 13.	Current (MPA)
R	R (Restricted): Those under 17 years of age must be accompanied by a parent or adult guardian because it contains adult material.	Current (MPA)
PG	PG (Parental Guidance Suggested): Parental guidance is suggested. Some content may not be suitable for young children.	Current (MPA)
G	G (General Audiences): For all audiences.	Current (MPA)
PASSED	The film complies with the strict moral standards of the time to be shown in cinemas.	They were used between the 1930s and 1960s under the famous Hays Code.
TV-14	TV-14: Parents strongly advised. Contains material that many parents would consider inappropriate for children under the age of 14.	TV Parental Guidelines
16	Not recommended for children under 16 years old.	Typical numerical age classification of European or Latin American systems.
TV-MA	It may be inappropriate for viewers under the age of 17
due to graphic violence, explicit sexual activity, or crude language.	TV Parental Guidelines
UNRATED	Not classified.
GP	GP: It was a temporary code used in the early 1970s. It was equivalent to what we know today as PG (Parental Guidance Suggestion).
APPROVED	The film complies with the strict moral standards of the time in order to be shown in cinemas.	They were used between the 1930s and 1960s under the famous Hays Code.
TV-PG	Recommended parental guidance.	TV Parental Guidelines
U/A	U is Universal (for everyone).	Rating in the UK

In the same way that we initialized the table and loaded the data from the Feeling table, we employ the following commands:

Note: To access the terminal of our Docker instance, use the following command:
Docker-compose exec iris iris session iris

Do ##class(St.vectorsearch.Data).InitMovie()

Next, we will load the movie data from the /opt/irisbuild/data/imdb_top_1000.csv directory, using the PopulateMovie command from the St.vectorsearch.Data class.

USER>do ##class(St.Vectorsearch.Data).PopulateMovie()
Truncating table St_Vectorsearch.Movie
Preparing to load data from file imdb_top_1000.csv
Loading data from file imdb_top_1000.csv
Total records loaded: 999
Calculating vectors for records...
Processing 116 of 999

Note: During the demo initialization process in Docker, the test data loading operations are already performed.

In each movie, we have initialized the vector value using the phrase we have created with the different fields. I encourage everyone to make appropriate changes to the St.Vectorsearch.Data.PopulateMovie class to align with your priorities better.

As I mentioned in the first part, there is another vector approximation method (by cosine similarity), which allows us to search vectors that form the closest angle (those that are closest in the same direction).

That is why it is the best system to use if you wish to find data recommendations.

To use this, we will need the condition “VECTOR_COSINE”, which can tell us the closest angles to the indicated vector.

SELECT TOP 5 ID, Link, Title, Year
FROM St_Vectorsearch.Movie 
WHERE Title <> ? 
ORDER BY VECTOR_COSINE(Vector, TO_VECTOR(?, float)) DESC

In this case, we are going to look for movies that approximate the angle of the vector associated with the film we have, without, of course, having it recommend itself.

You can access the demo via the link below:

http://localhost:52773/csp/user/movies.html

In this case, the recommended films are similar to 1988's "Akira," although I would personally put "Kôkaku Kidôtai," also known as "Ghost in the Shell," first. They are similar because they are both animated films. Mental note: I still need to watch Papurika...

So, that is all for now. You have everything you need to work with vector indices, including practical examples and an application you can use for your experiments.

Please leave any suggestions or ideas you have in the comments, including practical ways to implement this knowledge, etc...

See you at the next “InterSystems for Dummies”!

InterSystems for dummies – IRIS Vector Search (Part I)

InterSystems Developer — Sun, 23 Aug 2026 15:35:13 +0000

You may have heard the term "Vector Search" before. Do not worry, though; it is not "Vector Holmes" investigating a crime from 221B Baker Street.

So, let’s explain, step by step, how to tackle vector data searches.

:::pagebreak:::

What Are Vectors?

In mathematics, a vector is an arrow that indicates a quantity with three elements: its value (magnitude), its direction, and its course. It is used to represent things that cannot be described with a single number, such as velocity, force, or displacement.

Magnitude: It is the length of the arrow, which indicates the numerical value of the magnitude.
Direction: It is the straight line on which the vector acts (it can be horizontal, vertical, or diagonal).
Course: Indicates where the arrow points (it is the endpoint of the direction).
Point of application: It is the starting point of the vector.

Two vectors are equal when they have the same magnitude (modulus), direction, and course. It means that regardless of their position in space, if their components are identical, they are the same vector.

Two vectors are opposite when they have the same magnitude and the same direction, but opposite course, meaning they are facing away from each other.

In a two-dimensional system, a vector is represented by its start (origin) and end (destination) coordinates on the X and Y axes.

These two vectors are represented as follows:

{(1,1),(5,3)}

{(2,4),(7,5)}

In a three-dimensional space, coordinates include the X, Y, and Z axes.

What Do Mathematical Vectors Have to Do with Vector Search?

Vector search is a method of searching known in numerical representations as vectors. It is similar to the vectors we have seen previously, but with the origin point being point 0 in Euclidean space.

Instead of looking for precise keyword matches, this technique examines similarities between vectors, as previously explained, enabling more accurate, semantically and contextually meaningful results, even if the words in the query are not exactly the same.

For example, "Iron Maiden," "Van Halen," and "Scorpions" are all the names of heavy metal bands. If we convert these names into tokens to create vectors, their coordinates will be similar but not identical. There will be slight differences in magnitude and direction. Therefore, they will be “orbiting” in the same “band” zone.

Conversely, "Bob Dylan" or "Genesis" will point in the opposite direction. They are still musical groups, but their styles do not have "the same direction".[

If we perform a traditional search, we must use the exact same word, which is"Music group". It will encompass all groups. However, if we want to look for a specific genre, for instance, "thrash rock", we will not know how to differentiate Metallica from Dire Straits.

In contrast, if we perform a vector search, it would locate these groups based on their proximity in both genre and musical style, showing that Metallica and Slayer are similar.

Are Vectors Really “Arrows”?

In computer science, a vector is a data structure that includes an array of numbers. In our case, these vectors store a digital summary of the dataset to which they have been applied. Consider it a summary or a digital fingerprint.

Images can also be analyzed for similarities. If you had to develop an application to compare two images, how would you do it? If you simply compared every pixel of one image with every pixel of the other, you would only find images that are identical in resolution, color, encoding, and other aspects.
However, if you could examine the images and generate vector embeddings of the content, you would be able to compare them and identify similarities. In the case of images, a vector embedding explains the content of each image and then allows for comparison.
This constitutes a much more robust method for discovering similarities between images.

A vector, speaking in computer science terms, would have a representation similar to the one below

{10,-4,6,34,0,-35,67,203,466,4,356,3,-53,-3,0}

It will be like indicating the vector's final position only, since the vector's origin is point 0.

Vector Search Algorithms

The data, which includes images, texts, audio, etc., is encoded in numerical vectors called "Embeddings". These values have varying dimensions depending on how they are encoded. The more dimensions our vector has, the more specific its definition will be, and the better it can be grouped.

Vector Similarity Searches:

We can use different types of metrics in vector similarity searches, each with its own advantages and disadvantages. The appropriate metric will depend on the data type and the application.

Euclidean Distance:

To determine if two vectors are close, we should measure the “Euclidean distance”, which is the straight-line length between two points in Euclidean space. It equals the square root of the sum of the squared differences between the point coordinates:

In an n-dimensional space, it is measured as the difference between each of the dimensions squared.

Since the value is smaller, we can deduce that the final vector points are closer to each other than the initial ones.

If we compare it with other vectors in the same space, those with the smallest values will be approximate vectors.

The distance between v1 and v3 is less than the distance between v1 and v2.

It is important to know how to calculate the distance between two points because it will be used later for measuring the magnitude of a vector.

Magnitude of a Vector

It is the distance from the vector base to its endpoint. In our case, all vectors originate at point 0, so the magnitude of a vector would be calculated using the following formula:

The data above gives us the following magnitudes of the vectors:

V1 = 5,83095189

V2 = 10

V3 = 5,6568542

Dot Product

The dot product (also called the scalar product) is an operation between two vectors that results in a real number (a scalar). It is one of the most important tools in mathematics and physics because it tells us how "aligned" two vectors are.

It is calculated by multiplying the sum of the coordinates in each dimension of the vectors to be compared.

The information from our example gives us the dot product values as follows:

Dot product v1v2 = (3 * 6) + (5 * 8) = 58

Dot product v2v3 = (6 * 4) + (8 * 4) = 56

Dot product v1v3 = (3 * 4) + (5 * 4) = 32

The larger the dot product, the greater the similarity between these two vectors.

We can say that v1 and v2 are very similar.

Cosine Similarity

This search method allows us to look for vectors not by the distance between their points, but by the angle they form.

The cosine similarity measures the orientation between two vectors in a multidimensional space, ignoring their magnitudes. It is calculated by dividing the dot product of two vectors (A) and (B) by the product of their magnitudes, resulting in a value between -1 and 1.

It is calculated using the following formula:

Following the previous example,

Similarity of the cosine of v1 and v2:
Point product v1 y v2 = (3 * 6) + (5 *8) = 18 + 40 = 58
Magnitude v1 = 5,83095189
Magnitude v2 = 10
Cosine(v1, v2) = 58 / 58,309 = 0,9947

Similarity of the cosine of v2 and v3
Point product v2 y v3 = (6 * 4) + (8 * 4) = 56
Magnitude v2 = 10
Magnitude v3 = 5,6568542
Cosine(v2, v3) = 58 / 58,309 = 0,9899

Similarity of the cosine of v1 y v3
Point product v1 y v3 = (3 * 4) + (5 * 4) = 32
Magnitude v1 = 5,83095189
Magnitude v3 = 5,6568542
Cosine(v1, v3) = 32 / 32,984 = 0,9701

We can confirm that v1 and v2 are more similar than v2 and v3, and v1 and v3.

Note: In the case of multidimensional vectors, we should perform the sum of each of the dimensions.

This approach returns vectors with similar directions, so it can help us find resemblances to make recommendations (this is how Netflix or HBO works).

In the example of music groups, we can start by searching for "thrash rock" bands. Then we can suggest other groups not categorized as thrash rock but within the heavy metal genre. That is, we start by listening to Metallica and, through suggestions, move on to Van Halen. Now you understand why Netflix might suggest watching "The Nightmare Before Christmas" after seeing "Hotel Transylvania”.

As Foghorn Leghorn once said, “It’s math, son!! The numbers don’t lie.”

How Do We Use This Mathematical Knowledge In Vector Search?

First, we need to convert our data (text, images, etc.) into a vector, as we have indicated before.

However, vectors do not create themselves. That means it is not enough just to give them a random value defined by us.

LLM models allow us to create the dot product and use cosine similarity to perform searches within InterSystems IRIS. Euclidean search is not implemented, but could be applied with Python libraries.

Some people have already thought about this because it will allow us to associate correct vectors based on the text context… Yet, I will explain this in the next article.

Note: I am sorry for the math lesson. Yet, I had to explain how it works first to help you better understand the "search magic".

The Gaia Planetarium: A Full-Stack Embedded Python Project

InterSystems Developer — Sun, 23 Aug 2026 15:26:23 +0000

If you are a regular on the developer community, you may have seen some recent posts about the InterSystems First Employee Programming competition. The challenge is simple — transform some Gaia Epoch Photometry data, calculate the percentage change of flux (between the maximum and minimum values), and output a list of the stars with a percentage change of greater than 100.

Now while this was a fun challenge, but I felt there was something missing: a lack of scope for creativity. After all, we are looking at stars! How can something as magical as the night sky be distilled down to a CSV files of IDs and flux values?

So I decided to do something different with my main entry, and visualise stars the way they should be viewed — in the night sky above us. Let's take a look at the Gaia planetarium:

Project Design

The first question was what information is needed to plot the stars in the nights sky? Now its easy to plot a point on earth - you just need a longitude and latitude. For stars, you also need two locating values, Right Ascension (RA) and Declination (Dec). Of course, it gets more complex if you want to know where they are in location to the earth, but that was solved later.

These values aren't in the Photometry datasets, instead being found in the Gaia source table, which can helpfully be queried using a Python library called astroquery. This made the decision to use Python a no-brainer.

So I decided upon the following stack:

- PyProd production
- Ingests Photometry data files
- Calculates output (and adds to csv file)
- Queries the Gaia Source table to get the location for each source ID.

- Flask Web Application (hosted using IRIS WSGI hosting):
- Query data from IRIS tables using Embedded Python
- Create REST Service to send data to the front-end

- Front-end UI with HTML/CSS/JS

Now, before going through the implementation in a bit more detail, I will detail one issue I found. The Gaia photometry data is heavy. Each zipped file is around 15.5MB, which doesn't sound like that much, until you realise there is >3000 of them. What's more, each of these files maps a small portion of the sky in immense detail, whereas I am much more interested in covering the sky with stars that could be visible to the naked-eye.

I therefore decided to add separate production components which can just query the Gaia source data, ordered by brightness to add the most visible stars to my planetarium. I've still included the photometry dataset and, because it is a production, its easy to throw more files into the watched directory to add them into map. The challenge results are available as an overlay, and may not be visible depending on whether the small portion of the sky that the photometry data maps is overhead.

I also added star data from a different dataset — Hipparcos, because many of the most visible stars overload the Gaia sensor, so are not available in the Gaia dataset. Including Hipparcos stars was important for viewing constellations to my planetarium. I also added constellation data from Stellarium to visualise the constellations in the sky.

IRIS Implementation

PyProd

I've recently written about PyProd for another example project, so I am going to skip the technical details in this case. One comment I will make though — it was really nice to be able to build a production in Python because I required a few steps which are super easy to do in Python, and not so easy in ObjectScript. The key example of this was querying the Gaia dataset directly with the astroquery.gaia library.

I also used this project as a moment to road test a new PyProd agent skill. This way, as soon as I start using PyProd, my agent can read the skill and see exact patterns of how it should be working with PyProd. A version of this skill is now available in the iris-agentic-dev skill library

The Web App: Flask

Its not super well known that IRIS can host WSGI applications, lets face it, I didn't even know what a WSGI application was when I first heard this! Web-Server Gateway Interface is a Python standard for running web applications. Some of the most popular Python web application frameworks, including Flask and Django, run on WSGI.

Flask is a lightweight framework for developing REST APIs. It has pretty simple syntax, where you define a function with a decorator to make it an REST endpoint. Combining this with Embedded Python makes it easy to get data from IRIS. For example, a simplified version of the endpoint which collects stars from the IRIS table is as follows:

from flask import Flask, request

import iris # Embedded python IRIS import 

app = Flask(name, static_folder="/home/irisowner/dev/src/skymap/static)


  
  
  Endpoint to access stars from the Database


@app.route("/api/stars", methods=["GET"])

def get_stars() 

    # SQL Query 

    query = """

        SELECT TOP 1000 SourceId, Ra, DecDeg, PhotGMeanMag 

        FROM "Gaia.SourceLocation"

        """

# Execute query 
rows = iris.sql.exec(query)

# Collect results
output = [] 
for row in rows: 
    output.append({
      "source_id": row[0],
        "ra"     : row[1],
        "dec"    : row[2],
        "mag"    : row[3]
    })

# Return results
return output

And we can also use this to activate a PyProd adapterless Business Service:

from intersystems_pyprod import director 


  
  
  POST endpoint


@app.route("/api/more-stars", method=["POST"])

def add_stars(): 

    # Get the info from the post request

    n_stars = int(request.args.get("n_stars"))

# Create Business Service
status, service = director.create_business_service("Gaia.StarCatalogService")

# Activate Business Service
service.process_input(n_stars)

Flask hosting

WSGI applications can be hosted through the Management Portal at System -> Security -> Applications:

But I wanted to do this programatically through Embedded Python. Using the Security.Applications.Create() function required me passing an IRIS array by reference into the function, which can be achieved using an iris.arrayref(<python dict>):

import iris
# Define settings 
props = iris.arrayref({
            'Type': 2,
            'NameSpace': 'USER',
            'WSGIAppLocation': '/home/irisowner/dev/src', # Path to flask project
            'WSGIAppName': 'skymap.server', # FolderName.FileName (without .py)
            'WSGICallable': 'app',
            'WSGIDebug': 0,
            'WSGIType': 1,
            'AutheEnabled': 64,
            'Enabled': 1,
            'Description': 'Gaia sky map Flask/WSGI application',
            "DispatchClass":"%SYS.Python.WSGI", # Needed for WSGI hosting
            "Path":"/home/irisowner/dev/src", # Path to flask project
            "WSGIDebug": 1, # Refresh when the code changes
            "MatchRoles": ":%All" # Security roles
        })

# Create Web App
sc = iris.Security.Applications.Create('/skymap', props)

An easy point to miss here if you normally create WSGI applications through the management portal: you need to set the DispatchClass to "%SYS.Python.WSGI".

Front-end

Unlike a pure Python framework like Streamlit, Flask include a Python front-end framework, instead relying on building a front-end with HTML/CSS/JavaScript (or some front-end framework).

I'm going to skip most of the details on this because it was largely a question of me describing clearly what I wanted, and getting some AI generated code as a result.

It is pure HTML/JS/CSS, which I personally am a big fan of. I know it has limits, but sometimes I think starting with a front-end framework overcomplicates things.

The Front end is hosted in the Flask app through a static route:

from flask import Flask, jsonify, request, send_from_directory

STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
app = Flask(__name__, static_folder=STATIC_DIR)

@app.get("/")
def index():
        return send_from_directory(STATIC_DIR, "index.html")

The only other thing to mention is that Cross Origin Resource Sharing is also handled from Flask

@app.after_request
def add_cors(response):
        response.headers["Access-Control-Allow-Origin"] = "*"
        return response

Conclusion

As I mentioned at the start of this article, this project started out as a competition entry for the Employee Programming Competition. However, it quickly spiralled into something else, once I realised the limitations of only using the Gaia Photometry Data. It has become a Python Full Stack Application, which integrates multiple data sources (Gaia, Hipparcus and files of constellations and star names).

To be clear though, it still does what was asked by the competition, and it even plots it as a bright yellow/orange/red patch (coloured by magnitude of flux change) of sky which is covered by the Photometry data. So if you've made it this far, please consider voting for my planetarium in the community vote!

I hope you've enjoyed reading about this Embedded Python project as much as I've enjoyed making it!

iris-agentic-dev -- Give Your AI a Live Connection to IRIS, Part 1: The Problem, the Tool, and Getting Started

InterSystems Developer — Thu, 13 Aug 2026 09:35:07 +0000

Part 1 of a series. Part 2 covers the full tool catalog. Part 3 covers ObjectScript skills. Part 4 covers benchmarking and measuring what actually improves.

The Problem Hiding in the Comments

Thomas Mazur's post "Frogs, Chickens, AI, and VS Code" on VS Code productivity — Peacock, scoped workspace files, Copilot Agent mode — drew a sharper problem in the comments. Pietro Di Leo and Mike.W pointed out that when you work server-side in VS Code, the isfs:// workspace most production IRIS shops use, Copilot can only see the files open in your editor. It cannot index the virtual filesystem. On a mature IRIS application with thousands of classes, the AI works through a keyhole.

John Murray pointed people at a project I've been building — iris-agentic-dev — and noted no Developer Community article existed for it yet. So here it is: why the problem exists, how the tool addresses it, and how to get it running in about five minutes.

Why the AI Can't See Your Namespace

When you open an isfs:// workspace, your IRIS classes live on the server, not on disk. The VS Code ObjectScript extension streams them to you on demand via the Atelier API — open a class, it fetches it; save it, it writes back. This works beautifully for editing.

AI assistants such as Copilot work differently. They need a picture of the code around the file you're editing. Who calls this method? What inherits from this class? What other code touches this global? On a local project, the assistant can scan the files to answer those questions. An isfs:// workspace materializes files only when you open them, so there is nothing complete to scan.

For a new project with a handful of classes, that may be tolerable. For a production IRIS system — ten thousand classes, Ensemble productions, custom %Library subclasses, business logic accumulated across years of development — the AI becomes nearly useless for the hard questions. It can help you write a new method if you paste in the surrounding context yourself. It cannot help you understand the system.

Give the AI a different kind of connection, one that can ask IRIS directly instead of crawling the disk.

What iris-agentic-dev Is

iris-agentic-dev is an MCP server — a background process that gives AI assistants a set of tools they can call to interact with a live IRIS instance. It works with GitHub Copilot (via the VS Code extension), Claude Code, Cursor, and OpenCode. The IRIS instance can run natively on Windows or Linux, or in Docker.

Once configured, the MCP server's tools are available directly from chat. VS Code 1.99 and later support MCP for Copilot Agent mode; Claude Code and OpenCode have supported it since launch.

iris-agentic-dev connects to IRIS through the same Atelier REST API used by the ObjectScript extension. The assistant can then:

Search the entire namespace — full-text, regex, by category, without opening anything
Compile classes and get errors back with line numbers
Run ObjectScript and see the output
Execute SQL queries against any namespace
Introspect class definitions — properties, methods, parameters, inheritance chains
Inspect Ensemble productions — which items are running, what's wired to what, message bodies, business rule logic, and drift between the running config and source control
Run unit tests and report results
Debug — map INT line numbers back to original source lines, pull error logs

Part 2 covers the complete tool catalog. Instead of guessing from a few open tabs, the assistant can ask IRIS about the namespace itself.

---

Built With the Community

I started the project after running into this limitation repeatedly in my own IRIS work. Community contributions have shaped it since — often from the same people who show up more than once. John Murray, who pointed people at this project in the Frogs and Chickens thread, also built the Server Manager authentication integration you'll use in Step 2 below: instead of typing credentials into a config file, the MCP server reads them straight from the OS keychain through the same AuthenticationProvider the Server Manager extension itself uses. Dorian TETU has contributed fixes across search accuracy, source control elicitation, and surgical-edit diffs.

The project is open source under the intersystems-community GitHub organization. Contributions and bug reports are welcome, including "It doesn't work on my setup."

Getting Started: VS Code + GitHub Copilot

If you already use VS Code with the InterSystems ObjectScript extension, this is the fastest path.

Prerequisites: VS Code, GitHub Copilot subscription, and the InterSystems ObjectScript extension (which you almost certainly already have).

Step 1 — Install the VS Code extension

Search for iris-agentic-dev in the VS Code Marketplace and install it. On first activation, the extension locates or downloads the MCP server binary: if you already have it on PATH (e.g. via brew install iris-agentic-dev), it uses that; otherwise it downloads the right binary for your platform automatically. Either way, it registers itself with Copilot — no manual wiring required.

The iris-agentic-dev tool set appears in Copilot's Agent mode after installation.

Step 2 — Verify the connection

Open Copilot Chat and switch to Agent mode. Ask:

"Call check_config and show me the result."

You should see your IRIS connection details — host, port, namespace, Atelier API version. If the InterSystems Server Manager extension is installed, iris-agentic-dev finds your server configuration and retrieves credentials from the OS keychain automatically. The VS Code extension follows the active objectscript.conn, so developers with several Server Manager entries keep using the connection selected for that workspace. When running the MCP server outside the VS Code extension, set IRIS_SERVER_NAME to the corresponding key from intersystems.servers if more than one server is configured. The check_config result shows which connection is active and which other servers were detected.

check_config confirms the IRIS host, port, namespace, and connection source Copilot is using.

Step 3 — Ask something that requires the whole namespace

Now try a question that would be difficult to answer from open tabs alone:

"Search for all classes in this namespace that extend %Persistent. How many are there?"

"What are the properties and methods on MyApp.SomeClass?"

"Compile MyApp.*.cls and show me any errors."

None of these requires you to open the relevant files first. The assistant gets the answers from IRIS.

Getting Started: Claude Code

Install the binary (Mac):

brew tap intersystems-community/tap
brew install iris-agentic-dev

Or download directly from the releases page for Mac Intel, Linux, or Windows.

Configure the connection. Create ~/.iris-agentic-dev.toml:

host = "localhost"
web_port = 52773
username = "_SYSTEM"
password = "SYS"
namespace = "USER"

Register with Claude Code:

claude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp

Then verify:

> Call check_config and show me the result.

Example: How iris-agentic-dev tools support analyzing an IRIS Interoperability application

Here is a real exchange against the irisdemo-demo-readmission production — a health interop demo that processes hospital discharge events and scores patients for readmission risk.

"How does an ADT A03 discharge message flow through this production?"

Step 1: find what's compiled.

iris_symbols("IRISDemo.*")
→ 31 classes: BO.*, BP.*, BS.*, DTL.*, Util.*, and more

Key classes: IRISDemo.BP.ReadmissionRisk.Process, IRISDemo.DTL.HL7Discharge, IRISDemo.DTL.HL7Update, IRISDemo.HISHL7v2FileFeedRoutingRule.

Step 2: find the router's rule.

extract_message_map_routing("IRISDemo.HISHL7v2FileFeedRoutingRule")
→ NOT_FOUND — Ens.Rule.Definition, not a routing table class

Ens.Rule.Definition classes hold routing logic in XData. The tool can't map that structure, so read the class source directly:

iris_doc("IRISDemo.HISHL7v2FileFeedRoutingRule.cls") → XData rules:
  Rule 1: docName=ADT_A01 or ADT_A08  → transform DTL.HL7Update, target Readmission Risk Process
  Rule 2: docName=ADT_A03             → transform DTL.HL7Update, target Readmission Risk Process

A03 discharges go through IRISDemo.DTL.HL7Update, which stamps UpdateMessageType="A03" on the request — that field is what lets the business process branch differently for discharges vs. admits.

Step 3: map the business process.

extract_message_map_routing("IRISDemo.BP.ReadmissionRisk.Process")
→ kind: bpl, 4 outbound calls:
    Update Encounter          → LACE SOAP Operation
    Calculate Risk with LACE  → LACE SOAP Operation
    Calculate Risk with ML    → Readmission ML Model Consumer
    EMR Readmission Update    → HisDB Encounter Update Operation

Step 4: get the full step tree.

docs_introspect("IRISDemo.BP.ReadmissionRisk.Process") → xdata_flow:
  Call:  Update Encounter          → LACE SOAP Operation
  Call:  Calculate Risk with LACE  → LACE SOAP Operation
  Call:  Calculate Risk with ML    → Readmission ML Model Consumer
  Call:  EMR Readmission Update    → HisDB Encounter Update Operation  [async]
  If:    Discharge OK?
           (request.UpdateMessageType = "A03") && (context.UpdateEncounterResult = 1)
    If:  Risk Alert?
           (context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15)
      assign: Compose Alert Message
      Call:  Add Patient to Risk Program  → Care Team  [async]
      Call:  Alert Care Team              → Risk Alert Email Operation
      sync:  Follow up SLA 2 days
      If:    No follow up?  (synctimedout)

The session also flagged that IRISDemo.DTL.HL7Discharge exists and maps 9 HL7 fields to a DischargeRequest — but the routing rule never sends A03 through it. Dead code, spotted without opening a file.

The full exchange — every tool call, response, and reasoning step — is in this GitHub Gist.

In four steps the assistant answered the question: A03 discharges hit the router, get transformed into an UpdateEncounterRequest with the trigger event stamped as the branch signal, and the business process runs LACE and ML risk scoring in sequence — alerting the care team and starting a 2-day follow-up if either score exceeds the threshold. No files were open. Everything came from IRIS.

What's in the Next Parts

Part 2 — The Tools: A practical walkthrough of the tool catalog: what each tool does, when to use it, and which IRIS-specific problems it solves. The search, introspection, and Ensemble tools are especially useful for questions that open editor buffers cannot answer.

Part 3 — Skills: A live connection does not fix an AI model's weak grasp of ObjectScript: subtle syntax differences, %Status propagation, $$$ macros, and COS-specific idioms that are scarce in general training data. Skills are short instruction files that target these weaknesses. On my 22-task ObjectScript repair suite, a 205-word checklist called objectscript-review took the pass rate from 73% to 100% against Claude Sonnet 4.6 — a single run on a small public suite, with all the caveats that implies. Part 3 covers what the skills do; Part 4 covers how much to trust the number.

Part 4 — Benchmarking: How the benchmark harness works, how to run it, and what the numbers mean. That includes where skills help, where they have no effect, and at least one that appears to hurt performance when loaded globally — more instructions are not always better. It also covers the limits of a suite this size: contamination risk from public tasks, single-run variance, and why a lift measured on one model says little about another.

AI-Assisted Development on IRIS: Beginner tips and guidance

InterSystems Developer — Thu, 13 Aug 2026 09:32:54 +0000

This article provides an AI agent-agnostic view of developing with AI coding assistants, with an IRIS-specific focus. This guidance is based on standards that can be used whether you use Claude Code, GitHub Copilot, Codex, or one of the other coding agents. As such, it doesn't cover setup instructions. Instead, it covers key concepts and how they have improved the performance of AI for my work.

Hi everyone, I wanted to share some thoughts, advice and examples of using AI for IRIS development. Before starting though, I have lots of opinions on AI, far more than I can fit in this article. I am not an AI evangelist. I started as a skeptic and still hold on to a lot of skepticism, along with an intense dislike for slop. I am, however, an absolute believer in the ability of these tools if you can learn to use them correctly.

I use AI regularly, but make a conscious effort to follow, understand and review any code that isn't a toy project or personal tool. My opinions on AI coding softened dramatically when I first tried vibe-coding for a personal tool (a presentation app which displays web-pages directly alongside slides) and was amazed by success. I recommend next time you think "I wish I had an application/vs code extension/tool which does x", try asking an AI agent for it.

Of course, the correct approach will vary for each user and each scenario. People working with sensitive data in production database should be far more careful about using AI than I am creating demo projects in isolated containers. As such, I can't claim my experience will be the same as anyone else, but I do suggest taking some time to explore approaches that might work for you.

"I tried using AI to write ObjectScript but it hallucinated all the methods"

AI agents have improved a lot, even since I started at InterSystems in September 2025. Developer circles often talk about the November inflection point where the release of Claude Opus 4.5 and GPT-5.2 changed the game with agentic coding. Suddenly models had the ability (and context window) to chain together tool calls to develop, reason, and fix bugs. These models have been incrementally improving with each release cycle since and may well continue to do so.

In this time, ObjectScript coding from LLMs has improved dramatically. I recommend you re-evaluate any belief about the ability of AI in coding matters that pre-dates these releases, and try again with one of the latest (and most powerful) models in a coding harness.

Improving your agent's skillset

Frontier AI models (and their lesser counterparts) have a pretty good very good knowledge of most matters, essentially because they have consumed the entire internet. It is true that their ObjectScript knowledge is often less than other languages, primarily because there is less ObjectScript available on the web than other languages.

This is where agent skills come in.

Skills are markdown files with some YAML front-matter, it's (basically) that simple. In the metadata, you give the skill a name, and a description, which crucially should say when an agent should use the skill. The name and description are loaded into the agent's context window, and when they need the specific guidance the skill provides, they can activate the skill and use the markdown contents. This is great for specific knowledge, or advice, for example on a lesser used part of a coding language they are a bit ropey at.

iris-agentic-dev, the MCP server that @tomd recently shared with the community includes a skill library. One of the skills, @timothy.Leavitt's objectscript-review, only includes a checklist of the 10 most common ObjectScript errors, and yet dramatically includes benchmark performance. This skill obviously required extensive ObjectScript knowledge in the first place, alongside experience reviewing agent written ObjectScript to know the most common mistakes. But the benefit is the agent should now correct these mistakes itself, and the future code it produces will be better as a result.

Skills are reusable pockets of information. If you have a repeatable task an agent struggles with, let it struggle the first time, then when it gets to the right answer (maybe with your guidance) say "write a skill that covers the mistakes you've made here". I recommend reviewing and editing the generated skills carefully because agents tend to put in project specific information which doesn't generalise. But as long as the problems can be generalisable, the solutions can be reusable. Next time, the agents won't make the same mistakes (...probably, there's no certainty with non-deterministic models).

Improving your agent's toolset

Skills are great to prevent repeated errors, but they don't help the agent actually do things for you. This is where tools come in. Tools, in the context of AI agents, are functions which the agent can call using structured (JSON) responses. The standard protocol for adding tools to agents is the Model Context Protocol (MCP). This has been written about extensively on the community including articles by me, Pietro Di Leo and Tom. I will also once again plug this great intro video from InterSystems President Don Woodlock.

MCP servers can be used to expose business logic to external agents or connectors (see my introduction to MCP servers in AI Hub). However, to date at least, MCP servers are most commonly used as developer tools. This is the context I want to discuss here.

If you tell an LLM to write some ObjectScript using an obscure class, it will likely hallucinate how a statistically average version of how the class might look. Instead, if you give an agent with access to a tool to search the class reference documentation, it will likely look up the proper syntax before writing. If you give it access to an ObjectScript shell (or execution environment), it may even test the function syntax before writing.

Try to imagine you were asked to code something from scratch using an obscure library and think about what you would need to do a good job. It would probably include documentation and a feedback loop to test the code you've written. Coding agents require exactly the same.

This is the value of MCP servers. Agents can autonomously search for proper syntax, test functions and code, and try to compile classes. When they see an error, they can read the error trace and investigate. They can execute more code to find the bugs, and search for other classes for proper syntax.

iris-agentic-dev is an MCP server which provides many, many tools to do different functions in IRIS. If you are a system administrator managing multiple IRIS servers, it has tools to view and edit the roles, servers and logs. If you are a developer, the tools to execute ObjectScript, search existing classes or read production logs, might be more relevant to you.

Customisation

Many people have their own golden rules for using AI coding agents, like "tests are essential", "create and review specification docs before touching code", "always review the output", "anything intended to be read by a human should be written by a human". These are all valid (and good advice), but for me, there's one golden rule that is more important.

Customisation is key.

For agents to be useful for your use case, they need to be customised to your use case. Let's look at some ways to do this.

Skills

Skills are a great way to customise. I have a library of agent skills to cover my own preferences. For example I have skills make code more readable, to write check scripts for interactive tutorials, and to use PyProd to write productions in Python (this one has made it into iris-agentic-dev's skill library).

I also have skills which other's have recommended, e.g. obra/superpowers, that have been customised to my preferences. They are just markdown files after all. Take the bits you like, and add/remove sections to get the instructions right for your work.

iris-agentic-dev

For iris-agentic-dev, this customisation may come in the form of restricting tools that aren't generally useful to you with the IRIS_DISABLED_TOOLS argument. For example, I have turned off server-side source control tools because I always do source control on the client side, and otherwise agents see it and think that means they should use it. I've also turned off the system admin tools because 95% of my IRIS usage is done with SuperUser so role management is totally not required for my use case. For others, managing different users and using server-side source control will be incredibly valuable whereas giving an agent execution power might be too risky, so they might make the opposite decisions.

I've also created custom iris-agentic-dev instructions in the form of a skill, with the description "Use this skill when you want to connect to a running IRIS instance". This skill includes the line VS CODE COMPILES THE CLASS ON SAVE, YOU DO NOT NEED TO MANUALLY COMPILE CLASSES, because I've watched agents go in circles trying to copy a file into a docker container then compile it, only to find out its "suspiciously" already up-to-date. This use case-specific customisation informed by watching agents proves valuable in the long term.

AGENTS.MD

Finally, you can also customise your agents with AGENTS.MD (or CLAUDE.MD) files, either at a project root or the global config. The contents of these are automatically sent to the agent with every new conversation.

Project AGENTS.MD are good for project specific information, e.g. This project does x, the source files are in ./src/package, port 52773 on IRIS is mapped to port 62783. That way, each new conversation I have with an agent doesn't require an introduction, and the agent doesn't have to search through the whole project to find the relevant files.

Global versions are for rules you want the agent always to abide, for example my global CLAUDE.MD includes NEVER USE EMOJIS ANYWHERE NOT EVEN TICK MARKS about 3 times. I've also included some more useful guidance, e.g. Give a (very brief) explanation of tool calls or series of tool calls to ensure I can follow what you are trying to do.

Conclusions

For any customisation, you need to try using agents. See what works and what doesn't, what an agent is good at and bad at. If an agent does something you don't like, add instructions not to do it again in one of the places mentioned above.

Finally, in order to customise, you also need to know what your use case requires. You need to learn with the agent and know what you are directing the agent to do. There are times when letting the agent run autonomously is incredibly powerful, but in general, I prefer keeping a close eye on what the agent is doing, learning from the outputs, and course-correcting when it inevitably does something stupid.

Final notes

This article has been long, opinionated, and maybe a touch ramble-y, but I hope it has been interesting to some readers. If you would like to hear more on these topics, on opinionated guidance for using AI-assisted coding, or just need help getting started with skills, agents or iris-agentic-dev, feel free to reach out in the comments.

Building a Pure Python Healthcare Interoperability Production with PyProd and the openFDA API

InterSystems Developer — Fri, 31 Jul 2026 20:45:47 +0000

Hi Developers!

In my previous article, Electric Utility PyProd, we built a simple interoperability production that processed CSV files from a local directory using the PyProd framework. While that example introduced the basic building blocks of a production implemented entirely in Python, real-world interoperability solutions often need to communicate with external systems.

In this article, we'll build a more advanced production that retrieves healthcare data from the public openFDA Drug Adverse Event API, analyzes the returned data, and stores healthcare analytics in InterSystems IRIS.

Along the way, we'll see how to:

call an external REST API from a PyProd Inbound Adapter
work with large JSON payloads efficiently
perform batch-level healthcare analytics
persist the results in an IRIS SQL table
implement an entire interoperability production using only Python

Setting up

Clone the repository:

git clone https://github.com/Gra-ach/openfda-healthcare-pyprod.git

cd openfda-healthcare-pyprod

Start the container:

docker-compose up --build -d

Once the container is running, load the production:

intersystems_pyprod src/healthcare-openfda-pyprod/openfda_adverse_events.py

Step 1 – Create the Inbound Adapter

Unlike the previous example, this production doesn't wait for files to appear in a directory. Instead, the custom OpenFDAInboundAdapter periodically connects to the public openFDA Drug Adverse Event API. Rather than querying the same medication every time, the adapter rotates through a configurable list of common medications:

ASPIRIN

IBUPROFEN

ACETAMINOPHEN

NAPROXEN

LORATADINE

Each polling cycle:

selects the next medication
builds the REST query
downloads the latest adverse-event reports
saves the response as a JSON file
sends a lightweight production message

Saving the payload to disk instead of passing it through the production keeps messages small and avoids IRIS string-size limitations.

class OpenFDAInboundAdapter(InboundAdapter):
    api_base_url: str = IRISProperty(
        description="openFDA Drug Adverse Event API URL",
        settings="API Settings"
    )
    result_limit: int = IRISProperty(
        description="Number of records to retrieve per poll",
        settings="API Settings"
    )
    api_key: str = IRISProperty(
        description="Optional openFDA API key",
        settings="API Settings"
    )
    payload_dir: str = IRISProperty(
        description="Directory where raw openFDA JSON payloads are saved",
        settings="File Settings"
    )
    medication_names: str = IRISProperty(
        description="Comma-separated medication names to rotate through",
        settings="API Settings"
    )  

    def on_task(self):
        os.makedirs(self.payload_dir, exist_ok=True)

        meds = [
            med.strip().upper()
            for med in str(self.medication_names or "").split(",")
                if med.strip()
        ]

        if not meds:
            meds = ["ASPIRIN", "IBUPROFEN", "ACETAMINOPHEN", "NAPROXEN", "LORATADINE"]

        state_file = f"{OPENFDA_ROOT}/last_med_index.txt"
        os.makedirs(OPENFDA_ROOT, exist_ok=True)

        try:
            with open(state_file, "r", encoding="utf-8") as f:
                last_index = int(f.read().strip())
        except Exception:
            last_index = -1

        next_index = (last_index + 1) % len(meds)
        selected_med = meds[next_index]

        with open(state_file, "w", encoding="utf-8") as f:
            f.write(str(next_index))

        search_query = f'patient.drug.medicinalproduct:"{selected_med}"'

        params = {
            "search": search_query,
            "limit": int(self.result_limit or 50),
            "sort": "receiptdate:desc",
        }
        if self.api_key:
            params["api_key"] = self.api_key

        url = f"{self.api_base_url}?{urllib.parse.urlencode(params)}"
        pulled_at = datetime.utcnow().isoformat(timespec="seconds")
        safe_timestamp = pulled_at.replace(":", "").replace("-", "")
        pulled_at = pulled_at.replace("T", " ")
        payload_file_path = os.path.join(
            self.payload_dir,
            f"openfda_adverse_events_{safe_timestamp}.json",
        )

        IRISLog.Info(f"Calling openFDA API: {url}")

        try:
            with urllib.request.urlopen(url, timeout=30) as response:
                payload_bytes = response.read()

            with open(payload_file_path, "wb") as payload_file:
                payload_file.write(payload_bytes)
        except Exception as ex:
            IRISLog.Error(f"openFDA API call or payload write failed: {ex}")
            return Status.Error()

        msg = AdverseEventFileMessage(
            api_url=url,
            search_query=search_query,
            pulled_at=pulled_at,
            payload_file_path=payload_file_path,
            medicine = selected_med
        )
        self.business_host_process_input(msg)
        return Status.OK()

We can see the events in the log for the inbound adapter, each time info about a different medicine is requested:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/yben0tbb988bqfkld7xd.png)

Step 2 – Create the Business Service

The Business Service is intentionally simple. Its only responsibility is forwarding the metadata produced by the adapter to the Business Process.

Notice that we're no longer passing the entire JSON document between production components. The message AdverseEventFileMessage that is forwarded between the OpenFDAEventService and OpenFDAAnalysisProcess contains only:

API URL
search query
selected medication
timestamp
payload file path

class AdverseEventFileMessage(JsonSerialize): 
    api_url: str = Column() 
    search_query: str = Column() 
    pulled_at: str = Column() 
    payload_file_path: str = Column() 
    medicine: str = Column()

This keeps production efficient while preserving access to the original API response.

class OpenFDAEventService(BusinessService): 
    ADAPTER: str = IRISParameter( 
        value="HealthOps.OpenFDAInboundAdapter", 
        description="Pure Python CSV polling adapter" 
    ) 
    process_target: str = IRISProperty( 
        description="Business process target", 
        settings="Target Settings" 
    ) 

    def on_process_input(self, input): 
        return self.send_request_async(self.process_target, input)

Here are the messages in the Message Viewer:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/bx3sbri80t9ugrl041q4.png)

Step 3 – Create the Business Process

The Business Process performs the analytics. Using the payload file path, it reloads the JSON response and analyzes the complete batch of adverse-event reports.

For every API batch it calculates:

total number of reports
serious adverse-event count
serious adverse-event percentage
death count
hospitalization count
average patient age
most frequently reported reaction

Unlike the Electric Utility example, which generated one database row per input record, this production generates one analytics message representing the entire batch.

This greatly reduces message traffic while still preserving all meaningful statistics.

class OpenFDAAnalysisProcess(BusinessProcess): 
    operation_target: str = IRISProperty( 
        description="Operation that persists rows and analysis results", 
        settings="Target Settings" 
    ) 

    def _age_to_years(self, age_value, age_unit) -> Optional[float]: 
        if age_value in ("", None): 
            return None 
        try: 
            age = float(age_value) 
        except Exception: 
            return None 
        unit = str(age_unit or "") 
        if unit == "801": 
            return age 
        if unit == "802": 
            return age / 12.0 
        if unit == "803": 
            return age / 52.0 
        if unit == "804": 
            return age / 365.0 
        if unit == "805": 
            return age / 8760.0 
        return age 

    def _load_records(self, payload_file_path: str): 
        with open(payload_file_path, "r", encoding="utf-8") as payload_file: 
            payload = json.load(payload_file) 
        return payload.get("results", []) 

    def on_request(self, request): 
        try: 
            records = self._load_records(request.payload_file_path) 
        except Exception as ex: 
            IRISLog.Error(f"Failed to read openFDA payload file {request.payload_file_path}: {ex}") 
            return Status.Error() 

        record_count = len(records) 
        serious_count = 0 
        death_count = 0 
        hospitalization_count = 0 
        ages: List[float] = [] 
        reaction_counts: Dict[str, int] = {} 

        for record in records: 
            if str(record.get("serious", "")) == "1": 
                serious_count += 1 
            if str(record.get("seriousnessdeath", "")) == "1": 
                death_count += 1 
            if str(record.get("seriousnesshospitalization", "")) == "1": 
                hospitalization_count += 1 

            patient = record.get("patient", {}) or {} 

            age_years = self._age_to_years( 
                patient.get("patientonsetage"), 
                patient.get("patientonsetageunit"), 
            ) 
            if age_years is not None: 
                ages.append(age_years) 

            for reaction in patient.get("reaction", []) or []: 
                term = reaction.get("reactionmeddrapt") 
                if term: 
                    reaction_counts[term] = reaction_counts.get(term, 0) + 1 

        serious_rate_pct = round((serious_count / record_count) * 100, 2) if record_count else 0.0 
        avg_patient_age_years = round(sum(ages) / len(ages), 2) if ages else 0.0 

        top_reaction = "" 
        top_reaction_count = 0 
        if reaction_counts: 
            top_reaction, top_reaction_count = max(reaction_counts.items(), key=lambda item: item[1]) 

        analysis = AdverseEventAnalysisMessage( 
            api_url=request.api_url, 
            search_query=request.search_query, 
            pulled_at=request.pulled_at, 
            payload_file_path=request.payload_file_path, 
            record_count=record_count, 
            serious_count=serious_count, 
            serious_rate_pct=serious_rate_pct, 
            death_count=death_count, 
            hospitalization_count=hospitalization_count, 
            avg_patient_age_years=avg_patient_age_years, 
            top_reaction=top_reaction, 
            top_reaction_count=top_reaction_count, 
            medicine = request.medicine 
        ) 

        IRISLog.Info( 
            f"Batch analysis complete: " 
            f"medicine={request.medicine}, " 
            f"records={record_count}, " 
            f"serious={serious_count}, " 
            f"serious_rate={serious_rate_pct}%, " 
            f"deaths={death_count}, " 
            f"hospitalizations={hospitalization_count}, " 
            f"avg_age={avg_patient_age_years}, " 
            f"top_reaction={top_reaction}" 
        ) 

        return self.send_request_async(self.operation_target, analysis, response_required=0)

Here we can see the incoming and outgoing messages for the Business Process:

Here's the trace of messages for the whole cycle:

The message AdverseEventAnalysisMessage contains aggregated info about the received info about the concrete medicine:

class AdverseEventAnalysisMessage(JsonSerialize): 
    api_url: str = Column() 
    search_query: str = Column() 
    pulled_at: str = Column() 
    payload_file_path: str = Column() 
    record_count: int = Column() 
    serious_count: int = Column() 
    serious_rate_pct: float = Column() 
    death_count: int = Column() 
    hospitalization_count: int = Column() 
    avg_patient_age_years: float = Column() 
    top_reaction: str = Column() 
    top_reaction_count: int = Column() 
    medicine: str = Column()

And here's the log of the Business Process with the results of calculations:

Step 4 – Create the Business Operation

The Business Operation receives the batch analysis and stores it in InterSystems IRIS. If the SQL table doesn't exist yet, it is created automatically.

Each API request produces one row containing:

medication name
search query
API URL
payload file path
number of retrieved reports
serious-event statistics
hospitalization statistics
average patient age
top reported reaction

Once the insert succeeds, the JSON payload is moved into the archive directory.

class OpenFDADBOperation(BusinessOperation): 
    archive_payload_dir: str = IRISProperty( 
        description="Directory where successfully processed JSON payloads are archived", 
        settings="Operation Settings" 
    ) 

    message_map = { 
        f"{iris_package_name}.AdverseEventAnalysisMessage": "save_events" 
    } 

    def _ensure_table(self): 
        ddl = """ 
        CREATE TABLE IF NOT EXISTS HealthOps.OpenFDAAdverseEvents ( 
            id INTEGER IDENTITY PRIMARY KEY,             
            payload_file_path VARCHAR(1000), 
            api_url LONGVARCHAR, 
            search_query VARCHAR(1000), 
            pulled_at TIMESTAMP, 
            batch_record_count INTEGER, 
            batch_serious_count INTEGER, 
            batch_serious_rate_pct NUMERIC(6,2), 
            batch_death_count INTEGER, 
            batch_hospitalization_count INTEGER, 
            batch_avg_patient_age_years NUMERIC(10,2), 
            batch_top_reaction VARCHAR(255), 
            batch_top_reaction_count INTEGER, 
            medicine VARCHAR(60), 
            inserted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP 
        ) 
        """ 
        iris.sql.prepare(ddl).execute()     
    
    def save_events(self, request): 
        self._ensure_table()       

        insert_sql = """ 
        INSERT INTO HealthOps.OpenFDAAdverseEvents ( 
            payload_file_path, 
            api_url, search_query, pulled_at, batch_record_count, 
            batch_serious_count, batch_serious_rate_pct, batch_death_count, 
            batch_hospitalization_count, batch_avg_patient_age_years, 
            batch_top_reaction, batch_top_reaction_count, medicine 
        ) 
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) 
        """ 

        stmt = iris.sql.prepare(insert_sql) 
        
        stmt.execute( 
            request.payload_file_path, 
            request.api_url, 
            request.search_query, 
            request.pulled_at, 
            int(request.record_count), 
            int(request.serious_count), 
            float(request.serious_rate_pct), 
            int(request.death_count), 
            int(request.hospitalization_count), 
            float(request.avg_patient_age_years), 
            request.top_reaction, 
            int(request.top_reaction_count), 
            request.medicine 
        ) 
        
        os.makedirs(self.archive_payload_dir, exist_ok=True) 
        archive_path = os.path.join(self.archive_payload_dir, os.path.basename(request.payload_file_path)) 
        try: 
            os.replace(request.payload_file_path, archive_path) 
        except Exception as ex: 
            IRISLog.Warning( 
                f"Inserted records but could not archive payload file {request.payload_file_path}: {ex}" 
            ) 

        IRISLog.Info( 
            f"Inserted info about {request.medicine}: " 
            f"serious_rate={request.serious_rate_pct}%, " 
            f"death_count={request.death_count}, " 
            f"hospitalization_count={request.hospitalization_count}, " 
            f"avg_age={request.avg_patient_age_years}, " 
            f"top_reaction={request.top_reaction}" 
        ) 
        return Status.OK()

Here's the log of the Business Operation:

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/xt1y9jjnlei5kkg50es2.png)

Step 5 – Define the Production

As with the previous example, the entire production is assembled directly in Python. It consists of:

OpenFDAInboundAdapter
        ↓
OpenFDAEventService
        ↓
OpenFDAAnalysisProcess
        ↓
OpenFDADBOperation

Because everything is defined in Python, no manual production configuration is required after loading the project.

class OpenFDAHealthcareProduction(Production): 
    services = [ 
        ServiceItem( 
            "OpenFDAEventService", 
            "HealthOps.OpenFDAEventService", 
            host_settings={"process_target": "OpenFDAAnalysisProcess"}, 
            adapter_settings={ 
                "api_base_url": "https://api.fda.gov/drug/event.json", 
                "medication_names": "ASPIRIN,IBUPROFEN,ACETAMINOPHEN,NAPROXEN,LORATADINE", 
                "result_limit": 30, 
                "api_key": "", 
                "payload_dir": f"{OPENFDA_ROOT}/payloads" 
            } 
        ) 
    ] 
    processes = [ 
        ProcessItem( 
            "OpenFDAAnalysisProcess", 
            "HealthOps.OpenFDAAnalysisProcess", 
            host_settings={"operation_target": "OpenFDADBOperation"} 
        ) 
    ] 
    operations = [ 
        OperationItem( 
            "OpenFDADBOperation", 
            "HealthOps.OpenFDADBOperation", 
            host_settings={"archive_payload_dir": f"{OPENFDA_ROOT}/archive"} 
        ) 
    ]

Step 6 – Run the Production

Start the production:

python controls.py start HealthOps.OpenFDAHealthcareProduction

Or from the IRIS terminal:

zn "ENSEMBLE"
do ##class(Ens.Director).StartProduction("HealthOps.OpenFDAHealthcareProduction")

Or in the UI in Management Portal:

Every polling cycle automatically selects the next medication and downloads a fresh batch of adverse-event reports.

Results

The production stores one summary row for every API call. For example:

SELECT
    medicine,
    batch_record_count,
    batch_serious_rate_pct,
    batch_death_count,
    batch_hospitalization_count,
    batch_avg_patient_age_years,
    batch_top_reaction
FROM HealthOps.OpenFDAAdverseEvents
ORDER BY inserted_at DESC

This makes it easy to compare medications over time and observe trends without storing thousands of individual adverse-event records.

A Note About Large JSON Payloads

One interesting challenge when integrating with public APIs is message size. Initially, I passed the complete JSON response between production components. While this works for small payloads, larger responses can exceed IRIS string limits and I got the <MAXSTRING> error. The solution used in this project is to store the API response as a JSON file and send only its location through the production.

This approach has several advantages:

avoids large interoperability messages
preserves the original API response
makes troubleshooting easier
keeps the production lightweight

It's a useful design pattern whenever you're processing large REST responses or documents.

Summary

In this article, we've built a complete healthcare interoperability production in pure Python using PyProd.

Compared to the previous Electric Utility PyProd sample, this project demonstrates a more realistic integration scenario by communicating with an external REST service instead of processing local files.

Along the way, we've seen how to:

integrate with the public openFDA API
rotate automatically between multiple medications
process large JSON payloads efficiently
calculate batch-level healthcare analytics
archive source payloads
create SQL tables automatically
build an entire InterSystems IRIS production using only Python

Although this example focuses on the openFDA API, the same architecture can easily be adapted to FHIR servers, public health services, hospital APIs, or any REST-based healthcare integration.

I hope this project serves as a useful starting point for building more advanced Python interoperability solutions with PyProd.

45-Second Production: Testing ChatGPT’s Limits with InterSystems IRIS and PyProd

InterSystems Developer — Tue, 28 Jul 2026 19:12:16 +0000

It all started on a train ride to visit my parents, while I was chatting with a neighbor in my compartment. As it usually goes, the talk turned to technology, and she threw out a highly specific question: *Could ChatGPT be used to analyze the human genome?* I was highly skeptical that it could pull off something that complex. But the question lingered, burrowing into my mind. By the time I walked through my front door, my skepticism had transformed into a challenge. I didn't have a genome sequencing dataset on hand, but I did want to see if standard ChatGPT could build a functional Interoperability Production from scratch using the PyProd package. Besides, that would give me the chance to participate in the 1st round of the Community Bounty Program "Idea to Application" implementing the third idea.

I decided to test it with a multi-step prompt:

Using info from the following articles and github repository, write code for a complete InterSystems Production in Python using PyProd package:

step 1: come up with the domain for this production

step 2: create 4 csv files with 30 records in each in the step 1 domain

step 3: write sql create table statement with the structure from csv file

step 4: write inbound adapter in Python using PyProd package that reads the file

step 5: write a business process in Python that analyzes the structure of the step 2 file and makes 1 calculation that makes sense in the step 1 domain

step 6: write business operation in Python to save all the data read in 4 step and the result of calculation from 5 step to the table created in 3 step

Here are the articles and github repositories you should use:

https://community.intersystems.com/post/pyprod-pure-python-iris-interoperability

https://community.intersystems.com/post/pyprod-creating-iris-interoperability-productions-programmatically-python

https://community.intersystems.com/post/csvgen-pyprod https://github.com/intersystems/pyprod

https://github.com/gabriel-ing/csvgen-pyprod

I fed it all to ChatGPT and hit send. Then, I waited. For exactly 45 seconds.

The Delivery and the "Gotchas"

As a result, I got a smart_grid_pyprod.zip containing the ready-to-use code. Naturally, I was dying to know whether it actually worked or was just a convincing hallucination. Playing the part of a complete novice, I asked it how to set everything up. ChatGPT promptly walked me through all necessary steps.

1. Enabling interoperability in the `USER` namespace via the IRIS Terminal:

zn "%SYS"
do ##class(%EnsembleMgr).EnableNamespace("USER")

2. Configuring the environment variables for Windows 11 and installing the package:

set IRISINSTALLDIR=C:\InterSystems\IRIS
set IRISUSERNAME=SuperUser
set IRISPASSWORD=SYS
set IRISNAMESPACE=USER
set PATH=%IRISINSTALLDIR%\mgr\python;%PATH%
python -m pip install intersystems_pyprod --target %IRISINSTALLDIR%\mgr\python --upgrade

3. Compile the generated code using intersystems_pyprod smart_grid.py

4. Open the Management Portal, and start the production.

Did it work right out of the box? Well, no. Mostly, the problems were about commas where they shouldn’t be and a couple of wrongly written async requests, among other things. It took me about half a day to iron out the creases (granted, I was watching Landman in parallel while waiting for Docker to build, turned out to be quite apropos - pumping oil and electricity 😉). But, thanks to some basic Python knowledge and a crucial reference example from @gabriel.Ing, I got it running.

Anatomy of an AI-Generated Production

Once the code was fixed, the production (mostly) written by ChatGPT functioned beautifully. It consists of three components:

The business serviceSmartMeterFileService reads the input file
The business processSmartMeterAnalysisProcess computes per-file total kWh, average kWh, peak meter id, and peak kWh
The business operationSmartMeterDBOperation persists every CSV row with those calculation results

![ ](https://dev-to-uploads.s3.us-east-2.amazonaws.com/uploads/articles/jmn3lraxygfa1sz48m84.png)

Looking at the Visual Trace in the Management Portal, you can see messages flowing seamlessly from the service to the process and finally to the operation:

And when queried in SQL Explorer

SELECT * 
  FROM EnergyOps.SmartMeterReadings

the data was there, properly calculated, and perfectly structured:

The Verdict: Almost a Success

I would call this experiment an almost success. Almost, because it required me to know at least something about how it works, so the complete novice would be stumped (or would need to ask a lot of follow-up questions).

However, if you have a bit of foundational knowledge, a willingness to troubleshoot, and good community examples to lean on, you can make it work. It proves that while AI might not be ready to architect complex, enterprise-grade genome sequencing pipelines entirely on its own just yet, it is an incredible tool for taking an example and expanding on it to get a prototype off the ground.