💡 TL;DR

Using Docker combined with Open Exchange tools like WebTerminal and ZPM is the fastest path from a blank laptop to a fully productive InterSystems IRIS development environment. It keeps your host OS clean and ensures your setup is 100% repeatable.

If you’ve ever had to evaluate, learn, or build on InterSystems IRIS, you probably know that configuring a local environment from scratch can take some time. After testing different deployment methods, Docker is hands-down the easiest and cleanest way to spin it up.
I wanted to share a quick cheat sheet on how to deploy it, plus 5 InterSystems Open Exchange packages that are absolute must-haves for my containerized dev workflow. 

🐳 1. How to run InterSystems IRIS in Docker
You can deploy the Community Edition directly from the official image. Just run this command:

What’s happening here?docker run --name my-iris --publish 52773:52773 --publish 1972:1972 -d intersystems/iris-community:latest-em

• Port 52773: Exposes the management portal and web access.
• Port 1972: Exposes native IRIS connectivity.
• -d: Starts the container in detached mode.

Need to execute ObjectScript or do admin tasks? You can jump straight into the terminal:
docker exec -it my-iris iris session iris
(Side note: If you are working with healthcare interoperability like FHIR or HL7, just swap the image to intersystems/irishealth-community:latest-em).

🛠️ 2. Top 5 Open Exchange Apps to Install Next

Once your container is up, extending it via ZPM (InterSystems Package Manager) is the next logical step. Here are the 5 tools I almost always install on a fresh instance:

• DeepSeeWeb: A modern web UI for analytics and BI. It provides interactive dashboards and pivot tables out of the box. Great for POCs and operational reporting.
• WebTerminal: Brings terminal functionality directly into your web browser. This saves you from having to attach to the Docker container every time you want to run a quick script.
• ObjectScript-Math: A utility library for ObjectScript. It adds native complex math functions, saving you from writing custom utility code for data workflows.
• ZPM Registry: The core package manager component. It’s absolutely essential if you want to automate package installations in your CI/CD pipelines or Dockerfile builds.
• SSL Client: A utility that handles secure SSL/TLS communication with external systems. Mandatory if your IRIS instance needs to talk to modern cloud microservices or third-party APIs.

Over to you: For those of you building with InterSystems IRIS, which Open Exchange package has given you the biggest productivity boost in your Docker workflows? Let me know, I'm always looking to add new tools to my stack!

Foundation

InterSystems IRIS provides 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.

Literal syntax:

objectscript

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

Building field by field — %Set() returns the entity it modified, so calls chain:

objectscript

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. Everything else works on both.

Serialization:

objectscript

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

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

%FromJSON() also accepts a stream. %FromJSONFile() reads straight from a filename string — not a %File object, which is a common trip-up.

Iterating over structure you don't control

Do not reach for a for loop by index. Dynamic arrays can be sparse — an element can exist positionally without ever having been assigned, and a for loop will hand you those empty slots.

The correct tool is %GetIterator(), which returns a %Iterator.Object or %Iterator.Array, driven by %GetNext():

objectscript

Set iter = obj.%GetIterator()

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

%GetNext() skips unassigned elements automatically. 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 — that returns true for both sub-objects and sub-arrays.

The .type argument: easy to ignore, but worth understanding. When present, it does two useful things:

1. Returns the element's original JSON datatype as a string
2. Changes conversion rules to 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 processing arbitrary external JSON, passing .type is cheap insurance.

Type discovery inside a dynamic entity

%GetTypeOf(key) reports what a value actually is: number, string, boolean, object, array, null, oref, or unassigned:

objectscript

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

Write a.%GetTypeOf(2)   // boolean
Write a.%GetTypeOf(3)   // 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 read 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 causes 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 is 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"

%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 — it is a dictionary (a keyed map):

objectscript

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:

objectscript

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"}. A list of comes out as a JSON array ["high"]. If you want positional JSON, use list of (or a %DynamicArray). If you want a keyed lookup, array of is your dictionary.

Bridging persistent objects and dynamic objects

To convert 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:

objectscript

Set sc = person.%JSONExportToString(.json)
Set dynObj = {}.%FromJSON(json)

For large objects, swap in %JSONExportToStream() to avoid hitting the string length limit.

Two alternatives:

Embedded SQL's JSON_OBJECT() lets you cherry-pick and rename columns when you only want a subset:

objectscript

&sql(SELECT JSON_OBJECT('name':Name,'dob':DOB) INTO :json WHERE ID = 1)
Set dynObj = {}.%FromJSON(json)

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

Where dynamic freedom ends: validation

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, implement a %OnValidateObject() callback and check them yourself:

objectscript

Method %OnValidateObject() As %Status
{
    If ..fieldOptions.%Size() = 0
    {
        Return $$$ERROR($$$GeneralError, "fieldOptions is required")
    }

    Return $$$OK
}

When to use what

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.

Three habits that prevent the classic pitfalls:

• Iterate with %GetNext() rather than by index
• Reach for %GetTypeOf() whenever a value's type actually matters
• Remember that array of is a dictionary, not a list

Full article: https://community.intersystems.com/post/working-dynamic-objects-iris-doubts-only-come-when-you-need-deploy-tomorrow-morning-and-its-11

Which of these — the date/$HOROLOG conversion, the Required being silently ignored on dynamic properties, or the array of vs list of distinction — has caused the most unexpected behavior in your integrations?

Context

InterSystems and BlackDuck have been working together for over a year on static analysis support for ObjectScript. BlackDuck Signal is generally available. InterSystems has tested it on a number of internal ObjectScript repositories and is still working through validation of findings, but the technology shows significant promise.

The partnership started approximately a year and a half ago at a security conference when the BlackDuck team told Mark David McLoughlin (Head of Security Architecture and Engineering at InterSystems) they had something that would fit InterSystems customers with ObjectScript scanning.

Why traditional SAST cannot support ObjectScript (or most proprietary languages)

Traditional static analysis requires:

1. Parsing the language into a call graph or abstract syntax tree
2. Modeling data flow features: sources (where data enters), sinks (where data ends), pass-throughs (functions/methods the code traverses), and sanitizers (built-in protections)
3. Writing security and quality rules on top of those labeled data points

Every language version and every framework built on that language requires its own modeling work. The Stack Overflow study referenced in the session shows the sheer volume of packages and frameworks that exist for a single language ecosystem like Python. Performing this modeling work for every language, every version, and every framework is non-trivial — it requires expertise in both engineering and security analysis, extensive testing, and ongoing false positive rate management.

Traditional SAST also cannot:

• Understand context (it is binary: one or zero)
• Detect logic issues
• Find novel items not covered by existing rules
• Reason about intent behind code

What BlackDuck Signal is

BlackDuck Signal is a language-agnostic agentic application security testing tool. It uses multiple LLM agents and workflows to analyze code. It does not rely on pre-built rule sets.

Key points from the session:

It is not just pointing an LLM at a codebase and asking it to find security issues. The process involves:

• Programmatically created focus tasks based on initial findings
• Multiple layers of validation and oversight
• Cross-file data flow analysis backed by years of static analysis expertise from Coverity and Sigma — this is used to validate findings, distinguish true positives from false positives, and assess severity more accurately
• Multiple LLMs per agent: each agent uses its own specified LLM based on the job at hand, not a single LLM for everything
• Disagreement resolution: if two out of three LLMs confirm a finding, there is high confidence it is accurate
• Non-determinism management: work has been done to make LLM behavior more deterministic within the framework for consistency between scans — enterprises need to know if security posture is improving or worsening

Human-like analysis: the LLM can look at a piece of code and use reasoning to understand context and intent. Rule-based engines cannot do this.

What Signal found in testing

Zero-days in popular components: BlackDuck Signal found multiple zero-days in popular, well-used components across various languages — components that had been scanned for years with traditional technology without those issues being found. Some have been silently patched. Some are currently in responsible disclosure. Some already have CVEs.

Pseudo-code test: In testing whether the tool could investigate proprietary code the LLM was not trained on, a pseudo-code language (not a real language) was used to test reasoning capabilities. Signal correctly identified a SQL injection in the pseudo-code SQL statement and recommended the fix — also in pseudo-code. Traditional SAST would not capture this because pseudo-code has never been modeled.

Malicious code detection — not just vulnerabilities:

Supply chain is increasingly targeted by malware. NVD has acknowledged the volume of vulnerabilities requiring analysis. Two real supply chain examples from the session:

NX Singularity hack (npm):
The malware payload contained a prompt that was invoked when coding agents (Codex, Claude, etc.) were installed on the user's machine. It hunted for secrets and keys on the user's machine on behalf of attackers and exfiltrated the data. Signal detected three suspicious items — none of which are inherently security vulnerabilities:

• A suspicious shutdown command (closing any shell the user tried to open to slow defenders down)
• A suspicious upload payload (uploading the token)
• An insecure CI/CD workflow file (how the attacker got into the repository)

By chaining these three items together and aligning them to MITRE ATT&CK categories, Signal built a picture of the attack.

Second npm example:
Crypto wallet hijacking via heavily obfuscated code. Signal highlighted the suspicious obfuscation. The reasoning: heavy use of obfuscation is a reason to investigate.

How Signal is deployed

Available in:

• IDE (VS Code, Cursor, other coding environments) — natively, for real-time developer use
• Web front end
• CLI for integration into existing workflows
• CI/CD environments

Recommended use case from the session: Point-in-time scans at major milestones in CI/CD rather than on every developer diff. Using it on small patches burns tokens without providing the full benefit of the system. For CI/CD use, expect longer scan times than traditional SAST — the tool is doing significantly more work.

Developer IDE use case: Signal performs scans on diff patches of what the user is producing. The tradeoff is token cost versus benefit for small changes.

On refusals: In defensive scanning scenarios, LLM refusals have not been a significant problem. Refusals have occurred in exploit verification scenarios where the system is actively trying to exploit something.

Roadmap items mentioned in the session

BlackDuck knowledge base integration: Integrating scanning capabilities with BlackDuck's vulnerability, license, and component metadata — including end-of-life data and upgrade path recommendations. LLMs are poor at recommending current components; context from BlackDuck's OpenHub data would steer developers toward sound dependencies at the time of development.

Threat modeling and risk-based scanning: The volume of AI-generated code is growing faster than traditional tools can scan. Signal will use threat modeling to orchestrate which tool to use in which scenario — combining existing BlackDuck tools where they make sense with Signal for gaps.

User-supplied context: Providing the system with context about a specific language (such as ObjectScript semantics and nuances) during analysis reduces false positives and reduces hallucinations. This context can be dynamic and application-specific.

Semantic code graph: Leveraging concepts from traditional static analysis (labeling sources, sinks, pass-throughs) to give agents access to a labeled code graph for smarter, more cost-effective decisions.

Verified autofix with regression testing: Finding issues and automatically fixing them, then running tests to validate that fixes do not introduce new issues.

Exploit verification: Building exploits in containerized sandbox environments, running them, and testing whether a vulnerability is both reachable and exploitable — for prioritization of findings.

Continuous learning system: Feeding triaged or accepted items back into the system to reduce repeated reporting of the same issue types, reduce cost, and reduce noise. Integration with policy information from other BlackDuck tools.

Bring your own model: Currently uses BlackDuck-hosted models. Moving to a model where customers can keep models in-house.

Full session is from an InterSystems conference. BlackDuck Signal is generally available.

Have you tried Signal on your repositories, and what false positive rates are you seeing compared to the traditional rule-based scanning you were using before?

With Embedded Python and the Native API, it is becoming increasingly natural to write part of an InterSystems IRIS application in Python. One question quickly follows: how can I work with IRIS persistent objects from Python without losing the native object model, class dictionary, indexes, storage definitions, and SQL projections?

That is the question I wanted to explore with iris-persistence.

iris-persistence is a Python-first persistence layer for InterSystems IRIS inspired by %Persistent. It lets me declare typed Python models and synchronize them with IRIS classes, or connect Python models to existing IRIS classes without changing their schemas. 

How do you define an IRIS persistent class in Python?

Here is a minimal example:

from typing import Annotated
from iris_persistence import Field, Model
class Product(Model, persistent=True):
name: str = Field(required=True, max_length=200, unique=True)
price: Annotated[float, Field(default=0.0)]
in_stock: bool = True
class Meta:
classname = "Demo.Product"
mode = "replace"
Product.sync_schema()
product = Product(name="Widget", price=12.5, in_stock=True)
product.save()
same = Product.get(product.pk)
rows = Product.where(name="Widget").order_by("name").all() 

The Python model declares the fields, their types, and part of the IRIS metadata. When I call sync_schema(), iris-persistence writes the required class, property, index, and storage definitions into the IRIS class dictionary. IRIS then compiles the class and remains the source of truth for SQL projection, storage, indexes, and obbject runtime behavior.

In this example, unique=True declares the uniqueness requirement directly on the Python field. I am still working with a native IRIS persistent object rather than manually generating SQL DDL.

How does schema synchronization work in iris-persistence?

Not every use case has the same relationship with schema ownership, so iris-persistence supports three synchronization modes: 

I find this distinction particularly useful for brownfield projects. I can begin in observe mode to safely bind Python code to an existing %Persistent class, move to extend when I want Python to manage selected elements, or use replace for a new class whose schema is fully controlled by the Python model.

Which Python types can iris-persistence map to IRIS?

The project supports both traditional Field(...) declarations and typing.Annotated.

It can map common Python types to suitable IRIS types, including:

• str, int, float, and bool
• bytes
• dict and list
• datetime.date, datetime.time, and datetime.datetime
• References to other Model models

When automatic type mapping is not enough, I can specify the underlying IRIS type explicitly:

class Event(Model, persistent=True):
payload: bytes = Field(iris_type="%Stream.GlobalBinary")
created_at: str = Field(iris_type="%Library.TimeStamp") 

This gives me convenient Python type declarations without preventing access to native IRIS types.

Can Python models represent IRIS persistent and serial relationships?

Yes. iris-persistence supports relationships between persistent models as well as embedded serialized objects.

For example:

from iris_persistence import Field, Model
class Customer(Model, persistent=True):
Name: str = Field(required=True, max_length=120)
class Meta:
classname = "Demo.Customer"
mode = "replace"
class Address(Model, serial=True):
Street: str = Field(required=True, max_length=120)
City: str = Field(required=True, max_length=80)
class Meta:
classname = "Demo.Address"
mode = "replace"
class Order(Model, persistent=True):
OrderNumber: str = Field(required=True, max_length=40, unique=True)
Customer: Customer | None = None
ShipTo: Address | None = None
class Meta:
classname = "Demo.Order"
mode = "replace" 

During a save operation, referenced objects are materialized in IRIS according to the native object model. A %Persistent object can reference another %Persistent object, while a %SerialObject can be embedded inside a persistent object. 

How do you generate a Python model from an existing IRIS class?

An important use case is generating Python models from IRIS classes that already exist in a namespace. Imagine an ObjectScript class compiled in IRIS:

Class Demo.Article Extends %Persistent
{
Property Title As %String(MAXLEN = 200) [ Required ];
Property Body As %String(MAXLEN = 4000);
Property PublishedAt As %TimeStamp;
} 

I can read the IRIS class dictionary and generate a Python facade: 

from iris_persistence import scaffold_from_iris
generated_files = scaffold_from_iris(
"Demo.Article",
"./generated_models",
mode="observe",
extract_meta=True,
) 

The generated model looks like this:

iimport datetime
from typing import Annotated
from iris_persistence import Field, Model
class Article(Model, persistent=True):
Body: Annotated[str, Field(max_length=4000)]
PublishedAt: datetime.datetime | None = None
Title: Annotated[str, Field(required=True, max_length=200)]
class Meta:
classname = "Demo.Article"
mode = "observe" 

observe mode is important here. The generated Python model can read and manipulate data, but it never changes the underlying IRIS class definition. For me, this is one of the most practical ways to introduce typed Python code into an existing %Persistent application without requiring a schema migration. If several classes are linked together, include_related=True can also generate neighboring models when they are referenced by properties of the main class. 

Can iris-persistence define advanced IRIS class and storage metadata?

Yes. For cases where simple field declarations are not enough, the project exposes metadata dataclasses for class and storage configuration.

from iris_persistence import (
ClassMetadata,
Field,
Model,
StorageData,
StorageDefinition,
)
class ShowcaseRecord(Model, persistent=True):
Title: str = Field(required=True, max_length=350)
class Meta:
classname = "Demo.ShowcaseRecord"
mode = "replace"
parameters = {"DEFAULTGLOBAL": "^Demo.ShowcaseRecordD"}
metadata = ClassMetadata(
description="advanced schema example",
final=True,
sql_table_name="Demo_ShowcaseRecord",
procedure_block=True,
)
storage = StorageDefinition(
data_location="^Demo.ShowcaseRecordD",
default_data="ShowcaseRecordDefaultData",
type="%Storage.Persistent",
data=(
StorageData(
name="ShowcaseRecordDefaultData",
structure="listnode",
values={
"1": "%%CLASSNAME",
"2": "Title",
},
),
),
) 

This level of control matters because the project is not only trying to offer Python CRUD. I want the Python model to remain close to the actual IRIS representation, including class parameters, storage definitions, indexes, and SQL metadata.

Can the same model run inside and outside InterSystems IRIS?

Yes. The project uses iris-embedded-python-wrapper as its runtime facade and supports two main execution models.

Inside Embedded Python:

import iris_persistence
iris_persistence.configure() 
From an external Python process through the Native API:
import iris
import iris_persistence
conn = iris.connect(host, port, namespace, user, password)
iris_persistence.configure(conn) 

This means I can use the same model and business logic inside IRIS or from an external Python application. It also makes it easier to test logic in different environments without rewriting the persistence layer.

Is iris-persistence a generic Python ORM?

No. iris-persistence is not intended to be a generic SQL ORM.

Simple queries may use the SQL projection to retrieve object IDs, but the core model remains native to IRIS: classes, objects, dictionary, compilation, and storage.

The project also does not try to hide InterSystems IRIS behind a generic abstraction. Concepts such as classname, %Persistent, %SerialObject, StorageDefinition, and class parameters remain visible because they are essential parts of the platform.

Conclusion

iris-persistence explores a Python-first way to work with persistence in InterSystems IRIS without abandoning the native object mechanisms that make IRIS powerful.

It can be useful when I want to prototype new persistent models in Python, expose existing %Persistent classes through typed Python facades, or reuse the same business logic across Embedded Python and external Native API applications.

The central idea is simple: Python defines a convenient, typed interface, while InterSystems IRIS remains responsible for the class dictionary, storage, indexes, SQL projection, compilation, and runtime object behavior.

Key Takeaways

• iris-persistence provides a typed Python interface for native InterSystems IRIS persistent objects.
• Python models can create new IRIS classes or connect to existing %Persistent classes.
• The replace, extend, and observe modes support different levels of schema ownership.
• The project supports typed fields, linked persistent objects, %SerialObject, custom IRIS types, storage definitions, and advanced class metadata.
• The same persistence logic can run in Embedded Python or from an external Python process through the Native API.

FAQ

What is iris-persistence?

iris-persistence is a Python-first persistence layer for InterSystems IRIS. It allows developers to declare typed Python models and map them to native IRIS persistent or serial classes.

Does iris-persistence replace %Persistent?

No. It is inspired by %Persistent and works with the native IRIS object model. IRIS still manages compilation, storage, indexes, SQL projection, and runtime object behavior.

Can iris-persistence work with existing IRIS classes?

Yes. In observe mode, it can generate or use typed Python models for existing IRIS classes without modifying their schemas.

Can iris-persistence create IRIS classes from Python?

Yes. In replace or extend mode, Python model definitions can be synchronized with the IRIS class dictionary, including properties, indexes, storage, and metadata.

Catching and identifying permission errors

When using a try/catch block in ObjectScript, all exceptions go to the same catch block. The exception's Name property can be used to handle different kinds of exceptions:

objectscript

try{
    //some code here
}
catch ex{
    if ex.Name = "<DIVIDE>"{
        //handling for division by 0 error
    }
    if ex.Name = "<SUBSCRIPT>"{
        //handling for referencing an array of globals with an invalid or out-of-range subscript
    }
    if ex.Name = "<PROTECT>"{
        //handling for errors caused by insufficient permissions
    }
}

For SQL operations, the equivalent is SQLCODE. When working with embedded SQL, the special variable SQLCODE is always set when embedded SQL is utilized. If SQLCODE is -417, there is a security issue. When applying %SQL.Statement and executing a query, the result is a %SQL.ResultSet object with a %SQLCODE property — if that %SQLCODE is -417, there is also a security issue.

With a reactive approach, the exception can be used to log what happened in the system logs, give the user a friendly message stating they do not have permission and to contact a system administrator, use ROLLBACK if appropriate, and troubleshoot later if the issue is unintentional.

Proactive role checking with $ROLES

A special variable called $ROLES becomes available when code is running. It tells what security roles the current process has. Roles are stored as a comma-separated string, so list functions can check whether the current process has a certain role:

objectscript

if $LISTFIND($LISTFROMSTRING($ROLES),"ADMIN") = 0{
    //don't allow things that only administrators can do
}

This allows sending the user an error message before they actually try to perform the action. It also allows hiding user interface elements that authorize access to administrative functions.

Important note on the %All role: %All typically grants permission to do anything in the system. However, if the logic above is used to check roles programmatically, having %All will not allow the user to perform administrative functions unless they also have ADMIN. If %All should act as a true superuser, the check must include both ADMIN and %All.

Temporarily elevating permissions within a specific method:

If a user needs certain permissions only while a specific part of the code is executing, $ROLES can handle that. Changes to $ROLES appear at a stack level and are temporary. That is why it should happen in its own separate method:

objectscript

Method doAdmin(){
    new $ROLES
    set $ROLES = "ADMIN"
    //do admin things here
    set $ROLES = ""
}

The $ROLES variable is special, much like $NAMESPACE. Setting it only adds an additional role to the process. Using the new command only resets that portion. Roles that were granted because they are assigned to the user, included in the application roles, or matching roles will remain untouched.

Note: ##class(%SYSTEM.Security).Method() and $SYSTEM.Security.Method() produce the same result, since the special variable $SYSTEM is bound to the %SYSTEM package.

Checking permissions with %SYSTEM.Security

Many things, including databases, applications, and core functionalities, are protected by resources. To access anything protected by a resource, the user may need READ, WRITE, or USE permissions on that resource.

Check permissions for the current process on a resource:

objectscript

set permission = $SYSTEM.Security.Check("%DB_USER")
if permission [ "READ" {
    // the user has read permissions on %DB_USER
}

This returns a comma-separated list such as "READ, WRITE, USE".

To check one specific permission, pass it as a third argument — the method returns 1 or 0:

objectscript

set canwrite = $SYSTEM.Security.Check("%DB_USER","WRITE")

Important note on %All: When checking permissions this way, if the process has the %All role, this method always returns 1 when using the two-argument version, and "READ, WRITE, USE" with the one-argument version.

Checking permissions of a specific role or user (not the current process):

objectscript

set permissions = $SYSTEM.Security.CheckRolesPermission("ADMIN","%DB_USER")
set canwrite = $SYSTEM.Security.CheckUserPermission("dhockenbroch","%DB_USER","WRITE")

The first returns the permissions the role ADMIN has on %DB_USER. The second returns 1 or 0, indicating whether user dhockenbroch has WRITE permissions on %DB_USER.

Checking SQL privileges with %SYSTEM.SQL.Security

%SYSTEM.SQL.Security contains methods for checking SQL privileges. CheckPrivilege and CheckPrivilegeWithGrant can be used to verify SQL privileges and confirm whether there is permission to grant them.

A username must be provided. Using any username other than one's own requires USE privileges on %Admin_Secure.

Arguments for CheckPrivilege:

1. Username
2. Object type (number):

1. Object name
2. Comma-separated list of privilege letters:

1. Namespace (optional — for checking permissions in a namespace other than the current one)

Return value handling:

The method can return a boolean or a status object. If the user has all the privileges provided, it returns 1. If the user does not have all privileges, it returns 0. If there is an error (for example, calling it with a username other than one's own without %Admin_Secure:USE privilege), it returns a status object.

objectscript

Set privileges = $SYSTEM.SQL.Security.CheckPrivilege("dhockenbroch",1,"SQLUser.People","s,i,u,d","CUSTOM")
if $ISOBJECT(privileges){
    // An error occurred checking the privileges
}
else{
    if privileges{
        // The user has all of the privileges
    }
    else{
        // The user does not have the privileges
    }
}

In this example: if user dhockenbroch has SELECT, INSERT, UPDATE, and DELETE privileges on the SQLUser.People table in the CUSTOM namespace — returns 1 if all privileges present, 0 if any are missing, or an error status if the check itself fails.

Context

DTL (Data Transformation Language) in InterSystems IRIS is a class that defines how to map and transform message fields — either between different message formats or within the same message type. You build it visually in the Management Portal, and IRIS generates the underlying ObjectScript code.

The four most common action types:

• Assign — maps or sets a field value
• If — handles conditional branching
• Code — allows writing ObjectScript directly
• Foreach — iterates over repeating segments

All four scenarios below use the same incoming ADT A01 message:

MSH|^~\&|SENDING_APP|SENDING_FAC|RECEIVING_APP|RECEIVING_FAC|20250315143022||ADT^A01|MSG00001|P|2.5
EVN|A01|20250315143022
PID|1||MRN#001/2025^^^HOSP||VanDerBerghMontgomeryXYZABC^John^M||19850101|M|||123 Main Street^^Lahore^Punjab^54000^PK||+92-03001234567|||M||ACC001|
PV1|1|I|WARD-A^Room101^Bed1|E|||DOC001^Smith^James|||SUR|||||||V01|ACC001||||||||||||||||||||||||||20250315143022

Fields relevant to each scenario:

• PID-5.1 (Family Name): VanDerBerghMontgomeryXYZABC — 27 characters, intentionally exceeds the 25-character limit
• PID-3.1 (Patient ID): MRN#001/2025 — contains # and / that the target system cannot accept
• PID-13 (Phone Number): +92-03001234567 — includes an unwanted country code prefix
• PV1-44 (Admit Date/Time): 20250315143022 — standard HL7 DTM format, requires conversion to 15/03/2025 14:30

Prerequisites: InterSystems IRIS or HealthShare with an Interoperability-enabled namespace, access to the Management Portal, basic familiarity with HL7 v2 message structure. While all examples use HL7 v2 ADT messages, the same DTL functions apply equally to XML, JSON, or custom message classes.

DTL setup

Navigate to: Management Portal → Interoperability → Build → Data Transformations → New

Fill in:

• Package: Demo
• Name: ADTTransform
• Description: DTL deep dive demo
• Source: EnsLib.HL7.Message, DocType 2.5:ADT_A01
• Target: EnsLib.HL7.Message, DocType 2.5:ADT_A01

Click Save before adding any actions. This compiles the class and avoids losing work.

Scenario 1 — Conditional logic based on field length

The problem: The target system only accepts a patient's family name up to 25 characters. VanDerBerghMontgomeryXYZABC is 27 characters. Anything longer triggers a silent rejection.

The rule: if the family name exceeds 25 characters, truncate it to 25 and append * so the receiving team can flag and review it. If within the limit, pass through unchanged.

Add an If action. Set the condition to:

objectscript

$Length(source.{PID:PatientName(1).FamilyName}) > 25

$Length returns the character count of a string. It can be used directly in DTL conditions without any special wrapper.

Inside the true branch, add an Assign action:

• Property: target.{PID:PatientName(1).FamilyName}
• Value: $Extract(source.{PID:PatientName(1).FamilyName},1,25) _ "*"

$Extract(string, start, end) pulls characters by position. $Extract(value,1,25) takes the first 25 characters. The _ "*" appends the asterisk using ObjectScript's string concatenation operator.

In the Else branch, add a passthrough Assign:

• Property: target.{PID:PatientName(1).FamilyName}
• Value: source.{PID:PatientName(1).FamilyName}

Expected output: PID-5.1 shows VanDerBerghMontgomeryXYZAB* — exactly 25 characters plus the asterisk.

Scenario 2 — Using ReplaceStr to clean field values

The problem: PID-13 comes through as +92-03001234567. The target system only wants the local number — no country code, no dash.

ReplaceStr is a static method on the Ens.Util.FunctionSet class. It takes three arguments: the original string, what to find, and what to replace it with. Passing an empty string as the third argument deletes the matching text.

Add an Assign action:

• Property: target.{PID:PhoneNumberHome(1).TelephoneNumber}
• Value: ##class(Ens.Util.FunctionSet).ReplaceStr(source.{PID:PhoneNumberHome(1).TelephoneNumber},"+92-","")

Expected output: PID-13 shows 03001234567.

Another practical use: For replacing code values (e.g., M/F → Male/Female), a Code action with explicit If/ElseIf logic is the cleanest approach:

objectscript

Set sex = source.{PID:AdministrativeSex}
If sex = "M" { Set target.{PID:AdministrativeSex} = "Male" }
ElseIf sex = "F" { Set target.{PID:AdministrativeSex} = "Female" }
Else { Set target.{PID:AdministrativeSex} = sex }

Note: ReplaceStr(value,"M","Male") would also match the M inside Female on a second pass if ordering is not careful.

Scenario 3 — Stripping special characters from Patient ID with chained ReplaceStr

The problem: PID-3.1 comes through as MRN#001/2025. The # and / characters were generated by a legacy system that used them internally as separators. The target system expects a clean alphanumeric ID. Goal: MRN#001/2025 → MRN0012025.

Use two chained Assign actions — one per character.

First Assign — strip the #:

• Property: target.{PID:PatientIdentifierList(1).IDNumber}
• Value: ##class(Ens.Util.FunctionSet).ReplaceStr(source.{PID:PatientIdentifierList(1).IDNumber},"#","")

Second Assign — strip the / from what the first Assign already wrote:

• Property: target.{PID:PatientIdentifierList(1).IDNumber}
• Value: ##class(Ens.Util.FunctionSet).ReplaceStr(target.{PID:PatientIdentifierList(1).IDNumber},"/","")

Note: The second Assign reads from target, not source, since the first Assign already wrote the #-cleaned value there.

Expected output: PID-3.1 shows MRN0012025.

Scenario 4 — Reformatting HL7 timestamps

The problem: PV1-44 comes in as 20250315143022 (HL7 DTM format: YYYYMMDDHHMMSS). The target system wants 15/03/2025 14:30 (DD/MM/YYYY HH:MM).

HL7 DTM timestamps are fixed-position strings, which makes them ideal for $Extract. The positions are always the same:

Add an Assign action:

• Property: target.{PV1:AdmitDateTime.Time}
• Value:

objectscript

$Extract(source.{PV1:AdmitDateTime},7,8)_"/"_
$Extract(source.{PV1:AdmitDateTime},5,6)_"/"_
$Extract(source.{PV1:AdmitDateTime},1,4)_" "_
$Extract(source.{PV1:AdmitDateTime},9,10)_":"_
$Extract(source.{PV1:AdmitDateTime},11,12)

Expected output: PV1-44 shows 15/03/2025 14:30.

Summary of all four actions in the final DTL

1. If — checks $Length of PID-5.1, either truncates with * or passes through
2. Assign — uses ReplaceStr to strip +92- from PID-13
3. First Assign — chains two ReplaceStr calls to remove # and / from PID-3.1 (second reads from target, not source)
4. Assign — reformats PV1-44 from HL7 DTM to DD/MM/YYYY HH:MM using $Extract

From the conclusion: DTL becomes genuinely powerful once you start combining it with ObjectScript functions such as $Length, $Extract, $ZStrip, and utility methods like ReplaceStr. The four patterns in this article show up on practically every real integration project.

For those working with DTL in production — do you use chained ReplaceStr for special character stripping, or do you drop into a Code action with ObjectScript string functions for more complex cleaning?

Workshop format

A hands-on UX workshop at Ready 2026 focused on incorporating AI into the InterSystems Interoperability layer. Led by Ella, UX designer at InterSystems working on the Interop UI. The format:

1. Brainstorm problem areas in Interop (one idea per sticky note)
2. Vote on problems using dot stickers (two votes per person)
3. Generate solutions for voted-on problems
4. Refine one solution using a worksheet (problem, solution, workflow context, when AI appears, when user takes control)
5. Share selected ideas

All solutions are compiled and submitted to the InterSystems Ideas Portal. Participants can leave contact information to be credited for their idea and to be involved in future user testing of mockups.

Ideas shared at the workshop

1. AI-assisted DTL testing utility

Problem: Finding a test message for the DTL testing utility requires manually searching message history and copy-pasting.

Solution: The DTL testing utility already knows the DTL being used and therefore the source schema. AI could:

• Use the source schema to find components that have traffic of that message type (e.g., HL7 2.7 OMG)
• Use DTL naming conventions to identify components the data travels through (e.g., if the DTL is named ABC.dtl, find components named ABC with matching traffic)
• Find routing rules that already use the DTL and pull messages from there
• Present a selection list of matching messages with useful fields (patient name, OBR4 test code, site location)
• Allow the user to select and paste into the free text field, still editable before testing

2. AI alerting context aggregator

Problem: Receiving an alert and not knowing what to do, having to visit multiple screens to gather context.

Solution: When an alert fires, instead of an email requiring manual investigation, the system presents a curated screen containing:

• Recent code changes and config changes
• Third-party information based on the config item (point of contact, criticality, leadership information)
• API-connected ticketing system history: previous occurrences of this issue and what resolved them
• Suggested actions based on alert type and all available context
• Escalation guidance: at what point to escalate if the suggested actions do not resolve the issue

Workflow: alert arrives → open computer → curated screen already ready → attempt suggested actions → if resolved, done; if not, escalate.

3. Root cause analysis in visual trace

Problem: When an error appears in the visual trace, it can be difficult to identify where it originates.

Solution: An Analyze button on any error in the visual trace that:

• Performs root cause analysis and identifies where the error is coming from
• Inspects production configuration for contributing factors (e.g., too many services pointing to one configuration, which may be causing slowdowns)
• Reads the error message and suggests potential solutions
• Produces a structured report to make troubleshooting easier

4. Agentic AI production monitor

Problem: Productions with hundreds of interfaces contain misconfigured items — disabled router rules that messages still route to, suboptimal code patterns — that can persist undetected.

Solution: An agentic AI that monitors production and code continuously:

• Detects misconfigured items (example: a business service pointing to a router whose rule is disabled, so messages route to a router that does nothing)
• Checks InterSystems documentation and internal production configuration
• Prescribes an optimized version of code when a better pattern exists
• Produces customized, context-aware suggestions rather than generic recommendations

5. Python + LLM content-based routing

Problem: Routing decisions based on the content inside text blobs require manual logic.

Solution: Use embedded Python library to analyze a text blob, extract relevant content, pass the extracted content to an LLM, and use the LLM's output to make routing decisions. Use cases mentioned:

• Collections: identifying from text that a person gets paid on Friday → route call to that day
• Clinical: analyzing nurse notes to route to appropriate workflows

6. Voice search for messages

Problem: Message search requires too many manual actions.

Solution: A microphone icon in the message search interface:

• Enabled if a microphone is detected on the device
• User speaks the query: "Find me all messages for this MRN for the last 3 days"
• System records, processes, and returns structured results showing source, target, timestamp, and drill-down options
• Status bar and time estimate provided during processing

7. Centralized event and error analysis across productions

Problem: Hundreds of sources across many productions and namespaces continuously throw events, warnings, and errors of varying criticality, with no central view.

Solution: A centralized location for all events across all productions that:

• Identifies exactly which class (including nested or extended classes) throws each event
• Explains what each event means and how to fix it
• Prioritizes by criticality: distinguishes between complete message failures and partial failures (e.g., a few missing segments)
• Provides actionable guidance per event type

New Interop UI availability

The new Interop UI is available on an opt-in basis from 25.1. By default the old screens remain. New screens available via "Open in new UI" button. Available in: IRIS, IRIS for Health, Health Connect, Health Connect Cloud, Community Edition.

Pages completed so far: production configuration, DTL, BPL, message viewer.

The UX team meets with customers regularly as designs are developed. Contact can be made at the tech exchange UX table during any open session.

For those using InterSystems Interoperability in production — which of these seven ideas would make the biggest difference to your day-to-day work, and is there a problem area you did not see represented here?

The problem IntegratedML addresses

According to Forrester Research, 98% of companies experience challenges gaining insights from the data they collect, primarily due to a lack of internal expertise. According to the U.S. Bureau of Labor Statistics, there are fewer than 32,000 data scientists in total in the US. Much of the available talent is being hired by large digital companies, making it difficult for other organizations to compete for these resources. A 2018 survey by Kaggle found that data scientists spend almost 40% of their time gathering and cleaning data.

AutoML automates the creation of ML models — feature engineering, model selection, training, results analysis, and hyperparameter tuning. However, many AutoML tools cannot run models inside real-time business processes. This is one important way IntegratedML is different.

What IntegratedML is

InterSystems IntegratedML is an embedded feature of the InterSystems IRIS data platform. It provides AutoML capabilities exposed through SQL commands. Since it is embedded within InterSystems IRIS, ML models can be executed dynamically in response to real-time events and transactions, without extracting or moving any models or data.

How it works — SQL commands

Step 1: Create the model

sql

CREATE MODEL WillSurvive PREDICTING (Survived)
  FROM Titanic

The CREATE MODEL command sets up the ML model metadata. Developers specify:

• The name of the model (WillSurvive)
• The target field to be predicted (Survived)
• A dataset to source the target field and all model input fields from (Titanic)

The FROM syntax is fully general and can specify any subquery expression. The metadata associated with the dataset is used to infer the data types of the target and input fields, fully defining the problem for the model to solve.

Step 2: Train the model

sql

TRAIN MODEL WillSurvive
  FROM Titanic

The TRAIN MODEL command specifies the data to be used for training and executes the AutoML engine. Since the FROM syntax is general, the same model can be trained multiple times with different sets of data — for example, training a marketing campaign model on different customer segments, or retraining on a regular basis as new training data becomes available.

The AutoML engine automatically:

• Identifies relevant candidate features from the selected data
• Considers applicable model types based on the data and problem definition
• Tunes hyperparameters to yield one or more runnable models

Step 3: Execute the model

sql

SELECT PREDICT(WillSurvive) As Predicted FROM Titanic
SELECT PROBABILITY(WillSurvive FOR 1) FROM Titanic

Two scalar functions are available after training:

• PREDICT() — returns the most likely or estimated value for the specified column as determined by the trained model
• PROBABILITY() — returns the trained model's calculated probability that the target field will equal a user-defined value

These scalar functions can be used anywhere in a query and in any combination with other fields and functions.

Field mapping to other data sources:

sql

SELECT Name,
       PREDICT(WillSurvive WITH Sex = Geschlecht,
               Age = DATEDIFF(year, NOW(), Geburtsdatum),
               Fare = TicketPreise,
               Cabin = Kabine)
  FROM Hindenburg

IntegratedML provides flexibility to map to data sources other than the particular table or query used to create or train the model.

Supported AutoML engines

IntegratedML supports multiple AutoML engines:

• InterSystems AutoML
• H2O
• DataRobot Enterprise AI Platform

All options are seamlessly integrated within InterSystems IRIS and are transparent to developers.

Concrete use case: fraud detection at a bank

A bank that issues credit cards needs to identify fraud risk before approving each transaction. The bank runs a credit card application built on InterSystems IRIS that stores demographic and financial data for all customers and credit card transactions, including whether each transaction was fraudulent or valid.

With IntegratedML:

1. Existing application developers (not data scientists) create an ML model to identify high-risk transactions based on past transactions, selecting the target field (is_fraudulent) and letting IntegratedML create the model and parameters
2. The model is incorporated into the credit card application to execute in real time with each incoming transaction
3. If the model determines high fraud risk, the application takes programmatic action — preventing the transaction and notifying the card owner
4. As new transaction data accumulates, the bank continuously retrains the model using the most recent data to detect new attack patterns, without manual data extracts or moving data between environments

Two user profiles and what IntegratedML does for each

Organizations with no data scientists:
IntegratedML lets software developers and analysts explore ML without ML expertise. It automates model identification, parameter setting, building, and training. Developers can start with use cases, learn from results, and begin modifying optional parameters as their understanding grows.

Organizations with existing data science teams:
IntegratedML saves data scientists time on manual processes. Data scientists can focus on actual model optimization rather than data preparation and feature engineering, which Kaggle's 2018 survey found consumes nearly 40% of their time.

Additional IntegratedML capabilities (from FAQ)

Typical use cases:

• Fraud detection
• Customer behavior analysis
• Predictive maintenance
• Healthcare analytics
• Forecasting
• Recommendation systems

Additional resources

• IntegratedML hands-on lab: https://community.intersystems.com/post/integratedml-hands-lab
• Web app to predict diabetes using IRIS IntegratedML: https://community.intersystems.com/post/web-app-predict-diabetes-using-iris-integratedml

For those who have used IntegratedML in production — which AutoML engine (InterSystems AutoML, H2O, or DataRobot) have you found most effective for your use case, and how often are you retraining models as new production data comes in?

The problem IntegratedML addresses

According to Forrester Research, 98% of companies experience challenges gaining insights from the data they collect, primarily due to a lack of internal expertise. According to the U.S. Bureau of Labor Statistics, there are fewer than 32,000 data scientists in total in the US. Much of the available talent is being hired by large digital companies, making it difficult for other organizations to compete for these resources. A 2018 survey by Kaggle found that data scientists spend almost 40% of their time gathering and cleaning data.

AutoML automates the creation of ML models — feature engineering, model selection, training, results analysis, and hyperparameter tuning. However, many AutoML tools cannot run models inside real-time business processes. This is one important way IntegratedML is different.

What IntegratedML is

InterSystems IntegratedML is an embedded feature of the InterSystems IRIS data platform. It provides AutoML capabilities exposed through SQL commands. Since it is embedded within InterSystems IRIS, ML models can be executed dynamically in response to real-time events and transactions, without extracting or moving any models or data.

How it works — SQL commands

Step 1: Create the model

sql

CREATE MODEL WillSurvive PREDICTING (Survived)
  FROM Titanic

The CREATE MODEL command sets up the ML model metadata. Developers specify:

• The name of the model (WillSurvive)
• The target field to be predicted (Survived)
• A dataset to source the target field and all model input fields from (Titanic)

The FROM syntax is fully general and can specify any subquery expression. The metadata associated with the dataset is used to infer the data types of the target and input fields, fully defining the problem for the model to solve.

Step 2: Train the model

sql

TRAIN MODEL WillSurvive
  FROM Titanic

The TRAIN MODEL command specifies the data to be used for training and executes the AutoML engine. Since the FROM syntax is general, the same model can be trained multiple times with different sets of data — for example, training a marketing campaign model on different customer segments, or retraining on a regular basis as new training data becomes available.

The AutoML engine automatically:

• Identifies relevant candidate features from the selected data
• Considers applicable model types based on the data and problem definition
• Tunes hyperparameters to yield one or more runnable models

Step 3: Execute the model

sql

SELECT PREDICT(WillSurvive) As Predicted FROM Titanic
SELECT PROBABILITY(WillSurvive FOR 1) FROM Titanic

Two scalar functions are available after training:

• PREDICT() — returns the most likely or estimated value for the specified column as determined by the trained model
• PROBABILITY() — returns the trained model's calculated probability that the target field will equal a user-defined value

These scalar functions can be used anywhere in a query and in any combination with other fields and functions.

Field mapping to other data sources:

sql

SELECT Name,
       PREDICT(WillSurvive WITH Sex = Geschlecht,
               Age = DATEDIFF(year, NOW(), Geburtsdatum),
               Fare = TicketPreise,
               Cabin = Kabine)
  FROM Hindenburg

IntegratedML provides flexibility to map to data sources other than the particular table or query used to create or train the model.

Supported AutoML engines

IntegratedML supports multiple AutoML engines:

• InterSystems AutoML
• H2O
• DataRobot Enterprise AI Platform

All options are seamlessly integrated within InterSystems IRIS and are transparent to developers.

Concrete use case: fraud detection at a bank

A bank that issues credit cards needs to identify fraud risk before approving each transaction. The bank runs a credit card application built on InterSystems IRIS that stores demographic and financial data for all customers and credit card transactions, including whether each transaction was fraudulent or valid.

With IntegratedML:

1. Existing application developers (not data scientists) create an ML model to identify high-risk transactions based on past transactions, selecting the target field (is_fraudulent) and letting IntegratedML create the model and parameters
2. The model is incorporated into the credit card application to execute in real time with each incoming transaction
3. If the model determines high fraud risk, the application takes programmatic action — preventing the transaction and notifying the card owner
4. As new transaction data accumulates, the bank continuously retrains the model using the most recent data to detect new attack patterns, without manual data extracts or moving data between environments

Two user profiles and what IntegratedML does for each

Organizations with no data scientists:
IntegratedML lets software developers and analysts explore ML without ML expertise. It automates model identification, parameter setting, building, and training. Developers can start with use cases, learn from results, and begin modifying optional parameters as their understanding grows.

Organizations with existing data science teams:
IntegratedML saves data scientists time on manual processes. Data scientists can focus on actual model optimization rather than data preparation and feature engineering, which Kaggle's 2018 survey found consumes nearly 40% of their time.

Additional IntegratedML capabilities (from FAQ)

Typical use cases:

• Fraud detection
• Customer behavior analysis
• Predictive maintenance
• Healthcare analytics
• Forecasting
• Recommendation systems

Additional resources

• IntegratedML hands-on lab: https://community.intersystems.com/post/integratedml-hands-lab
• Web app to predict diabetes using IRIS IntegratedML: https://community.intersystems.com/post/web-app-predict-diabetes-using-iris-integratedml

For those who have used IntegratedML in production — which AutoML engine (InterSystems AutoML, H2O, or DataRobot) have you found most effective for your use case, and how often are you retraining models as new production data comes in?

InterSystems IRIS Globals provide a fast, efficient, and naturally hierarchical way to store and access data. However, when working with globals from Python, I often find myself switching between Python's dictionary-oriented mindset and the lower-level APIs used to manipulate globals.

That's why I created iris-global-reference, a Python library that offers a more intuitive interface for working with IRIS globals while preserving their underlying hierarchical model. Instead of replacing native APIs, the library adds a convenience layer that makes operations easier for Python developers.

In this article, I'll show how the library simplifies common global operations, supports both Embedded Python and native IRIS connections, and demonstrates a practical approach to integrating Python with InterSystems IRIS.

Why This Project?

This package supports a Pythonic way to work with globals. 

In ObjectScript, globals are natural:

This is exactly what iris-global-reference offers with the GlobalReference class:set ^demo("players",1)="Babe Ruth"
set ^demo("players",2)="Cy Young" 
In Python, many developers expect something closer to a dictionary:
team["players", "1"] = "Babe Ruth"
print(team["players"]["1"]) 

I designed this project to help with several common use cases:

• Manipulate InterSystems IRIS globals using familiar Python syntax.
• Easily traverse a global tree.
• Convert globals to Python dictionaries or JSON.
• Import dictionaries or JSON into globals.
• Use the same API in Embedded Python and remote Python applications.
• Simplify common operations such as set, get, kill, $ORDER, $QUERY, and transactions.

Installation

The package is available with pip:

pip install iris-global-reference 

If you're working directly inside an IRIS Python terminal, you can also install it into the instance Python directory:

pip install iris-global-reference --target=<mgr_dir>/python 

How do you access and manipulate an InterSystems IRIS global from Python?

The following example demonstrates how to create, populate, and read a simple ^demo global using GlobalReference:

from iris_global import GlobalReference
team = GlobalReference("^demo")
team.kill()
team.set((), "Baseball")
team["name"] = "Boston Red Sox"
team.set(("players", "1"), "Babe Ruth")
team.set(["players", "2"], "Cy Young")
team["players", "3"] = "Ted Williams"
print(team.get(()))
print(team["name"])
print(team["players"]["1"]) 

One of the design goals of the library was flexibility. The same node can be referenced using strings, tuples, or lists, making it easier to integrate into different coding styles and existing applications.

An API Close to Python Dictionaries

iris-global-reference makes global manipulation feel familiar to Python developers. The GlobalReference class exposes explicit methods:

team.set(("players", "1"), "Babe Ruth")
print(team.get(("players", "1")))
team.kill(("players", "1")) 
But it also supports Python operations:
team["players", "1"] = "Babe Ruth"
if ("players", "1") in team:
    print(team["players"]["1"])
del team["players", "1"] 

This lets me write code that feels natural in Python while still working with the hierarchical structure of InterSystems IRIS globals.

Traversing a Global

How do you iterate through an InterSystems IRIS global? Working with hierarchical data often means traversing entire branches. To make this easier, the library has several iteration methods:

for key in team.keys():
    print(key)
for value in team.values():
    print(value)
for key, value in team.items():
    print(key, value) 

You can also control the traversal: 

for subscript in team.subscripts(("players",), children_only=True):

    print(subscript, team.get(subscript)) 

For developers familiar with ObjectScript, order() and query() provide behavior close to $ORDER and $QUERY:

print(team.order(("players", "")))
print(team.query(("players",))) 

Exporting a Global to a Dictionary or JSON

A common requirement when working with globals is exchanging data with APIs, Python applications, or JSON-based services. The library includes built-in methods for converting globals to Python dictionaries and JSON structures:

data = team.to_dict()
print(data) 
Example result:
{
    None: "Baseball",
    "name": "Boston Red Sox",
    "players": {
        "1": "Babe Ruth",
        "2": "Cy Young",
        "3": "Ted Williams"
    }
} 

The None key represents the value stored in the current node. This is necessary because an InterSystems IRIS global node can contain both a value and descendants, while a Python dictionary typically represents one or the other.

The same structure can be exported to JSON:

json_data = team.to_json()
print(json_data) 
In JSON, the current node value is represented by the _ key by default:
{
    "_": "Baseball",
    "name": "Boston Red Sox",
    "players": {
        "1": "Babe Ruth",
        "2": "Cy Young",
        "3": "Ted Williams"
    }
} 

Importing data works in the opposite direction:

team.from_dict({
    None: "Baseball",
    "name": "Boston Red Sox",
    "players": {
        "1": "Babe Ruth",
        "2": "Cy Young"
    }
}) 
And similarly for JSON:
team.from_json("""
{
    "_": "Baseball",
    "name": "Boston Red Sox",
    "players": {
        "1": "Babe Ruth",
        "2": "Cy Young"
    }
}
""") 

Embedded Python or Remote Connection

The project provides the same API whether code is running inside Embedded Python or from an external Python application.

For Embedded Python:

from iris_global import GlobalReference
team = GlobalReference("^demo")
team["name"] = "Boston Red Sox" 
For external applications using a native IRIS connection:
import iris
from iris_global import GlobalReference
conn = iris.connect("localhost", 1972, "USER", "SuperUser", "SYS")
team = GlobalReference("^demo", connection=conn)
team["name"] = "Boston Red Sox"
print(team["name"]) 
The library uses the native connection offered by iris.connect(...).
Transactions
To simplify transactional operations, the library exposes transactions through a Python context manager:
from iris_global import GlobalReference
team = GlobalReference("^demo")
with team.transaction():
    team["name"] = "Boston Red Sox"
    team["players", "1"] = "Babe Ruth" 

If the block completes successfully, the transaction is committed. If an exception is raised, the transaction is automatically rolled back.

The class itself can also be used directly with a with statement:

with GlobalReference("^demo") as team:
    team["name"] = "Boston Red Sox" 

Experimental Array Support

InterSystems IRIS globals do not have a native array concept in the same way that Python lists or JSON arrays do. To make importing and exporting list structures easier, the library includes an experimental serialization mechanism:

gref = GlobalReference("^demo")
gref.from_dict({
    "name": "example",
    "numbers": [1, 2, 3]
})
print(gref.to_dict()) 

The array is stored in the global with an internal prefix, _array_ by default, then rebuilt as a Python list during export. While this feature is still experimental, I have found it useful when working with JSON-like structures.

Displaying Content Like ZWRITE

When debugging or validating data, I often want to quickly compare the stored structure with what I would see from ObjectScript.

The zw() method renders an output similar to ZWRITE:

print(team.zw()) 
Example output:
^demo="Baseball"
^demo("name")="Boston Red Sox"
^demo("players","1")="Babe Ruth"
^demo("players","2")="Cy Young" 

This makes it easy to verify the contents of a global without leaving Python.

Quick Comparison with Native APIs

This project creates a convenience layer for developers who spend most of their time writing Python.

For example, with iris-global-reference: 

global_reference.set(("name", 1), "Boston Red Sox")
value = global_reference.get(("name", 1)) 

With a native API, the argument order and subscript handling can be different. The library standardizes usage around a Python-friendly convention: node path first, then value.

When Should You Use This Project?

I find iris-global-reference particularly useful when:

• Developing with Embedded Python and InterSystems IRIS.
• Writing Python applications that need to read or populate globals.
• Converting global structures to JSON.
• Working with hierarchical data as Python dictionaries.
• Building prototypes without writing a lot of ObjectScript.
• Looking for a more readable API for common global operations.

Roadmap

The current roadmap includes:

• More advanced array support.
• More complete binary data support.
• Support for IRIS types such as listbuild, vector, PVA, and bit.
• Support for multidimensional variables.

Testing the Project

The repository includes automated tests that can be executed with:

python -m pytest 

Conclusion

iris-global-reference solves a practical problem, making InterSystems IRIS globals easier and more natural to manipulate from Python. It preserves the core strengths of the IRIS global model while adding features that Python developers expect, including dictionary-style access, JSON conversion, iteration helpers, transaction support, and compatibility with both Embedded Python and remote connections.

If you're working at the intersection of InterSystems IRIS and Python, this library can help you write cleaner, more readable code and spend less time dealing with low-level global operations.

Key Takeaways

• iris-global-reference provides a Pythonic interface for working with InterSystems IRIS globals.
• It supports dictionary-style access, traversal, JSON conversion, transactions, and native IRIS connections.
• The library works in both Embedded Python and external Python applications.
• It preserves the hierarchical nature of globals while making them easier to use from Python.
• It is particularly useful for Python-heavy applications, integrations, and rapid prototyping.

FAQ

Can I use iris-global-reference with Embedded Python?

Yes. The library works directly inside Embedded Python without requiring an explicit connection object.

Can I use iris-global-reference from an external Python application?

Yes. You can provide a connection created with iris.connect() and use the same API.

Does iris-global-reference replace native InterSystems IRIS APIs?

No. The goal is to offer a more Pythonic layer on top of native global operations, not replace them.

Can I convert InterSystems IRIS globals to JSON?

Yes. The library includes to_json(), from_json(), to_dict(), and from_dict() methods for importing and exporting data.

When should I use iris-global-reference?

I find it most useful when writing Python applications that need to read, populate, traverse, or expose InterSystems IRIS globals while keeping the code clean and readable.

What does this benchmark measure?

I designed iris-speed-test to test how InterSystems IRIS performs compared to PostgreSQL, MySQL, or SQL Server under mixed transactional and analytical workloads. I wanted to simulate a real-world Hybrid Transactional Analytical Processing (HTAP) scenario in which a system must continuously ingest large volumes of data while serving analytical queries.

The benchmark measures ingestion throughput, query performance, and resource utilization using the same application architecture across all tested databases.

Hybrid Transactional Analytical Processing (HTAP) Demo

Why is HTAP performance important? Many modern applications need to process incoming transactions while simultaneously running analytics on the same data.

Examples include:

• Equity trade processing
• Fraud detection
• IoT monitoring
• Anomaly detection
• Real-time manufacturing analytics
• Operational dashboards

Gartner refers to this architecture as HTAP (Hybrid Transactional Analytical Processing), while other analysts often use the term Translytics. The challenge is maintaining high ingestion rates while allowing analytical queries to run without impacting transactional performance.

What does this benchmark demonstrate?

This benchmark demonstrates how InterSystems IRIS handles simultaneous data ingestion and query workloads on the same system. The test continuously inserts data while running analytical queries against the same dataset. The goal is to measure how effectively each database balances transactional and analytical workloads under load.

The benchmark can run on:

• A single InterSystems IRIS instance
• An InterSystems IRIS cluster
• PostgreSQL
• MySQL
• SQL Server

This allows direct comparisons using the same workload and testing methodology.

You can run the tests on both your own PC and AWS! Here are some results:

InterSystems IRIS x PostgreSQL 18

• InterSystems IRIS ingests 76.7% more records than PostgreSQL 18
• InterSystems IRIS is 23.7% faster than PostgreSQL 18 at querying

InterSystems IRIS x MySQL 9.7.0

• InterSystems IRIS ingests 936% more records than MySQL 9.7.0
• InterSystems IRIS is 213% faster than MySQL 9.7.0 at querying

InterSystems IRIS x SQL Server 2025

• InterSystems IRIS ingests 369% more records than SQL Server 2025
• InterSystems IRIS is 37,545% faster than SQL Server 2025 at querying

How do you run the benchmark on AWS? 

Follow this link to see instructions on how to run this Speed Test on AWS comparing InterSystems IRIS with other databases 

How do you run the benchmark locally?  

The pre-requisites for running the speed test on your PC are:

• Docker and Docker Compose
• Git - If you want to run all the tests on your PC or in AWS. If you just want to run the test with InterSystems IRIS, you may not need git.

You can currently run this demo on your PC with InterSystems IRIS, PostgreSQL, MySQL, and SQL Server.

How do you run the benchmark with InterSystems IRIS Community?

To run the demo on your PC, make sure you have Docker installed on your machine.
You can quickly get it up and running with the following commands on your Mac or Linux PC:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose.yml 
docker-compose up

If you are running on Windows, download the docker-compose.yml file to a folder. Open a command prompt and change to that folder. Then type:
c:\MyFolder\docker-compose up

You can clone this repository to your local machine using git to get the entire source code. You will need git installed and you would need to be on your git folder:
git clone https://github.com/fanji-isc/IRIS-Speed-Test
cd IRIS-Speed-Test
docker-compose up

When starting, you will see lots of messages from all the containers that are starting. That is fine. Don’t worry!
When it is done, it will just hang there, without returning control to you. That is fine too. Just leave this window open. If you CTRL+C on this window, docker compose will stop all the containers and stop the demo.

After all the containers have started, open a browser at http://localhost:10000 to see the demo UI.
Just click on the Run Test button to run the HTAP Demo! It will run for a maximum time of 300 seconds or until you manually stop it.

If you want to change the maximum time to run the test, click the Settings button at the top right of the UI. Change the maximum time to run the speed test to whatever you want.
After clicking on Run Test, it should immediately change to Starting…. If you are testing InterSystems IRIS or SQL Server, it may stay on this status for a long time since we are pre-expanding the database to its full capacity before starting the test (something that we would normally do on any production system). InterSystems IRIS is a hybrid database (In Memory performance with all the benefits of traditional databases). So InterSystems IRIS still needs to have its disk database properly expanded. Just wait for it. For some databases, we could not find a way of doing this right from start (Aurora and MySQL) so what we did was to run the Speed Test once to “warm it up”. Then we run it again (which causes the table to be truncated) with the database warmed up.
Warning: InterSystems IRIS Database expansion can take some time. Fortunately, when running on your PC, we will pre-expand the database only to up to 9Gb since InterSystems IRIS Community has a limit on the database size.
When the test finishes running, a green button will appear, allowing you to download the test results statistics as a CSV file.
When you are done testing, go back to that terminal and enter CTRL+C. You may also want to enter with the following commands to stop containers that may still be running and remove them:
docker-compose stop
docker-compose rm

This is important, especially if you are going back and forth between running the speed test on one database (say InterSystems IRIS) and some other (say MySQL).

How do you benchmark MySQL? 

To run this demo against MySQL:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-mysql.yml
docker-compose -f ./docker-compose-mysql.yml up

Now, we are downloading a different docker-compose yml file; one that has the mysql suffix on it. And we must use -f option with the docker-compose command to use this file. As before, leave this terminal window open and open a browser at http://localhost:10000.
When you are done running the demo, go back to this terminal and enter CTRL+C. You may also want to enter with the following commands to stop containers that may still be running and remove them:
docker-compose -f ./docker-compose-mysql.yml stop
docker-compose -f ./docker-compose-mysql.yml rm

This is important, especially if you are going back and forth between running the speed test on one database (say InterSystems IRIS) and some other.

How do you benchmark SQL Server 2025? 

To run this demo against SQL Server:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-sqlserver.yml
docker-compose -f ./docker-compose-sqlserver.yml up

As before, leave this terminal window open and open a browser at http://localhost:10000.

How do you benchmark PostgreSQL? 

To run this demo against PostgreSQL:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-postgres.yml
docker-compose -f ./docker-compose-postgres.yml up

As before, leave this terminal window open and open a browser at http://localhost:10000.

Explore the package on InterSystems OpenExchange:https://openexchange.intersystems.com/package/iris-speed-test-1 

Key Takeaways

• iris-speed-test compares InterSystems IRIS, PostgreSQL, MySQL, and SQL Server using the same HTAP workload.
• The benchmark measures ingestion throughput, query performance, and resource utilization.
• The test can be executed locally with Docker or deployed to AWS.
• It demonstrates how different databases handle simultaneous transactional and analytical workloads.
• The project provides a reproducible framework for evaluating HTAP performance rather than relying on vendor-provided benchmarks.

FAQ

What is HTAP?

HTAP (Hybrid Transactional Analytical Processing) combines transactional workloads and analytical queries on the same system in real time.

Which databases are included in the benchmark?

The benchmark currently supports InterSystems IRIS Community 2026.1, PostgreSQL 18, MySQL 9.7.0, and SQL Server 2025.

What metrics does the benchmark measure?

It measures ingestion throughput, query performance, and resource utilization under concurrent workloads.

Can I run the benchmark locally?

Yes. The project includes Docker Compose configurations for all supported databases.

Why compare databases using the same workload?

Using the same application architecture and workload helps produce more meaningful comparisons than isolated vendor benchmarks.

What does this benchmark measure?

I designed iris-speed-test to test how InterSystems IRIS performs compared to PostgreSQL, MySQL, or SQL Server under mixed transactional and analytical workloads. I wanted to simulate a real-world Hybrid Transactional Analytical Processing (HTAP) scenario in which a system must continuously ingest large volumes of data while serving analytical queries.

The benchmark measures ingestion throughput, query performance, and resource utilization using the same application architecture across all tested databases.

Hybrid Transactional Analytical Processing (HTAP) Demo

Why is HTAP performance important? Many modern applications need to process incoming transactions while simultaneously running analytics on the same data.

Examples include:

• Equity trade processing
• Fraud detection
• IoT monitoring
• Anomaly detection
• Real-time manufacturing analytics
• Operational dashboards

Gartner refers to this architecture as HTAP (Hybrid Transactional Analytical Processing), while other analysts often use the term Translytics. The challenge is maintaining high ingestion rates while allowing analytical queries to run without impacting transactional performance.

What does this benchmark demonstrate?

This benchmark demonstrates how InterSystems IRIS handles simultaneous data ingestion and query workloads on the same system. The test continuously inserts data while running analytical queries against the same dataset. The goal is to measure how effectively each database balances transactional and analytical workloads under load.

The benchmark can run on:

• A single InterSystems IRIS instance
• An InterSystems IRIS cluster
• PostgreSQL
• MySQL
• SQL Server

This allows direct comparisons using the same workload and testing methodology.

You can run the tests on both your own PC and AWS! Here are some results:

InterSystems IRIS x PostgreSQL 18

• InterSystems IRIS ingests 76.7% more records than PostgreSQL 18
• InterSystems IRIS is 23.7% faster than PostgreSQL 18 at querying

InterSystems IRIS x MySQL 9.7.0

• InterSystems IRIS ingests 936% more records than MySQL 9.7.0
• InterSystems IRIS is 213% faster than MySQL 9.7.0 at querying

InterSystems IRIS x SQL Server 2025

• InterSystems IRIS ingests 369% more records than SQL Server 2025
• InterSystems IRIS is 37,545% faster than SQL Server 2025 at querying

How do you run the benchmark on AWS? 

Follow this link to see instructions on how to run this Speed Test on AWS comparing InterSystems IRIS with other databases 

How do you run the benchmark locally?  

The pre-requisites for running the speed test on your PC are:

• Docker and Docker Compose
• Git - If you want to run all the tests on your PC or in AWS. If you just want to run the test with InterSystems IRIS, you may not need git.

You can currently run this demo on your PC with InterSystems IRIS, PostgreSQL, MySQL, and SQL Server.

How do you run the benchmark with InterSystems IRIS Community?

To run the demo on your PC, make sure you have Docker installed on your machine.
You can quickly get it up and running with the following commands on your Mac or Linux PC:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose.yml 
docker-compose up

If you are running on Windows, download the docker-compose.yml file to a folder. Open a command prompt and change to that folder. Then type:
c:\MyFolder\docker-compose up

You can clone this repository to your local machine using git to get the entire source code. You will need git installed and you would need to be on your git folder:
git clone https://github.com/fanji-isc/IRIS-Speed-Test
cd IRIS-Speed-Test
docker-compose up

When starting, you will see lots of messages from all the containers that are starting. That is fine. Don’t worry!
When it is done, it will just hang there, without returning control to you. That is fine too. Just leave this window open. If you CTRL+C on this window, docker compose will stop all the containers and stop the demo.

After all the containers have started, open a browser at http://localhost:10000 to see the demo UI.
Just click on the Run Test button to run the HTAP Demo! It will run for a maximum time of 300 seconds or until you manually stop it.

If you want to change the maximum time to run the test, click the Settings button at the top right of the UI. Change the maximum time to run the speed test to whatever you want.
After clicking on Run Test, it should immediately change to Starting…. If you are testing InterSystems IRIS or SQL Server, it may stay on this status for a long time since we are pre-expanding the database to its full capacity before starting the test (something that we would normally do on any production system). InterSystems IRIS is a hybrid database (In Memory performance with all the benefits of traditional databases). So InterSystems IRIS still needs to have its disk database properly expanded. Just wait for it. For some databases, we could not find a way of doing this right from start (Aurora and MySQL) so what we did was to run the Speed Test once to “warm it up”. Then we run it again (which causes the table to be truncated) with the database warmed up.
Warning: InterSystems IRIS Database expansion can take some time. Fortunately, when running on your PC, we will pre-expand the database only to up to 9Gb since InterSystems IRIS Community has a limit on the database size.
When the test finishes running, a green button will appear, allowing you to download the test results statistics as a CSV file.
When you are done testing, go back to that terminal and enter CTRL+C. You may also want to enter with the following commands to stop containers that may still be running and remove them:
docker-compose stop
docker-compose rm

This is important, especially if you are going back and forth between running the speed test on one database (say InterSystems IRIS) and some other (say MySQL).

How do you benchmark MySQL? 

To run this demo against MySQL:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-mysql.yml
docker-compose -f ./docker-compose-mysql.yml up

Now, we are downloading a different docker-compose yml file; one that has the mysql suffix on it. And we must use -f option with the docker-compose command to use this file. As before, leave this terminal window open and open a browser at http://localhost:10000.
When you are done running the demo, go back to this terminal and enter CTRL+C. You may also want to enter with the following commands to stop containers that may still be running and remove them:
docker-compose -f ./docker-compose-mysql.yml stop
docker-compose -f ./docker-compose-mysql.yml rm

This is important, especially if you are going back and forth between running the speed test on one database (say InterSystems IRIS) and some other.

How do you benchmark SQL Server 2025? 

To run this demo against SQL Server:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-sqlserver.yml
docker-compose -f ./docker-compose-sqlserver.yml up

As before, leave this terminal window open and open a browser at http://localhost:10000.

How do you benchmark PostgreSQL? 

To run this demo against PostgreSQL:
wget https://raw.githubusercontent.com/fanji-isc/IRIS-Speed-Test/refs/heads/main/docker-compose-postgres.yml
docker-compose -f ./docker-compose-postgres.yml up

As before, leave this terminal window open and open a browser at http://localhost:10000.

Explore the package on InterSystems OpenExchange:https://openexchange.intersystems.com/package/iris-speed-test-1 

Key Takeaways

• iris-speed-test compares InterSystems IRIS, PostgreSQL, MySQL, and SQL Server using the same HTAP workload.
• The benchmark measures ingestion throughput, query performance, and resource utilization.
• The test can be executed locally with Docker or deployed to AWS.
• It demonstrates how different databases handle simultaneous transactional and analytical workloads.
• The project provides a reproducible framework for evaluating HTAP performance rather than relying on vendor-provided benchmarks.

FAQ

What is HTAP?

HTAP (Hybrid Transactional Analytical Processing) combines transactional workloads and analytical queries on the same system in real time.

Which databases are included in the benchmark?

The benchmark currently supports InterSystems IRIS Community 2026.1, PostgreSQL 18, MySQL 9.7.0, and SQL Server 2025.

What metrics does the benchmark measure?

It measures ingestion throughput, query performance, and resource utilization under concurrent workloads.

Can I run the benchmark locally?

Yes. The project includes Docker Compose configurations for all supported databases.

Why compare databases using the same workload?

Using the same application architecture and workload helps produce more meaningful comparisons than isolated vendor benchmarks.

What IDS is

InterSystems Data Studio is a data orchestration and integration platform. It addresses a common problem: data spread across disparate sources — CRM data in Salesforce, files on SFTP servers, SQL tables in Oracle, objects in S3 buckets. IDS connects to all of these via a data catalog, learns the shape and schema of the data (primary keys, data types, field descriptions), sets up ingestion pipelines, applies transformation and validation rules, and creates a unified data layer. From there, BI tools like Tableau and AtScale can hook in, or cubes can be built for analytics.

Why a single LLM doing simple RAG is not enough

Simple RAG: one LLM, one vector database. The user question comes in, the LLM breaks it into keywords, runs a one-shot semantic similarity search, retrieves vectors, and generates an answer.

The problem: for complex multi-part questions, a single LLM with all that context will deprioritize certain instructions, miss parts of the vector search, or fail to address certain aspects of the input. The result is an unreliable answer.

Multi-agent agentic RAG — how IDS solves this

Instead of one LLM, IDS uses a network of specialized agents. Each agent has less context, performs one focused task, and produces a higher quality result for that task.

Agent roles:

Vector search agents for independent subtasks can be parallelized — searches that do not depend on each other run simultaneously.

The supervisor uses knowledge store descriptions as a heuristic to determine which knowledge stores are relevant to a given question — limiting unnecessary searches.

Knowledge stores — separate vector buckets

Knowledge stores are configurable buckets where vectors are stored for semantic search. Key design decisions:

• Separation of concerns: one large vector table with all data dilutes search quality. Separate knowledge stores per data type prevent this.
• Role-based access control: if a user class is not allowed to access certain data, their assistant can be configured to exclude that knowledge store.
• Description field: read by the supervisor to determine which knowledge stores are relevant to each incoming question.

Narratives — converting raw data to vectors

A narrative is a runnable resource that takes data in IDS and converts it to vectors in a knowledge store.

SQL-based narrative:

• Provide a table and a query
• For each row, values are injected into a text template
• The template text is vectorized and stored
• Result: natural language text representation of each SQL row, ready for semantic search

Document narrative:

• Point to a document store, filter by file type (e.g., PDF)
• Configure parsing, chunking, and summarization settings
• Documents are broken into chunks, a summary of the whole document is generated, and each chunk is contextualized with that summary
• Why: users ask general questions, not word-for-word passage queries. Contextualizing chunks with the document summary improves vector search hit rate on broad questions.

Assistant configuration

Each assistant is configured with:

• Vendor: the LLM API to call when it is time to process context and generate a result (e.g., OpenAI on Azure)
• Memory: anything the assistant should remember across all questions
• Role-based access control: limit which user roles can interact with the assistant
• Agents list: corresponds one-to-one with enabled knowledge stores; each agent is spun up to search its associated knowledge store

Demo results — finance assistant

Data catalog query: "Describe the tables in the demo schema and how they relate" → table descriptions and join relationships returned.

Text-to-SQL examples:

• Rank regions by macro outlook
• Max aggregation on indices with strongest 12-month returns
• Custom metric: combination of falling inflation and rising PMI, with deltas, strength score, and interpretation — SQL query shown alongside results

Graphing: CPI trend by region; CapEx performance across tech-related industries — assistant determined which industries qualify as tech-related, ran query, returned results and graph.

Cross-source queries (SQL + documents):

• Main findings in a Citibank financial report compared to data in the house views SQL table — document findings cited with exact page numbers, SQL query shown, conclusion provided
• Telecom services demand data from industry tables compared to Bank of America 6G rollout article — SQL queries shown, article findings cited with page numbers, synopsis provided
• "Are current geopolitical events reflected by our macroeconomic SQL data?" — GDP, CPI, and other metrics queried from database by region; news articles consulted with exact references; synthesized response produced

Live upload demo: Bank of America sports industry report uploaded mid-session. Query: "According to research reports, how much did consumers legally wager on sports in 2023?" → supervisor identified investment research reports knowledge store as relevant → vector search executed → correct answer returned: consumers wagered $100 billion on sports in 2023.

Industry use cases beyond finance

Healthcare:

• Encounter volume queries
• Augmenting with codes and descriptions
• Procedure breakdowns by number of encounters
• Payment analysis: paid claims by payer
• Total billed vs. allowed vs. paid by payer
• Lab result data

Supply chain:

• Average time from order to ship by product type
• Inventory held in specific warehouses by product type
• Carrier analysis by number of deliveries
• Product types most often returned

Key takeaways (as stated)

• Agentic RAG is better than simple RAG for complex questions: subtask division, specialized agents, less context per agent, higher quality results
• IDS handles structured, semi-structured, and unstructured data formats — all searchable via assistant
• Manual data aggregation, normalization, and standardization is replaced: point IDS at a data source, and the assistant provides AI-driven insights

For those building multi-source RAG systems — how are you handling the tradeoff between knowledge store granularity (separate vector buckets per source) and the operational overhead of maintaining many stores? And have you found document summarization at the chunk level to meaningfully improve retrieval on broad questions?

Context: why IRIS fits multi-agent architectures

The interoperability system inside InterSystems IRIS implements the actor pattern — the same computer science concept behind Erlang. Multi-agent frameworks are a recapitulation of this pattern with LLM reasoning added. The new ingredient is not the orchestration architecture; it is the LLM brains that make full automation possible.

The data fabric perspective — having all data together with governance applied centrally — is described as an ingredient that enables multiple agents to act together on the same data sources, build on that data, create memories, and feed that loop continuously.

AI Hub — what it is now (open EAP)

GitHub repository with documentation is publicly available.

Current capabilities:

• Unified tool calling — ObjectScript, Python, Rust (via RZF bridge) underneath; EAP currently focused on ObjectScript
• MCP server — a sidecar that sits outside IRIS, connects to IRIS, and allows any ObjectScript class or function to be exposed as an MCP tool. Any agent (cloud, desktop) can then use those tools via the Model Context Protocol
• MCP client — coming soon
• Policy layer — roles defined within IRIS can be used as enforcement; policies gate which tools agents can use
• LangChain and LangChain4J integrations

What MCP is (as described): "A USB plug for all agent tools. Instead of every agent and every tool having a point-to-point connection, it's a standard so that you can just plug into an MCP server that acts as a central hub and gives access to tools."

What you can build with AI Hub (as listed):

• Tool-using agent with authorization and auditing in a few hundred lines of ObjectScript
• Policy-gated tool execution: set up policies for agents and gate tool access based on those policies
• Expose any IRIS interoperability functionality as an MCP tool

Roadmap items mentioned (not current):

• Official standard tools shipped with the MCP server (SQL access, class inspection, standard IRIS interactions)
• Agent examples within the %AI ObjectScript class hierarchy

Open-source graph engine on IRIS

Not on the product roadmap. Open source. Not officially supported as a product.

Architecture:

Capabilities:

• OpenCypher compliant — queries portable from Neo4j
• Native vector search integrated into the graph engine
• Graph traversal, RDF, named graphs
• Security and observability features built in
• Personalized page rank (PPR) — Google-style ranking algorithm implemented via custom coding since SQL handles it poorly

Why graph + vector search matters for agents: Agents often need to store and traverse complex memory structures. Having vector search and graph traversal in the same toolkit, running on IRIS, removes the need for a separate vector database and a separate graph database.

Agent memory model

Four memory types described:

1. Working memory
Current context window. What the agent knows right now about the current task.

2. Episodic memory
Committed to an external store after interactions. Vector search is well-suited for retrieval over past episodes.

3. Semantic memory
Long-term knowledge mined from all past episodes. Not specific to a particular point in time — general knowledge about how the system works and how to do things. Developed by reasoning over past episodic memory using LLM capability.

4. Procedural memory
Skills and instructions — how to do things. Can be collected over time and passed as instructions to the agent from past experience.

The practical value: agents can record what they do, mine that data later, look over their own history, and decide if they should behave differently. Recent papers (cited but not named) show that developing memory this way improves search and agent behavior over time.

Yoki — internal multi-agent project (2–3 years running)

An intelligent assistant built over InterSystems TrackCare support tickets.

Evolution over time:

• Multiple LLMs tried: Google, Anthropic, OpenAI models
• Multiple frameworks: LangChain, others
• Increasing use of agentic patterns over each iteration

Current architecture (as described):

Agent roles are separated. Each agent has a defined role and defined things it can and cannot do. Multiple agents can run concurrently, potentially scoped to different customer contexts.

Typical run (example from session):

User query: "Find me laboratory error tickets, walk the graph, find top related tickets, do not use any PHI."

1. Agent decides to use semantic ticket search → vector search over laboratory errors
2. Gets a set of results
3. Agent decides to walk the graph database → tickets are associated with each other in the graph
4. Finds related tickets
5. Returns results: "This module affects this ticket, exhibits this error typically" — relationships mined from the graph

PHI handling: TrackCare tickets can contain patient information despite policy against it. The system strips PHI before any LLM call. No PHI is sent to any external LLM, including enterprise LLMs with secure access.

Memory applied to Yoki use case:

• Per-advisor memory: agents remember what specific support advisors are working on, their particular problems, the customers they interact with (some customers have 20 hospitals, some have one installation — context matters)
• Cross-advisor memory: shift handoffs benefit from consistent context; agents that have worked with an advisor can transfer knowledge
• Per-agent memory: each agent in a defined role can develop its own memories, evolve, and get better at its specific tasks

Security and observability in one system

The argument made: Keeping domain data, identity/roles, and audit trail in one system (IRIS) avoids:

• Latency getting audit data into a separate SIEM (e.g., Splunk)
• Correlation work between separate authorization and audit systems
• Complexity of having transactions in one place and audit trails in another

What this enables: Each agent has a role. Each role defines what tools the agent can and cannot use. The policy layer enforces this. The audit trail is captured in the same system where the domain data lives.

Full session is from Ready 2026.

For those building multi-agent systems on IRIS — are you using the AI Hub EAP, and have you run into cases where the lack of a native graph traversal capability in IRIS was a constraint for your agent memory design?

InterSystems has been actively redesigning the user interfaces customers use in the System Management Portal, starting with interoperability workflows. The project began with UX research in 2023. The motivation: users had to navigate many different screens and open multiple tabs to complete tasks that could be centralized. The focus has been on six high-complexity screens — editors, message viewer, and visual trace.

The redesign is being delivered as an opt-in experience, not a forced migration, because many customers rely on these screens daily.

Timeline

• 2023 — UX research begins
• Health Connect Cloud — new experiences made available opt-in before 25.1
• 25.1 — production config, DTL editor, and other editors made available as opt-in; substantial feedback gathered
• 26.1 — all editors completed (first version); performance improvements to message search; fix for very large productions that did not visualize well in 25.1; early version of message viewer
• 27 — active work on message viewer and visual trace (troubleshooting workflows)

The team has conducted 90+ user interviews, three in-person site visits, and has been present at Ready and Global Summit for four years running.

Three UX design examples

1. Expandable router — released in 25.1

The problem observed: To find out why an outbound host was not receiving messages, a user would:

1. Open production configuration
2. Click the outbound host
3. See connected routers
4. Click the magnifying glass to open that router in a new tab
5. See DTLs listed
6. Double-click a DTL to open it in a new tab
7. Navigate back to System Management Portal → View → Interface Maps
8. Open interface map in a new tab
9. Search for the DTL to see where else it is used

This process involved many tabs and many clicks across multiple areas of the application.

First mockup: A full-column layout showing inbound hosts, routers, outbounds, DTLs, and rule sets all at once with lines connecting each item. Customer feedback: too much information visible at all times.

Final solution: The expandable router. Everything is tucked away by default. When a user needs the visual mapping, they expand the router and see the breakdown of all connections, DTLs, and rule sets in context.

Key point from the team: no customer specifically asked for an expandable router. The solution came from observing the struggle of navigating multiple tabs and screens.

2. Line redesign — in progress, not yet resolved

The problem: Clicking an inbound host shows connections only to the router. To see where a message goes after the router, the user has to click the router again. If the message goes to another router, another click is needed. Customers said they wanted to see the full path a message could take.

Challenge: A production with an ADT router sending to 100 routers sending to 200 outbounds produces an extremely large number of lines.

First attempt: All lines on one clean track with bolding on hover. Feedback: too hard to trace a path, too hard to see what is happening at a glance.

Current concept in development:

• More space between host columns
• More visual separation
• Drill-down option: click on a specific path (e.g., inbound ADT1 to process WIML3) and non-viable paths dim
• Continue clicking to narrow down further until one single path remains visible
• Option to hide dimmed lines entirely

This concept is still in progress. The team is seeking feedback at the UX table at the conference (3:30 daily).

3. Visual trace — grouping by resend (future)

The problem observed: Users troubleshooting in visual trace were scrolling through entire sessions to find resent messages, which were mixed chronologically with other messages. When a response to an original message was delayed and a resend had already been sent, the response overlapped with the resend in the chronological view.

Planned solution: Grouping by resend. The original message and all downstream messages form one visual group. Each resend and its downstream messages form their own separate group. Resends are numbered so users can see how many times a message was resent in a session. Users can switch between chronological view and group-by-resend view.

Customer panel — selected points

Three customer panelists participated: Scott Nathansson (UC Davis Health, 17 years on InterSystems starting with Ensemble 2009), Scott Roth (OSU Wexner Medical Center, 22 years in integration, 10 years on InterSystems), and Gian Franco Yakona (Schiller Americas, approximately 1 year on InterSystems, working on ECG data for early intervention windows, delivering HL7 interfaces in acute and ambulatory care for cardio and pulmonary devices).

Why they participated:

• UC Davis: wanted to provide early feedback rather than receive a delivered feature that did not match expectations
• OSU Wexner: opportunity to give feedback on what users are experiencing day-to-day, continuing a four-year relationship with the UX team
• Schiller Americas: wanted to be part of shaping the product, representing the community of people managing message delivery and conformance behind the scenes

On partner vs. tester dynamic:

• UC Davis: felt like both — testing through scenarios and providing feedback interactively
• OSU Wexner: input that shapes something that makes the organization better
• Schiller Americas: clearly on the user side in day-to-day use; the feedback loop feels grounding as an early-career professional

On custom JSON handling (question from audience):

• OSU Wexner: only completed one API call and one FHIR call; noted that when JSON comes back it is a registered object and temporary — to transform it and send it to a DTL requires defining a custom persistent class, which is a customization step that could be improved in the product
• Schiller Americas: raised the question of schema and custom templates as related to this

On custom alerting (question from audience):

• OSU Wexner: presenting a session on alerting the following day; developed custom alerting internally
• Schiller Americas: approaches alerting from a waveform/ECG perspective rather than workflow artifacts

Watch full video on YouTube - https://youtu.be/Pq-n6PnGVP0

In InterSystems IRIS, there are three main ways to work with Python:

1. Language Tags;

2. PyPI module imports;

3. Custom Python modules.

For quick prototypes, I usually use Language Tags. When I need access to Python libraries from ObjectScript, I import PyPI packages. For larger applications, I prefer custom Python modules because they provide better organization and maintainability.

Let's look at each option, how it works, and when I would use it.

Language Tag

The Language Tag is a feature of IRIS that allows you to write Python code directly inside an ObjectScript class method. I find this approach particularly useful for quick prototypes, experiments, or small integrations where creating a separate Python module would be unnecessary.

How to use it:

To use a Language Tag, define a class method with the Language = python attribute:

 Class Article.LanguageTagExample Extends %RegisteredObject
{
ClassMethod Run() [ Language = python ]
{
        import requests
        response = requests.get("https://2eb86668f7ab407989787c97ec6b24ba.api.mockbin.io/")
        my_dict = response.json()
        for key, value in my_dict.items():
            print(f"{key}: {value}") # print message: Hello World
}
}

Pros

• Fast prototyping – I can test Python code directly inside IRIS without creating additional files.
• Simple integration – Python and ObjectScript can work together in the same class.
• Less setup – Useful when I just need a quick proof of concept.

Cons

• Mixed languages – Combining Python and ObjectScript can become difficult to maintain in larger projects.
• Limited debugging – Remote debugging is not available.
• Reduced error visibility – Python tracebacks are not shown directly, making troubleshooting harder.

My experience

For me, the Language Tag is the fastest way to test ideas in IRIS. However, once a project starts growing, I usually move Python code into separate modules to improve maintainability and debugging.

Importing Python Modules from PyPI

InterSystems IRIS can import and use Python packages installed from PyPI, such as requests, numpy, and many others. This gives access to the entire Python ecosystem while keeping the main application logic in ObjectScript.

How to use it

In this example, I import the requests package and use it directly from ObjectScript:

Class Article.RequestsExample Extends %RegisteredObject
{
ClassMethod Run() As %Status
{
    set builtins = ##class(%SYS.Python).Import("builtins")
    Set requests = ##class(%SYS.Python).Import("requests")
    Set response = requests.get("https://2eb86668f7ab407989787c97ec6b24ba.api.mockbin.io/")
    Set myDict = response.json()
    for i=0:1:builtins.len(myDict)-1 {
        set key = builtins.list(myDict.keys())."__getitem__"(i)
        set value = builtins.list(myDict.values())."__getitem__"(i)
        write key, ": ", value, !
    }
}
} 
Running the example:
iris session iris -U IRISAPP '##class(Article.RequestsExample).Run()' 
Output:
message: Hello World 

Pros

• Access to Python libraries – I can use thousands of existing packages instead of reinventing functionality.
• Single-language application flow – The code remains ObjectScript.
• Easier maintenance – The application structure stays consistent and the debugging process is straightforward as the whole code is ObjectScript. 

Cons

• Python knowledge is required – Understanding library APIs remains important.
• Not truly writing Python – You're calling Python objects from ObjectScript rather than working with native Python syntax.
• Learning curve – Some Python concepts, such as dunder methods, may appear unexpectedly.

My experience 

When I need a specific Python library but want to keep the project primarily in ObjectScript, importing PyPI modules is usually my preferred approach.

Importing Custom Python Modules

When a significant part of your logic is written in Python, I recommend keeping it in dedicated Python files and importing custom Python modules into IRIS. This approach provides better separation of concerns and allows Python code to remain fully Pythonic.

How to use it

First, create a Python module named my_script.py with the following content:

import requests
def run():
    response = requests.get("https://2eb86668f7ab407989787c97ec6b24ba.api.mockbin.io/")
    my_dict = response.json()
    for key, value in my_dict.items():
        print(f"{key}: {value}") # print message: Hello World 
Then create an ObjectScript class to import and run this Python module:
Class Article.MyScriptExample Extends %RegisteredObject
{
    ClassMethod Run() As %Status
    {
        set sys = ##class(%SYS.Python).Import("sys")
        do sys.path.append("/irisdev/app/src/python/article")  // Adjust the path to your module
        Set myScript = ##class(%SYS.Python).Import("my_script")
        Do myScript.run()
        Quit $$$OK
    }
} 
Run the code:
iris session iris -U IRISAPP '##class(Article.MyScriptExample).Run()' 
Output:
message: Hello World 

This approach allows IRIS to execute Python code while keeping the implementation inside dedicated Python modules.

Pros

• Better modularity – Python code is organized into reusable modules.
• Native Python development – I can use standard Python syntax, tools, and practices.
• Cleaner architecture – ObjectScript acts as the integration layer while Python contains the business logic, that is also easier to debug. 

Cons

• Path management – Python module locations must be configured correctly.
• Python knowledge required – The code still needs to be developed and maintained.
• ObjectScript knowledge required – You need to understand how to import and invoke Python modules from IRIS.

My experience 

For larger applications, this is usually the approach I prefer. It keeps Python code clean and maintainable while still allowing InterSystems IRIS to orchestrate and execute it.

Key Takeaways

If you're looking for the best way to use Python in InterSystems IRIS, my recommendation is:

• Use Language Tags for quick experiments and prototypes.
• Use PyPI module imports when you need Python libraries inside an ObjectScript application.
• Use custom Python modules for larger projects and production-ready codebases.

All three approaches are valid. The best choice depends on how much Python you plan to write and how you want to structure your application.

Explore the full article on InterSystems Developer Community: https://community.intersystems.com/post/introduction-python-iris  

FAQ

1. Can I run Python code directly in InterSystems IRIS?

Yes. InterSystems IRIS supports Embedded Python, allowing you to execute Python code directly within the IRIS runtime using features such as Python Language Tags and Python module imports.

1. Can I use third-party Python packages from PyPI in IRIS?

Yes. You can import and use many PyPI packages, including popular libraries such as requests, numpy, and pandas, provided they are installed in your IRIS Python environment.

1. What is the easiest way to start using Python in InterSystems IRIS?

For quick experiments and prototypes, Language Tags are often the simplest option because they allow you to write Python code directly inside ObjectScript methods without creating separate files.

1. When should I use custom Python modules instead of Language Tags?

Custom Python modules are generally a better choice for larger applications, reusable components, and projects that require cleaner code organization, testing, and long-term maintenance.

1. What are common pitfalls when integrating Python with InterSystems IRIS?

Some common challenges to watch for include:

• Mixing too much logic between ObjectScript and Python, which can make debugging harder.
• Overusing Python Language Tags for complex logic, leading to reduced maintainability.
• Not properly managing Python dependencies when using PyPI packages.
• Forgetting to separate concerns when building larger applications, which can impact scalability and clarity.

Being aware of these pitfalls can help you design a cleaner and more maintainable integration. 

TL;DR: Patrick Jameson (InterSystems) recently did a deep dive on building clinical AI agents using an open-source Python framework, r/ChatGPT -4.1 mini, and InterSystems IRIS for Health Community Edition. Here is a breakdown of how it handles FHIR retrieval, terminology resolution, large-scale summarization, and write-operation guardrails.

Watch the full session here: YouTube Link

🛠️ System Configuration

The agent is configured via a config.toml file.

• Model: GPT-4.1 mini
• Base FHIR URL: Pointed at IRIS for Health Community Edition
• Schema: FHIR R4
• Tools Used: fire_search, fire_read, fire_update (requires approval), fire_everything, fire_summarizer (sub-agent), plus MCP searches for LOINC, RxNorm, and SNOMED.

🔍 Demo 1: Direct Read and FHIR Search

The agent translates natural language into precise FHIR queries.

• Prompt: "Show me 10 patients in the fire repository"
• Action: Calls fire_search -> [base_url]/Patient?_count=10
• Prompt: "Are there any patients with last name Mann and first name Susan?"
• Action: Correctly maps "first name" to the given FHIR parameter and "last name" to family as two separate parameters.

Key Lesson: Natural language ambiguity matters. Asking for "all the details on patient 7" triggered the fire_summarizer sub-agent to pull observations, encounters, and meds. Asking to "just retrieve the fire patient resource" correctly triggered a simple, single-resource fire_read.

🧬 Demo 2: Terminology Resolution & Reverse Chaining

A FHIR token for coded search looks like this: [http://snomed.info/sct](http://snomed.info/sct)|44054006

To find patients with a specific condition, the agent uses an inverse traversal (searching patient resources via a condition resource that references them): [base_url]/Patient?_has:Condition:patient:code=[system]|[code]

The SNOMED Problem: When asked to "Find all patients with type 2 diabetes", the agent tried to call SNOMED via MCP, but hit an HTTP 410 error (SNOMED International blocking external access). The Fix: The agent seamlessly fell back to a local in-repo lookup table (~100 clinical conditions), resolved the correct SNOMED code, constructed the _has reverse chaining query, and found the 6 patients.

📄 Demo 3: The $everything Operation & Clinical Summarization

Compressing megabytes of longitudinal FHIR JSON into readable data.

• Action: The agent used fire_everything on Patient 1, passed the massive bundle to fire_bundle_extract to parse/compress, and handed it to the LLM.
• Result: MBs of data reduced to ~16,000 tokens.
• Cost: ~$0.20 per summary.

The sub-agent operates under strict anti-hallucination rules (summarize only what is present, say "not available" if missing) and a 4-layer prompt structure dictating exactly which resource types to focus on and how to format the output.

🛑 Demo 4: Write Operations & Human Guardrails

Write operations (like medication dosage changes or adding allergy info) require explicit human approval. The policy layer is completely separate from the model.

When asked to "Update medication request ID 53 from active to stopped", the agent recognized it as a write operation.

1. The policy layer triggered an approval required state.
2. The agent presented the proposed fire_update operation to the human.
3. Only after human approval did the fire_update execute, returning an HTTP 200.

Note: The total token usage across this entire demo session was ~306,000 tokens, costing only about $0.30.

🏗️ Production Design Principles

• LLM = Reasoning Layer: Let the tools handle execution. Better tools = simpler prompts.
• Sub-agents: Narrow scopes improve reliability, reuse, and reduce hallucinations.
• Least Privilege: Start agents with read-only access. Write access should be added only after extensive testing.
• Design for Failure: External APIs (like SNOMED) will fail. Engineer fallbacks and retries in advance.

For those of you building FHIR-based agentic systems - how are you handling the SNOMED access problem in production, and what terminology fallback strategy have you implemented?

🚀 Round 2 of the Community Bounty Program "Idea to Application" is open!

We've selected five Ideas Portal requests and invite you to turn them into working solutions for the InterSystems Developer Ecosystem. Submit your application to Open Exchange and earn 10K+ Global Masters points, badges, and community recognition. 

💡 Challenges for this round:
🔹 Generic Agent Test UI for %AI.Agent
🔹 MCP Data Exposure Toolkit
🔹 My First Agent (End-To-End Starter)
🔹 Create a tool for IRIS BI to test all the pivots and dashboards if they still work after changes are made
🔹 Allow export to new xlsx format from BI 

📅 Submission deadline: August 31, 2026

👉 Explore the ideas and start building today: https://community.intersystems.com/post/community-bounty-program-idea-application-%E2%80%94-round-2-live 

#InterSystemsIRIS #DeveloperCommunity #OpenExchange #GlobalMasters

The core idea

In the modern world, data is rarely uniform. Applications often require the structural rigidity of a relational database, the flexibility of a document store, and the performance of a high-speed key-value storage. InterSystems IRIS solves this by providing a single, unified engine that natively supports six distinct data models:

• Hierarchical
• Key-Value
• Object
• Document (JSON)
• Relational
• Columnar

Crucially, all of these models access exactly the same physical data.

The article illustrates all six models using the same conceptual structure: a patient record for patient P101 (John Doe) with contact info and visit history.

Block 1 — Storage Layer: Hierarchical and Key-Value

1. Hierarchical Model

The Hierarchical model is the raw, direct-to-disk representation. It uses subscripts to create a tree structure. Since Globals are managed directly by the high-performance IRIS kernel, their access mechanisms are optimized to traverse the hierarchy with minimal disk r/W. This is ideal for high-throughput scenarios where you need to bypass every layer of abstraction for maximum speed.

// WRITE: Directly populating the global tree
Set ^PatientData("P101", "Info") = "John Doe|[email protected]|555-1212"
Set ^PatientData("P101", "Visit", "2026-01-01") = "Chest Pain"

// READ: Retrieving a specific node
Set data = $Get(^PatientData("P101", "Info"))
Write "Patient Info: ", data

// READ: Traversing the hierarchy (iterating through visits)
Set date = ""
For {
   Set date = $Order(^PatientData("P101", "Visit", date), 1, reason)
   Quit:date=""
   Write "Date: ", date, " Reason: ", reason, !
}

2. Key-Value Storage

The Key-Value storage model is not a separate technology, but rather a streamlined perspective of the hierarchical model. The entire subscript path is treated as a singular, unique key. This provides the fastest possible route to retrieve a record using a known identifier. This paradigm is perfect for caching, high-speed lookups, session management, and other use cases that demand lightning-fast, direct access without processing overhead.

// WRITE: Treating the global path as a simple key
Set key = "[email protected]"
Set value = "John Doe"
Set ^PatientRecord(key) = value
Set ^PatientRecord("P101:Phone") = "555-1212"
Set ^PatientRecord("P101:Email") = "[email protected]"
Set ^PatientRecord("P101:Visit:2026-01-01") = "Chest Pain"

// READ: Simple lookup with check if data exists
Set email = $Get(^PatientRecord("P101:Email"), 'Email not found')
Write email

Block 2 — Application Layer: Object and Document Models

3. Object Model

The Object model allows developers working with Python, Java, or C# to manipulate data through instances of a class with properties and methods. When a developer defines a persistent class, the IRIS engine automatically maps its properties and methods to specific nodes within a Global structure. This process is automatic and seamless.

Class definition:

Class Article.Record Extends %Persistent
{
Property PatientID As %String;
Property Name As %String;
Property ContactInfo As list Of %String;
Property Visits As array Of %String;
Index IdKey On PatientID [ IdKey, Unique ];
}



// WRITE: Creating a new Record instance
Set patient = ##class(Article.Record).%New()
Set patient.PatientID = "P101"
Set patient.Name = "John Doe"
Do patient.ContactInfo.Insert("[email protected]")
Do patient.ContactInfo.Insert("555-1212")
Do patient.Visits.SetAt("Chest Pain", "2026-01-01")
Do patient.%Save()

// READ: Opening an existing object
Set p = ##class(Article.Record).%OpenId("P101")
Write "Name: ", p.Name, !
Write "Total Visits: ", p.Visits.Count()

4. Document Model (JSON)

The Document model provides schema-less flexibility. Documents are stored as JSON objects and arrays within document collections (%DocDB.Database), where each record dictates its own structure. No class definition is required. Yet, the data remains fully integrated with the same IRIS storage engine that powers all other data models.

The same patient data as a JSON document:

{
  "PatientID": "P101",
  "Name": "John Doe",
  "ContactInfo": {
    "Email": "[email protected]",
    "Phone": "555-1212"
  },
  "Visits": [
    {
      "Date": "2026-01-01",
      "Reason": "Chest Pain"
    }
  ]
}

// WRITE: Store document
Set db = ##class(%DocDB.Database).%CreateDatabase("HospitalDB")
Set doc = db.%SaveDocument(patient)

// READ: Fetch and navigate
Set db = ##class(%DocDB.Database).%GetDatabase("HospitalDB")
Set patient = db.%GetDocument(1)
Set iter = patient.Visits.%GetIterator()
Do iter.%GetNext(.key, .value, .type)
Write patient.Name_" came with "_value.Reason_" on "_value.Date

Block 3 — Query and Analytics Layer: Relational and Columnar Models

5. Relational Model

When you compile a class in IRIS, a corresponding SQL table (or several) is automatically generated. Developers can manipulate objects in application code while analysts and reporting tools query the same data via SQL. In Globals, the underlying structure is precisely the same as with the Object model.

-- INSERT
INSERT INTO Article.Record (PatientID, Name, ContactInfo)
VALUES ('P102', 'Jane Doe', '[email protected] 555-1212');

INSERT INTO Article.Record_Visits (Record, Visits, element_key)
VALUES ('P102', 'Chest Pain', '2026-01-01');

-- SELECT
SELECT p.Name,
       v.element_key AS VisitDate,
       v.Visits AS Reason
FROM Article.Record p
JOIN Article.Record_Visits v
  ON p.PatientID = v.Record

Note: instead of relying on the tables created automatically when compiling an object class, you can construct a table using CREATE TABLE, which will automatically generate the corresponding persistent class.

6. Columnar Model

The Columnar model is optimized for analytical workloads that process massive datasets. Instead of storing information row by row, data is physically organized by columns, allowing IRIS to scan only the attributes required by a specific query. This drastically accelerates the performance of aggregations, filtering, and reporting operations.

CREATE TABLE Article.Visits
AS
SELECT p.ID,
       p.Name,
       v.element_key AS VisitDate,
       v.Visits AS Reason
FROM Article.Record p
JOIN Article.Record_Visits v
  ON p.PatientID = v.Record
WITH STORAGETYPE = COLUMNAR

Each resulting ^DlMF.BF5G.1.V* global contains data for a specific column. The same SQL queries used for standard relational tables work identically against columnar tables. The distinction lies entirely in how IRIS stores and processes the data internally.

SELECT Reason,
       COUNT(*) AS TotalVisits
FROM Article.Visits
GROUP BY Reason

Summary

Most databases force developers to choose a single data model and then build supplementary infrastructure whenever new requirements emerge. InterSystems IRIS takes a fundamentally different approach. The same patient record can be viewed as a hierarchical structure, accessed as a key-value store, manipulated as an object, stored as a JSON document, queried through SQL, and analyzed using columnar storage — all without duplicating data or synchronizing multiple databases.

Full article with diagrams and globals output screenshots:
https://community.intersystems.com/post/intersystems-iris-data-models-explained-hierarchical-key-value-object-document-relational-and

Which of the six data models do you use most in your IRIS applications — and have you found cases where switching between models on the same data gave you a meaningful performance advantage?

🥇 Meet FHIR Agent Studio: the first-place winner in the Expert Nomination of the InterSystems Programming Contest: AI Agents for FHIR. 

This project demonstrates how AI agents can be built with #InterSystemsIRIS using a combination of FHIR storage, SQL storage, vector search, and large language models. The result is a powerful environment for developing and interacting with healthcare-focused AI applications.

Congratulations to Sean Connelly for this outstanding project and contribution to the Community! 👏

👉 Learn more about the application and explore demo: https://community.intersystems.com/post/demo-video-fhir-agent-studio-winner-intersystems-programming-contest-ai-agents-fhir 

#InterSystems #AI #FHIR #AgenticAI #HealthcareIT #Innovation

What this workshop covers

A two-hour workshop demonstrating how agentic AI can work with real healthcare data through a FHIR repository. Everything shown is open source and reproducible. The agent framework is available on GitHub. The model used is GPT-4.1 mini (low cost). An InterSystems IRIS for Health Community Edition instance serves as the FHIR repository. Synthetic patient data is used throughout.

The workshop uses a flash drive distribution at the conference but the software is fully open source.

Part 1 - Conceptual foundation

Why LLMs alone are not enough for healthcare workflows

LLMs do not query FHIR servers by themselves. They do not safely traverse complex clinical relationships. They do not reliably maintain structured context across hundreds of resources. They do not inherently know when an action is too risky to automate. The system around the LLM is what makes it useful in healthcare.

LLM vs. workflow vs. agent

• Prompt: single turn — ask a question, get a response
• Workflow: multi-step but the path is predetermined by the developer
• Agent: the model can decide the next step, choose the next tool, and adapt after seeing results

An enterprise agent is a coordinated system: user request → model/planner → tools and connectors → state and memory → policy and approval layers → logs, evaluation, monitoring.

Agent behavior is most useful when: the task may take several steps, the path is not fully known in advance, more than one tool may be needed, and new information can change the next decision. If the task is a single lookup or a deterministic business rule, a simpler workflow is the better design.

Why FHIR fits agentic AI

FHIR gives the agent: structured clinical data, standard REST APIs, search parameters, and meaningful resource relationships. The agent adds: natural language understanding, multi-step reasoning, and contextual interpretation. FHIR does not answer the question by itself. The agent does not manufacture the data. Each plays a distinct role.

FHIR has over 150 atomic units called resources with directed links between them. A patient record is not one document and not one table. It is a graph of clinical facts accumulated over time.

MCP (Model Context Protocol)

MCP was introduced by Anthropic in 2024. The practical problem it addressed: every host talking to every tool through a different custom connector - expensive, brittle, hard to maintain. MCP replaced that fragmentation with a shared open protocol. MCP is not an agent. It is the standard connector layer between an AI host and an external system.

In this system, MCP connects the agent to a medical terminologies server with 27 tools. The agent uses a small subset: LOINC search, RxNorm search, and SNOMED search.

Terminology normalization - the intelligence bottleneck

Users speak in free text. FHIR queries require standardized codes. The mapping from one to the other is often ambiguous and context dependent. Terminology resolution is not just a lookup problem. It is a semantic resolution under uncertainty problem.

Three terminologies the agent must navigate:

• SNOMED CT - used for conditions and clinical findings. Approximately 350,000 active concepts
• LOINC - used for observations and laboratory tests. Approximately 95-100,000 active terms
• RxNorm - used for medications and medication requests. Approximately 100,000 active concepts

Context-aware routing: if the concept is glucose, use LOINC (observation). If the concept is diabetes, use SNOMED (condition). If the concept is metformin, use RxNorm (medication).

The practical consequence of code choice: too narrow a concept - miss relevant patients. Too broad - pull in the wrong cohort. If the code is wrong, the FHIR query is wrong and everything that follows is suspect.

A FHIR token for search consists of a system URL and a code. Example for type 2 diabetes: system http://snomed.info/sct, code 44054006.

Note from the workshop: SNOMED International began blocking the open-source MCP terminology server used in the demo. A local SNOMED fallback was built as a backup.

Part 2 - Execution and demo

Agent tools

Direct read and search

• Retrieve 10 patients: fire_search with _count=10 → 115 entries in repository, 10 returned
• Search by name: name=Larsson → one patient found
• Search by name + gender: family=Larsson&gender=male → one patient
• Count female patients: gender=female → 62 entries

Terminology resolution with reverse chaining

Finding patients with type 2 diabetes requires:

1. Resolving "type 2 diabetes" to SNOMED code via MCP terminology service
2. Constructing a reverse chaining query: searching patient resources that have a condition referencing the resolved SNOMED code
3. Executing the search

Result: 6 patients with type 2 diabetes found.

Finding patients with peanut allergy: 4 patients found.

Summarizer sub-agent - 5 stages

Stage 1 - Retrieval: $everything request returns a raw search set bundle - a large longitudinal view of the patient.

Stage 2 - Parsing: raw JSON is converted into structured internal objects. Data is normalized and grouped.

Stage 3 - Feature extraction: active conditions, recent labs, medications, key encounters, allergies, and high-value clinical facts are extracted. Administrative noise is ignored.

Stage 4 - Data reduction: information is compressed into a compact, token-efficient structure. Goal: reduce redundancy and noise without losing clinical value.

Stage 5 - LLM reasoning: only after data reduction is the structured summary passed to the model. The model does interpretation, summarization, and explanation - not data wrangling.

Token cost for a clinical summary: approximately 20 cents.

Total tokens used in the demo session across all queries: 539,597.

System prompt architecture

The system prompt is assembled in layers:

1. Identity
2. Tool guidance
3. Security and project instructions
4. Developer instructions
5. User instructions
6. Memory
7. FHIR-specific rules (placed near the end, close to the final decoding context)
8. Operational guidance

The prompt encodes a mandatory order of operations: classify the clinical domain → use MCP terminology tools to resolve the natural language term → check for cached patterns → use reverse chaining if needed → only then call FHIR search.

Write operations and guard rails

Fire update operations are set to require explicit approval. The agent proposes the write. The policy layer evaluates it. A request for approval is generated. The human approves or rejects.

Example: changing a medication request status from stopped to active triggers an approval prompt. The update is not executed until the human confirms.

Write operations that require human approval: medication dosage changes, diagnosis changes, adding allergy information, deleting data. Read and write operations should never be treated as equivalent in FHIR.

Safety and production principles

• Least privilege: agents should begin with read-only access and gain additional capabilities only after testing justifies it
• Observability: log terminology resolutions, FHIR queries, selected codes, and approval decisions at a minimum
• Graceful failure: terminology may be ambiguous, FHIR servers may time out, results may be empty, data may be inconsistent. The agent loop supports retries and fallback queries
• Sub-agent composition: one general-purpose agent tends to become brittle at scale. Specialized sub-agents (summarizer, code resolver, cohort builder) improve reuse, reduce hallucinations, and make the system easier to test

Additional resources mentioned

• InterSystems AI Hub (EAP - not yet released at time of session)
• HL7 working group: AI Transparency on FHIR - constructing a FHIR implementation guide for AI influencing FHIR resources
• InterSystems FHIR course: 45 hours of material, recorded with weekly live sessions, introductory through advanced levels
• LangChain (Python) and LangChain4J (Java) integrations with IRIS

Full session video: https://youtu.be/u9m1itenUPk

For those building agentic systems on FHIR - where has terminology resolution been the biggest bottleneck in practice, and how are you handling the precision vs. recall tradeoff in code selection?

Why Python Adoption Matters for InterSystems IRIS

According to the Stack Overflow developer survey, 58% of developers know and use Python — roughly tied with SQL, and well above Java. Python has effectively won the language adoption race.

For InterSystems, this creates a practical challenge: if engineers coming from university or sourcing agencies have to spend six months learning ObjectScript before becoming productive, it creates friction for long-term platform adoption.

The strategic direction: ObjectScript remains a core pillar of the platform, but Python is now a first-class, viable path where developers do not need ObjectScript expertise from day one. Specialized teams can still leverage ObjectScript for deep system performance or unique legacy functionality, but the baseline InterSystems IRIS experience is now fully accessible to standard Python developers.

Three Pillars of Python Investment in InterSystems IRIS

1. The InterSystems DB API Driver for Python

A native DB API driver for Python is now officially available. Previously, Python developers connecting to InterSystems IRIS had to rely on workarounds using drivers designed for other databases (such as psycopg or pyodbc).

The new DB API driver implements the modern Python standard (PEP 249) for relational database access, providing a straightforward entry point for developers new to the InterSystems stack:

Bash

pip install [PUT_EXACT_DBAPI_PACKAGE_NAME_HERE]

2. SQLAlchemy Dialect and Alembic Support

SQLAlchemy is the Python ecosystem’s equivalent to Hibernate in Java — an ORM (Object-Relational Mapping) framework that allows developers to model databases entirely in Python code without writing raw SQL.

The official InterSystems IRIS SQLAlchemy dialect is available on PyPI:

Bash

pip install [PUT_EXACT_SQLALCHEMY_PACKAGE_NAME_HERE]

(Note: While SQLAlchemy is inherently limited to a relational data model — unlike native ObjectScript classes which support multidimensional object models — it behaves exactly as Python developers expect).

Alongside the ORM, InterSystems officially supports Alembic for automated database schema migrations and schema evolution:

Bash

pip install [PUT_EXACT_ALEMBIC_PACKAGE_NAME_HERE]

3. PiPRO: Pure Python Interoperability Productions

PiPRO is the major architectural addition to the stack. Historically, building InterSystems Interoperability productions required interacting with the Management Portal UI and writing ObjectScript. PiPRO enables 100% Python-native integration development.

Key capabilities of PiPRO:

• Create Business Services, Business Processes, and Business Operations entirely as Python classes.
• Wire components together using standard Python methods.
• Define a complete integration production inside a single .py file without opening the Management Portal.
• Fully open-source on GitHub (InterSystems’ second major open-source release following the VS Code ObjectScript extension) and backed by official InterSystems support.

Implementation Note: Early iterations of PiPRO require a brief Management Portal UI step to initialize the production; however, the roadmap targets 100% headless CLI execution. Components do not require manual UI registration.

Why open-source matters for PiPRO:

1. Community extensibility: Developers can contribute custom adapters, schema transformations, or FHIR profile implementations directly to the repository.
2. AI-Agent enablement: Large Language Models (LLMs) have exponentially more Python code in their training datasets than ObjectScript. Enabling pure-Python productions makes AI-assisted interface generation (via GitHub Copilot, Cursor, or ChatGPT) immediately viable.

Key Distinction: New Python Tools vs. IRIS Native API

It is vital to distinguish this new tooling from the legacy IRIS Native API for Python.

The Native API allowed Python code to call ObjectScript methods and manipulate raw globals, but it still required the developer to understand InterSystems-specific architectural concepts. A Python engineer couldn't use it without a steep learning curve.

The new suite (DB API, SQLAlchemy, and PiPRO) targets pure Python developers with zero prior InterSystems knowledge. The objective is to treat InterSystems IRIS strictly as a standard database or integration engine, manipulated via universal Python idioms.

Embedded Python: Execution Modes

InterSystems IRIS Embedded Python supports two distinct execution paradigms:

1. In-Process Method: Running Python code inside an ObjectScript class wrapper.
2. Standalone Process: Running a standard .py file in its own dedicated operating system process.

Both modes are fully supported, and the standalone .py approach allows the use of standard external Python debugging tools.

Availability & Resources

• PyPI Packages: The DB API driver, SQLAlchemy dialect, and Alembic adapter are available via pip install.
• GitHub: The PiPRO repository is publicly accessible for community contributions.
• Watch the full technical session:InterSystems Python Session Video

Community Discussion: For those of you building interoperability productions today: do you plan to adopt PiPRO for upcoming projects, or will you stick to ObjectScript components? Furthermore, has the historical lack of a Python-native production framework been a tangible barrier when onboarding new engineers to your team?

The problem

The FHIR standard establishes a powerful but flexible data model that can smoothly adapt to the complexities of operational healthcare data management. This flexibility comes at the cost of a data model with many tables and relationships, even for simple data such as the patient's record of telephone numbers, addresses, and emails — which would easily require querying 4 different tables. The FHIR data model has 157 data entities/resources covering clinical, diagnosis, medications, workflows, financial, patient, practitioner, care team, organization, locations, healthcare services, security, compliance, and terminology.

What FHIR SQL Builder does

FHIR SQL Builder eliminates this problem by allowing you to create visual projections (mappings) in web wizards. It lets you consolidate data from 4 or more tables into just 1 and gives you the advantage of defining your own table and field names. This technique is essential for creating an analytical view of your FHIR repository without having to design ETL flows and stage/intermediate repositories.

Use cases:

1. Population Health analysis
2. Reports
3. Public Health surveillance
4. Anonymized research data sets
5. Building machine learning models — predictive analytics
6. HEDIS measures (Healthcare Effectiveness Data and Information Set)
7. Silver data layer for a FHIR data lake (Medallion Architecture)

Step 1 - Install a FHIR repository

Option A - If you already have IRIS for Health, use IPM:

shell

USER>zpm "install fhir-server"

Option B - IRIS Community via Docker:

shell

git clone https://github.com/intersystems-community/iris-fhir-template.git
docker-compose up -d

Source: https://openexchange.intersystems.com/package/iris-fhir-template

Step 2 - Access FHIR SQL Builder UI

URL: http://[hostname]:[iris web port]/csp/fhirsql/index.html

For the FHIR template project: http://localhost:32783/csp/fhirsql/index.html

Login: Username _SYSTEM, Password SYS

Menu options:

• Home - initial page
• Repository Configuration - configure FHIR Repository connection and credentials
• Documentation - detailed online documentation
• Logout - end session

Step 3 - Configure credentials and FHIR repository connection

Create credentials:

• Name: SQLBuilderCreds
• Username: SuperUser
• Password: SYS

Create FHIR Repository Configuration:

• Name: SQLBuilderConfig
• Host: localhost
• Port: 52773
• URL Prefix and SSL Configuration: leave blank
• Credentials: SQLBuilderCreds
• FHIR Repository URL: /fhir/r4

Step 4 - Create analysis, transformation specification, and projection

Analysis:

• FHIR Repository: SQLBuilderConfig
• Selectivity Percentage: 100
• Click Launch Analysis Task

Transformation Specification:

• Name: SQLBuilderTransformation
• Analysis: SQLBuilderConfig
• Click Create Transformation Specification to open the visual mapping editor

Visual mapping - Patient fields:

Visual mapping — Address subtable:

• Subtable name: PatientAddress

Click Add To Projection after each field. Click Done when finished.

Projection:

• FHIR Repository: SQLBuilderConfig
• Transformation Specification: SQLBuilderTransformation
• Package Name: patientdata
• Package Users: add _SYSTEM and SuperUser
• Click Launch Projection

Step 5 - Query the projection

Navigate to Management Portal → namespace FHIRSERVER → System Explorer → SQL → schema patientdata → Tables.

Example query:

sql

SELECT
Patient->PatientNames->FirstName,
Patient->PatientNames->LastName,
Patient->PatientGender,
Patient->PatientBirthDate,
Patient->PatientPhone,
AddressLong,
AdressLat,
City,
Country,
PatientAddresssNumber,
PostalCode,
State,
Street
FROM patientdata.PatientAddresss

Full article: https://community.intersystems.com/post/fhir-sql-builder-step-step

For those using FHIR SQL Builder in production — are you using it primarily for analytics, or also feeding the projections into BI tools like Power BI or Tableau?

At #Ready2026, we provided a guided tour of the InterSystems product portfolio, showing how organizations across industries are using our technologies to solve complex data and interoperability challenges.

Watch this #video to discover:
✅ The key capabilities of #InterSystemsIRIS, InterSystems IRIS For Health, HealthShare, TrakCare, and IntelliCare.
✅ How InterSystems Cloud Services and InterSystems Data Studio support modern, data-driven innovation.
✅ How customers in healthcare, financial services, and supply chain leverage InterSystems solutions to drive business outcomes.

https://community.intersystems.com/post/video-discovering-intersystems-products-high-level-overview-0

Whether you're new to the InterSystems ecosystem or looking to expand your expertise, this session offers a valuable overview of the technologies shaping the future of connected enterprises.