Home

InterSystems IRIS Cheat Sheet

Notes from an Intersystems IRIS course that I attended in 2024.

Core Concepts

IRIS Data Platform

  • Database + application server in same process = fast cache access
  • Hierarchical data structure using Globals (multi-dimensional arrays)
  • Namespace-based application isolation
  • Multiple API layers: Objects, SQL, Globals
  • Database = Ensemble = Caché (superset of relational database)

Process Types

  • Core processes: Code with direct database cache access
    • Generic memory heap
    • Routine cache
    • Database cache
  • User processes: Standard application processes

Storage Model

// Storing data in Globals (tree-like structure)
Set ^Patient("123") = "John Doe"
Set ^Patient("123","Age") = 30
Set ^Patient("123","Address") = "123 Main St"

// Retrieving data
Write ^Patient("123")           // Output: John Doe
Write ^Patient("123","Age")     // Output: 30

Globals Tree Example

heroes                                           // root node, valueless, 2 child nodes
   heroes('dogs')                                // level 1 node, valueless, 4 child nodes
      heroes('dogs','Balto') = 1919              // level 2 node, value=1919
      heroes('dogs','Hachiko') = 1923            // level 2 node, value=1923
      heroes('dogs','Lassie') = 1940             // level 2 node, value=1940, 1 child node
         heroes('dogs','Lassie','Timmy') = 1954  // level 3 node, value=1954
      heroes('dogs','Whitefang') = 1906          // level 2 node, value=1906
   heroes('sheep')                               // level 2 node, valueless, 1 child node
      heroes('sheep','Dolly') = 1996             // level 2 node, value=1996

Persistence

  • Everything stored as globals internally
  • Tree-based sparse arrays implement multidimensional storage
  • IRIS.dat = database file containing data + code
  • Changes: memory → journal files → IRIS.dat
  • Write image journal files created during backup

Backup Methods

  • File system snapshot of: IRIS.dat + write image journal files + journal files
  • Alternative: freeze call → backup files → thaw call

Interoperability Architecture

Production Components

External System → Protocol → Business Service (input)
    ↓
Ensemble Message → Business Process (logic)
    ↓
Ensemble Message → Business Operation (output) → Protocol → External System

Business Hosts

  • Business Service: Input adapters, protocol handlers
  • Business Process: Business logic, routing, transformations
  • Business Operation: Output adapters, external system connections

Messages

  • Interoperability messages = communication between hosts
  • Persisted objects with ID, Session ID, Header, Body
  • Statuses: Created, Deferred, Queued, Delivered, Completed, Error
  • All messages viewable via Interoperability → Message Viewer
  • Indexing done with SearchTable classes (e.g., EnsLib.HL7.SearchTable)

HL7 Integration

HL7 v2 Structure

  • Message Type: ADT, ORU, ORM
  • Trigger Event: A01 (admit), A03 (discharge)
  • Segments: MSH, EVN, PID, etc.
  • v2.5: World’s most popular version
  • v2.3.1: Version used in Finland

MLLP Protocol

<11>              // start block character
MSH|^~\&|...      // HL7 message
EVN||...
<28><13>          // end block characters

Finnish MLLP Variants

  • Esko: MLLP1/2, Byte ACK, drops connection after 2s
  • Effica: MLLP, Immediate ACK, stays connected
  • Kuopio Musti: [Configuration varies]
  • Naantali Pegasos: [Configuration varies]
  • Joensuu TcLab: [Configuration varies]

Order Critical Processing

  • Use Pool Size = 1 for HL7 business processes
  • One worker dequeuing and processing messages sequentially

ObjectScript Fundamentals

Core Languages

  • ObjectScript: Also known as Caché ObjectScript, compiled into object code
  • Business Process Language (BPL): Visual workflow language
  • Data Transformation Language (DTL): Data mapping language

Basic Syntax

// Variables (case sensitive)
Set name = "John Doe"
Set age = 30

// Commands (case insensitive)
Write "Hello World"
Set ^Global("key") = "value"

// Special variables
Write $ZVersion        // System version
Write $Horolog         // Current time

// Macros (don't work in terminal)
#define MYMACRO "Hello"
Write $$$MYMACRO       // Call macro with $$$

// Class references
##class(MyClass).Method()

Classes

Class Events.DB.Contact Extends %Persistent
{
    Property FirstName As %String;
    Property LastName As %String;
    Property Email As %String;

    Method GetFullName() As %String
    {
        Return ..FirstName _ " " _ ..LastName
    }
}

Class Types

  • RegisteredObject: Not persisted in database
  • PersistentObject: Persisted in database (extends %Persistent)
  • SQL table definition generated automatically
  • Cannot be renamed, only copied

Method Parameters

// Pass by reference
Method UpdateContact(ByRef contact As %String)
{
    // modify contact
}

// Call with dot notation
Do ..UpdateContact(.myContact)

Development Tools

Console Access

1# Enter IRIS terminal
2docker exec -it <container> iris session IRIS
3
4# Select namespace
5zn "events"
6
7# Exit
8h

Debugging

// Examine object
Set obj = ##class(Ens.MessageHeader).%OpenId(513)
zwrite obj      // Show object details

Visual Studio Code

  • Install InterSystems plugins
  • Right-click file: Compile, Export
  • Wizards for Business Hosts

Message Management

Query Messages

 1-- Search by message ID
 2SELECT * FROM Ens.MessageHeader WHERE id = 413;
 3
 4-- Search by session ID
 5SELECT * FROM Ens.MessageHeader WHERE SessionId = 2411;
 6
 7-- Time-based search
 8SELECT Id, SessionId FROM Ens.MessageHeader
 9WHERE TimeCreated >= ? AND TimeCreated <= ?
10AND TargetConfigName = 'To_Espoo_Effica'
11AND Status <> ?
12ORDER BY SessionId;

Resend Messages

Set tStatus = ##class(Ens.MessageHeader).ResendDuplicatedMessage(
    pMessageId, .tNewMessageId, "HL7v2MessageRouter")

Time Conversion

#Dim tTimeCreatedMin As Ens.DataType.UTC =
    ##class(Ens.DataType.UTC).DisplayToLogical("2022-06-16 12:00:00.552")

Monitoring & Alerts

Navigation

  • Interoperability → Monitor → System Monitor
  • Interoperability → Monitor → Production Monitor
  • Interoperability → Monitor → Queues

Alert Configuration

  • Enable “Alert On Error” in Business Services/Processes
  • Set “Queue Count Alert” = 5
  • Set “Queue Wait Alert” = 5

Alert Process

  1. Wait for alert (Ens.AlertRequest messages)
  2. Identify component using messages/event log
  3. Fix: settings, rules, or code
  4. Clean up: resend modified messages

Business Rules

Rule Components

  • Rule set: begin, start, one or more rules
  • Routing rules: Direct messages to destinations
  • Ordinary rules: Custom business logic
  • Allow non-technical users to change system behavior

High Availability

Mirror Configuration

  • Primary Member: Active database server
  • Backup Members: Standby replicas
  • Arbitrer: Helps determine primary in failover

Setup

  • Installer wizard → Configure foundation → Mirror Database
  • Replicates data across multiple servers
  • Automatic failover capability

Data APIs

JSON Support

Class MyClass Extends (%Persistent, %JSON.Adaptor)
{
    // Automatic JSON serialization/deserialization
}

XML Support

Class MyClass Extends (%Persistent, %XML.Adaptor)
{
    // Automatic XML serialization/deserialization
}

Dynamic Objects

Set obj = {}                    // %Library.DynamicObject
Set arr = []                    // %Library.DynamicArray

Best Practices

Performance

  • Use Pool Size = 1 for order-critical HL7 processes
  • Database + application in same process = fast cache access
  • Core processes have direct database cache access
  • Message warehouse stores every message exchange between business hosts

Security

  • Never commit secrets to repository
  • Use proper authentication for external connections
  • Follow least privilege access principles

Development

  • Export code using Visual Studio InterSystems plugin
  • Use namespaces to isolate applications
  • Clean up persisted messages manually (they don’t auto-delete)

Common URLs

Development Environment

  • Management Portal: http://localhost:52773/csp/sys/UtilHome.csp
  • Class List: http://localhost:52773/csp/sys/exp/%25CSP.UI.Portal.ClassList.zen

Key Packages

  • Ens.* → Interoperability core (EnsLib database)
  • EnsLib.* → Interoperability library
  • HS.* → Healthcare-specific code

InterSystems Users

  • Healthcare & Life Sciences (laboratories, etc.)
  • Financial Services (high-performance trading, etc.)
  • Government & Public Sector
  • etc

Installation

Containers

1# Run IRIS container
2docker run -d --name iris -p 52773:52773 intersystemsdc/iris-community
3
4# Access terminal
5docker exec -it iris iris session IRIS

Tools

1# Install Postman for API testing
2brew install --cask postman

Version Control

  • Export code via Visual Studio Code InterSystems plugin
  • Store exported code in version control
  • Import during deployment
  • Source code available for IRIS platform

Deployment Options

  • Containers
  • Kubernetes
  • Installation Kit for Windows, Linux, and macOS
Tags: Database, Healthcare, Objectscript, Iris, Nosql, Integration