You may notice when upgrading to IRIS For Health from 2024.1 to 2024.2+ (2025.1, 2026.1, etc.) that where you were previously accessing your FHIR Portal you are now receiving Not Found.

This article is intended as a beginner level article for people that want to learn how to use OAuth2 in their web applications natively.

There is an accompanying video/demo that may be helpful here: 

and you can reproduce this locally with the Open Exchange application attached.

OAuth2 as a native authentication type for web applications

OAuth (Open Authorization) 2.0 is a standard way to let one application call another application’s API without sharing a username and password.

One of the recommendations when deploying InterSystems Technologies for production is to set up High Availability. The recommended API Manager for these InterSystems Technologies is the InterSystems API Manager (IAM). IAM (essentially Kong Gateway) has multiple deployment topologies.

If you are looking for high availability you could use:

a) Kong Traditional Mode: Multiple Node Clusters

b) Hybrid Mode

c) DB-less Mode

Before we break them down let's first understand the out of the box deployment that is provided by InterSystems: Installing IAM Version 3.10.

Often times when working with FHIR data, for example with IRIS For Health, you'll find it useful to create a custom FHIR operation. The FHIR Standard comes with a set of defined operations (such as $everything) but a custom operation comes in handy when you need to create some extra functionality that goes beyond the set of standard FHIR operations. The docs take you step-by-step (though this comment may be helpful to those of you just getting started). One thing I would highlight, purely for aesthetic purposes, is how to syntactically name your function such that you can call it with hyphens.

If you look at the values.yaml of the IKO's Helm chart you'll find:

useIrisFsGroup:false

Let's break down what it is and in what situations you may want to set it to true.

FsGroup refers to the file system group.

By default, Kubernetes volumes are owned by root, but we need IRIS to own its files (IRIS in containers is installed under irisowner user). To get around this we employ one of two methods:

1) initContainers

The initContainers run before app containers (like IRIS) in a pod. They generally set up the environment for the application and then run to completion/terminate.

The Istio Service Mesh is commonly used to monitor communication between services in applications. The "battle-tested" sidecar mode is its most common implementation. It will add a sidecar container to each pod you have in your namespace that has Istio sidecar injection enabled.

It's quite easy to get started with, just put the istioctl executable in your PATH, and label your namespace such that it tells Istio to acitvate side car injection there.

All pods are assigned a Quality of Service (QoS). These are 3 levels of priority pods are assigned within a node.

The levels are as following:

1) Guaranteed: High Priority

2) Burstable: Medium Priority

3) BestEffort: Low Priority

It is a way of telling the kubelet what your priorities are on a certain node if resources need to be reclaimed. This great GIF below by Anvesh Muppeda explains it.

If resources need to be freed, firstly pods with Best Effort QoS will be evicted, then those with Burstable, and finally those with Guaranteed.

You may have noticed that to configure a mirror for InterSystems IRIS for Health™ and HealthShare® Health Connect there is a special requirement. I wanted to go through it step by step in this article.

This assumes you have already configured the second failover member and confirmed a successful failover member status in the mirror monitor:

Step 1: Enable HS_Services user (on backup and primary) 

Step 2: Switch to Namespace HSSYS and go to Interoperability > Configure > Credentials.

IAM - InterSystems API Manager is a great tool for monitoring your traffic. If you are trying to use it in your Kubernetes cluster you may have tried doing a deployment similar to this one:

apiVersion: intersystems.com/v1alpha1
kind: IrisCluster
metadata:
  name: iris
spec:
  licenseKeySecret:
    name: iris-key-secret
  configSource:
    name: iris-cpf
  imagePullSecrets:
    - name: intersystems-pull-secret
  topology:
    data:
      image: containers.intersystems.com/intersystems/iris-arm64:2024.1"2024.1.2"

Say I want to uninstall the IKO - all I need to do is:

> helm uninstall intersystems

What happens behind the scenes is that helm will uninstall what was installed when you ran :

> helm install intersystems <relative/path/to/iris-operator>

In some sense - this is symmetric to when we ran install - however with a different image.

You'll notice that when you install, it knows what image to take from:

operator:
  registry: containers.intersystems.com
  repository: intersystems/iris-operator-amd
  tag: 3.7

Data Analysis

This is the sequel to Data Collection. If you have not had a chance to go through and install that you should first do that.

What is provided here is the analysis for the collection of that data that was collected earlier.

In much the same way as was done in that repository you will need to import the xml that makes up this repository.

Starting at the topmost level there is a task:

InvestigateInfoTask

This task will allow us to set parameters that we will be monitoring. They are as follows:

GrowthPercentageWarning: What percentage growth is 'acceptable' for a global to grow.

Graphical Display of Tables

Here we will document how you can get the results of your Data Collection to be displayed graphically. The output of your project will look like this:

Note that I am working on a local machine. If you are doing this on a server then be aware to use the correct IP address.

First, we will import the three classes from the that we are going to need (note that we will edit them later):

You can take the xml and import it to your system.

The spec will actually create the dispatch class and implementation template.

Data Collection

This is a step-by-step instruction guide for creating a task to collect data about the InterSystems database and globals therein (as seen in the associated Open Exchange App - find all the associated code there)

UPDATE (Aug 1 2024): Recently I've been asked about the differences between this and the History Monitor functionality. In short, the data collection monitor builds on the history monitor by adding the ability to track growth of individual globals.

Disclaimer: This software is merely for TEST/DEMO purposes.

In case you're planning on deploying IRIS For Health, or any of our containerized products, via the IKO on OpenShift, I wanted to share some of the hurdles we had to overcome.

As with any IKO based installation, we first need to deploy the IKO itself. However we were getting this error:

Warning FailedCreate 75s (x16 over 3m59s) replicaset-controller Error creating: pods "intersystems-iris-operator-amd-f6757dcc-" is forbidden: unable to validate against any security context constraint:

proceeded by a list of all the security context constraints (SCCs) it could not validate against.

The IKO will dynamically provision storage in the form of persistent volumes and pods will claim them via persistent volume claims.

But storage can come in different shapes and sizes. The blueprint to the details about the persistent volumes comes in the form of the storage class.

This raises the question: we've deployed the IrisCluster, and haven't specified a storage class yet. So what's going on?

You'll notice that with a simple

kubectl get storageclass

you'll find the storage classes that exist in your cluster.

The IKO allows for sidecars. The idea behind them is to have direct access to a specific instance of IRIS. If we have mirrored data nodes, the web gateway will (correctly) only give us access to the primary node. But perhaps we need access to a specific instance. The sidecar is the solution.

Building on the example from the previous article, we introduce the sidecar by using a mirrored data node and of course arbiter.

apiVersion: intersystems.com/v1alpha1
kind: IrisCluster
metadata:
  name: simple
spec:
  licenseKeySecret:
    #

We now get to make use of the IKO.

Below we define the environment we will be creating via a Custom Resource Definition (CRD). It lets us define something outside the realm of what the Kubernetes standard knows (this is objects such as your pods, services, persistent volumes (and claims), configmaps, secrets, and lots more). We are building a new kind of object, an IrisCluster object.

apiVersion: intersystems.com/v1alpha1
kind: IrisCluster
metadata:
  name: simple
spec:
  licenseKeySecret:
    #

The IKO documentation is robust. A single web page, that consists of about 50 actual pages of documentation. For beginners that can be a bit overwhelming. As the saying goes: how do you eat an elephant? One bite at a time. Let's start with the first bite: helm.

What is Helm?

Helm is to Kubernetes what the InterSystems Package Manager (IPM, formerly ObjectScript Package Manager - ZPM) is to IRIS.

It facilitates the installation of applications on the platform - in a fashion suitable for Kubernetes.

With the world (as well as our own technology) moving to the cloud at such a fast pace it is easy (at least for myself) to get caught up in the little details. One thing I, and some clients of ours, had run into a couple of times was the necessity to specify the version of the images one plans to use with the IKO.

For example, one issue that often gets overlooked is the compatibilityVersion field for the IKO. Depending on which IKO you are using there is a default value (for IKO 3.6 this happens to be 2023.2.0, and for IKO 3.5 this is 2022.3.0).