This article will describe and include an example of how to embed an external PDF file into an HL7 segment, specifically ADT_A01:2.3.1 OBX().  This can be useful when attempting to insert pictures or other external data into an HL7 message.  In this example, the name of the PDF file to be embedded is provided in the incoming HL7 message in OBX(1):ObservationValue field.

2 3 8,426

Mirroring 101

Caché mirroring is a reliable, inexpensive, and easy to implement high availability and disaster recovery solution for Caché and Ensemble-based applications. Mirroring provides automatic failover under a broad range of planned and unplanned outage scenarios, with application recovery time typically limited to seconds. Logical data replication eliminates storage as a single point of failure and a source of data corruption. Upgrades can be executed with little or no downtime.

2 21 5,554


This article is a small overview of a tool that helps to understand classes and their structure inside the InterSystems products: from IRIS to Caché, Ensemble, HealthShare.

In short, it visualizes a class or an entire package, shows the relations between classes and provides all the possible information to developers and team leads without making them go to Studio and examine the code there.

If you are learning InterSystems products, reviewing projects a lot or just interested in something new in InterSystems Technology solutions — you are more than welcome to read the overview of ObjectScript Class Explorer!

2 35 4,678

Created by Daniel Kutac, Sales Engineer, InterSystems

Warning: if you get confused by URLs used: the original series used screens from machine called dk-gs2016. The new screenshots are taken from a different machine. You can safely treat url WIN-U9J96QBJSAG as if it was dk-gs2016.

Part 2. Authorization server, OpenID Connect server

2 12 4,008
Istvan Hahn · Oct 5, 2016 13m read
RESTful way of data transfer

This article gives a brief introduction how a RESTful service consumer and a RESTful service provider exchange data. It is a beginner’s guide. Data is transferred from a consumer to a provider as parameters of the service. Parameters are part of a service request. The result of the service action a response is returned from a provider to a consumer. Both the service request and response are standard HTTP messages. Since HTTP is a flexible standard regarding to the message contents, RESTful services also enjoy the versatility of data transfer methods.

0 0 3,834
Bill McCormick · Feb 19, 2016 4m read
Why Atelier? And what about Studio?

I have been meaning to make a post about this topic for a few weeks and the other day an issue came in through the WRC about it so it seems this is a conversation we should be having. I want to begin by taking a few moments to explain "Why Atelier" then we can talk about what this means in the general sense for Studio and Atelier and Caché developers. We have wrestled with what to do with Studio for years. When I moved to Product Management in 2008 this was already a "thing". At the time we could not reach a consensus. Some felt Studio was fine as is.

0 2 3,424

The %Net.SSH.Session class lets you connect to servers using SSH. It's most commonly used with SFTP, especially in the FTP inbound and outbound adaptors.

In this article, I'm going to give a quick example of how to connect to an SSH server using the class, describe your options for authenticating, and how to debug when things go wrong.

Here's an example of making the connection:

0 3 3,155

This article will provide tips and tricks on customizing Ensemble business hosts with configurable settings.

Ensemble production Settings are configurable values that control the behavior of a production and its hosts.

The documentation for adding and removing Settings and specifying categories and controls for Settings is provided at the link:

2 6 2,997
Tani Frankel · Feb 17, 2016 3m read
Listing files in folder


How do I get a list of files residing in a certain folder/directory, according to some wildcard/filter.

For example all '*.txt' files in 'C:\Temp'.



You can use the %Library.File's FileSet class query.

Here's some sample code using it (also attached):


0 2 2,927

Configuring an Ensemble production can be a challenging task involving a thorough understanding of the system and production functionality and a detailed understanding towards each configuration item. After successfully configured an Ensemble production, you might need to set up an identical production on the mirror environment, or deploy the production on a development system to a live system, or send a copy for diagnostic/debug purposes. Other times you might have spent some time designing a BPL/DTL and some other productions can use the same logic.

0 0 2,921
Istvan Hahn · Oct 12, 2016 12m read

Beginner’s guide to RESTful Application Program Interface (API) design and documentation. Through the example you will learn some common pattern for RESTful API.

Before you read

You need to know

0 0 2,632

Two fairly common requests we receive from HL7 customers are (1) how to remove all trailing delimiters for fields and segments in HL7 messages and (2) how to "find and replace" for an entire HL7 message (as opposed to one segment/field at a time).  The code sample below shows a custom function that solves for item 1 and by extension item 2 above.  In other words the same approach can be used for finding/replacing any sequence of chars in an entire HL7 message, with some tweaks to the custom function.

0 6 2,496

Created by Daniel Kutac, Sales Engineer, InterSystems


Part 3. Appendix

InterSystems IRIS OAUTH classes explained

In the previous part of our series we have learned about configuring InterSystems IRIS to act as an OAUTH client as well as authorization and authentication server (by means of OpenID Connect). In this final part of our series we are going to describe classes implementing InterSystems IRIS OAuth 2.0 framework. We will also discuss use cases for selected methods of API classes.

The API classes implementing OAuth 2.0 can be separated into three different groups according to their purpose. All classes are implemented in %SYS namespace. Some of them are public (via % package), some not and should not be called by developers directly.

2 0 2,344
Michael Breen · Nov 9, 2016 5m read
How the Ensemble Scheduler Works

The Ensemble Scheduler is used for automatically turning on and off business hosts at certain dates and times.   You could use it if, for example, you wanted to only run a business host from 9am to 5pm every day.    Conversely, if you want do to trigger an event to occurr at a specific time, for example, a job running at 1am to batch up and send off all the previous day's transactions in one file, we recommend other methods such as the Task Manager.

3 3 2,229
Istvan Hahn · Sep 30, 2016 8m read
Consuming RESTful Web Services

The article is a step by step guide for beginners to learn how to build a RESTful web service consumer (or client) in Ensemble. The provider can be any RESTful service, but the example is based on the service we made during the previous sessions.

0 0 2,211
Istvan Hahn · Sep 23, 2016 6m read
Creating a RESTful Service using Ensemble

This is a detailed guide to develop RESTful services using InterSystems Ensemble. The goal of this guide is to make you understanding the basic concept and building blocks of a RESTful service. The service is going to provide a very basic functionality (a “Hello world!”).

You will learn how to create required components as Ensemble classes, configure the run-time as an Ensemble Production and create a service configuration as a web application.

0 1 2,031
Istvan Hahn · Sep 21, 2016 7m read
REST in Pieces

A beginners guide to develop Ensemble RESTful web services.


Before you start reading this short introduction please go through the on-line documentation of Ensemble with special attention to chapter “Creating REST services and clients with Ensemble”.

The approach in the documentation is undisputable the fastest and easiest way to create RESTful services. As a beginner I went through the documentation and I had several questions. This short article is listing those questions plus my humble answers.

0 6 1,982

GraphQL is a standard for declaring data structures and methods of data access that serves as a middleware layer between the client and the server. If you’ve never heard about GraphQL, here is a couple of useful online resources: here, here and here.

In this article, I will tell you how you can use GraphQL in your projects based on InterSystems technologies.

10 24 1,831

EnsLib.HL7.Message.cls provides many API methods for manipulating an HL7 message.  RemoveSegmentAt(), for example, can be used to remove a segment by path or index, but only one segment at a time.   There may be times that you'll need to remove all segments within a group or even many groups of segments from the HL7 message.  Surely you can iterate through each segment in each group and remove them one by one, but there's a much easier way. 


With just one command, like below, you can remove all OBX segments in an ORU_R01 message (msg):

0 1 1,628

DTL Transformations and GetValueAt/SetValueAt calls on HL7 messages will truncate any fields longer than 32K.  To avoid this, the methods GetFieldStreamRaw and StoreFieldStreamRaw must be used when dealing with fields that might be larger than 32K.  OBX:5 is a frequent example.  These methods have some subtleties and must be used carefully.

This can't be done by simply dragging from left to right in a DTL.  It must be done with a code action.  Also, the StoreFieldStreamRaw call must be the last edit made to the segment because the segment becomes immutable after that.

3 6 1,596
John Murray · Apr 24, 2017 1m read
Diagnosing the cause of <PROTECT> errors

If your application is raising <PROTECT> errors and you're finding it hard to work out why, here's a way to get additional information.

First, if auditing is not already enabled, turn it on:

Then use "Configure System Events" (highlighted above) and locate the event named %System/%Security/Protect. In the screenshot below I used the Filter field to do this (type "protect" - highlighted below - and press TAB):

0 1 1,473
Istvan Hahn · May 16, 2016 11m read
Accelerate Ensemble

Introducing non-persistent messages. eXpert-to-eXpert


InterSystems Ensemble as a tool does a lot for the Developer. One of the nice features is the Message trace utility. It shows a message flow diagram. The diagram shows the progress of the message processing real time. You can get many-many useful information from the production. In any case, someone needs to find a bug in a production implementation, without the Message trace utility it could turn into a real nightmare. 

On the other hand, keeping message “traceability” is not for free. A heavy loaded production can very quickly run out of resources just because of the house keeping functions of Ensemble. House keeping functions such as maintaining message header, log entries, message queue generates a significant load on the Caché database used by Ensemble.

This article is about to show how to force Ensemble work more for the everyday life, instead of being prepared for “any-time-debugging”.

This is an eXpert-to-eXpert article. Therefore, I assume the deep understanding of Ensemble.

1 1 1,455