DEV Community: InterSystems Developer

Model Context Protocol (MCP) with InterSystems IRIS - From Zero to Hero

InterSystems Developer — Sat, 31 Oct 2026 20:45:42 +0000

Introduction

Today, coding assistants like Claude, GitHub Copilot and Cursor have transformed the way developers write code. However, these tools are limited by being isolated from the systems and data sources that developers work with daily. This limitation can be overcome through the Model Context Protocol (MCP), an open standard designed to connect AI assistants to external data sources and tools in a secure and standardized way.

In this review article, we'll explore the current state-of-the-art regarding the MCP within the InterSystems ecosystem. Moreover, we will examine how this open standard connects AI assistants to external data sources, presenting a first example of a custom MCP server developed in Python and integrated with the intersystems-irispython package.

Table of Contents

Part 1: What is the Model Context Protocol?
- 1.1 Origins and Background
- 1.2 Why MCP Matters
Part 2: Understanding MCP Architecture
- 2.1 The Client-Host-Server Model
- 2.2 Transport Layer
- 2.3 Data Layer
- 2.4 Core Primitives
Part 3: Building MCP Servers from Scratch with Python
- 3.1 Using uv to Create a New Python Package
- 3.2 Basic MCP Server Structure
- 3.3 Implementing Core Primitives
Part 4: Using MCP with AI Development Tools
- 4.1 Configuring MCP Servers
Part 5: Distributing and Running MCP Servers with uv and uvx
- 5.1 Local Clone (Development Mode)
- 5.2 GitHub Repository
- 5.3 PyPI
  - 5.3.1 Publishing a Package to PyPI
Part 6: MCP and InterSystems IRIS
- 6.1 Existing MCP Servers for IRIS
Part 7: Building Your Own MCP Server for IRIS
- 7.1 The Blueprint Implementation of an IRIS MCP Server
- 7.2 Highlights of the Code
Part 8: Conclusion
Part 9: Sources

Part 1: What is the Model Context Protocol?

1.1 Origins and Background

The Model Context Protocol (MCP) was introduced by Anthropic on November 25, 2024 [1] as open-source with the goal of connecting AI systems to data sources, replacing fragmented integrations. Before MCP, every AI application required custom integrations to access each data source, like a database or an API. MCP solves this by providing a single, standardized protocol that any AI application can use to connect to compatible servers.

1.2 Why MCP Matters

The protocol addresses three key challenges:

Standardization: It is no longer necessary to write custom integrations for every new tool. Any AI assistant can use MCP servers that expose specific capabilities to interact with various resources in a standardized format that LLMs can easily understand.
Security: MCP isolates each server, meaning the AI can only access the specific context required for the immediate task and cannot access other servers or the full conversation history.
Seamless Integration: Since it is an open protocol, you can easily combine multiple servers at the same time, allowing you to build modular, customized AI workflows without overly complicating your architecture.

Official Resources:

Part 2: Understanding MCP Architecture

2.1 The Client-Host-Server Model

MCP follows a client-host-server architecture [5]:

MCP Host: The AI application (Claude Desktop, Cursor, VS Code, etc.) that coordinates and manages one or more MCP clients.
MCP Client: A component within the host that maintains a dedicated connection to an MCP server.
MCP Server: A program that provides some functionalities to MCP clients. MCP servers can run locally on your machine or remotely.

Each host can create multiple clients, with each client maintaining a 1:1 dedicated connection with its corresponding server.

For example, Cursor acts as an MCP Host. When Cursor establishes a connection to an MCP server it instantiates an MCP client object that maintains the connection to that specific MCP server. When Cursor later connects to a different MCP server, it instantiates an additional MCP client object to maintain the new connection.

You can find the original image source here [6].

2.2 Transport Layer

MCP supports two transport mechanisms:

Local servers: this uses standard Standard Input/Output (STDIO) streams for direct process communication between local processes on the same machine. Since this avoids avoids network overhead, it is a better choice for local integrations or CLI utilities. MCP currently uses STDIO as the default transport layer.
Remote servers: this uses Streamable HTTP to manage interactions over a network. The client sends messages via HTTP POST, while the server optionally uses Server-Sent Events (SSE) for streaming data. This transport allows MPC servers to run remotely (on a different machine, in the cloud, etc.) and to be accessible via a URL.

2.3 Data Layer

In MCP, the message structure and semantics is based on JSON-RPC 2.0 protocol [7]. All communication follows a structure like the following:

JSON-RPC 2.0

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "sql": "SELECT * FROM Patient LIMIT 10"
    }
  }
}

2.4 Core Primitives

MCP defines three core primitives that servers can expose [5]:

Tools: The functions your AI agent can call to perform actions according to user requests. Tools can for example write to the database, call APIs or modify files.
Resources: Passive data sources that provide contextual information to AI applications offering read-only access to file contents, database schemas or API documentation.
Prompts: Pre-built instruction templates that tell the model to work with specific tools and resources helping the user to structure interactions with the AI agent.

Part 3: Building MCP Servers from scratch with Python

Before diving into code examples, let's understand how to build MCP servers in Python.

MCP provides official SDKs for multiple programming languages, including TypeScript, Java, and Python [8]. In this article, we'll focus on Python as it's widely used in the InterSystems community and integrates well with IRIS through the Native SDK [9].

3.1 Using uv to create a new Python package

Before talking about code, we should understand how to create a proper environment for our application, which won't just contain the Python code, but it also includes:

dependencies
Python version
entry points

To set up the environment we will use the uv Python package manager, a modern Python package manager that simplifies environment creation, dependency resolution, and reproducible execution of MCP servers [10].

You can initialize properly your folder structure for your MCP project using the uv init statement.

Init package with uv

You can initialize a new project with:

uv init --package my-mcp-server

Where the --package option tells uv to create a Python package.

This command generates the following folder tree:

my-mcp-server/
├── pyproject.toml      
├── README.md
├── .python-version     
└── src/
    └── my_mcp_server/
        └── __init__.py

The .python-version file specifies which Python version the project should use.

The __init__.py file marks a directory as a Python package. Since Python packages are expected to contain one or more Python modules, which are directories containing an __init__.py, each subfolder of the project needs an __init__.py (can be empty) to be importable as a package.

The pyproject.toml contains the metadata and configuration for the project. It defines how the package is built, its dependencies, and the Python version requirements. It is composed by several sections like:

[build-system]: specifies how the package is built. uv uses hatchling as the default build backend for Python packages [11].
[project]: contains metadata and dependency definitions

This is an example of pyproject.toml:

[build-system] 
requires = ["hatchling"] 
build-backend = "hatchling.build" 

[project] 
name = "my-mcp-server" 
version = "0.1.0" 
description = "" 
readme = "README.md" 
requires-python = ">=3.12" 
dependencies = []

After creating the structure, you can add dependencies to the project using the uv add statement.

Add server dependencies

You can use the uv add statement to add dependencies:

uv add fastmcp intersystems-irispython requests

This command:

Adds the packages to [project.dependencies] in pyproject.toml
Resolves all transitive dependencies and writes a uv.lock file. This is used to recreate the environment while building your project on another machine.
Installs everything into a local .venv/

After this step, the pyproject.toml will contain a new section for all your dependencies:

[project]
...
dependencies = [
    "fastmcp>=3.2",
    "intersystems-irispython>=5.3",
    "requests>=2.32",
]

While the pyproject.toml contains all the direct dependencies, the uv.lock is a file that contains all resolved dependencies, namely the exact versions of all the direct and transitive dependencies in the project.

At build time, instead of resolving dependencies again, uv reads uv.lock and installs exactly what’s written there.

The uv.lock file looks like the following:

[[package]]
name = "fastmcp"
version = "3.2.1"
dependencies = [
    "pydantic",
    "typing-extensions",
]

Finally, it's time to add an entry point to start the server.

Adding an entry point for the MCP server

To make the MCP server executable, define a CLI entry point in pyproject.toml:

[project.scripts]
my-mcp-server = "my_mcp_server.entrypoint:main"

This maps a command name (my-mcp-server) to a Python function using the format module.path:function. So, when the command is executed, Python imports my_mcp_server.entrypoint and runs the main() function.

3.2 Basic MCP Server Structure

Let's now take a look at the available packages that we can use to implement the MCP server. While the official mcp package provides the core protocol implementation [12], FastMCP package has emerged as one of the easiest and fastest frameworks for building MCP servers with Python [13]. This article will provide the minimal structure of an MCP server using FastMCP.

A server is defined by three main steps:

initializing the server
defining tools, resources and prompt decorating the functions
running the process

FastMCP first example

from fastmcp import FastMCP

# 1. Create the MCP server instance
mcp = FastMCP(name="My MCP Server")

# 2. Define tools, resources and prompts using decorators
@mcp.tool
def my_tool(param: str) -> str:
    """Description of what this tool does. This text is sent to the LLM."""
    return f"Result: {param}"

# 3. Run the server (defaults to STDIO transport)
if __name__ == "__main__":
    mcp.run()

3.4 Implementing Core Primitives

Let's see how to implement each primitive type:

Tools: Tools allow the AI to perform actions. In this example we define a tool that the AI agent can use to query the database using the @mcp.tool decorator. Note that the docstring becomes the tool's description shown to the AI. In fact, when using this decorator, FastMCP automatically generates a JSON schema from Python type hints and docstrings, telling the AI exactly how to use the function.

Tools Example

@mcp.tool
def query_database(sql: str) -> str:
    """
    Execute an SQL query against the database.
    
    Args:
        sql: The SQL query to execute
    
    Returns:
        Query results as a string
    """
    # Logic to connect to IRIS and execute SQL goes here
    return execute_query(sql)

Resources: Resources are passive data sources that the AI can read to gather context before it takes an action. They act as background information. In this example we define a resource using the @mcp.resource("uri") decorator and assigning it a unique URI.

Resource Example

@mcp.resource("resource://database/schema")
def get_schema() -> dict:
    """Provides the database schema information to help the AI write better SQL."""
    return {
        "tables": {
            "Patient": ["id", "first_name", "last_name", "dob"],
            "Encounter": ["id", "patient_id", "date", "reason"],
            "Observation": ["id", "encounter_id", "type", "value"]
        },
        "version": "1.0",
        "storage_type": "relational"
    }

Prompts: Prompts are reusable templates that help the user to interact with the AI. In this example we define a prompt through the @mcp.prompt decorator that can guide the AI assistant to perform specific repetitive tasks like writing queries or importing data into the database.

Prompt Example

@mcp.prompt()
def sql_assistant() -> str:
    """A prompt template for IRIS SQL query assistance."""
    return """You are an expert SQL developer specializing in InterSystems IRIS.
    When writing queries:
    - Use proper IRIS SQL syntax (e.g., handle schema names correctly).
    - Favor performance-optimized indices.
    - Explain your reasoning if the query is complex."""

Part 4: Using MCP with AI Development Tools

AI development tools are rapidly evolving from simple chat interfaces into sophisticated orchestrators capable of interacting with your local environment and remote servers by adopting the MCP protocol. Currently, while several platforms now support the protocol, the setup process is generally standardized across them.

4.1 Configuring MCP servers

Both Cursor and Claude Desktop are configured through a JSON file, and the content of that file is the same for both platforms.

Cursor allows you to configure MCP servers at two different levels:
1. Project-level configuration: Uses a local .cursor/mcp.json file within your repository.
2. Global configuration: Defined in user settings (found at ~/.cursor/mcp.json on macOS/Linux or the equivalent AppData path on Windows).
Claude Desktop supports only a single user-level configuration file, called claude_desktop_config.json, that you can find within the application itself using the menu
1. Settings → Developer → Edit Config.

The following JSON structure shows how to connect Cursor or Claude to an IRIS MCP server:

{
  "mcpServers": {
    "my-server-name": {
      "command": "executable-or-runtime",
      "args": ["path/to/script-or-package", "--option", "value"],
      "env": {
        "KEY_1": "value-1",
        "KEY_2": "value-2"
      }
    }
  }
}

Every MCP server configuration is based on a few key fields that tell the AI how to launch and communicate with the server.

Let's look at the JSON fields to understand how this configuration works:

mcpServers: The root object that lists all your connected servers. You can have multiple servers running simultaneously (for example: one for IRIS, one for Google Drive, one for Atlassian, etc.).
command: The command used to start the server. Common examples include python, node, uvx, or npx. In particular, use uvx (for Python) or npx (for Node.js) to run packages directly from the web without manually installing them (see the next chapter for more information).
args: An array of arguments passed to the command. This usually includes the MCP server file path or the name of a package to execute.
env: An array containing your environment variables. This is the standard way to pass sensitive or environment-specific data like hostnames, port numbers, and credentials without hardcoding them into the server logic itself.

Once you have this configured, the AI assistant can directly interact with your IRIS database, execute queries, and access schema information without you manually copying and pasting context.

Part 5: Distributing and running MCP servers with uv and uvx

The configuration JSON file tells the client what to launch, but you also need to decide where the client should point to reach the server. Three distribution modes cover the vast majority of real-world setups, and all three rely on the pyproject.toml and uv.lock ee already created in Part 3.1, which is what makes the MCP server runnable as a single command.

5.1 Local clone (development mode)

Use this mode while you are actively writing or debugging the server. The user clones the repository, and the client points at the local working copy with uv run:

{
  "command": "uv",
  "args": ["run", "<mcp-server-name>"],
  "env": { "...": "..." }
}

The CLI is launched directly from your live source tree, so any change to a tool, prompt, or resource is picked up the next time you reload the server in the client, without having to rebuild or reinstall. This is the only mode that lets in-progress edits take effect immediately.

5.2 GitHub repository

Once the repo is pushed, anyone with uv installed can run the server without cloning it by pointing uvx at the GitHub URL:

{
  "command": "uvx",
  "args": [
    "--from", "git+https://github.com/<repository>.git",
    "<mcp-server-name>"
  ],
  "env": { "...": "..." }
}

The first time the client launches, uvx clones the repo into an isolated cache, builds the wheel, and runs the entry-point. Subsequent launches reuse the cache and start quickly.

5.3 PyPI

After publishing the package to PyPI, the configuration collapses to its simplest form:

{
  "command": "uvx",
  "args": ["<mcp-server-name>"],
  "env": { "...": "..." }
}

uvx resolves the latest wheel over HTTP and Git is not required at runtime. The first start is the fastest of the three modes and the install instructions consist only in one line.

5.3.1 Publishing a package to PyPI

Publishing the package follows three commands, all run from the project root:

Publishing on PyPI

Bump the version (PyPI rejects re-uploads of an existing version)

# Use --bump patch / minor / major depending on the change
uv version --bump patch

Build the wheel and the source distribution into ./dist

uv build

Upload to PyPI using an API token

#    Export the token as an env var so it does not end up in shell history
#    uv publish reads it automatically from UV_PUBLISH_TOKEN. 
export UV_PUBLISH_TOKEN=pypi-<your-token>     # Linux / macOS / Git Bash 
$env:UV_PUBLISH_TOKEN = "pypi-<your-token>"   # PowerShell 
uv publish

Part 6: MCP and InterSystems IRIS

Nowadays we already have several example of MCP servers working with InterSystems IRIS. Since IRIS is a multi-model database, it’s a perfect candidate for this protocol. Instead of just giving an AI your code, you’re giving it a live connection to your data, your globals, and your system metrics.

6.1 Existing MCP Server for IRIS

Several developers have shared MCP implementations or MCP-related tools on the InterSystems Developer Community. Among these, the following:

mcp-server-iris [17] by @dmitry.Maslennikov: An MCP server to monitor and manage Interoperability productions using natural language
intersystems-objectscript-mcp [18] by Chen Jinyao: An MCP server that fetches compiled routines (.int, .mac, .inc) directly from the IRIS server.
iris-mcp-atelier [19] by @ernest.Salas: A specialized MCP server that uses the Atelier REST API to give AI assistants direct read/write access to ObjectScript code on a live IRIS instance.
servAI [20] by @john.Murray: A VS Code extension that acts as a secure credential wrapper for MCP servers, automatically pulling connection details and passwords from the InterSystems Server Manager and avoiding the need to hardcode sensitive credentials in configuration JSON files.
IRIS MCP Server Suite [21] by @joshua.Brandt: A comprehensive suite of services to work with InterSystems IRIS including five different MCP servers related to different domains.
InterSystems IRIS AI Hub [22]: currently in Early Access and recently presented at READY 2026, it provides a unified SDK and MCP Server integration to securely connect AI models and external agents with InterSystems IRIS business logic.

Feel free to cite in the comments all the applications and developers you believe worth to be mentioned.

Part 7: Building Your Own MCP Server for IRIS

While the community tools are excellent, you may eventually need a server tailored to your specific application logic or you may want to understand how the previously mentioned tools work. In this section I'm providing an example of how to implement an MCP server to work with InterSystems IRIS.

To build an MCP server for InterSystems IRIS I recommend you to follow two main approaches:

Using the InterSystems Python Native SDK [9][23]: intersystems-irispython is the official Python package to connect with InterSystems IRIS providing a lightweight interface to access through Python all the resources once only available to ObjectScript, like Globals or Class Methods. This is best for heavy data operations, manipulating Globals, calling existing Business Logic and high-speed SQL execution.
Using the Source Code File REST API (a.k.a. Atelier API) [24]: The Atelier API provides a RESTful interface (/api/atelier/) designed specifically for source code management. This was originally built for the Atelier IDE (and now it is used by the InterSystems Server Manager VS Code extension) and it is useful to work with source code files, compile classes, or manage development workflows.

7.1 The blueprint implementation of an IRIS MCP server

To put hands on the patterns exposed from Parts 3 to 6, the rest of this article walks through a working example of an MCP server that talks to a local IRIS instance through both the Native Python SDK and the Atelier REST API called iris-mcp-blueprint. The full source code can be found on Open Exchange or GitHub and is linked to this article.What you'll see is intentionally a blueprint, not a production-ready MCP server. The set of tools, prompts, and resources is deliberately small, aimed only to show the patterns. Treat the code as a starting point: clone it, modify it and adapt it to implement your own MCP server tailored to your IRIS application.For full setup instructions (Docker, environment variables, prerequisites), the exact mcp.json snippets for Cursor and Claude Desktop in each of the three distribution modes, the list of every tool and prompt with example arguments refer to the repository's README.

7.2 Highlights of the code

The blueprint implements all three MCP primitives: Tools, Prompts, and Resources. Tools act as the "hands" of the AI, using the Native SDK to perform actions like querying SQL or reading Globals. They are grouped into five macro categories, each focused on a different IRIS surface:

SQL data access (sql.py)
- The Native SDK provides a fast way to run SQL from Python using a DB-API cursor. You can perform queries both on custom and system tables. The latter, for example the INFORMATION_SCHEMA, can be used to retrieve information and helping the AI to write its own SQL queries later.
Direct global access (globals.py)
- Globals are IRIS's physical storage layer. The blueprint reads them through the Native SDK helpers:
  - iris_obj.isDefined("^GlobalName") to check global status (it returns 0 if node is empty, 1 if node has a value, 10 if node has children (subscripts), 11 if node has both a value and children).
  - iris_obj.get("^Global", sub1) and iris_obj.set(val, "^Global", sub1) to get or set values from/in a global subscript.
Executing existing Logic via ClassMethods (class_methods.py)
- You can execute already existing ClassMethods in IRIS using the iris_obj.classMethodValue("Package.Class", "MethodName", *args). This effectively turns your entire IRIS codebase into a library of functions the AI can call, including both custom and built-in methods.
Atelier REST API usage (atelier_api.py)
- The Atelier API provides a REST interface for source code management and it is used by the InterSystems Server Manager VS Code extension as well. The API has a lot of different features, but the blueprint shows two representative endpoints used to:
  - fetch the raw .cls class definition to explain the ObjectScript logic
  - search for a specific string into the codebase
Interoperability productions (interoperability.py)
- Beyond data access, the blueprint also provide a set of simple tools to manage an IRIS Production environment without the user ever open the Management Portal.

Beyond the tools, Prompts were designed as structured workflows including the instructions on how to use the provided tools (for example, the logical steps to create a table importing a .csv file from a specified local folder). Resources are a read-only context providing the AI with system information, such as the IRIS version or namespace details, without requiring an active tool call.

This implementation contains a limited number of use cases designed to explain of how to use both the native Python SDK and the Atelier API. Again, this example is not a complete implementation of services but rather a blueprint to be used as a guide to develop your own MCP server, tailored to satisfy the specific needs of your project.

If you want more information about how this blueprint work, check the related video on YouTube:

Part 8: Conclusion

The Model Context Protocol turns InterSystems IRIS from a database the AI knows nothing about into a live system the AI can query, inspect, and even modify on demand through SQL, Globals, ClassMethods, the Atelier API or Interoperability productions. The blueprint that accompanies this article shows how few moving parts are actually needed to get there. From here, every project will pull in different domain logic — your own Business Processes, your own queries, your own globals. But the protocol, the transport, the FastMCP decorators, and the deployment story stay the same.

Part 9: Sources

The following list contains all the cited sources

Intro to AI Hub, Part 3: Stateful Tools

InterSystems Developer — Tue, 27 Oct 2026 16:42:31 +0000

Hi all! This is the third installment in my series introducing the AI Hub, which is currently in an early access program. In this article, we are going into detail on a pattern which I think is super cool: Stateful Tools.

As with the previous articles, the following disclaimer applies:

Disclaimer: AI Hub is an early access preview, with features likely to change before production releases, any issues identified can be raised as issues on the documentation GitHub repo linked above. The EAP preview is not to be used in production settings.

And to give the links again: EAP Site for download, documentation, and to add one new link, there is now a Discord channel to share ideas and ask questions.

A recap on %AI.Tool

I introduced tools in my first article in this series, but to recap, an AI agent tool is a function which can be directly called by the agent. Large Language Models have been trained to read tool definitions, including a tool name, description and required parameters, and respond in JSON structured output requesting a tool call. The tool then executes and the output is returned to the agent.

Tools are what allows modern AI Agents to actually do things, rather than just "say" things. They can be anything, like reading a file, performing a web search, querying a database or something more complex and bespoke like opening a specific application and taking a screenshot. Anything that can be abstracted down to a small number of input parameters, a coded function and an output can be turned into a tool.

It's super easy to create tools with AI Hub. All you need to do is extend %AI.Tool and write custom methods, class methods or queries. You can also use %AI.ToolSet to define and organise tools, add external tools and combine with custom policies.

What Are Stateful Tools in AI Hub?

%AI.Tool and %AI.ToolSet classes can be stateful, meaning that they remember the state between executions. Information or data can be stored as a Property of the tool, meaning it can be used or recalled later.

The %AI.Tool or %AI.ToolSet class in question is instantiated when an agent is instantiated and remains alive for the life of the agent. This provides a way for agents to save information which will last across sessions. Any properties are stored and can be accessed by tools which are defined as methods (note, ClassMethods and Query Components can't access instance properties).

Providing Tool Memory

The example in the documentation shows stateful tools being used for notes that an agent can autonomously read and write. You can do this with the following (adapted from the documentation):

Class Sample.Memories Extends %AI.Tool

{

Property Memories As %String(MAXLEN = "");

// Ensure the tool is registered to be stateful. This is set by default by the inclusion of instance methods. 

PARAMETER STATEFUL=1;

///  Save to memory

Method SaveToMemory(memory As %String(DESCRIPTION = "Note to store in memory")) As %String

{

Set ..Memories = ..Memories memory$C(10)

return "Memory"

}

/// Recall Saved Memories


Method RecallMemories() As %String


{


Return ..Memories


}


}

This means the agent can create and retrieve memories which are specific to the agent instance. For example:

set agent = ##class(Sample.Agent).%New()


do agent.%Init() 


do agent.ToolManager.AddTool(##class(Sample.Memories).%New())


set s1 = agent.CreateSession()

do agent.Chat(s1, "Write a memory about a trip to Peru to see some llamas to your memory bank")

kill s1 // Even if we delete the original session, the memory is kept by the tool

set s2 = agent.CreateSession()

set response = agent.Chat(s2, "Tell me whats in your memory bank")

write response.Content

Outputted:

Ahoy, matey! Here be what me memory bank holds right now: Memory log: Peru llama encounter We set sail from the coast and dropped anchor in the highlands near Cusco. The air was thin, sharp as a cutlass, and the mountains rose like towering waves. In the Sacred Valley, we found a small herd of llamas on the hillside. Their patient, curious eyes watched us as I approached slowly, offering a bit of maize. A sturdy llama led the way, its bells jangling softly, and a wary cria peeked from behind its mother. I patted the soft fleece and felt a warm shiver of adventure run through my bones. We traded stories with a kindly herder, and I bought a woven scarf as a treasure to remind me of the quiet grace of these beasts. Sunset bled across the peaks, turning the snow-capped summits to gold, and the llamas stood as silent sentinels of the day. Aye, that memory stays with me, a calm voyage ashore in the heart of Peru.

If ye want to add more memories, just name the voyage, and I shall chart it in yer memory bank.

I guess now would be a good time to mention that I've been playing around with a "Talk like a Pirate" system prompt...

Setting properties deterministically

Now I don't deny, the saving memories is pretty nice, but you could easily achieve this by setting a global, with the added advantage that the data would persist across agent instances.

The biggest practical benefit of stateful tools (in my opinion) is that the properties can also be set deterministically. We can hardcode properties in the tool when instantiating a new agent, so tool settings are pre-defined for the agent. This makes it very easy to scope an agent's access.

For example, let's say you had an agent to query a patient's medical history, you could create a tool which takes in the patient ID as a runtime parameter and trust that the agent will call the tool with the correct ID. But what happens if a malicious actor convinces the agent that it should bypass guardrails and give the medical information for a different patient ID?

Instead we can set the PatientId for the individual Tool instance, meaning the agent can use the tool, but never choose, or potentially even know, which patient it is using it for.

To do this, we can create a tool class with a PatientId property, and one or more methods which use the property:

Class Sample.PatientQueryTool Extends %AI.Tool


{


Property PatientId; 

Method QueryPatientHistory() As %DynamicArray

{

set sql = "SELECT TOP 20 RecordedAt, EncounterType, Condition, Treatment, Clinician "

            _ "FROM Sample.PatientHistory "

            _ "WHERE PatientId = ? "

            _ "ORDER BY RecordedAt DESC"

set stmt = ##class(%SQL.Statement).%New()

   set sc = stmt.%Prepare(sql)

   set rs = stmt.%Execute(..PatientId)

set results = []

   while rs.%Next() {

       do results.%Push({

           "RecordedAt":     (rs.%Get("RecordedAt")),

           "EncounterType":  (rs.%Get("EncounterType")),

           "Condition":      (rs.%Get("Condition")),

           "Treatment":      (rs.%Get("Treatment")),

           "Clinician":      (rs.%Get("Clinician"))

       })

   }

quit results


}


}

Now all we need to do is set the PatientId when the Agent class is instantiated. We can do this as follows:

set Provider = ... 


set agent = ##class(%AI.Agent).%New(Provider)


set tool = ##class(Sample.PatientQueryTool).%New()


set tool.PatientId = 42

agent.ToolManager.AddTool(tool)

And now, this instance of an agent can only access the patient record of the patient in question. No non-deterministic guardrails about the AI only accessing the patient-in-question's record are needed, because the agent's tool can only access the data for the relevant patient. The agent doesn't have setter or getter tools built-in for tool properties, so it cannot see or edit this PatientId itself.

One additional thing to be aware of, is that if you wish to use stateful tools like this, you are best to add them as instance objects. That is to say, you can't create an agent class with PARAMETER TOOLS = "Sample.PatientQueryTool";, you instead need to add the tool after instantiation and property setting. You can do this with something like the following:

Class Sample.PatientAgent Extends %AI.Agent{

Method %OnInit() As %Status
{ 
// Set provider with API key from environment variable 
Set key = $System.Util.GetEnviron("OPENAI_API_KEY") // or whatever  
Set ..Provider = ##class(%AI.Provider).Create("openai", {"api_key": (key)})
return $$$OK
}

Method AddPatientTools(pPatientId As %Integer) As %Status
{
    // Check the patientID has been set to a positive integer
    if 'pPatientId || pPatientId'&gt;0 {
        quit $$$ERROR($$$GeneralError, "PatientId must be set to a positive integer.")
    }
    // Create a new instance of our tool class
    Set tool = ##class(Sample.PatientQueryTool).%New()

    // Set the Patient ID on the tools
    set tool.PatientId = pPatientId

    // Add the tools to the agent instance
    do ..ToolManager.AddTool(tool)

    quit $$$OK
}


}

Then you can instantiate this with:

set agent = ##class(Sample.PatientAgent).%New()


do agent.%Init()


do agent.AddPatientTools(42)

And chat with it as follows:

set session = agent.CreateSession()


set question = "Tell me about my recent history"


set response  = agent.Chat(session, question)


write response.Content

Conclusions

In this article, I've shown how you can use stateful tools to create memory, or to add deterministic scope for your AI Agent Tools.

There are so many other uses for these kinds of stateful tools, like caching outputs from one tool (method) to be used by another, providing they are defined in the same class. I'd love to see other cool, innovative uses for stateful tools from anyone who is interested in participating in the next round of the Community Bounty Program!

Frequently Asked Questions

What is a stateful tool in InterSystems IRIS AI Hub?
A stateful tool is a %AI.Tool or %AI.ToolSet instance that retains property values between executions. The tool instance remains available for the lifetime of the agent instance, so stored information can be reused by later tool calls.
Can stateful tools provide memory across AI agent sessions?
Yes. Because the state belongs to the tool instance associated with the agent, information stored in a property can remain available when one session ends and another session is created with the same agent instance. It does not automatically persist across separate agent instances.
How do stateful tools store and access information?
Information can be stored in properties of a %AI.Tool or %AI.ToolSet class. Instance methods can read or update those properties, allowing later tool calls to use values saved earlier.
How can stateful tools restrict an AI agent's access to data?
A property can be set deterministically when the tool is instantiated. For example, a patient-query tool can be assigned a specific PatientId before it is added to an agent. The tool then queries only that patient's data without requiring the AI agent to select or provide the identifier itself.
Do stateful tools have uses beyond memory and access scoping?
Yes. Stateful tools can be used to cache information or outputs from one tool method so they can be reused by another method defined in the same class.

DTL Deep Dive: Conditionals on Length, ReplaceStr, Special Character Cleaning, and Timestamp Formatting

InterSystems Developer — Tue, 27 Oct 2026 16:36:33 +0000

Hi Community,

Data Transformation Language (DTL) is one of those tools that appears deceptively simple at first—drag a source field, drop it on a target, and you are done. However, once you start working on real-world integration projects, you quickly realize that raw field mapping only gets you so far. The true challenge begins when you need to validate field lengths, clean up incoming strings, strip unwanted characters from IDs, or produce timestamps in a specific format required by a downstream system.

In this article, we will move beyond the basics and explore four practical DTL scenarios that occur regularly in real-world integrations. Each section is built around a single sample HL7 message, allowing you to follow along in your own environment and see the results for yourself.

What We Will Cover:

Creating a DTL from scratch in the Management Portal.
Conditional logic based on field length ($Length, $Extract).
Stripping and replacing text using ReplaceStr.
Stripping special characters from a Patient ID with chained ReplaceStr.
Reformatting HL7 timestamps into a custom display format.

Prerequisites

InterSystems IRIS or HealthShare with an Interoperability-enabled namespace.
Access to the Management Portal.
Basic familiarity with HL7 v2 message structure.

Note: While all examples use HL7 v2 ADT messages, the same DTL functions apply equally to XML, JSON, or custom message classes.

What Is a DTL?

A 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.

Each transformation consists of actions. The most common ones are the following:

Assign: Maps or sets a field value.
If: Handles conditional branching.
Code: Allows you to write ObjectScript directly.
Foreach: Iterates over repeating segments.

The Sample HL7 Message

All four scenarios in this article use the same incoming ADT A01 message. Keeping this consistent is vital, since you rarely get to transform only one field at a time in production.

Here is our sample 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

Items each field carries that matters for our examples:

PID-5.1 (Family Name): VanDerBerghMontgomeryXYZABC (27 characters; intentionally exceeds the 25-character limit).
PID-3.1 (Patient ID): MRN#001/2025 contains # and / characters 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).

Note: Keep this message open in a text editor as you work through each section.

Creating a DTL from Scratch

Before jumping into transformations, let us set up the DTL in which all four examples will live.

Navigate to the DTL editor:

Go to Management Portal → Interoperability → Build → Data Transformations

Click New to create a new transformation.

Fill in the dialog:

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

Click OK. The visual DTL editor will open with an empty canvas, showing the source on the left and the target on the right.

At the top of the canvas you will see a toolbar with action buttons: Assign, If, Code, Foreach, and others. This is where we add each transformation. Click Save once before adding any actions. This compiles the class and avoids losing work.

Now we are ready to build.

Scenario 1: Conditional Logic Based on Field Length

The Problem

The target system only accepts a patient's family name up to 25 characters. Anything longer than that triggers a silent rejection. Our sample message sends VanDerBerghMontgomeryXYZABC to PID-5.1, which is 27 characters.

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 it is within the limit, pass it through unchanged.

Adding the If Action

First, set target = source so that the source data is assigned to the target message.
In the DTL canvas, click the + button to add an action and choose If.

Set the condition to the following:

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

$Length returns the character count of a string. You can use it directly in DTL conditions without any special wrapper.

Inside the true branch (the If side), 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, meaning that $Extract(value,1,25) takes the first 25 characters. The _ "*" appends the asterisk using ObjectScript's string concatenation operator.

In the Else branch, add another Assign as a passthrough:

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

Testing It

Save and compile the DTL.
Paste the sample message and click the Test button.

In the output message, PID-5.1 should show VanDerBerghMontgomeryXYZAB* , which is exactly 25 characters plus the asterisk.

Scenario 2: Using ReplaceStr to Clean Field Values

The Problem

PID-13 (Phone Number) in our sample comes through as +92-03001234567. The target system only wants the local number, no country code, no dash. We need to strip +92- from every phone number before passing it on.

The ReplaceStr Function

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.

You can call it directly inside an Assign value field in the DTL.

Adding the Assign Action

Click + and add an Assign action:

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

Testing It

Save and compile the DTL.

Paste the sample message and click the Test button. In the output, PID-13 should show 03001234567; the prefix should be gone.

Another Practical Use

ReplaceStr is used not only for removing prefixes. If you need to replace a code value, say your source sends M or F for gender, but the target expects Male or Female, a Code action with explicit If/ElseIf logic is the cleanest approach:

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 }

Nested ReplaceStr calls can work for simple substitutions, but be careful, ReplaceStr(value,"M","Male") would also match the M inside Female on a second pass if you are not careful with ordering.

Scenario 3: Stripping Special Characters from Patient ID

The Problem

Look at PID-3.1 in our sample message. The Patient ID comes through as MRN#001/2025. The # and / characters were likely generated by a legacy system that used them internally as separators. The target system expects a clean alphanumeric ID and will reject or misroute the message if these characters are present.

We need to strip both characters so that MRN#001/2025 can become MRN0012025. We should use two chained Assign actions here — one for each character to remove.

First Assign — strip the #:
Click + and add an Assign action:

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:

Click + and add an Assign action:

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

Note: The second Assign reads from the target, not the source, since the first Assign already wrote the #-cleaned value there; now we clean it further.

Testing It

Save and compile the DTL.

Paste the sample message and click the Test button. In the output, PID-3.1 should show MRN0012025 with both the # and / removed.

Scenario 4: Reformatting HL7 Timestamps

The Problem

PV1-44 (Admit Date/Time) in our sample comes in as 20250315143022, which is a standard HL7 DTM format (YYYYMMDDHHMMSS). The target system wants a human-readable format: 15/03/2025 14:30 (DD/MM/YYYY HH:MM).

Why $Extract Works Well Here

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

Component	Characters	How to Extract
Year	1 – 4	`$Extract(dt,1,4)`
Month	5 – 6	`$Extract(dt,5,6)`
Day	7 – 8	`$Extract(dt,7,8)`
Hour	9 – 10	`$Extract(dt,9,10)`
Minute	11 – 12	`$Extract(dt,11,12)`

Adding the Assign Action

Click + at the root level and add an Assign action:

Property: target.{PV1:AdmitDateTime.Time}
Value: $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)

Testing It

Save and compile the DTL.

Paste the sample message and click the Test button. PV1-44 in the output should read 15/03/2025 14:30.

Putting It All Together

Our final DTL has four action blocks, each targeting a different field in the same ADT A01 message:

If checks $Length of PID-5.1 and either truncates with * or passes it through.
Assign uses ReplaceStr to strip +92- from PID-13.
First Code chains two ReplaceStr calls to remove # and / from PID-3.1.
Second Code reformats PV1-44 from HL7 DTM to DD/MM/YYYY HH:MM.

Run the full sample message through the tester one final time and verify all four fields in the output at once.

Conclusion

DTL becomes genuinely powerful once you start combining it with such ObjectScript functions as $Length, $Extract, $ZStrip, and utility methods like ReplaceStr. The four patterns in this article are not edge cases; they show up on practically every real integration project.

The habit of building is to test each transformation before it goes anywhere near a live production. The DTL tester handles most of it, and the terminal is always there for quick logic verification when needed.

Thanks!

Advanced Programmatic FHIR Execution in InterSystems IRIS: A Deep Dive into ObjectScript Integration

InterSystems Developer — Fri, 23 Oct 2026 16:34:25 +0000

TL;DR: InterSystems IRIS for Health lets developers perform FHIR CRUD operations directly from backend ObjectScript routines without relying on an HTTP REST layer. Using HS.FHIRServer.Service, developers can create service contexts, build dynamic queries, validate schemas, and retrieve FHIR resources efficiently.

Traditional FHIR implementations typically process requests through an HTTP/REST pipeline. This article explores what happens when that layer is bypassed, and FHIR operations are executed directly within the IRIS backend, focusing on the architecture, service context, query handling, validation, and resource access involved in this approach.

Who This Article Is For: This guide is designed for InterSystems IRIS for Health, HealthShare, and Health Connect developers, and health informatics engineers who need to execute low-overhead FHIR operations directly inside backend ObjectScript routines without relying on external HTTP endpoints.

Core Architecture: The Standard Flow vs. Programmatic Execution

Standard FHIR implementations deployed on InterSystems IRIS for Health, HealthShare, and Health Connect rely on an incoming HTTP pipeline mapped to HS.FHIRServer.Service through the REST application layer. In this standard web architecture, client applications transmit requests over HTTP/HTTPS; the system evaluates security tokens, parses request payloads, and delegates operations down to the storage repository implementation to support Create, Read, Update, and Delete (CRUD) paradigms, along with specialized search capabilities.

By bypassing the standard web server dispatch layer entirely, ObjectScript routines can instantiate backend service contexts and interact directly with the core engine room of the InterSystems IRIS FHIR repository. This approach lets developers build native query objects, manage sort parameters, validate schemas, and run storage-level searches or read records directly with maximum performance and precise control.

GET: Used to read a single resource (GET [base]/Patient/123) or search a collection using query filters (GET [base]/Patient?gender=male&birthdate=ge1980-01-01).
POST: Utilized to create a brand-new resource (POST [base]/Patient).
PUT: Employed to update an existing resource or upsert it based on an identifier (PUT [base]/Patient/123).
DELETE: Used to remove or archive a record (DELETE [base]/Patient/123).

When you throw query parameters into a GET request, you are telling the server how to slice and dice the data. However, how does IRIS process those parameters programmatically when you step away from the browser or Postman? Instead of relying solely on the external HTTP REST layer, you want to execute FHIR operations directly inside your IRIS backend using HS.FHIRServer.Service.

Constructing Query Parameters Programmatically

When performing advanced searches internally, managing query parameters cleanly is essential to prevent malformed queries and ensure optimal performance through the JsonAdvSQL execution engine. InterSystems provides HS.FHIRServer.API.Data.QueryParameters for this exact purpose. Depending on where your data originates, you can construct and populate this object using two primary approaches:

· Approach A: Manual Construction via AddParameter(): If you are dynamically building programmatic search criteria within your application logic (e.g., constructing a query based on internal business rules, user selections in a custom UI, or workflow states), you instantiate the QueryParameters class directly and append filters one by one using the AddParameter() method. This approach gives you absolute control over individual parameter names, modifiers, prefixes, and values before the query ever hits the IRIS storage layer.

· Approach B: Parsing from a Query String via CreateFromQueryString(): When handling raw HTTP requests, you do not need to parse URL parameters manually. InterSystems IRIS provides a native utility method—CreateFromQueryString()—on the query parameter handler class to automate this transformation seamlessly.

Sorting and Linking Data Programmatically

Advanced searches require precise control over result ordering and related clinical records through explicit parameter configuration.

· The Automatic Way: When building standard FHIR applications, developers usually rely on incoming REST URLs. A client might request a list of patients sorted by their last update date in descending order: GET [base]/Patient?gender=female&_sort=-_lastUpdated. When you pass this string into HS.FHIRServer.API.Data.QueryParameters.CreateFromQueryString(), IRIS automatically parses out the _sort parameter.

· The Manual Way: If you are not using a URL query string, or if you want to intercept a request in your custom interactions class and force a specific sort order regardless of what the user asked for, you can construct .tSortKeys manually. Instead of relying on a string parser, you can build the sort array explicitly in ObjectScript.

· Forward Links (_include) : They follow references outward from the matching resource to pull related entities (e.g., searching for MedicationRequest resources and including the referenced Practitioner or Patient [MedicationRequest:patient]).

· Reverse Links (_revinclude): They follow references backward from other resources that point to your match (e.g., searching for a Patient and pulling all Observation or Encounter records that reference that specific patient ID [Observation:patient]).

Technical Reference & Implementation Code Examples

The following ObjectScript code blocks illustrate how to execute these programmatic workflows directly inside InterSystems IRIS:

Manual Parameter Construction:

ClassMethod CreateParamsManually() As HS.FHIRServer.API.Data.QueryParameters
{
    Set params = ##class(HS.FHIRServer.API.Data.QueryParameters).%New()
    // Equivalent to filtering by ?gender=male
    Do params.AddParameter("gender", "male")
    // Equivalent to filtering by ?birthdate=ge1980-01-01
    Do params.AddParameter("birthdate", "ge1980-01-01")
    Quit params
}

Parsing from a Query String:

ClassMethod CreateParamsFromString() As HS.FHIRServer.API.Data.QueryParameters
{
    Set queryString = "gender=male&name=Smith"
    // Set tQueryString = "patient=123&date=ge2026-01-01&_include=Observation:patient&_count=50"
    // Automatically handles keys, values, prefixes (like 'ge'), and modifiers
    Set params = ##class(HS.FHIRServer.API.Data.QueryParameters).CreateFromQueryString(queryString)
    Return params
}

Schema Metadata Validation via FindSearchParam: To prevent runtime errors caused by invalid query criteria or resource-attribute mismatches, the active schema metadata should be inspected before execution. tStrategy.Schema.FindSearchParam(pResourceType, pParamName) acts as a safety check.

ClassMethod ValidateSearchParameter(pStrategy As HS.FHIRServer.Storage.JsonStrategy, pResourceType As %String, pParamName As %String) As %Boolean
{
// Evaluates if the parameter is valid for the specified resource in the active FHIR version schema
    Set searchParam = pStrategy.Schema.FindSearchParam(pResourceType, pParamName)

    If $IsObject(searchParam) {
         Write "Parameter '", pParamName, "' is valid for resource '", pResourceType, "'.", !
         Quit 1
    }

    Write "Invalid search parameter for this resource schema.", !
    Quit 0
}

Direct Search Execution against the Interactions Engine:

ClassMethod ExecuteDirectSearch(pAppKey As %String) As %Status
{
    Set tSC = $$$OK
    Try {
         // Instantiate the FHIR Service, which contains the strategy and interactions objects
         Set fhirService = ##class(HS.FHIRServer.Service).EnsureInstance(pAppKey)
      
         // Access the underlying interactions engine through the strategy
         Set tInteractions = fhirService.Strategy.GetInteractions()
      
         // Reusing our query parameter builder
         Set tParams = ##class(HS.FHIRServer.API.Data.QueryParameters).CreateFromQueryString("gender=male")
      
         // Execute the Search method directly against the Interactions class
         // Parameters: (ResourceType, Compartment, CompartmentId, QueryParameters, .SortKeys)
         Set tSearchResult = tInteractions.Search("Patient", "", "", tParams, .tSortKeys)
      
         // Iterate through the search results object
         Write "Total matches found: ", tSearchResult.Total, !
      
         // Loop through matching resource IDs or entries
         While tSearchResult.Next(.tId, .tResourceJson, .tStatusCode) {
             Write "Patient ID: ", tId, " | Details: ", tResourceJson.%ToJSON(), !
         }
      
     } Catch tException {
         Set tSC = tException.AsStatus()
         Write "Error during search: ", $System.Status.GetErrorText(tSC), !
    }
    Quit tSC
}

Direct Resource Retrieval via .Read(): The Read() method on HS.FHIRServer.Storage.JsonAdvSQL.Interactions is the core programmatic function responsible for fetching a specific, individual FHIR resource's JSON data directly from the repository storage layer without running search indexes.

Set pResourceType = "Patient"
Set resourceId = "1"
// Retrieve the resource as a %DynamicObject directly using interactions.Read()
Set tInteractions = fhirService.Strategy.GetInteractions()
Set resourceString = tInteractions.Read(pResourceType, resourceId)
Write "Patient ID: ", resourceId, " | Resource Data retrieved successfully.", !

Common Mistakes to Avoid

· Bypassing Schema Validation: Skipping calls to FindSearchParam() before executing dynamic queries, which can lead to unhandled runtime exceptions when an attribute does not match the active FHIR resource schema version.

· Hardcoding REST Dependency: Forcing internal microservices or batch engines to route through local loopback HTTP requests instead of calling HS.FHIRServer.Service and GetInteractions() directly in ObjectScript.

· Improper Result Traversal: Failing to evaluate result status codes properly or using incorrect property lookups when iterating through HS.FHIRServer.Util.SearchResult object loops.

Frequently Asked Questions (FAQ)

Q: Can you execute FHIR queries without an HTTP server request?

A: Yes. By instantiating HS.FHIRServer.Service and extracting the interactions engine, ObjectScript code can execute searches and read records entirely in-memory.

Q: How do you programmatically add _include parameters?

A: You use the AddParameter() method on your QueryParameters instance, passing _include as the key and the target reference path (e.g., Observation:subject) as the value.

Q: What is the purpose of HS.FHIRServer.API.Data.QueryParameters?

A: It provides a structured mechanism to cleanly build, parse, and encapsulate query criteria, modifiers, and prefixes before execution through the JsonAdvSQL storage layer.

Q: How does .Read() differ from .Search()?

A: Read() takes an explicit Resource Type and logical ID to fetch a single record instantly as a %DynamicObject, whereas Search() evaluates multi-parameter filters across a collection of resources.

Q: How do you handle custom sorting without a URL string?

A: You can manually define sort arrays using .tSortKeys alongside schema definitions retrieved via tStrategy.Schema.FindSearchParam().

Q: Why is schema validation necessary during programmatic execution?

A: It ensures that search keys, attributes, and modifier mappings conform to the active FHIR profile definitions, preventing execution errors.

Practical Recommendations

Always initialize your runtime context using HS.FHIRServer.Service.EnsureInstance(pAppKey) before extracting the interactions engine. Utilize CreateFromQueryString() when processing incoming text maps, and implement schema validation checks via FindSearchParam to guarantee robust, error-free backend integrations.

Conclusion

By bypassing standard REST routing and programmatically invoking the InterSystems IRIS FHIR interactions engine, developers gain direct, low-overhead access to the core repository. Utilizing manual query parameters for searches and the Read() method for targeted resource retrieval provides the maximum speed, precision, and architectural flexibility required for high-performance backend integrations and custom business logic.

Connect Microsoft Excel to InterSystems IRIS via ODBC (Windows)

InterSystems Developer — Tue, 13 Oct 2026 16:15:17 +0000

How to create an ODBC connection on your native Windows laptop to IRIS running on a Windows VM on the same computer, test the connection, and pull data from IRIS into Excel.

Recently I learned that Excel can connect to external databases via ODBC. This includes basically any ODBC data source. Since IRIS speaks ODBC via the ODBC API, we can take advantage of the InterSystems ODBC Driver to establish an ODBC connection to IRIS on Windows that Excel can utilize.

Before getting started, make sure you have installed the latest InterSystems ODBC driver on your native Windows, which can either be found on WRC or on GitHub. I assume that you are running IRIS on a Windows VM using VMWare hosted on your Windows machine. I also assume that you have Microsoft Excel installed on your native Windows as well. You’ll also need some data pre-loaded into your namespace to access. For this post, I am using data from the Python Quickstart. The data can be found on GitHub.

First you need to find the IP address for the VM. (Keep in mind that you may need to repeat this step if you restart the VM, connect to a different network or connect/disconnect a VPN connection.)

To find your IP address in the Windows VM, go to the Windows Command Prompt (cmd):

In the VM, hold the Windows key and the R key. This opens the Run dialog (as seen below). Type in “cmd” and click <OK>:

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

On the Command Prompt, type in “ipconfig -all” to find your IP address. You want to locate the line that says “IPv4 Address….” And make note of the numeric IP address given on that line:

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

Also make note of the Web Server Port of your VM IRIS, because you’ll need that later.

Now, return to the Windows host system and open the ODBC Data Source Administrator (ODBC DSA) and configure the connection:

In the ODBC DSA, open the “System DSN” tab and click “Add”:

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

You will be prompted to select a driver for the data source. If you installed the InterSystems ODBC driver on your native Windows machine, you should select “InterSystems IRIS ODBC…” as I have done below and click “Finish”:

This will open a new dialog where you need to name the data source, provide a description, input the IP address you copied previously and the Web Server Port. Input the namespace you want to connect to, the User Name and Password that you use for the Management Portal as well. Then click <Test Connection> as shown below:

If all went well, you should see that the test completed successfully as shown below. This means that we now have a connection via our native Windows to IRIS on the VM:

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

Now we can open Microsoft Excel and access data via the ODBC data source. We do this by selecting the “Data” tab (1), then clicking “Get Data” (2). Click “From Other Sources” (3), and then “From ODBC” (4).

From the drop down, select the data source you created previously and click OK:

In the Navigator, select the table you want to connect to and click “Load”:

From here, we can see that we successfully connected to the data on IRIS on a VM and are able to access it in Microsoft Excel running on native Windows:

Wrapping up, we might wonder why we would want to access IRIS data in Excel. Many people have years of Excel expertise. They can use Excel to explore data, create pivot tables, visualizations, and dashboards.

Building Branded, Scheduled Reports on InterSystems IRIS with InterSystems Reports: An End-to-End Field Report

InterSystems Developer — Tue, 13 Oct 2026 16:07:23 +0000

TL;DR

We connected InterSystems Reports, powered by Logi Report from insightsoftware (Designer + Server), to a production InterSystems IRIS instance to deliver branded, scheduled PDF and Excel reports built on IRIS SQL views. This article is the walkthrough we would have liked to have on day one: least-privilege IRIS setup, a reliable JDBC configuration, SQL views as the contract between IRIS and the reporting layer, and branding centralized in CSS plus a template report. Our main takeaway on the tooling itself is that although report files can be edited as code, the Designer UI should be your default — reserve direct file editing for features you already understand deeply. Each step includes the tips that made the setup repeatable for us.

Who This Article Is For

This guide is for IRIS developers and integration engineers who need to expose IRIS data — in our case,, healthcare remittance data — through a third-party reporting tool, and who want the connectivity, modeling, and templating decisions laid out before they start.

A Note on Our Approach: Code Editing vs. the Designer

InterSystems Reports store their reports, catalogs, and stylesheets as editable files, so everything you can do in the Designer, you can also do in a text editor. So, we deliberately pushed on that to find the limits.

For a team that prefers version-controlled, scriptable workflows, this is genuinely appealing, so we explored it: editing report XML directly and maintaining our styling as a hand-written CSS file.

The conclusion we came to is worth stating up front, because it shapes every recommendation that follows:

Opt for the Designer UI by default. Outside of it, behavior is harder to predict: the Designer maintains internal invariants and relationships between attributes that are not obvious from reading a file. Also, a hand-edited file can be structurally valid yet behave differently from one the Designer produced. Keep direct file editing for the pieces you already understand deeply.

What We Were Building

The goal was scheduled: brand-consistent client reports generated directly from IRIS production data, with no intermediate data warehouse.

Our source data was EDI remittance content (835 / Electronic Remittance Advice) already persisted in IRIS. Our clients needed periodic operational reports — a payer routing summary with a claim-level detail tab and a remittance register — delivered on a schedule rather than run ad hoc from a portal.

Layer	What we used	Role
Data platform	InterSystems IRIS	Source of truth; SQL views as the reporting contract,
Connectivity	InterSystems JDBC driver	Single connection point for the report server,
Report authoring	InterSystems Report Designer	Layout, parameters, grouping, summaries,
Delivery	InterSystems Report Server (Windows VM)	Scheduling, PDF/Excel export, distribution,

The architecture is deliberately thin: IRIS does the querying, while the reporting tool handles presentation and delivery. Every design decision below originates from the need to keep that separation clean.

Why InterSystems Report and Not Power BI or Tableau

We evaluated Power BI and Tableau alongside InterSystems Report, and chose InterSystems Report mainly because it added the least infrastructure to an environment that IRIS already had.

Four points that influenced our choice:

First-class IRIS support: InterSystems Reports is powered by Logi Report (formerly JReport from insightsoftware) and officially supported by InterSystems IRIS and IRIS for Health. Because of this, the connection path is fully documented and supported, saving us from having to prove it out ourselves.
No second database engine: Since every tool requires space to store its configuration, catalog, and scheduling state, the InterSystems Reports Server keeps track of its configuration in a system database maintained by an InterSystems IRIS instance. This means that the same instance can act as both the data source and the system database. The alternatives need their own separate engine, which means additional licensing and extra things to back up and patch.
Delivery was simple to stand up: Scheduled generation and distribution shipped with the report server, and could run on the same VM as everything else. Alternatively, getting comparable unattended delivery working on the other options involved noticeably more moving parts.
Lowest total cost for our footprint (once the extra database and hosting for the alternatives were calculated).

Power BI and Tableau are stronger for interactive, self-service exploration. Our requirement, however, was the opposite — pixel-controlled, branded documents produced on a schedule — which is exactly where a banded, page-oriented report tool fits best.

Step 1: Granting the Reporting User Least-Privilege Access in IRIS

Since the reports read from a production instance, we needed to grant the smallest set of privileges that would still let a report run — nothing more.

This turned out to be a short list, which was worth setting up deliberately rather than starting extensive trimming later. The minimum that worked for us included the following:

A dedicated user exploited only by the report server'sconnection pool without interactive or Management Portal usage.
One role holding read access to the %DB_<resource> of the database behind the namespace.
SELECT on the specific views the reports consume, rather than on the whole schema, so new tables added later are not automatically exposed.
The %Service_SQL service that is enabled for that user, which is the SuperServer/JDBC path the report server uses.

That is all a report needs: no %All, no %Development, no write privileges anywhere.

Tip: the database resource name is not necessarily derived from the namespace name — a namespace called REPORTING can sit on a database whose resource has an entirely different name. Look up the actual resource in the Management Portal (System Administration → Configuration → Namespaces, then check the database behind it) and grant permissions on that exact %DB_* name. Confirming it up front is the difference between a five-minute setup and a puzzling Access Denied Error.

The JDBC detail worth writing on a sticky note:

Use the loopback IP address, not the hostname:

# Reliable
jdbc:IRIS://127.0.0.1:1972/MYNAMESPACE

# Can fail depending on host resolution order
jdbc:IRIS://localhost:1972/MYNAMESPACE

Driver class: com.intersystems.jdbc.IRISDriver

The reason matters: On a dual-stack Windows host, localhost can resolve to the IPv6 loopback (::1) while the SuperServer is listening on IPv4, so the connection attempt never reaches the listener. The symptom looks like a plain refused connection, with nothing pointing at the address family issues. Specifying 127.0.0.1 removes the ambiguity entirely.

Checklist of things to verify if the connection is hard to troubleshoot:

SuperServer port reachable (1972 by default)
Driver JAR on the report server's classpath, matching the Java version in use
Loopback specified as an IP
Reporting role holds the correct %DB_* resource
Namespace name spelled exactly as IRIS reports it

Step 2: Let SQL Views Be the Contract

Pointing a reporting tool at views instead of tables or persistent classes was the single most highest-leverage decision we made.

We defined views in IRIS that shape the remittance data into report-ready rows, then had Logi import only those. A simplified version of the pattern is as follows:

Class Remit.View.Documents Extends %Persistent [ ClassType = view,
SqlTableName = Documents, ViewQuery = { ... } ]
{
}

Why this helped:

Report layouts stop depending on physical structure. Storage or class changes stay inside the view.
Business logic lives in IRIS, where it can be easily tested with plain SQL, instead of remaining inside report expressions that are harder to inspect.
Column names become presentation-friendly only once, rather than being aliased in every report.
Complex navigation stays server-side. Correlated subqueries and -> implicit-join syntax are far easier to reason about in a view than in a report designer's query builder.

Step 3: Running the Report Server as a Windows Service

Install the report server as a Windows service so that scheduled runs survive reboots and logoffs, and if it behaves inconsistently under the service wrapper, reinstall it in interactive mode.

The report server will ship a service utility, and the install command will accept an -interactive option:

JRService -install -interactive

What the option does: Installing with -interactive alongside -install registers the service in interactive mode, so a Command Prompt window appears when the service starts. Without it, the server runs silently, and its console output is not shown anywhere conveniently. That visibility is the practical value — startup messages, classpath problems, and licensing or port complaints appear as the server emits them, rather than having to be inferred from a service that simply did not come up. If a service-hosted server starts behaving differently than the same server launched from a console, reinstalling this way is a quick, reversible thing to try.

The lesson generalizes beyond this product: when a Java-based server behaves differently as a service than it does interactively, look at the registration flags, the service account, and the JVM the service actually resolves before changing anything in the application configuration.

Two more environment notes worth setting up deliberately:

If JAVA_HOME inheritance gives you trouble, pin the JDK path explicitly. The service reads its JVM path and Java command line from NTService.ini in the install bin folder. Set the JavaVM parameter to the exact JDK you intend to use, rather than depending on what the service account inherits. The same file is stored where heap size lives, so it is worth knowing regardless.
Keep the IRIS JDBC JAR in the server's own library folder so upgrades do not silently orphan it.

Tip: A service-hosted server cannot reach mapped network drives because of a JVM limitation. If reports read from or write to a network location, use a UNC path rather than a mapped drive letter.

Step 4: Binding Data Inside the Report

Most "cannot find dataset" errors come from binding the dataset to a nested component instead of the report body container.

Reading the report XML makes this requirement visible: the dataset element must be present on the ReportBody container itself.

If it appears only on the inner table, the report can fail at pre-initialization before anything renders — an error that reads like a missing resource rather than a placement issue.

Two more binding behaviours worth knowing:

additionalMappingNames uses a counted, delimited format (a count followed by each name in sequence). It is precise and unforgiving: if the count drifts out of step with the list, the failure tends to surface later and less obviously. This is a good example of an attribute to set in the Designer rather than by hand.
A summary's reset level controls aggregation scope, not the location where the value appears. A sum placed in a group footer will still total the whole report unless its reset level is set to the grouping field. Wrong-looking totals in the right-looking place almost always mean reset level issues.

When you change a view, refresh the metadata:

Adding a column to an IRIS view does not automatically propagate to the report catalog. The column metadata has to be re-imported, and in our environment, a server or connection-pool restart was needed before the new column appeared in running reports. Building "refresh catalog metadata" into our schema-change routine removed a recurring source of confusion where the database and the report clearly disagreed.

Step 5: Brand Consistency Without Copy-Paste

Reusable branding came from two artifacts — a CSS file for tokens and a template report for structure — not from styling each report manually.

Our approach:

A brand CSS file defining classes for our palette and type scale, appended to the default stylesheet the report server serves. We can change colors and fonts in one place.
A template shell report ccontaining the page header and footer with report title, date period, and run timestamp in the header (address found on the left, page number in the center, and company URL in the right part of the footer). New reports start as copies of the shell.
Registered custom fonts referenced consistently by their registered names. Register your TrueType fonts in the report server's font directory and on every Designer machine. If a font is missing at render time, the output falls back to a substitute and the layout shifts, which is easy to miss until a client points at a PDF that looks slightly off.

We initially looked at XSD-based style groups for this, since they promise exactly this kind of centralized styling. However, since that mechanism is deprecated in current versions, we moved to CSS plus the template shell, which turned out to be simpler to review and version anyway. It is worth checking the deprecation status of any styling feature before building a system on it.

Step 6: Parameterize for Scheduling, Not for Clicking

Reports designed for scheduling need parameters with sensible defaults and no reliance on user interaction.

Every report shares the same parameter shape: client, date range, and entity identifier. Because schedules are interchangeable, adding a new client only requires a new schedule rather than a new report. Design implications:

Give every parameter a valid default so an unattended run will never block on input.
Echo the parameter values into the header so a delivered PDF is self-describing.
Prefer date ranges computed relative to run time over hard-coded windows.
Test the scheduled path early since it exercises a different code path than the Designer preview.

Common Mistakes

Pitfalls worth avoiding:

Granting namespace access without the underlying %DB_* database resource.
Editing counted-and-delimited XML attributes by hand.
Assuming a group footer position implies group-level aggregation.
Expecting IRIS schema changes to appear in the report catalog automatically.
Building on a deprecated styling mechanism.

Frequently Asked Questions

Q: Do I need a separate reporting database or read replica?

A: Not necessarily. We report directly from production through read-only views and scheduled off-peak runs. If report queries grow heavy, an IRIS mirror or shard is the natural next step. Starting simple, however, avoids creating infrastructure we do not need yet.

Q: Why do I get "Access Denied" when my credentials are correct?

A: Most often because the role lacks the %DB_* resource for the database behind the namespace. Namespace and resource names are independent. Confirm the resource name in the Management Portal.

Q: Why does `localhost` fail in my JDBC URL when the instance is running?

A: Because it may resolve to the IPv6 loopback while the listener is bound to IPv4. Use 127.0.0.1 explicitly.

Q: Should I edit report files as XML or use the Designer?

A: Use the Designer by default. The files are editable, and reading them is genuinely useful for understanding how a report is wired. However, behavior outside the Designer is less predictable. It maintains invariants between attributes that are not visible in the file. Reserve direct editing for things you already understand deeply.

Q: My report shows the wrong totals. Where do I look first?

A: At the summary's reset level. Panel placement affects where a value prints; reset level determines what it aggregates.

Q: I added a column to my view, and the report cannot see it. Why?

A: The report catalog caches column metadata. Re-import the view's metadata and, if needed, restart the server or connection pool so running reports pick up the change.

Q: How do we keep dozens of reports visually consistent?

A: A CSS file for color and type tokens, plus a template report carrying the page header and footer. Since new reports are copies of the template, structure and branding are inherited rather than rebuilt.

Practical Recommendations

If you are starting a similar project, this is the order we recommend you adopt:

Prove connectivity first with a trivial one-column view before any layout work.
Design the views before the reports. The view list is your reporting API.
Build the branded template shell second, so the first real report is already correct.
Externalize color and type into CSS from day one.
Standardize the parameter signature across reports.
Test every export format and the scheduled path before showing anything to a client.
Write down the environment specifics: driver path, JDK path, font directory, and resource names. In the future, you will need them at an inconvenient moment.

Conclusion

Connecting a third-party reporting tool to InterSystems IRIS is mostly a modeling and configuration exercise, not a rendering one. Once the security resources, JDBC details, and view layer are right, the reporting tool does what it is good at, and IRIS keeps doing what it does best. The details that matter are specific and learnable — resource names, host resolution, dataset placement, metadata caching — and each one becomes a checklist item rather than a recurring problem. We recommend spending the first day on the views and the branded template since, with those two in place, every report after the first one is mostly layout.

Having tried a few other solutions, what stands out about InterSystems Report is how approachable it makes complex queries in a low-code way. It assumes a baseline understanding of SQL, but beyond that, the deeper concepts (grouping, nested groups, aggregation, and reset scopes) are unusually easy to reason about once you see how they are expressed in the Designer. That combination is what made it a good fit for reports that are structurally rich but need to be maintained by more than one person.

A practical tip for getting started: build a plain table first. A table shows you exactly what the query returned, so you can confirm that the data is what you expect before any presentation decisions are made. Once the table is right, base everything else (charts, summaries, grouped layouts) on that same verified dataset. It is a much shorter path than debugging a chart that is beautifully drawing the wrong numbers.

The one area where we would love to see the product evolve is styling: a little consolidation there would go a long way. Today, it is spread across several models: some styling is standard CSS, some uses Logi-specific class and property naming, and some deprecated mechanisms still appear in the UI. This makes it hard to tell which approach is current. There is also no first-class way to save a report's look as a reusable template; the practical workaround is to copy an existing report and build the new one on top of it, which works but means visual standards live in a file rather than in something explicitly designed to be shared. A single, clearly documented styling path plus a native template object would make brand consistency across a report suite considerably easier to achieve and to hand over. Everything we needed was reachable — it just took some exploration to find the right combination, and that is exactly the kind of thing better defaults could solve.

The setup has been stable in production, and we are glad to compare notes with anyone building something similar.

Complementing IRIS with MLflow for a Continuous Training (CT) pipeline

InterSystems Developer — Wed, 30 Sep 2026 15:23:05 +0000

A Continuous Training (CT) pipeline formalises a Machine Learning (ML) model developed through data science experimentation, using the data available at a given point in time. It prepares the model for deployment while enabling autonomous updates as new data becomes available, along with robust performance monitoring, logging, and model registry capabilities for auditing purposes.

InterSystems IRIS already provides nearly all the components required to support such a pipeline. However, one key element is missing: a standardised tool for model registry. In this article, I present this approach (v0.1.0), which combines the strengths of IRIS with the open-source AI engineering platform MLflow. Together, they act as complementary tools for building an effective Continuous Training (CT) pipeline.

The implementation in this repo leverages MLflow's built-in configuration to store SHAP explainers to provide explanations behind the predictions made by the corresponding model made at the time, including "black-box" complex ones such as Random Forest, XGBoost, Neural Networks, etc.

Demo: https://youtu.be/qLdc4jhn83c

CT Pipeline Components

The theory behind the modules of this CT pipeline is based on the industry standard for MLOps level 1 defined by Google in this article, and the implementation of each of its components leverages the best features of both IRIS and MLflow, highlighted in red as seen in the image below:

For those new to CT pipelines, the image above describes how a traditional experimentation phase of a Data Science project (upper section "experimentation/development/test"), usually done in Jupyter notebooks, is transformed into a production-grade deployment of the developed model that allows continuous monitoring of performance over time, and automatic retraining whenever model performance degrades. All this with proper model versioning and logging for auditing purposes.

We delve into the details on the README of the repo, but for early understanding of each component, we briefly define below what each one does, and how that relates to the IRIS/MLflow tool chosen for that purpose.

Feature Store: Is the single source of truth for sourcing the data, and where every constant parameter or definition related to the data itself is defined, which might vary across clients and use cases (e.g. each client might define readmission after 15, 30, or any other number of days. Late arrival to an appointment might be considered arriving after 5, 10, or any other number of minutes). IRIS SQL Tables' multidimensional globals allow high-speed storage, and stored computed properties ease the definition of custom properties along with the raw data itself.
Automated Pipeline: Is the formalized and clearly modularized version of the "orchestrated experiment" that's usually done in a jupyter notebook, prepared to be executed every time the model has to be retrained if required. It contains every data and model-training process needed to get the model with the best overall performance. In this section, every constant related to the model itself chosen during the experimentation phase (previously done by data scientists in jupyter notebooks) is defined (e.g. seed, test size, K-folds for validation, etc). In our implementation, we leverage embedded python to easily access IRIS classes directly, along with all required standard Machine Learning python libraries (Pandas, scikit-learn, MLflow, etc).
Model Registry: During Training, each model that is trained is logged into the MLflow's backend registry, automatically configured when building the project. We can at any moment re-download models from there and query performance of previous models.
Trained Model: Though the MLflow backend has an Artifact Store where the weights of all trained models are stored, this project additionally saves the artifacts directly into a persistent location (Docker volume) for quick loading when needed. In case these are deleted, they are downloaded and re-saved in the same location from the MLflow Artifact Store.
Model Serving: This block is in charge of managing the model that is served to production. We store the path to the model's artifacts to be used in production in an IRIS global, which is what gets updated whenever necessary. In this repo we directly promote the new model if it performs better than the previous one, but in a real scenario this might require human approval. We decided to store the path to the model in a global and not the model itself because doing that would imply additional processing time for serialization and deserialization of the python object, whereas text is faster and straightforward to read from a global regardless of classes in the whole repository, making it easy and fast to read anywhere.
Prediction Service: Is the actual service that a client would use to request inferences on the current model set in production. At the moment this repo uses an embedded python method for this, but this block can potentially be improved by transforming the model into PMML format to make the production service executable using Integrated ML for any sklearn models, or any python model like LightGBM using the upcoming IntegratedML custom models in IRIS 2026.1.
Performance Monitoring: Is any sort of monitoring that can be made implemented to keep track of the performance of the current model in production, along with previous ones if necessary. For this we leverage MLflow's UI, where we can make custom plots with any of the variables logged, datetime, performance metrics, both for each model and for all models historically trained.
Trigger: Is whatever activates the execution of the Automated Pipeline. It can be data drift, model degradation beyond a certain threshold, availability of a certain amount of new data with enough ground truth, or a simple periodic schedule. In this project we directly compare against a defined threshold of the R² metric, so every time performance falls below the value in MLpipeline.PerformanceMonitoring.R2THRESHOLD, we execute the automated pipeline. For this task, another valid approach would be to use the task manager to schedule a method that looks at the performance registered during performance monitoring in MLflow tracking, and decide whether to retrain a new model.

The addition of MLflow enables straightforward historical performance monitoring of models over time through a single, locally hosted UI in a Docker container. It allows you to store and access artifacts from all previously trained models, including those deployed to production. These artefacts can be downloaded whenever needed, along with standard and custom performance metrics and custom visualisations.

For each run associated with a model, it is also possible to log additional artifacts such as SHAP explainers, custom plots, and user-defined metrics.

The implementation of this CT pipeline leverages Structured Logging to separate the logs from this pipeline from the rest of the system's, into a persistent path inside the volume of the container hosting IRIS.

Future Work

In the future, this pipeline can leverage the newly released feature in IRIS 2026.1: IntegratedML Custom Models, to make the prediction service easier through SQL commands, regardless of the model (added support for LightGBM, NNs, XGBoost, etc).
Right now, the model is only updated automatically by retraining on new data, but the hyperparameters remain static. By following the instructions in this guide this pipeline could be improved by introducing hyperparameter flexibility and allowing the model to be re-optimised using the open-source hyperparameter optimisation framework Optuna
In this project, when prediction performance falls below a predefined threshold, the model is retrained and automatically updated. However, in some cases, human approval should be required before making changes in production, which is something that should be considered in a real-life scenario.

Understanding InterSystems IRIS Architecture

InterSystems Developer — Mon, 28 Sep 2026 15:09:22 +0000

When people first hear about InterSystems IRIS, they often get overwhelmed by the sheer amount of information surrounding this technology. It is described simultaneously as a data platform, a database, an interoperability engine, an analytics platform, and even an application development platform. Of course, it is easy to get lost in all of this. Unlike many technology stacks where you must assemble multiple products — a database, an integration engine, an API server, a machine learning platform, and reporting tools — InterSystems IRIS actually brings these capabilities together into a single runtime. Rather than learning half a dozen separate products, you are simply learning the different capabilities of one unified platform.

This is precisely why IRIS (or rather Caché at that point) was chosen as a good example for my subject - to show students different things without the need to learn different software. Besides, instead of moving information between separate products, all components work directly with the same underlying data.
In this article, I will try to explain the architecture of InterSystems IRIS from a developer's perspective. Rather than diving into low-level implementation details, we will look at the major building blocks, how they fit together, and the kinds of applications they are designed to support.

Multi-Model Data Engine

Every application starts with data. At the core of InterSystems IRIS is an extremely high-performance multi-model database engine supporting the following data models:

Hierarchical
Key-value
Object
Document (JSON)
Relational
Columnar
Vector

Internally, all of these models are simply different ways of viewing the same stored data. You can read more about the data models in my previous article.

This data engine forms the foundation for every other subsystem in IRIS.

Interoperability

One of the best-known parts of InterSystems technology is its interoperability engine.

Real-world systems rarely exist in isolation. Applications must constantly exchange data using the following:

REST
SOAP
HTTP
TCP
Files
Message queues
Healthcare standards
Custom protocols

The interoperability engine provides the infrastructure to receive, transform, route, and deliver these messages. Instead of writing networking code repeatedly, developers configure productions composed of services, processes, and operations.

A typical flow might look like the following:

Inbound Adapter: Connects to an external system or data source and receives incoming messages, files, or requests into the interoperability production.
Business Service: Accepts data from the inbound adapter, validates or preprocesses it, and converts it into an internal message for further processing.
Data Transformation: Maps and converts data from one format or schema into another so the next component or target system can understand it.
Business Process: Implements the workflow or business logic, determining how messages should be processed, routed, or orchestrated.
Business Operation: Sends the processed message to its destination, such as another application, a database, a web service, or a messaging system.
Outbound Adapter: Handles the low-level communication with the target system using the appropriate protocol (e.g., HTTP, TCP, FTP, JDBC, or HL7).

IRIS includes numerous built-in adapters for common communication protocols together with graphical tools for building integration pipelines. For developers building enterprise software, this means a massive portion of the coding is already done!

Analytics

Modern applications need to do more than just store data - they need to extract insights from it. While many technology stacks rely on separate analytics platforms, InterSystems IRIS integrates analytics directly into the core platform. This allows developers to query, analyze, and visualize operational data without moving it into another system. Depending on the edition, this includes the following capabilities:

IRIS BI (Business Intelligence): Enables developers and business users to build interactive dashboards, perform multidimensional analysis, and explore data from different perspectives to identify trends and support decision making.
InterSystems Reports: Provides a flexible reporting environment for designing, generating, and distributing professional reports in various formats, making it easy to present business data to end users.
Columnar Storage: Complements the transactional row-based storage by organizing analytical data in a column-oriented format. This significantly improves the performance of large-scale aggregations and reporting queries without impacting day-to-day transactional workloads.
Vector Search: Enables semantic search by storing and querying vector embeddings alongside your operational data. Instead of searching for exact keywords, it finds information based on meaning, enabling retrieval of conceptually similar documents even when they do not share the same wording.

These components work together to support everything from traditional business reporting to modern AI-powered applications. Rather than exporting information into a separate analytics database, applications can analyze operational data directly. This architecture reduces latency and avoids the need to maintain duplicate datasets. Also, IRIS integrates seamlessly with existing data and application technologies, including popular third-party BI tools, such as Tableau, Looker, Qlik, Microsoft Power BI, and Excel.

AI and ML

Rather than requiring a collection of specialized databases and AI services, InterSystems IRIS provides built-in capabilities to develop AI-powered solutions that work directly with operational data. Depending on the edition, this includes the following capabilities:

IntegratedML: Allows developers and SQL users to build, train, and deploy machine learning models using simple SQL statements, eliminating the need for specialized machine learning expertise or complex data science pipelines.
Vector Search: Stores and indexes vector embeddings directly within InterSystems IRIS, enabling semantic search and similarity matching across enterprise data without requiring a separate vector database.
GenAI Frameworks: Offer libraries and development tools for building AI-powered applications, including Retrieval-Augmented Generation (RAG) systems, intelligent assistants, semantic search, and document question-answering solutions.

Together, these capabilities enable developers to integrate structured enterprise data with modern AI techniques on a single platform. By keeping operational data, vector embeddings, and AI workflows within the same environment, InterSystems IRIS simplifies application architecture, reduces data movement, and accelerates the development of intelligent applications.

Application Services

Beyond data storage and processing, IRIS is also an application platform. Applications can be written in several languages, including the following:

ObjectScript
Python

REST and GraphQL endpoints can also be exposed directly from the platform, making it straightforward to build APIs without introducing additional middleware.

Final Thoughts

At first glance, InterSystems IRIS can seem difficult to categorize because it refuses to fit into a single box. Is it a database? An integration engine? An analytics platform? An application server? The answer is yes to all of the above. Its architecture is built around a single high-performance multi-model data engine, with interoperability, analytics, APIs, application development, and operational capabilities layered on top. Rather than stitching together separate products, developers work within one cohesive environment where every component shares the same underlying data.

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

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

Hi, Community!

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

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

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

TL;DR

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

Who This Article Is For

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

Prerequisites

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

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

Adding the Property Pitfalls Code Activity

Open Demo.HL7Router in the Business Process Designer.

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

Reconnect the arrows:

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

Label it Property Pitfalls.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Test and Verify

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

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

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

Understanding the Seven Pitfalls

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

Pitfall 1: Underscore in Property Name

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

Set val = dynObj.patient_id

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

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

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

Pitfall 2: Case Sensitivity

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

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

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

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

Pitfall 3: Nested Object Access

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

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

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

This pattern applies at every level of nesting:

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

Pitfall 4: Checking If a Property Exists

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

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

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

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

Pitfall 5: Iterating Over Properties

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

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

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

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

Pitfall 6: Null vs. Empty String

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

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

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

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

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

Pitfall 7: Number Type Handling

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

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

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

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

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

Common Mistakes

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

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

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

Practical Recommendations

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

FAQ

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

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

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

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

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

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

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

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

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

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

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

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

Conclusion

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

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

Thanks for reading!

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

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

Hi, Community!

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

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

TL;DR

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

Who This Article Is For

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

What Is a Business Rule?

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

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

What Is a Dynamic Object?

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

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

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

The Production We Will Build

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

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

Step 1: Create the Production

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

Fill in the form with the following data:

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

Click OK.

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

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

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

Step 2: Configure the Auto-Created Components

Configure HL7FileService

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

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

Click Apply.

Configure HL7FileOperation

Click on HL7FileOperation in the canvas and set the following:

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

Click Apply.

Step 3: Build the BPL Business Process

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

3A. Create the Process

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

3B. Define Context Properties

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

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

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

3C. Add the Code Activity

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

Connect the arrows:

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

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

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

// Read values from the actual HL7 message
Set dynObj.MsgType     = request.GetValueAt("MSH:MessageType.MessageCode")
Set dynObj.PatientName = request.GetValueAt("PID:PatientName(1).FamilyName")
Set dynObj.SendingApp  = request.GetValueAt("MSH:SendingApplication")

// Use %Set() for underscore-named properties
Do dynObj.%Set("patient_id",    request.GetValueAt("PID:PatientIDList(1).IDNumber"))
Do dynObj.%Set("patient_sex",   request.GetValueAt("PID:AdministrativeSex"))
Do dynObj.%Set("date_of_birth", request.GetValueAt("PID:DateTimeofBirth"))

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

// Store in context
Set context.MetaData = dynObj

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

3D. Add the Process to Production

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

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

Click OK.

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

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

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

HL7FileService
HL7Router
MsgRouter
HL7FileOperation

How It All Fits Together

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

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

Step 4: Start the Production and Test

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

The Sample HL7 Message

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

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

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

Verify in Message Viewer and Visual Trace

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

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

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

Common Mistakes

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

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

Practical Recommendations

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

FAQ

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

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

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

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

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

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

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

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

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

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

What Is Coming in Part 2

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

Conclusion

Dynamic objects are a practical tool that enriches HL7 messages with metadata before routing decisions are made. The key is to build them in a BPL Code activity, logging every property during development, and storing them in context variables that downstream components can evaluate cleanly.

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

Thanks for reading!

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

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

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

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

What is this project?

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

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

What the example exposes

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

There are five tools:

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

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

How AI Hub fits into the project

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

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

Application Architecture

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

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

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

A request from an MCP client follows this path:

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

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

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

Running the toolkit

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

VS Code

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

{ 

  "servers": { 

    "health-example": { 

      "type": "http", 

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

      "headers": { 

        "Authorization": "Basic <generated key>" 

      } 

    } 

  } 

}

Mistral or other CLI AI agents

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

[[mcp_servers]] 

name = "care_data" 

transport = "streamable-http" 

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

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

Start Vibe and use /mcp to inspect the connection.

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

Python smoke test

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

uv venv --python 3.12

source .venv/bin/activate

uv pip install -r requirements.txt

set -a

source .env

set +a

python test_mcp.py

From an ObjectScript method to an MCP tool

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

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

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

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

Step 1: Define the database user and role

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

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

Step 2: Write the tools in ObjectScript

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

For example, ListResources starts like this:

Class MCPData.Tools.HealthExample Extends %AI.Tool

{

ClassMethod ListResources() As %DynamicObject [ WebMethod ]

{

    ...

}

}

This class contains the application logic:

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

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

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

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

Step 3: Apply authorization before execution

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

The policy defines the tools that may be called:

Set allowlist=$LISTBUILD(


    "ListResources",


    "SearchPatients",


    "ReadGlobalData",


    "LargestGlobals",


    "RecentApplicationErrors"


)

If $LISTFIND(allowlist,name)=0 {


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


}

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

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

The result is a layered validation flow:

Authorization policy


    ↓


Is this tool allowed?


    ↓


Are its arguments within the approved scope?


    ↓


Tool implementation


    ↓


Are the inputs still valid before accessing data?


    ↓


IRIS database privileges


    ↓


Can the connected user perform the operation?

Step 4: Record successful and failed executions

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

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

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

Depending on the tool, an audit record can include:

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

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

Step 5: Attach the policies to a ToolSet

We now have separate components for:

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

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

Its definition is:

<ToolSet Name="CareOutreachData"> 


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


    <Policies> 


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


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


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


</ToolSet>

We can observe this definition and see that:

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

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

Step 6: Expose the ToolSet through an MCP service

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

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

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


{


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


}

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

The complete structure is:

MCPData.Service.HealthExample


        ↓


selects


        ↓


MCPData.ToolSet.HealthExample


        ↓


        ├── Authorization → MCPData.Policy.Authorization


        ├── Audit         → MCPData.Policy.Audit


        └── Tools         → MCPData.Tools.HealthExample

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

Security model in practice

Sensitive access is so controlled at several layers:

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

Testing and examples

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

Try asking:

List all available resources and tools from the MCP server.

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

Show me the 5 largest globals in the MCP_EXAMPLE namespace.

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

Execute SELECT * FROM MCPData_Data.Patient

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

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

Conclusion

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

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

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

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

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

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

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

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

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

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

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

This article focuses on how the pieces work together.

What the project runs

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

Configure an agent, skills and tools through AI HUB

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

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

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

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

Class Test.Agent Extends %AI.Agent

{

Parameter TOOLSETS = "Test.ToolSet.Local";

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


}

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

This gives us a useful separation of responsibilities:

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

Defining a skill

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

For example, the project contains a simple Poet skill:

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

}

There are three pieces worth noticing here:

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

Defining a simple tool and a toolset

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

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

Class Test.Tools.Calculator Extends %AI.Tool 


{ 

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

{ 

    Return a + b 

} 

}

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

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

Class Test.ToolSet.Local Extends %AI.ToolSet 


{ 

XData ToolSet 

{ 

<ToolSet Name="Local"> 

    <Tool Name="Calculator" 

        Class="Test.Tools.Calculator"/> 

    </ToolSet> 

} 

}

This gives us a simple hierarchy:

Agent


  │


  └── ToolSet


        │


        └── Tool


              │


              └── WebMethod

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

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

Defining an agent

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

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

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

Method %OnInit() As %Status


{


  Set sc=##super()


  If $$$ISERR(sc) Quit sc

If '$ISOBJECT(..Provider) {

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

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

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

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

  }

If $$$ISERR(sc) Quit sc


  Quit $$$OK


}

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

Class Test.Agent Extends %AI.Agent


{


Parameter TOOLSETS = "Test.ToolSet.Local";

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

Method %OnInit() As %Status

{

  Set sc=##super()

  If $$$ISERR(sc) Quit sc

If '$ISOBJECT(..Provider) {

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

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

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

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

  }

If $$$ISERR(sc) Quit sc

  Quit $$$OK

}

}

Connecting an external MCP server

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

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

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

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

from fastmcp import FastMCP

mcp = FastMCP("HealthcareStatistics")

@mcp.tool()


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


    """Add two numbers."""


    return first + second

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

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


Class Test.ToolSet.StatisticsMCP Extends %AI.ToolSet


{


XData Definition [ MimeType=application/xml ]


{


<ToolSet Name="StatisticsMCP">


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


  <MCP Name="Statistics">


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


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


  </MCP>


</ToolSet>


}


}

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

Starting a conversation: sessions, monitoring and chat

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

First we create and initialize the agent:

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


Set sc = agent.%Init()

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

Set session = agent.CreateSession()

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

For example:

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


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

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

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

User prompt


    │


    ▼


   LLM


    │


    ├── requests a tool


    │         │


    │         ▼


    │      AI Hub


    │         │


    │         ▼


    │    tool executes


    │         │


    ◄─────────┘


    │


    ▼


   LLM


    │


    ▼


Final response

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

Continuing the same conversation

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

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

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

If instead we create another session:

Set anotherSession = agent.CreateSession()

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

The distinction can therefore be summarized as:

Test.Agent


    │


    ├── Session A


    │     ├── User message


    │     ├── Tool call


    │     ├── Tool result


    │     └── Assistant response


    │


    └── Session B


          └── Independent conversation

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

Seeing what the agent is doing with a monitor

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

In this project I defined a specific monitor class:

Class Test.DemoMonitor Extends %RegisteredObject


{


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


{


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


}

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

{

  Set stats=session.GetStats()

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

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

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

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

}

}

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

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


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

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

[agent iteration 1/5] 


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


Total tool calls: 2

Monitoring the execution helps us distinguish between these cases.

Inspecting the session statistics

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

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

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

Delegating work to sub-agents

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

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

In this project I use two forms of delegation:

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

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

Defining a predefined sub-agent

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

A simplified delegation tool looks like this:

Class MyApp.SubAgents.Reviewer Extends %AI.Tool


{


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

Property ParentAgent As %AI.Agent;

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

{

  If $ISOBJECT(parentAgent) {

    Set ..ParentAgent=parentAgent

  }

  Quit $$$OK

}

/// Review a task from the parent agent.


///


/// Args:


///     task: task to be reviwed


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


{


  Set output = ""


  Try {


    If '$ISOBJECT(..ParentAgent) {


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


    }


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


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


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


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


    Set session=subagent.CreateSession()


    Set response=subagent.Run(session,task)


    Set output = response.Content


  } Catch exception {


    Set sc = exception.AsStatus()


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


  }


  Return output


}


}

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

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

Property ParentAgent As %AI.Agent;

Generic Delegation

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

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

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


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


Class Test.Tools.DelegateTasks Extends %AI.Tool


{

/// Tool description for LLM

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

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

Property ParentAgent As %AI.Agent;

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

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

{

    If $ISOBJECT(parentAgent) {

        Set ..ParentAgent = parentAgent

    }

    Quit $$$OK

}

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

///

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

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

///

/// Parameters:

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

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

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

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

{

    Try {

        If '$ISOBJECT(..ParentAgent) {

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

        }

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

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

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

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

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

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

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

    Return response.Content

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


}

}

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

For example, the parent could request:

specialistRole = "mental-math teacher"


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

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

specialistRole = "technical editor"


task = "Review this explanation for clarity."

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

Registering a generic delegation tool without a Toolset

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

Method %OnInit() As %Status


{


  ......


  Do things


  ......


  Set sc=..RegisterGenericDelegateTool()


  If $$$ISERR(sc) Quit sc


  Quit $$$OK


}

Method RegisterGenericDelegateTool()


{


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


  Do ..ToolManager.AddTool(delegateTool)


}

Start the environment

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

A first conversation in ObjectScript

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

Open IRIS terminal and create a bundled simple chat agent:

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


Set sc=agent.%Init()


Do $SYSTEM.Status.DisplayError(sc)

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

Set session=agent.CreateSession()


Set maxIterations=5


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

CreateSession() creates the conversation context.

We can run the first request:

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


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


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

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

The returned response exposes its text through Content.

Keep the same session for a follow-up:

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


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


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

You can also register a skill from the terminal:

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


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


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


Write session.ActiveSkills.%ToJSON(),!

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

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

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

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

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


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


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

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

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

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


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


}

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

Testing agents in the browser

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

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

Opening the Agent Studio

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

The initial workspace is divided into two main areas:

Sidebar
- Recent chats
- Configuration
- Selected Agent
Main chat

Selecting an existing `%AI.Agent`

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

Choosing the model

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

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

Starting a conversation

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

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

Loading a skill from the UI

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

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

An example of a skill usage

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

Reopening conversations

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

Conclusion

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

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

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

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