DEV Community: InterSystems

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.

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

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

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

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

Let's start with the foundation

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

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

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

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

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

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

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

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

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

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

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

Iterating over structure you don't control

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

Set iter = obj.%GetIterator()

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

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

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

Type discovery inside a dynamic entity

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

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

// the indexes are:

//       0,      1,    2,       3,       4

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


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


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

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

The date gotcha

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

Two things both called "array"

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

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

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

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

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

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

Set key = ""


For 


{ 


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


    Write !, key, ": ", value 


}

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

Bridging persistent objects and dynamic objects

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

Set sc = person.%JSONExportToString(.json)


Set dynObj = {}.%FromJSON(json)

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

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


Set dynObj = {}.%FromJSON(json)

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

Where dynamic freedom ends: validation

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

Method %OnValidateObject() As %Status


{


    If ..fieldOptions.%Size() = 0 


    {


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


    }

Return $$OK


}

Choosing well

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

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

InterSystems for dummies – IRIS Vector Search (Part II)

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

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

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

Vector Calculation

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

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

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

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

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

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

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

First Steps

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

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

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

You can create the data by running the following command:

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

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

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

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

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

The values of feelings are as follows:

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

For example:

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

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

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

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

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

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

Example:

“Today, I’m very happy.”

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

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

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

Dot Product Search

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

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

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

This search gives us the following results:

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

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

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

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

This search gives us the following results:

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

Cosine Similarity Search

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

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

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

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

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

Does it Support Multiple Languages?

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

“Hoy, estoy muy feliz.”

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

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

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

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

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

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

I recommend testing the same text in different languages.

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

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

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

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

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

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

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

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

Case Study

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

You can access the demo via the link below:

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

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

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

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

See you at the next “InterSystems for Dummies”!

InterSystems for dummies – IRIS Vector Search (Part I)

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

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

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

:::pagebreak:::

What Are Vectors?

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

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

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

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

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

These two vectors are represented as follows:

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

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

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

What Do Mathematical Vectors Have to Do with Vector Search?

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

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

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

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

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

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

Are Vectors Really “Arrows”?

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

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

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

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

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

Vector Search Algorithms

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

Vector Similarity Searches:

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

Euclidean Distance:

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

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

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

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

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

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

Magnitude of a Vector

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

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

V1 = 5,83095189

V2 = 10

V3 = 5,6568542

Dot Product

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

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

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

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

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

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

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

We can say that v1 and v2 are very similar.

Cosine Similarity

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

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

It is calculated using the following formula:

Following the previous example,

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

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

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

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

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

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

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

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

How Do We Use This Mathematical Knowledge In Vector Search?

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

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

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

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

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

The Gaia Planetarium: A Full-Stack Embedded Python Project

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

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

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

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

Project Design

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

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

So I decided upon the following stack:

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

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

- Front-end UI with HTML/CSS/JS

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

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

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

IRIS Implementation

PyProd

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

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

The Web App: Flask

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

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

from flask import Flask, request

import iris # Embedded python IRIS import 

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


  
  
  Endpoint to access stars from the Database


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

def get_stars() 

    # SQL Query 

    query = """

        SELECT TOP 1000 SourceId, Ra, DecDeg, PhotGMeanMag 

        FROM "Gaia.SourceLocation"

        """

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

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

# Return results
return output

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

from intersystems_pyprod import director 


  
  
  POST endpoint


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

def add_stars(): 

    # Get the info from the post request

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

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

# Activate Business Service
service.process_input(n_stars)

Flask hosting

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

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

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

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

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

Front-end

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

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

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

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

from flask import Flask, jsonify, request, send_from_directory

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

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

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

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

Conclusion

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

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

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

DEV Community: InterSystems

Connect Microsoft Excel to InterSystems IRIS via ODBC (Windows)

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

TL;DR

Who This Article Is For

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

What We Were Building

Why InterSystems Report and Not Power BI or Tableau

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

The JDBC detail worth writing on a sticky note:

Step 2: Let SQL Views Be the Contract

Step 3: Running the Report Server as a Windows Service

Step 4: Binding Data Inside the Report

When you change a view, refresh the metadata:

Step 5: Brand Consistency Without Copy-Paste

Step 6: Parameterize for Scheduling, Not for Clicking

Common Mistakes

Frequently Asked Questions

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

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

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

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

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

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

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

Practical Recommendations

Conclusion

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

CT Pipeline Components

Future Work

Understanding InterSystems IRIS Architecture

Multi-Model Data Engine

Interoperability

Analytics

AI and ML

Application Services

Final Thoughts

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

TL;DR

Who This Article Is For

Prerequisites

Adding the Property Pitfalls Code Activity

Test and Verify

Understanding the Seven Pitfalls

Pitfall 1: Underscore in Property Name

Pitfall 2: Case Sensitivity

Pitfall 3: Nested Object Access

Pitfall 4: Checking If a Property Exists

Pitfall 5: Iterating Over Properties

Pitfall 6: Null vs. Empty String

Pitfall 7: Number Type Handling

Common Mistakes

Practical Recommendations

FAQ

Conclusion

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

TL;DR

Who This Article Is For

What Is a Business Rule?

What Is a Dynamic Object?

The Production We Will Build

Step 1: Create the Production

Step 2: Configure the Auto-Created Components

Configure HL7FileService

Configure HL7FileOperation

Step 3: Build the BPL Business Process

3A. Create the Process

3B. Define Context Properties

3C. Add the Code Activity

3D. Add the Process to Production

How It All Fits Together

Step 4: Start the Production and Test

The Sample HL7 Message

Verify in Message Viewer and Visual Trace

Common Mistakes

Practical Recommendations

FAQ

What Is Coming in Part 2

Conclusion

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

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

Selecting an existing `%AI.Agent`