Ensemble HL7 Version 2 Development Guide - InterSystems ...

Ensemble HL7 Version 2 

Development Guide 

Version 2008.1.1 

17 June 2008 

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Ensemble HL7 Version 2 Development Guide 

Ensemble Version 2008.1.1 17 June 2008 

Copyright © 2008 InterSystems Corporation 

All rights reserved. 

This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from 

the following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at 

www.w3c.org. The primary document development tools were special-purpose XML-processing applications built 

by InterSystems using Caché and Java. 

and 

Caché WEBLINK, Distributed Cache Protocol, M/SQL, N/NET, and M/PACT are registered trademarks of InterSystems 

Corporation. 

and 

InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of 

InterSystems Corporation. 

All other brand or product names used herein are trademarks or registered trademarks of their respective companies 

or organizations. 

This document contains trade secret and confidential information which is the property of InterSystems Corporation, 

One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation 

and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other 

purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or 

translated into any human or computer language, in any form, by any means, in whole or in part, without the express 

prior written consent of InterSystems Corporation. 

The copying, use and disposition of this document and the software programs described herein is prohibited except 

to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering 

such programs and related documentation. InterSystems Corporation makes no representations and warranties 

concerning such software programs other than those set forth in such standard software license agreement(s). In 

addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of 

such software programs is limited in the manner set forth in such standard software license agreement(s). 

THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY 

INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER 

SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE 

LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE 

UPON REQUEST. 

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the 

right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices 

described in this document. 

For Support questions about any InterSystems products, contact: 

InterSystems Worldwide Customer Support 

Tel: +1 617 621-0700 

Fax: +1 617 374-9391 

Email: support@InterSystems.com

Table of Contents 

About This Book ................................................................................................................................ 1 

1 Design Model for a Routing Production ....................................................................................... 3 

1.1 Fundamentals ......................................................................................................................... 3 

1.2 Configuration Items ............................................................................................................... 3 

1.3 Application Specification ....................................................................................................... 6 

1.4 Production Spreadsheet .......................................................................................................... 6 

1.5 Interface Design ..................................................................................................................... 8 

1.6 Naming Conventions ............................................................................................................ 11 

1.6.1 Business Services ....................................................................................................... 12 

1.6.2 Routing Processes ...................................................................................................... 13 

1.6.3 Routing Rule Sets for HL7 ........................................................................................ 14 

1.6.4 Business Operations ................................................................................................... 14 

1.6.5 Data Transformations ................................................................................................. 15 

1.6.6 Custom Schema Categories ....................................................................................... 16 

1.7 Production Diagram ............................................................................................................. 16 

1.8 Production Settings .............................................................................................................. 17 

2 Elements of a Routing Production .............................................................................................. 19 

2.1 Namespaces .......................................................................................................................... 21 

2.2 Building the Production ....................................................................................................... 22 

2.3 HL7 Business Services ........................................................................................................ 23 

2.3.1 Creating an HL7 Business Service ............................................................................ 23 

2.3.2 Configuring an HL7 Business Service ...................................................................... 25 

2.3.3 Integrating an HL7 Business Service ......................................................................... 31 

2.4 HL7 Custom Schema Categories ......................................................................................... 31 

2.5 HL7 Routing Processes ........................................................................................................ 34 

2.5.1 Creating an HL7 Routing Process ............................................................................. 34 

2.5.2 Configuring an HL7 Routing Process ........................................................................ 35 

2.5.3 Integrating an HL7 Routing Process .......................................................................... 37 

2.6 HL7 Sequence Manager ....................................................................................................... 38 

2.6.1 Creating an HL7 Sequence Manager ......................................................................... 38 

2.6.2 Configuring an HL7 Sequence Manager ................................................................... 39 

2.6.3 Integrating an HL7 Sequence Manager ..................................................................... 44 

2.7 Routing Rule Sets for HL7 .................................................................................................. 44 

2.8 DTL Data Transformations for HL7 .................................................................................... 53 

2.8.1 Utility Functions ........................................................................................................ 57 

2.8.2 Utility Class Methods ................................................................................................ 58 


iii

2.9 HL7 Business Operations .................................................................................................... 58 

2.9.1 Creating an HL7 Business Operation ........................................................................ 58 

2.9.2 Configuring an HL7 Business Operation .................................................................. 60 

2.9.3 Integrating an HL7 Business Operation ..................................................................... 65 

2.10 Pager and Email Alerts ....................................................................................................... 65 

2.11 HL7 Search Tables ............................................................................................................. 66 

3 Settings for a Routing Production .............................................................................................. 75 

3.1 HL7 Message Validation and Bad Messages ....................................................................... 75 

3.1.1 The d Validation Flag ................................................................................................. 76 

3.1.2 The m Validation Flag ................................................................................................ 76 

3.1.3 The z Validation Flag ................................................................................................. 77 

3.1.4 Bad Message Handlers ............................................................................................... 78 

3.1.5 Overriding the Validation Sequence .......................................................................... 78 

3.2 HL7 Acknowledgement (ACK) Mode ................................................................................. 79 

3.2.1 The AckMode Setting ................................................................................................ 81 

3.2.2 The UseAckCommitCodes Setting ............................................................................ 81 

3.2.3 The IgnoreInboundAck Setting ................................................................................. 82 

3.2.4 The AckTargetConfigNames Setting ......................................................................... 82 

3.2.5 The GetReply Setting ................................................................................................. 82 

3.2.6 The ReplyCodeActions Setting ................................................................................. 82 

3.2.7 The AddNackERR Setting ......................................................................................... 84 

3.3 HL7 Dual Acknowledgement Sequences ............................................................................. 84 

3.3.1 Dual ACK Sequence for Incoming Messages ............................................................ 84 

3.3.2 Dual ACK Sequence for Outgoing Messages ............................................................ 85 

3.3.3 Configuring a Dual ACK Sequence ........................................................................... 87 

3.4 HL7 Message Framing Types .............................................................................................. 88 

3.5 HL7 Batch Messages ........................................................................................................... 90 

3.6 HL7 Business Service Classes ............................................................................................. 95 

3.7 HL7 Business Operation Classes ......................................................................................... 97 

4 Syntax for a Routing Production ................................................................................................ 99 

4.1 HL7 Message Class .............................................................................................................. 99 

4.1.1 The DocType Property ............................................................................................. 100 

4.1.2 The TypeCategory Property ..................................................................................... 101 

4.1.3 The BuildMapStatus Property ................................................................................. 101 

4.1.4 The Name Property .................................................................................................. 102 

4.1.5 The RawContent Property ........................................................................................ 102 

4.1.6 The GetValueAt Method .......................................................................................... 102 

4.1.7 The SetValueAt Method ........................................................................................... 103 

4.2 Virtual Property Syntax ...................................................................................................... 103 

4.2.1 Curly Bracket {} Syntax .......................................................................................... 104 

iv 

Ensemble HL7 Version 2 Development Guide

4.2.2 Square Bracket [] Syntax ......................................................................................... 107 

4.2.3 Parenthesis () Syntax in Business Rules .................................................................. 107 

4.2.4 Angle Bracket Syntax in Business Rules ........................................................... 108 

4.3 Literal String Syntax .......................................................................................................... 108 

4.3.1 HL7 Separator Characters ........................................................................................ 110 

4.3.2 HL7 Escape Sequences ............................................................................................ 111 

4.3.3 XML Entities ........................................................................................................... 113 

4.3.4 Numeric Character Codes ........................................................................................ 114 

4.3.5 Null Mapping Codes ................................................................................................ 114 

4.4 Schema Category Syntax ................................................................................................... 115 

4.4.1 .............................................................................................................. 118 

4.4.2 ................................................................................................ 119 

4.4.3 .......................................................................................... 120 

4.4.4 ................................................................................................ 121 

4.4.5 ....................................................................................................... 123 

5 Viewing and Transforming Messages ....................................................................................... 125 

5.1 Starting the Ensemble Management Portal ........................................................................ 126 

5.2 The Schema Structures Page .............................................................................................. 127 

5.2.1 Viewing a List of Document Types .......................................................................... 128 

5.2.2 Viewing a Message Structure ................................................................................... 128 

5.2.3 Viewing a Segment Structure ................................................................................... 130 

5.2.4 Viewing a Data Structure ......................................................................................... 132 

5.2.5 Viewing a Code Table .............................................................................................. 133 

5.2.6 Choosing a Different Category ................................................................................ 133 

5.3 The Document Viewer Page ............................................................................................... 134 

5.3.1 Viewing a Message .................................................................................................. 136 

5.3.2 Parsing the Message ................................................................................................. 138 

5.3.3 Displaying the Segment Address ............................................................................. 139 

5.3.4 Displaying the Field Address ................................................................................... 140 

5.3.5 Viewing Batch Messages ......................................................................................... 141 

5.3.6 Saving the Output to a File ...................................................................................... 143 

5.4 Filtering HL7 Messages ..................................................................................................... 144 

5.5 Comparing HL7 Messages ................................................................................................. 144 

6 Converting Interfaces to Ensemble ........................................................................................... 145 

6.1 Backing Up the Production ................................................................................................ 148 

6.1.1 Backup from Studio ................................................................................................. 148 

6.1.2 Backup from ObjectScript ....................................................................................... 149 

6.2 Describing the Interface ..................................................................................................... 150 

6.2.1 The Inbound Interface .............................................................................................. 151 

6.2.2 The Outbound Interface ........................................................................................... 151 


v

6.3 Choosing Schema Categories ............................................................................................. 152 

6.3.1 Choosing an Incoming Schema Category ................................................................ 152 

6.3.2 Choosing an Outgoing Schema Category ................................................................ 153 

6.4 Creating Data Transformations .......................................................................................... 153 

6.5 Defining Routing Rule Sets ............................................................................................... 153 

6.6 Adding Business Operations .............................................................................................. 154 

6.7 Creating or Editing a Routing Process ............................................................................... 154 

6.8 Adding Business Services .................................................................................................. 155 

6.9 Testing the Interface ........................................................................................................... 155 

6.10 Deploying the Interface .................................................................................................... 156 

vi 


List of Figures 

HL7 Interface in Ensemble Terms ....................................................................................................... 4 

Routing Rules and Data Transformations ........................................................................................... 5 

Sample Production Spreadsheet .......................................................................................................... 7 

Sample Routing Production with Multiple Interfaces ....................................................................... 10 

Sample HL7 Routing Production ...................................................................................................... 17 

HL7 Routing Engine in Ensemble Terms ......................................................................................... 20 

Ensemble DTL Visual Editor ............................................................................................................ 54 

HL7 Message Acknowledgement (ACK) Types ............................................................................... 80 

Paired Business Service and Business Operation for Incoming Dual ACK ...................................... 85 

Paired Business Service and Business Operation for Outgoing Dual ACK ...................................... 87 

Parent and Child Documents in HL7 Batch Messages ..................................................................... 92 

HL7 Business Service Class Hierarchy, Showing Inheritance of Settings ........................................ 96 

HL7 Business Operation Class Hierarchy, Showing Inheritance of Settings .................................... 98 

HL7 Message Class Overview Showing Inheritance ...................................................................... 100 

Ensemble Studio View of a Built-in HL7 Category Definition ...................................................... 116 

Ensemble Studio View of a Custom HL7 Category Definition ...................................................... 118 

Ensemble HL7 Message Structure Page, DocType 2.3.1:ORM_O01 ............................................. 128 

Ensemble HL7 Message Structure Page, DocType 2.3:ADT_A01 ................................................. 130 

Ensemble HL7 Segment Structure Page ......................................................................................... 130 

Ensemble HL7 Data Structure Page ................................................................................................ 132 

Ensemble HL7 Code Table Page ..................................................................................................... 133 

Ensemble HL7 Message Structure Page, DocType 2.4:ORD_O04 ................................................ 134 

Ensemble HL7 Message Structure Page, DocType 2.5:ORD_O04 ................................................ 134 

Document Viewer Page ................................................................................................................... 136 

Source for Message Data ................................................................................................................ 137 

DocType or Schema for Message Data ........................................................................................... 137 

Applying a Data Transformation ..................................................................................................... 138 

Document Viewer Parsing Summary .............................................................................................. 139 

Document Viewer Showing Hover-Text Help for Segment Address .............................................. 139 

Document Viewer Showing Hover-Text Help for Field Address .................................................... 141 

HL7 Batch Message with FHS and BHS, Top-Level Parent Document ......................................... 141 

HL7 Batch Message with FHS and BHS, Mid-Level Parent Document ........................................ 142 

HL7 Batch Message with FHS and BHS, Child Document ............................................................ 143 

Hospital IT Configuration Featuring an Interface Engine .............................................................. 146 


vii

List of Tables 

Built-in Search Table Entries for HL7 .............................................................................................. 67 

Attributes for the Element in Search Tables ......................................................................... 71 

Values for the Validation Setting ....................................................................................................... 76 

Acknowledgement (ACK) Modes for HL7 Business Services ......................................................... 81 

Enhanced-Mode ACK Commit Codes for HL7 2.3 and Higher ....................................................... 82 

Code Values for Reply Code Actions ................................................................................................ 83 

Action Values for Reply Code Actions .............................................................................................. 83 

Framing Types for HL7 Business Operations and Business Services ............................................... 89 

HL7 Batch Message Handling Options ............................................................................................. 94 

HL7 Escape Sequences Using Backslash as Escape Character ...................................................... 112 

XML Entities for Use in BPL and DTL Strings ............................................................................. 113 

Attributes for the Element in Schema Category Definitions ...................................... 118 

Attributes for the Element in Schema Category Definitions ........................ 119 

Attributes for the Element in Schema Category Definitions .................. 120 

Attributes for the Element in Schema Category Definitions ........................ 122 

Attributes for the Element in Schema Category Definitions ............................... 123 

Sample Comparison of Interface Terms: SeeBeyond and Ensemble ............................................. 151 

viii 


About This Book 

This book is one of a set that describes how to build Ensemble productions that route and transform 

documents in Electronic Data Interchange (EDI) formats. This book explains how to route HL7 Version 

2 messages from one application to another using Ensemble as the routing engine. It also contains 

fundamental information that applies to all routing productions, including those for HL7 Version 3, 

X12, and ASTM E 1394–97. 

This book contains the following sections: 

• Design Model for a Routing Production 

• Elements of a Routing Production 

• Settings for a Routing Production 

• Syntax for a Routing Production 

• Viewing and Transforming Messages 

• Converting Interfaces to Ensemble 

The following books provide related information: 

• Ensemble Virtual Documents explains how the concept of virtual documents allows Ensemble to 

provide efficient support for EDI document exchange. 

• Ensemble HL7 Version 3 Development Guide explains how to add HL7 Version 3 interfaces to a 

routing production. 

• Ensemble X12 Development Guide explains how to add X12 interfaces to a routing production. 

• Ensemble ASTM Development Guide explains how to add ASTM E 1394–97 interfaces to a routing 

production. 

Ensemble HL7 Version 2 Development Guide 1

1 

Design Model for a Routing 

Production 

This chapter describes a design model that Ensemble customers have used successfully to build interface 

routing solutions. As such, it can be thought of as a collection of best practices for developing an 

Ensemble routing production. 

This chapter describes only one approach. Other implementation strategies can be successful as well. 

Each organization has its own standards for writing code and conducting programming projects. This 

chapter simply describes those aspects of a routing production that are unique to Ensemble and that 

benefit from a carefully structured approach. 

In general, the key to a good design is clarity and simplicity. Simplicity does not mean a small number 

of parts. Simplicity means that each part within the model has a clear function and is intuitively easy 

to find. 

1.1 Fundamentals 

Each member of the project must read the “Ensemble Productions” chapter in Developing Ensemble 

Productions. 

1.2 Configuration Items 

An Ensemble production consists of configuration items. There are three types of configuration item: 


Design Model for a Routing Production 

• Business services accept incoming messages. 

• Business operations send outgoing messages. 

• Business processes direct all the work in between. There are some specialized types of business 

process: 

A routing process routes and transforms messages by invoking these key components of a routing 

production: 

- Routing rules direct messages to their destinations based on message contents. 

- Schema categories provide a means to validate and access message contents. 

- Data transformations apply changes to prepare messages for their destinations. 

A sequence manager ensures that related messages arrive at their targets with the proper sequence 

and timing 

HL7 Interface in Ensemble Terms 

The following figure expands the diagram of a routing process to show how it uses routing rules to 

direct the flow of information through the interface. The following figure includes details about the 

routing rules and data transformations that are only implied by the dotted circle in the diagram above. 

A routing process has a routing rule set associated with it. Depending on how the rule set is defined, 

and depending on the type of message that arrives from the source application, the rule set identifies 

which of its rules should execute. More than one rule can execute, in sequence, but for simplicity the 

following figure shows the case where the rule set chooses only one rule. From this point, as shown, 

a rule can either delete the message or it can send the message to a destination within Ensemble. If 

4 Ensemble HL7 Version 2 Development Guide

this destination is a business operation, the message then leaves Ensemble on its way to the target 

application. 

Routing Rules and Data Transformations 

Configuration Items 



1.3 Application Specification 

Ideally, a clinical application provides an HL7 application specification document, or implementation 

guide, that explains which types of HL7 event the application can send (or receive), and which message 

segments and pieces of each segment the application sends (or expects) for these events. 

A formal document of this kind is extremely detailed, and extremely useful. If a specification document 

is available, the administrator for the clinical application can show it to you, and can explain to you 

which of the many possible events are actually in use in the enterprise. This is usually a small subset 

of the full list of events. 

Even if there is no application specification document, there is usually some informal documentation. 

Ask the application administrator to see any notes that are available. 

As an alternative to documentation, or to validate that the existing documentation is correct, you can 

examine the messages themselves to determine which types of HL7 event the application sends or 

expects to receive. Ask the application administrator to provide you with a sampling of the message 

data, saved in files. 

Once you have the HL7 message files, you can use the Document Viewer to view and parse them 

using various schema definitions. In this way you can quickly determine whether or not the application 

is using a standard HL7 schema. If not, you can use the Message Viewer to refine and test a custom 

HL7 schema for the application. 

Background information that supports these tasks can be found in subsequent chapters of this book: 

• “HL7 Message Schema Categories” in the chapter “Elements of a Routing Production” 

• “Message Validation and Bad Messages” in the chapter “Settings for a Routing Production” 

• “Schema Category Syntax” in the chapter “Syntax for a Routing Production” 

• “The Document Viewer Page” in the chapter “Viewing and Transforming Messages” 

• “Choosing Schema Categories” in the chapter “Converting Interfaces to Ensemble” 

1.4 Production Spreadsheet 

It is helpful to maintain a spreadsheet that organizes your information system, application by application. 

You can create the spreadsheet on paper, or using any software tool that you prefer. 


Production Spreadsheet 

Sample Production Spreadsheet 

As a general guideline, you should provide a row for each application that provides an incoming or 

outgoing data feed. In each row, the following columns are useful: 

• Feed — An interface engine or server often feeds messages from several applications into the 

routing production. When this is the case, note the engine or server name here. 

• Application — Briefly identify a specific application, its role in your system, and the person to 

contact about any issues or problems with this application. Ideally, this description makes sense 

to members of your organization who do not use Ensemble, but who are generally familiar with 

how the system works. 

• Name — A unique 3– to 6–character name for this application. 

• Type — The protocol that the application uses for external communications. 

• Connection — Connection details, such as an IP address and port number. 

• Sends — The HL7 Version 2 message structures that this application contributes to the information 

system. 

Consider the incoming message structure after it enters the information system. Does it need to 

be routed or transformed differently depending on the destination system or other factors If so, 

list it multiple times, with a note regarding the differences. This way, your spreadsheet can serve 

as a checklist while you create the necessary routing rules, data transformations, and custom 

schemas for each case. 



• Receives — The HL7 Version 2 message structures that this application consumes from the 

information system. 

• ACKs — Acknowledgement details. Are ACK and NACK messages expected Is there a separate 

interface for sending and receiving them Should Ensemble generate the ACKs and NACKs, or 

will the receiving application do so 

When you begin the project, your initial spreadsheet does not need to describe every application in 

the information system. You can add to the spreadsheet as you deploy each new interface. 

1.5 Interface Design 

This topic outlines an effective way to keep interface designs modular so that your Ensemble production 

remains easy to understand, scale, and maintain at each stage of its development: 

• Provide one business service for each application that sends HL7 messages into Ensemble. This 

is an application that has at least one entry in the Sends column of the production spreadsheet. 

One business service can receive all of the message structures for the same application. This is 

usually the appropriate design. When you set up a business service for this purpose you generally 

intend for it to stay connected to its application system all the time. 

There might be aspects of the configuration that require you to provide additional business services 

connected to the same application. For example, if the source application is already configured 

to send messages to two different TCP/IP ports, you could set up one business service to receive 

all the messages from one port, and another business service for the other port. This is generally 

consistent with the model of one business service per application, since there is one business service 

per communication source. 

Alternatively, when hundreds of users of the same clinical application are sending data into the 

enterprise, it can be useful to route all of these messages into Ensemble via one business service 

that may or may not stay permanently connected to any single instance of the application. 

• Provide one routing process for each business service. The routing process can route messages 

based on the contents of the message itself, or information stored in Ensemble. If the routing 

depends on the contents of other messages, or requires invocation of external applications to 

determine the routing, the routing process should be a BPL business process that calls out to other 

classes. However, in most cases a routing process based on the built-in routing rule engine is 

sufficient. 

Consider using a sequence manager when it is vital that related messages arrive at their targets in 

the proper sequence. 


Interface Design 

• Provide one business operation for each application that receives HL7 messages from Ensemble. 

This is an application that has at least one entry in the Receives column of the production 

spreadsheet. 

One business operation can send all the different message structures for the same application. 

This is usually the appropriate design. When you set up a business service for this purpose you 

generally intend for it to stay connected to its application system all the time. However, as for 

business services, there might be variations on this model. 

The guiding principle is to keep your design modular. That is, develop one interface at a time and use 

one routing process for each interface. This contrasts with a model in which a single large routing 

process serves as the routing engine for all interfaces. There are a number of reasons why many routing 

processes are better than one: 

• Each routing rule set is simpler and easier to maintain because it only covers the cases required 

by one interface. It is easier to share and reuse work that is self-contained and solves a simple set 

of problems. 

• Interfaces become easy to develop, replace, and maintain individually. If the enterprise must 

remove or upgrade a particular application, only those routing processes that deal with that 

application need to be touched. If an interface goes down, only that interface needs to be disabled, 

diagnosed, repaired, and retested before you can bring it back up. 

This is much cleaner than requiring you to retest and validate all of the rules in one large routing 

process every time you need to add, remove, or repair one interface. These considerations become 

especially important as some of your interfaces go live, while others are still in development. Each 

addition to a routing process that is already in production might require you to retest and validate 

hundreds of existing rules. 



Sample Routing Production with Multiple Interfaces 

Each configuration item in the production has a specific role to play. Keep each item to its role: 

• Keep business services and business operations simple. In general, it is not necessary to write 

your own code for business services or business operations. Choose the built-in classes that 

Ensemble provides. This choice gives you the correct adapters automatically. Configure these 

classes using Ensemble Management Portal settings. 

• Place all complex activities under control of a routing process. If an interface is simple, its routing 

processes need not be complex, but if complexity exists, it belongs in a routing process, not in a 

business service or business operation. To accomplish tasks, a routing process can chain to other 

routing processes, or it can invoke business rules, routing rules, data transformations, business 

processes, or custom code. For details, see the chapter “Elements of a Routing Production. ” 


Naming Conventions 

1.6 Naming Conventions 

This topic explains the importance of naming conventions and provides examples. 

Typically you will develop your Ensemble production incrementally, one interface at a time. There is 

a temptation to name items “as you go,” and to allow naming conventions to grow incrementally along 

with the project. InterSystems recommends you do not take this incremental approach to naming 

conventions. 

Remember that a full HIS system can involve hundreds of interfaces. Anticipate the task of managing 

the routing production once all of these interfaces are included. The name of each component should 

clearly identify its purpose. This way, developers and system administrators can easily predict a 

component’s name based on its function. 

InterSystems recommends that you establish a full set of naming conventions at the start of the project, 

then stick with them. This alleviates the need to backtrack into your production configuration just to 

correct names. 

Any convention that clearly identifies components by function is fine. The following is a full set of 

naming conventions that several Ensemble customers have used successfully: 

• List the individual segments that you will assemble to create names. These might include: 

- Keywords: 

• From for incoming 

• To for outgoing 

• Router for routing 

• Rules for rule sets 

• A base schema category number — 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5 — for schemas 

- A short name for each application 

- Keywords that identify a general class of message structures (ADT, ORM, etc) 

- Full message structure names (ADT_A01, ADT_A04, ORM_O01, etc) 

• Keep each segment of the name brief (3–6 characters) 

• Remember that names are case-sensitive 

• Use only alphanumeric characters 

• Do not use the characters ;:|, 



• Do not use underscore characters (_) in data transformation names, because for data transformations 

the configuration name must be the same as the class name, and class names cannot use underscores. 

You may use underscores in the names of configuration items that are business hosts, because in 

that case the configuration name can be different from the class name. 

For each element of the production, assemble a name from the segments that you have defined: 

• Business services: FromSourceAppName 

• Business operations: ToTargetAppName 

• Routing processes: SourceAppNameRouter 

• Routing rule sets: SourceAppNameRules 

• Data transformations: 

SourceAppNameSourceMessageTypeToTargetAppNameTargetMessageType 

• Custom schema categories: SourceAppNameBaseSchemaNumber 

For more complex designs: 

• Business services: FromSourceAppNameMessageTypes 

• Business operations: ToTargetAppNameMessageTypes 

• Routing processes: SourceAppNameMessageTypesRouter 

• Routing rule sets: SourceAppNameMessageTypesRules 

The following topics provide explanations and examples for these naming conventions. 

1.6.1 Business Services 

Convention 

Examples 

FromERChart, FromFineOR, FromDeskAdm 



Variation 

If you have decided to organize an interface so that one application sends messages into Ensemble via 

more than one business service, also include a keyword that classifies the MessageTypes that pass 

through each business service. A typical MessageTypes keyword uses the first three letters of the HL7 

Version 2 message structure, such as ADT, ORM, or ORU. In this case the convention for the business 

service name is FromSourceAppNameMessageTypes. 

Examples 

FromERChartADT, FromERChartORM, FromERChartOther 

1.6.2 Routing Processes 

Convention 

Examples 

ERChartRouter, FineORRouter, DeskAdmRouter 

If you have decided to organize an interface so that one application sends messages into Ensemble via 

more than one business service, also include a keyword that classifies the MessageTypes that pass 

through each business service to its routing process. In this case the format for the routing process 

name is as follows: 



Variation 

Examples 

ERChartADTRouter, ERChartORMRouter, ERChartOtherRouter 

1.6.3 Routing Rule Sets for HL7 

Convention 

Each routing process has an associated rule set whose rules determine message destinations. The rules 

direct the messages to data transformations or business operations based on message type, message 

contents, time of day, or other factors. Name each rule set to match its routing process. That is, for 

each SourceAppNameRouter, call the rule set SourceAppNameRules. For each 

SourceAppNameMessageTypesRouter, call the rule set SourceAppNameMessageTypesRules. 

Examples 

DeskAdmRules 

DeskAdmORMRules 

1.6.4 Business Operations 

Convention 

Examples 

ToImagit, ToFineOR, ToPindex 



Variation 

If you have decided to organize an interface so that one application receives messages from Ensemble 

via more than one business operation, also include a keyword that classifies the MessageTypes that 

passes through each business operation. A typical MessageTypes keyword uses the first three letters 

of the HL7 Version 2 message structure, such as ADT, ORM, or ORU. In this case the convention for 

the business operation name is as follows: 

Examples 

ToMainLabADT, ToMainLabORM, ToMainLabOther 

1.6.5 Data Transformations 

Convention 

Remember that the SourceMessageType and TargetMessageType may have the same name, but represent 

the same message structure in different schema categories. 

Examples 

ERChartADTA03ToMainLabADTA03, ERChartADTA02ToMainLabADTA01 



1.6.6 Custom Schema Categories 

Convention 

The ApplicationName can represent a sending application or a receiving application. 

Examples 

ERChart2.2, Imagit2.3.1, OurFavorite2.5 

1.7 Production Diagram 

The following production diagram illustrates some of the best practices described in this chapter. This 

is the type of diagram that you can build and view from the Ensemble Management Portal [Ensemble] 

> [Productions] page, as described in the next chapter, “Elements of a Routing Production.” Keep in 

mind that only true configuration items are shown: business services, business processes, and business 

operations. Supporting the business processes are the other production components, including business 

rules, data transformations, and custom schema definitions. 


Production Settings 

Sample HL7 Routing Production 

1.8 Production Settings 

When you are viewing a configuration diagram on the [Ensemble] > [Productions] page, you can click 

on one of the production items in the diagram. Its full range of settings display in a panel below the 

diagram. For details about these settings, see “The Configuration Page” chapter in Managing 

Ensemble Productions. 

In an Ensemble production, Pool Size controls how many system jobs a configuration item can consume 

at the same time. Many jobs can be running at once, but a Pool Size of 1 ensures that each configuration 

item gets only one of these jobs at a time. A Pool Size of 1 prevents the possibility that a message from 

a particular source could “skip over” other messages from the same source by using a faster, parallel 

job to arrive at its destination sooner. This ensures first-in, first-out (FIFO) processing so that each 

message from a given source arrives at its configured destination in the same order in which it was 

sent. 

Proper message sequence is essential for many HL7 applications. Suppose a patient enters a hospital 

and requires care. System A sends out an admit event, followed by a treatment order, but System B 

receives the order first. System B cannot process the order without an admit, so upon receiving the 

order, it produces an error. This may delay patient care or require the information system to execute 

complex logic to associate admit with the order after the admit finally arrives at System B. For this 

reason, it is generally the case that every configuration item in an HL7 routing production should have 

its Pool Size setting configured to 1. 


2 

Elements of a Routing Production 

This chapter explains how to build each element of an HL7 message routing production based on the 

starter production that you can create from the Ensemble Management Portal [Ensemble] > [Productions] 

page. Topics include: 

• Namespaces 

• Building the Production 

• HL7 Business Services 

• HL7 Message Schema Categories 

• HL7 Routing Processes 

• HL7 Sequence Manager 

• Routing Rule Sets for HL7 

• DTL Data Transformations for HL7 

• HL7 Business Operations 

• Pager and Email Alerts 

• HL7 Search Tables 

Note: 

If you are replacing an existing interface engine (such as eGate) with Ensemble, also see the 

chapter “Converting Interfaces to Ensemble.” 

The following figure illustrates the flow of an HL7 Version 2 message through an Ensemble production. 

This figure expands the simple view of a single interface shown in the “Configuration Items” section 

of the previous chapter, by adding elements that are referenced by configuration items, but that are 

not themselves configuration items. These include routing rule sets, data transformations, virtual doc- 



uments, and schema definitions. You will create these items when you follow the instructions in this 

chapter. 

HL7 Routing Engine in Ensemble Terms 

An HL7 Version 2 message flows through the elements of an Ensemble HL7 routing production as 

follows: 

1. An HL7 business service receives an incoming message from the specific source application 

whose messages it is configured to accept. 


Namespaces 

2. The business service passes the message to a specific HL7 routing process. This is an Ensemble 

business process that prepares incoming messages from a HL7 business service for delivery outside 

Ensemble via a specific HL7 business operation. 

3. The routing process may validate the message against an expected HL7 schema definition. This 

may be a standard HL7 schema or a custom schema. 

(Not shown) If validation fails, the HL7 routing process passes the message to its configured bad 

message handler. This is an HL7 business operation that disposes of any incoming HL7 messages 

that fail validation, usually by saving the messages to a file. It may also enter an error in the Even 

Log or alert an operator. 

4. The HL7 routing process applies a routing rule set to the message. The routing rule set chooses 

one or more target business operations and applies any data transformations that may be needed 

to prepare the message for the target application. 

5. In the typical case, some data transformation is required to prepare the message for the target. 

The routing rule set may invoke transformations that are custom coded, but commonly transformations 

are constructed using the Ensemble Data Transformation Language (DTL). DTL can call 

out to utility functions or utility class methods for more complex calculations. 

6. When the outgoing message is ready, the routing process passes it to an HL7 business operation. 

The business operation provides the address and framing information required to send HL7 messages 

to the target application. 

(Not shown) By default, all HL7 messages that pass through the production are retained in the 

Ensemble message warehouse for as long as wanted. While in the message warehouse, the contents 

of HL7 messages are available for tracking and viewing using Ensemble Management Portal 

features such as the EDI / HL7 Manager, Message Browser, and Visual Trace, or by issuing an 

SQL query. Old messages can be purged automatically or at an administrator’s discretion, 

depending on how you configure the production. 

2.1 Namespaces 

In InterSystems products, a namespace is a collection of data and programs in a virtual work space. 

Ensemble documentation frequently refers to something called an Ensemble namespace or an 

Ensemble-enabled namespace. This is a namespace that has the Ensemble classes loaded into it. Of 

the system-provided namespaces, only the following are Ensemble-enabled: ENSLIB, ENSEMBLE, 

and ENSDEMO. Once you have successfully installed Ensemble, any new namespace that you create 

is automatically Ensemble-enabled. 



Important: 

InterSystems recommends that you always create new namespaces in which to work, 

rather than placing data or custom code in any of these system-provided namespaces 

where it could be overwritten and lost. 

You can create a new namespace by using the System Management Portal [Home] > [Configuration] > 

[Namespaces] > [New Namespace] page. 

2.2 Building the Production 

You can construct a new HL7 message routing production as follows: 

1. Start the Ensemble Management Portal. 

2. Choose your working namespace from the selection box at the top right of the [Ensemble] home 

page. 

3. From the main menu choose Productions. The [Ensemble] > [Productions] page displays. 

4. Click Create New Production. The [Ensemble] > [Productions] > [Production Wizard] page displays. 

5. Enter a Package Name, Production Name, and Description. 

6. Choose the HL7 Messaging option. 

7. Click OK. The [Ensemble] > [Productions] > [Production Model] page displays the “starter elements” 

for HL7 message routing productions. 

8. Click Configure Production. The [Ensemble] > [Productions] page displays the configuration diagram 

with the production name (Package Name.Production Name) and Description that you entered in 

previous steps. You may now begin to configure the production. 

The starter production has one interface, whose elements are: 

• HL7FileService — A disabled HL7 file service with default settings 

• MsgRouter — An HL7 routing process with an empty routing rule set 

• HL7FileOperation — A disabled HL7 file operation with default settings 

In building an HL7 routing production, you will create and configure many such interfaces. You can 

start by enabling these starter elements, copying them, renaming them, and modifying them to suit 

your needs. As you build an interface, it frequently happens that while configuring one item you must 

enter the name of another item that you have not yet created. A clear naming convention is essential 

to avoid confusion. For suggestions, see the “Naming Conventions” section in the chapter “Design 

Model for a Routing Production.” 


HL7 Business Services 

Note: 

You can only use alphanumeric characters, periods (.) and underscores (_) in configuration 

names. Do not use underscores in the names of data transformations. 

In addition to interface elements, the starter production provides several elements that do not route 

HL7 messages, but that provide supporting functionality for the production: 

• Bad Message Handler — A built-in destination for messages that fail validation. 

• Ens.Alert — A routing process with a routing rule set that you can configure to route alert messages 

to different email business operations depending on the source of the alert (that is, which element 

is in trouble) and various conditions (such as the time of day) to suit your corporate schedules and 

procedures. 

• PagerAlert and EmailAlert — Email business operations that can be configured to send a text 

message (such as an alert) to a pager or email address. 

The next several topics explain how to build a complete HL7 message routing production beginning 

from this foundation. 

2.3 HL7 Business Services 

An inbound adapter receives an incoming HL7 message from a source outside Ensemble, and relays 

it to an HL7 business service. The business service parses the message and provides all of the information 

necessary to route the message to a destination inside Ensemble. 

To build an HL7 business service for use in an HL7 message routing production, you must create it, 

configure it, and integrate it into the production. This topic explains each step. 

2.3.1 Creating an HL7 Business Service 

For your HL7 routing production to receive HL7 messages from outside Ensemble, you must add an 

HL7 business service to the production configuration. Ensemble provides built-in business services 

that accept messages from external sources over TCP, File, FTP, and HTTP connections. Generally, 

you will choose one of these built-in business services rather than write your own. 

For your convenience, in addition to the HL7 business services, two simple business services are also 

built into Ensemble: EnsLib.File.PassthroughService and EnsLib.FTP.PassthroughService. You can 

choose either of these business services if you simply need to pass a file through the HL7 routing 

production, and do not want to parse or format the file as HL7. 

Additionally, you might want your HL7 routing production to receive data from outside Ensemble 

that is not an HL7 message. This can be accomplished by creating a business service class associated 



with an inbound adapter for some specific technology, as described in Developing Ensemble Productions 

and in each of the Ensemble Adapter Guides. 

To add a business service to an HL7 routing production: 


2. Add an FTP, File, or TCP business service for HL7 as follows: 

• Start the Business Service Wizard in one of the following ways: 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Service. 

- While viewing the configuration diagram on the [Ensemble] > [Productions] page, do one 

of the following: 

• Left-click on the diagram background. A row of buttons displays below the diagram. 

Click Add Service. 

• Right-click on the diagram to reveal the context menu. Choose Add, then Business 

Service. 

• Choose HL7 Input. 

• Enter information in the following fields: 

- Choose TCP, File, or FTP to determine the host class. Each class already exists and requires 

no programming. Simply choose one. 

- Give the item a configuration Name. 

- Use the Target Name field to identify the routing process or business operation to which 

this business service will send the HL7 messages that it receives. 

• Click OK to save your changes, Cancel to ignore them. 

3. Add other types of HL7 business service as follows: 

• Start the Business Service Wizard in one of the following ways: 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Service. 




Click Add Service. 


Service. 



• Choose Other. 


- Choose the host class. Each class already exists and requires no programming. Choices 

include: 

• EnsLib.File.PassthroughService 

• EnsLib.FTP.PassthroughService 

• EnsLib.HL7.Service.HTTPService 

• EnsLib.HL7.Service.TCPService 

• EnsLib.HL7.Service.HTTPAckInService 

• EnsLib.HL7.Service.TCPAckInService 

• Any other business service class in the namespace 

- Give the item a configuration Name. For suggestions, see the “Naming Conventions” 

section in the chapter “Design Model for a Routing Production.” 


4. To add a business service of any type, by copying another business service: 

• Display the configuration diagram on the [Ensemble] > [Productions] page. 

• Select the business service in the diagram. 

• Click the Copy button. A dialog prompts you to enter a configuration name. 

• Enter a unique name and click OK. Your new business service appears in the diagram 

• When first created, the copy has the same host class and settings as the original; only the 

name is different. You must make the new copy different by configuring it. 

Note: 

The Copy button works only within the same production. You cannot copy a business 

service from one production to another. 

2.3.2 Configuring an HL7 Business Service 

You can configure an HL7 business service by clicking on it while viewing the configuration diagram 

on the [Ensemble] > [Productions] page. The following fields display below the diagram; you can edit 

these fields to configure the routing process. 



Note: 

To navigate to the configuration diagram from the [Ensemble] > [Productions] > [Production 

Model] page, where the previous topic ended, click Configure Production, then continue. 

You may configure an HL7 business service by entering values in the following fields. When you are 

done editing, click Apply to save your changes, or Cancel to ignore them. 

• General Settings — This column of settings appears at left. These are settings that configure the 

HL7 business service as a production item. The most important of these for HL7 are as follows. 

For descriptions of the other General Settings, see the section “Business Service Settings” in 

“The Configuration Page” chapter of Managing Ensemble Productions. 

- PoolSize — The default PoolSize value of 1 ensure FIFO (First In, First Out) processing. In 

many cases, multiple patient demographic updates must be received in order. For example, 

many applications require receipt of an ADT Registration message before they can process 

an Order message, an Order message must be received before a Result message, and so on. 

- Category — This text label permits configuration items to be sorted in the configuration diagram. 

For example, you can assign the same Category name to all items in the same interface. 

You may enter multiple category names separated by commas. Space characters count (do 

not use them around the commas). 

• Specific Settings — This column of settings appears at right. The column is organized into settings 

that configure the HL7 business service (at top) and settings that configure its associated adapter 

(at bottom). The specific settings will be different depending on which HL7 business service you 

are configuring, and which adapter that business service is using. The following list describes 

how to configure the most important of these settings. For details about which class provides 

which settings, see the “HL7 Business Service Classes” section in the chapter “Settings for a 

Routing Production.” 

The Specific Settings for an HL7 business service are as follows: 

AckMode 

Helps to establish the format and conventions for issuing HL7 acknowledgement messages 

in response to HL7 messages received. For a list of codes to enter in this field, see the “HL7 

Acknowledgement (ACK) Mode” section in the chapter “Settings for a Routing Production.” 

Ack Target Config Names 

(File and FTP only) Unlike TCP business services, File and FTP business services have no 

persistent connection on which to send HL7 acknowledgement messages (ACK or NACK). 

For this reason, the default AckMode for File and FTP business services is Never, which is 

usually appropriate. However, when you do want to send ACKs from a File or FTP business 

service, use the Ack Target Config Names setting to identify an Ensemble routing process or 

business operation that will receive the ACK messages. For AckMode details, see the “HL7 

Acknowledgement (ACK) Mode” section in the chapter “Settings for a Routing Production.” 



Adapter Class 

AddNackERR 

Identifies the TCP, File, or FTP inbound adapter for HL7. 

If True, add ERR error code segment when generating NACK messages; otherwise do not 

embed internal error state information in NACK messages. For details and related settings, 

see the “HL7 Acknowledgement (ACK) Mode” section in the chapter “Settings for a 


Alert Grace Period 

Alert On Error 

Archive IO 

Business services can be configured with an Alert Grace Period during which errors relating 

to external connections do not trigger alerts, even if Alert On Error is True. The Alert Grace 

Period is allowed to elapse, giving the business service and the external source time to 

reestablish their connection. If the error condition still exists after the Alert Grace Period, the 

business service triggers an alert; otherwise no alert is triggered. 

Setting Alert Grace Period to 0 disables this feature for the business service. 

If True, the HL7 business service automatically triggers an alert upon encountering an error. 

See the “ “Pager and Email Alerts” ” section in this chapter. 

If True, the adapter associated with this business service will log in the Ensemble I/O archive 

each input and output communication it shares with the external system. This is not related 

to the ArchivePath. See the section “Working with the I/O Archive” in the “What to Manage” 

chapter of Managing Ensemble Productions. 

Batch Handling 

How to treat received message batches. The options are: 

• Whole Batch — Do not process message documents individually; accumulate and 

send the whole batch as one composite document. 

• Single-Session Batch — Forward all messages in the batch together in one session; 

the session includes objects representing the batch header and trailer segments. This is 

the default. 

• Multi-Session Batch — Forward each message in the batch in its own session; 

each session includes objects representing the batch header and trailer segments. 

• Individual — Forward each child message in the batch in its own session; do not 

forward objects representing the batch header and trailer segments. 



For more about batch handling, see the “HL7 Batch Messages” section in the chapter 

“Settings for a Routing Production.” 

DefCharEncoding 

Framing 

The default character encoding to use when reading or writing HL7 messages. If any incoming 

HL7 message has an empty MSH:18 (Character Set) field, Ensemble uses the DefCharEncoding 

value in its place. Supported values are UTF-8 or any member of the Latinn family. The 

value Native means to use the native default encoding installed on the Ensemble server. 

The default value for DefCharEncoding is Latin1. 

Placing a ! (exclamation point) character at the beginning of this field forces Ensemble to 

use the DefCharEncoding value and ignore any value found in MSH:18. For example: !UTF-8 

Placing a @ (at sign) character at the beginning of this field means that the field identifies an 

internal NLS Translation Table instead of a logical character encoding. 

Controls how the HL7 business service interprets the incoming HL7 message packet. For a 

list of framing options, see the “HL7 Message Framing Types” section in the chapter “Settings 

for a Routing Production.” If you are unsure what value to use, accept the default of 

Flexible framing for HL7 business services. 

IgnoreInboundAck 

If True, the business service ignores any inbound ACK messages to avoid creating an ACK 

feedback loop. For details and related settings, see the “ “HL7 Acknowledgement (ACK) 

Mode” ” section in the chapter “Settings for a Routing Production.” 

ImmediateByteAck 

(TCPAckIn and HTTPAckIn only) If this value is set to True, then in addition to forwarding a 

full ACK message according to the AckMode setting, the business service also returns an 

immediate 1–byte ACK on its TCP connection. For details, see the “Dual Acknowledgement 

Sequences” section in the chapter “Settings for a Routing Production.” 

Local Facility Application 

Colon-separated LocalFacility:LocalApplication code that represents the facility and application 

that receive HL7 messages via this business service. If this business service constructs 

its own ACK, Local Facility Application provides the SendingFacility:SendingApplication 

codes for the ACK message; otherwise, this setting is ignored. 

Message Schema Category 

The name of one of the following items: 



• A standard HL7 schema: 2.1, 2.2, 2.3, 2.3.1, 2.4, or 2.5. 

• A custom HL7 schema 

For example, if your custom schema definition looks like this: 

 

Then in the Message Schema Category field, enter the value: 

myCustomCategory 

If you have not yet prepared a custom schema definition for the HL7 business service, you 

may leave this field blank for now. However, do not leave it blank permanently unless you 

also disable validation for the routing process, or validation errors will automatically occur. 

See the “Message Validation and Bad Messages” section in the chapter “Settings for a 


PartnerOperation 

(TCPAckIn and HTTPAckIn only) The EnsLib.HL7.Service.TCPAckInService is a specialized 

HL7 TCP business service that receives ACKs on behalf of a paired HL7 TCP business 

operation. This enables the dual ACK sequence required by some client applications. There 

is also an EnsLib.HL7.Service.HTTPAckInService. For details, see the “Dual Acknowledgement 

Sequences” section in the chapter “Settings for a Routing Production.” 

When TCPAckIn or HTTPAckIn is the business service class, PartnerOperation identifies the 

paired business operation. The business operation must exist and have the underlying class 

EnsLib.HL7.Operation.TCPAckOutOperation or EnsLib.HL7.Operation.HTTPAckOutOperation, 

respectively. 

Search Table Class 

The package and class name of a search table class that you have defined in this Ensemble 

namespace. A search table class is a specialized tool that you can create to work with virtual 

documents, such as HL7 messages. A virtual document is efficient because it contains a large 

amount of raw data but no instantiated properties. Creating a search table enables Ensemble 

to efficiently index a few of the fields in a virtual document so that these fields are available 

to be searched as if they were properties in a standard message body. 

To create a search table class, see the “HL7 Search Tables” section in this chapter. For 

conceptual information, see the book Ensemble Virtual Documents. 

Target Config Names 

The configured name of one or more of the following items: 

• An HL7 routing process (for a routing interface) 



• An HL7 business operation (if your design bypasses a routing process for this interface 

and simply relays messages from the incoming business service to the outgoing business 

operation) 

Use Ack Commit Codes 

True or False. If True, when constructing an ACK message for HL7 messages version 2.3 or 

higher, the business service places one of the “enhanced-mode” ACK commit codes in the 

MSA segment AcknowledgmentCode field. For a list of codes, see “The UseAckCommitCodes 

Setting” in the chapter “Settings for a Routing Production.” 

The remaining entries in the Specific Settings column are determined by the type of adapter: FTP, File, 

TCP, or HTTP. The following adapter settings are especially important for HL7 business services: 

AppendTimestamp 

ArchivePath 

CallInterval 

(File only) If True, the HL7 business service automatically appends a time stamp to filenames 

in the ArchivePath. The format for this time stamp is %f_%Q where: 

• %f is the name of the data source, in this case the input filename 

• _ is the literal underscore character, which will appear in the output filename 

• %Q indicates ODBC format date and time 

In substituting a value for the format code %f, Ensemble strips out any of the characters 

|,,\,/,:,[,],,&,,,;,NUL,BEL,TAB,CR,LF, replacing spaces with underscores (_) and slashes 

(/) with hyphens (-). When the output file is being saved on an OpenVMS system, Ensemble 

replaces colons with hyphens (-). Otherwise, colons (:) become dots (.). 

(File and FTP only) If this field is not empty, Ensemble creates a copy of each HL7 message 

received via this business service and saves it as a file in the specified ArchivePath. The 

archived filename is the same as the input filename. 

The number of seconds to wait before looking for more input. 

For further information about any setting, hovering the cursor over the setting name, or consult these 

references: 

• “Adapter Settings” in the “FTP Inbound Adapter” chapter of Using FTP Adapters with Ensemble 

• “Adapter Settings” in the “File Inbound Adapter” chapter of Using File Adapters with Ensemble 

• “Adapter Settings” in the “TCP Inbound Adapter” chapter of Using TCP Adapters with 

Ensemble, which describes the settings for the general-purpose TCP inbound adapter. The difference 


HL7 Custom Schema Categories 

for the special-purpose adapter called EnsLib.HL7.Adapter.TCPInboundAdapter is that it has 

JobPerConnection set to False, which is usually appropriate for HL7. 

• The “Using the HTTP Inbound Adapter” chapter in Using HTTP Adapters with Ensemble 

2.3.3 Integrating an HL7 Business Service 

To integrate a new HL7 business service into an Ensemble production, you must associate it with the 

routing process or business operation to which it relays messages. Additionally, if you expect the 

business service to receive non-standard message structures you will need to create a custom HL7 

schema definition to parse and validate these messages. To do this: 

1. Complete the instructions for creating any TargetConfigNames or Message Schema Category items 

that your HL7 business service needs. The items might be: 

• An HL7 routing process (for a routing interface) 

• An HL7 business operation (if your design bypasses a routing process for this interface and 

simply relays messages from the incoming business service to the outgoing business operation) 

• A custom HL7 schema definition, to parse the incoming HL7 messages 

The next several topics provide instructions for creating these items. 

2. Return to the configuration diagram on the [Ensemble] > [Productions] page. Select the new HL7 

business service. If the TargetConfigNames and Message Schema Category fields were previously 

blank, configure them now, and Apply your changes. 

2.4 HL7 Custom Schema Categories 

The HL7 standard is easily extensible, and many of the clinical applications that produce and consume 

HL7 data take advantage of this feature. The common practice in customizing HL7 is to add custom 

segments to an otherwise standard HL7 message structure. By convention, the custom segments have 

names that begin with the letter Z (ZEK, ZPM, etc.), so custom segments are called Z-segments. A 

custom message structure often consists of a standard message with a few Z-segments added to it. 

If a clinical application uses no non-standard messages, there is no need to create a custom schema. 

However, this is rarely the case. For non-standard message structures, a custom schema is needed in 

order for Ensemble to be able to: 

• Perform structural message validation 

• Use segment and field path names in BPL, DTL, and routing rule syntax. 



Ensemble provides a built-in schema category definition for each published version of the HL7 standard. 

These HL7 category definitions can be viewed and edited in XML format by opening the corresponding 

.HL7 file in Ensemble Studio. Each .HL7 file consists of a set of XML statements which define the 

HL7 messages. 

To create your own custom schema category, simply create a new .HL7 file and add XML statements 

to it. You can do this by creating a new file or copying an existing file, as follows: 

1. Start Ensemble Studio and change to an Ensemble-enabled user namespace. 

Important: 

InterSystems recommends that you do not place custom code or data in the systemprovided 

namespaces ENSLIB or ENSDEMO where it will be deleted the next 

time you upgrade Ensemble. The ENSEMBLE namespace and any new namespace 

that you create to hold your work is preserved across Ensemble upgrades. 

2. From the File menu, choose New. 

3. The New dialog displays. Select the Custom tab. 

4. Select the HL7 Schema icon and click OK. 

5. Enter a New Schema Name. This is the name of the new schema. When you save the 

schema definition, it becomes the name of the new *.HL7 file. 

6. Enter a Base Schema Name. Specify the name of the schema base. Use one of the 

built–in categories: 2.1, 2.2, 2.3, 2.3.1, 2.4, or 2.5. 

7. Click OK. 

If you have already created a custom schema category that matches your requirements closely, you 

might prefer to copy and edit this custom schema instead of creating a new custom schema. Use the 

following steps: 

1. Open any existing custom schema category file as follows: 

• Start Studio. 

• Select File Open. 

• For the Look in field choose an Ensemble-enabled user namespace. 

• In the Files of type field select All files. 

• In the File name field enter the extension *.hl7 or *.HL7. The names of several schema 

category files appear. 

• Select an existing custom schema category file as the model for your new file. Do not select 

any of the built–in schema category files (2.1.HL7, 2.2.HL7, 2.3.HL7, 2.3.1.HL7, 

2.4.HL7, or 2.5.HL7). If there are no custom schema category files to choose from, create 

a new file as described in the previous procedure. 


HL7 Custom Schema Categories 

• Click Open. 

2. From the File menu, choose Save As. Enter a new filename with the *.HL7 extension. For 

example: 

myCustomCategory.HL7 

3. Edit the name and base attributes for : 

• For name specify the new *.HL7 filename. 

• For base specify the name of the schema base. Use one of the built–in categories: 

2.1, 2.2, 2.3, 2.3.1, 2.4, or 2.5. 

For example: 

 

You are now ready to edit your new file to add and remove XML statements from the 

block. You may open and study existing .HL7 schema files using Ensemble Studio. The editing steps 

for the new .HL7 schema file are as follows: 

1. Define Z-segments using elements. 

2. Define custom elements that contain the Z-segments. 

3. Define custom elements that contain the custom message structures. 

4. Remove any unneeded XML statements that remain from examples you have copied. 

5. From the File menu, choose Save. This action both saves and compiles the new category definition. 

6. Try viewing the new category definition from the Ensemble Management Portal. Select EDI / HL7 

Manager and then Schema Structures. You should see your new custom category listed along with 

the standard categories. 

7. You can use the new custom schema definition in an HL7 routing production as follows: 

• When creating a DTL data transformation, identify the custom schema category as the 

sourceDocType or targetDocType 

• When configuring an HL7 business service, identify the custom schema category as the 

Message Schema Category 

For a formal syntax guide to the XML used in schema category definitions, see the “Schema Category 

Syntax” section in the chapter “Settings for a Routing Production.” 



2.5 HL7 Routing Processes 

To build an HL7 routing process for use in an HL7 message routing production, you must create it, 

configure it, and integrate it into the production. This topic explains each step. 

2.5.1 Creating an HL7 Routing Process 

To create an HL7 routing process: 


2. If the production already contains a similar HL7 routing process, you may copy it using the following 

sequence of steps: 


• Select the routing process in the diagram. 


• Enter a unique name and click OK. Your new routing process appears in the diagram 


name is different. Your next step is to configure the copy. 

Note: 

The Copy button works only within the same production. You cannot copy a routing 

process from one production to another. 

3. To create an entirely new HL7 routing process, without copying, use the following sequence of 

steps: 

• Start the Business Process Wizard in one of the following ways: 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Process. 




Click Add Process. 


Process. 

• Choose HL7 Message Router. The following fields display: 

- Accept the default Router Class of EnsLib.HL7.MsgRouter.RoutingEngine. 


- Give the routing process a configuration Name. Use a simple name that contains no dot 

(.) separators or space characters. 

- The Routing Rule Name field identifies the routing rule set that the routing process will 

execute to decide where to send the messages that it receives. 


HL7 Routing Processes 

2.5.2 Configuring an HL7 Routing Process 

You can configure an HL7 routing process of the class EnsLib.HL7.MsgRouter.RoutingEngine by 

clicking on it while viewing the configuration diagram on the [Ensemble] > [Productions] page. The 

following fields display below the diagram; you can edit these fields to configure the routing process. 

Note: 



You may configure an HL7 routing process by entering values in the following fields. When you are 

done editing, click Apply to save your changes, or Cancel to ignore them. 

AckType 

AddNackERR 

Determines the ACK type (that is, AA or CA) if constructing an ACK or NACK reply message 

locally. A is the default code. For further details, see the “HL7 Acknowledgement (ACK) 

Mode” section in the chapter “Settings for a Routing Production.” 

True or False. If True, add an ERR error code segment when generating NACK messages. If 

False, do not embed internal error state information in NACK messages. 

Alert On Bad Message 

If True, any message that fails validation automatically triggers an alert. 

Bad Message Handler 

Identifies the HL7 business operation that disposes of any incoming HL7 messages that fail 

validation. 

Business Rule Name 

The full name of the routing rule set for this routing process. If you generated the routing 

process using the Business Process Wizard, use the default value provided by the wizard. 



ForceSyncSend 

If True, make synchronous calls for all “send” actions from this routing process. If False, 

allow these calls to be made asynchronously. The ForceSyncSend setting is intended to ensure 

FIFO ordering in the following case: This routing process and its target business operations 

all have Pool Size set to 1, and ancillary business operations might be called asynchronously 

from within a data transformation or business operation called from this routing process. 

If ForceSyncSend is True, this can cause deadlock if another business process is called by a 

target that is called synchronously from this routing process. 

Note that if there are multiple “send” targets, ForceSyncSend means these targets will be 

called one after another in serial fashion, with the next being called after the previous call 

completes. Also note that synchronous calls are not subject to the Response Timeout setting. 

Local Facility Application 

NackCode 

Colon-separated LocalFacility:LocalApplication code that represents the facility and application 

that receive HL7 messages via this routing process. If this routing process constructs 

its own ACK or NACK messages, Local Facility Application provides the 

SendingFacility:SendingApplication codes for the messages; otherwise, this setting is ignored. 

Determines the NACK code type (that is, AE or AR) if constructing a NACK reply message 

locally to report an error. E is the default code. For further details, see the “HL7 Acknowledgement 

(ACK) Mode” section in the chapter “Settings for a Routing Production.” 

Response From 

A comma-separated list of configured items within the production. This list identifies the 

targets from which a response may be forwarded back to the original caller, if the caller 

requested a response. 

If a Response From string is specified, the response returned to the caller is the first response 

that arrives back from any target in the list, and if there are no responses, an empty “OK” 

response header is returned. If the Response From value is empty, nothing is returned. 

The Response From string allows special characters as follows: 

• The * character by itself matches any target in the production, so the first response from 

any target is returned. If there are no responses, an empty “OK” response header is 

returned. 

• If the list of targets begins with a + character, the responses from all targets return together, 

as a list of message header IDs in the response header. If none of the targets responds, 

an empty “OK” response header is returned. 


HL7 Routing Processes 

• If the list of targets begins with a - character, only error responses will be returned, as 

a list of message header IDs in the response header. If none of the targets responds with 

an error, an empty “OK” response header is returned. 

Response Target Config Names 

A comma-separated list of configured items within the production. If specified, this list 

identifies the destinations, in addition to the caller, to which responses will be forwarded. If 

empty, responses are only returned to the caller. This setting takes effect only if the Response 

From field has a value. 

Response Timeout 

Validation 

Maximum length of time to wait for asynchronous responses before returning a “timed-out 

error” response header. A value of -1 means to wait forever. Note that a value of 0 is not 

useful, because every response would time out. This setting takes effect only if the Response 

From field has a value. 

If blank, the routing process skips validation and simply routes messages. For details about 

validation conventions when this field contains a value, see the “Message Validation and 

Bad Messages” section in the chapter “Settings for a Routing Production.” 

An HL7 routing process has other configurable settings that apply to all business hosts. Documentation 

for these common settings is available in the section “Business Process Settings” in “The Configuration 

Page” chapter of Managing Ensemble Productions. 

2.5.3 Integrating an HL7 Routing Process 

To integrate a new HL7 routing process into an Ensemble production, you must associate it with the 

business service that receives its incoming messages, and with the routing rule set that determines its 

actions based on those messages. To do this: 

1. Select the HL7 business service. In the TargetConfigNames field enter the name of the new HL7 

routing process. 

2. Create a routing rule set for the routing process. Select the routing process in the configuration 

diagram. In the BusinessRuleName field enter the full name of the new routing rule set. 



2.6 HL7 Sequence Manager 

An HL7 sequence manager is a business process that accepts incoming HL7 messages from multiple 

sources, then forwards the messages to a target configuration item in the order specified by the MSH:13 

SequenceNumbers field in the messages. 

The sequence manager has the ability to detect duplicate messages and timing gaps between messages. 

It also determines when the timing gaps between sequential messages are sufficiently large to indicate 

a problem. Its level of sensitivity can be adjusted using its configuration settings. 

To build an HL7 sequence manager for use in an HL7 message routing production, you must create 

it, configure it, and integrate it into the production. This topic explains each step. 

2.6.1 Creating an HL7 Sequence Manager 

To create an HL7 sequence manager: 


2. If the production already contains a similar HL7 sequence manager, you may copy it using the 

following sequence of steps: 


• Select the sequence manager in the diagram. 


• Enter a unique name and click OK. Your new sequence manager appears in the diagram 


name is different. Your next step is to configure the copy. 

Note: 

The Copy button works only within the same production. You cannot copy a sequence 

manager from one production to another. 

3. To create an entirely new HL7 sequence manager, without copying, use the following sequence 

of steps: 

• Start the Business Process Wizard in one of the following ways: 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Process. 




Click Add Process. 


HL7 Sequence Manager 


Process. 



- For the ProcessClass choose EnsLib.HL7.SequenceManager. 

- Give the item a configuration Name. For suggestions, see the “Naming Conventions” 

section in the chapter “Design Model for a Routing Production.” 


2.6.2 Configuring an HL7 Sequence Manager 

A sequence manager is a business process of the class EnsLib.HL7.SequenceManager. You can configure 

a sequence manager by clicking on it while viewing the configuration diagram on the [Ensemble] > 

[Productions] page. The following fields display below the diagram; you can edit these fields to configure 

the sequence manager. 

Note: 



You may configure an HL7 sequence manager by entering values in the following fields. When you 

are done editing, click Apply to save your changes, or Cancel to ignore them. 

AlertOnError 

If True, the HL7 sequence manager automatically triggers an alert upon encountering errors 

trying to connect with its external target. The default is False. 

DuplicatedMessageTarget 

The configured Name of an item within the production, usually a business operation. If 

specified, this is where the sequence manager sends any duplicate messages that it receives. 

EnableDuplicatedMessageCheck 

If True, the sequence manager checks to see if any incoming messages are duplicates of a 

previously received message. It does this by checking the following three fields in the MSH 

segment of each message: 

• MSH:3 SendingApplication 

• MSH:4 SendingFacility 



LargeGapSize 

• MSH:10 MessageControlId 

A sequence manager can check for duplicate messages and messages out of sequence, 

duplicate messages or messages out of sequence, or neither. This makes EnableDuplicatedMessageCheck 

entirely independent of PerformSequenceNumberCheckOn in that either, one, or 

both of these settings may be True. 

A number that indicates a significant gap in the sequence of messages. 

A late message is a message that arrives with a sequence number larger than the previously 

received message in the sequence, but not exactly sequential. For example, when message 

102 arrives after message 101, 102 is not late; it is the next message in sequence. However, 

when message 110 arrives after message 101, 110 is a late message. 

When there is a late message, and the sequence numbering gap between the preceding and 

subsequent messages is less than the configured LargeGapSize, this is a small gap. A gap 

larger than this is a large gap. 

• For any small gap, the sequence manager waits for MessageWaitTimeout seconds to see 

if messages will arrive to fill the gap. If the messages arrives within the waiting period, 

the sequence manager aligns them in their proper sequence. If they do not arrive and the 

MessageWaitTimeout expires, the sequence manager stops waiting and sends whatever 

it has for messages in the current sequence. 

• When there is a large gap, the sequence manager does not wait for any period of time. 

It immediately sends an alert, then sends whatever it has for messages in the current 

sequence. 

The default LargeGapSize is 100. 

MessageResendableTimeWindow 

Time window during which the sequence manager considers a duplicate message to be a 

duplicate. The reason for the MessageResendableTimeWindow is that sometimes a duplicate 

message is not a mistake. Sometimes it is the result of deliberately resending a message 

sequence. 

Suppose a message arrives and the sequence manager detects that it is a duplicate of a previously 

received message. In this case: 

• If it has been more than MessageResendableTimeWindow seconds since the sequence 

manager first saw this message, it interprets the new arrival as a deliberately resent copy. 

The sequence manager begins tracking the messages in this resent sequence independently 

from its tracking of the main sequence of messages. 


Suppose the sequence manager is processing a sequence that includes numbers such as 

1001, 1002, 1003, and 1004, but at the same time it begins receiving messages with the 

sequence numbers 1, 2, and 3. If the older messages with smaller sequence numbers were 

first received more than MessageResendableTimeWindow seconds ago, the sequence 

manager interprets them as messages in a resent sequence, rather than as messages out 

of sequence. It begins tracking the main sequence and the resent sequence simultaneously. 

While doing so, it keeps the two sequences separate, appropriately ignoring gaps between 

unrelated sequence numbers such as 2 and 1001. 

• If it has been less than MessageResendableTimeWindow seconds since the sequence 

manager first saw this message, the new arrival is understood to be a true duplicate, and 

the sequence manager handles it appropriately. See EnableDuplicatedMessageCheck. 

The default MessageResendableTimeWindow is 300 seconds (5 minutes). 

MessageWaitTimeout 

For definitions of large gaps, small gaps, and late messages, see the LargeGapSize setting. 

For any small gap, the sequence manager waits for MessageWaitTimeout seconds to see if 

messages will arrive to fill the gap between the preceding message and the late message. If 

they do not arrive and the MessageWaitTimeout expires, the sequence manager stops waiting 

and sends whatever it has for messages in the current sequence. 

The default MessageWaitTimeout is 60. 

OutOfSequenceMessageTarget 

The configured Name of an item within the production, usually a business operation. If 

specified, this is where the sequence manager will send any out-of-sequence messages that 

it receives. 

OutputFacilityApplication 

Specifies the facility and application to be used in the message transformation when PerformOutputTransformationOn 

is set to Sender or Receiver. 

The format for the OutputFacilityApplication value is: 

Facility:Application 

OutputTargetConfigNames 


A comma-separated list of configured items within the production. If specified, this list 

identifies the destinations to which the sequence manager will send any message that passes 

its tests. 



PassThroughMessageTypes 

A comma-separated list of message types that are exempt from duplicate checks, sequence 

checks, or output transformations. The sequence manager always passes these messages 

through unchanged. The default list is: 

QBP_Q21,QBP_Q22,RSP_K21,RSP_K22,ACK 

PerformOutputTransformationOn 

Fields for the sequence manager to transform before sending out a message. The output 

transformation provides new facility, application, and sequence number fields as described 

in the following list, then sends the message to its configured targets. Possible values for 

PerformOutputTransformationOn are: 

• Sender — This is the default. The sequence manager copies Facility and Application 

from the OutputFacilityApplication setting and assigns a new sequence number. The result 

is that the following fields are changed in the outgoing message: 

- MSH:3 SendingApplication 

- MSH:4 SendingFacility 

- MSH:13 SequenceNumber 

• Receiver — The sequence manager copies Facility and Application from the Output- 

FacilityApplication setting and assigns a new sequence number. The result is that the 

following fields are changed in the outgoing message: 

- MSH:5 ReceivingApplication 

- MSH:6 ReceivingFacility 


• None — The sequence manager does not perform any transformation before sending the 

message. 

PerformSequenceNumberCheckOn 

Fields for the sequence manager to check to see if any of the incoming messages are out of 

sequence. If so, the sequence manager resequences the messages and sends them to its configured 

targets. 

Possible values for PerformSequenceNumberCheckOn are: 

• Sender — This is the default. The sequence manager checks: 






• SendingFacility — The sequence manager checks: 



• SendingApplication — The sequence manager checks: 



• Receiver — The sequence manager checks: 




• ReceivingFacility — The sequence manager checks: 



• ReceivingApplication — The sequence manager checks: 



• None — The sequence manager does not check for messages out of sequence. 

A sequence manager can check for duplicate messages and messages out of sequence, 

duplicate messages or messages out of sequence, or neither. This makes EnableDuplicatedMessageCheck 

entirely independent of PerformSequenceNumberCheckOn in that either, one, or 

both of these settings may be True. 

An HL7 sequence manager has other configurable settings that apply to all business hosts. Documentation 

for these common settings is available in the section “Business Process Settings” in “The 

Configuration Page” chapter of Managing Ensemble Productions. 



2.6.3 Integrating an HL7 Sequence Manager 

To integrate a new HL7 sequence manager into an Ensemble production, you must associate it with 

the business service that receives its incoming messages, and with the target destination for the messages 

that it sends, once it has sorted out their proper sequence. To do this: 

1. Select the HL7 business service. In the TargetConfigNames field enter the name of the new HL7 

sequence manager. 

2. Return to configuring the HL7 sequence manager. Provide it with a list of OutputTargetConfigNames 

for successful messages. 

3. If you want the sequence manager to check for duplicate messages, set EnableDuplicatedMessageCheck 

to True. 

If you want to save the duplicate messages for troubleshooting purposes, create a HL7 business 

operation to receive them. In the DuplicatedMessageTarget field enter the name of the new HL7 

business operation. 

4. If you want the sequence manager to check for out-of-sequence messages, set PerformSequenceNumberCheckOn 

to Sender or Receiver and configure the details of sequence checking by 

setting values for LargeGapSize and MessageWaitTimeout. Otherwise, set PerformSequenceNumberCheckOn 

to None. 

If you want to save the out-of-sequence messages for troubleshooting purposes, create a HL7 

business operation to receive them. In the OutOfSequenceMessageTarget field enter the name of 

the new HL7 business operation. 

5. If you want the sequence manager to transform messages before sending them outside Ensemble, 

set PerformOutputTransformationOn to Sender or Receiver and set a value for the OutputFacilityApplication. 

Otherwise, set PerformOutputTransformationOn to None. 

6. Identify any PassThroughMessageTypes that the sequence manager should simply send to the 

OutputTargetConfigNames without checking or transforming them. 

2.7 Routing Rule Sets for HL7 

When creating a routing rule set for an HL7 interface, your goal is to tell Ensemble what to do with 

the source message based on the segments found within it. Sometimes it matters which segments are 

found; sometimes it matters which values are found within those segments. 

In ordinary rule sets, each Action returns a value to the business process that invoked the rule set. In 

a routing rule set, an Action usually directs an HL7 message to a destination, possibly transforming 

the HL7 message before sending it. 


The following figure illustrates the [Ensemble] > [Business Rules] > [Message Routing Rule Editor] 

page, which is used to create routing rule sets. The format of the Message Routing Rule Editor is the 

same as the Business Rule Editor in the following ways: 

• The top row of buttons: Rule List, Rule Log, Edit or Revert, Save, Delete 

Routing Rule Sets for HL7 

• The basic information table: Package Name, Rule Name, Routing Engine Class and so on 

• 

Activity buttons in the bottom display: 

This topic explains how to use the features of the Message Routing Rule Editor that are different from 

those of the Business Rule Editor. For background information about the Business Rule Editor, see 

the chapters “Managing Business Rules” and “Creating Rule Sets” in Using Business Rules with 

Ensemble. 

To build a routing rule set for use with an HL7 routing process: 


2. Display the Message Routing Rule Editor in one of the following ways: 

• While viewing a configuration diagram on the [Ensemble] > [Productions] page, click on a 

routing process in the Business Processes column. Click the View Rules button. The [Ensemble] 

> [Business Rules] > [Message Routing Rule Editor] page displays. 

Click Edit. 

• From the main menu, choose Business Rules. The [Ensemble] > [Business Rules] page displays 

a list of rule sets. Find a routing rule set and click Edit next to its name. 

• From the main menu, choose Business Rules. The [Ensemble] > [Business Rules] page displays 

a list of rule sets. Click the Create New Message Routing Rule button. 

3. When you create a new HL7 routing process using the Business Process Wizard, Ensemble creates 

a new, empty routing rule set to accompany the new routing process. Its information table contain 

the following values acquired from the Business Process Wizard: 

• Package Name — The package that contains the production class. For example, if you used 

the wizard to add a routing process to a production called TestRule.MyTest, the associated 

routing rule has a Package Name of: 

TestRule 

• Rule Name — The simple Routing Rule Name that you chose in the wizard, such as: 

MyRule 

The combination of the Package Name and Rule Name identify the rule uniquely within the 

Ensemble namespace. The full name for any rule definition is the Package Name and Rule 

Name connected by a dot (.) as in: 



TestRule.MyRule 

This full name, rather than the Rule Name, is the correct value to use in the BusinessRuleName 

field when configuring an HL7 routing process. The Business Process Wizard sets this up 

automatically. 

• Routing Engine Class — The default Router Class from the wizard; do not change it: 

EnsLib.HL7.MsgRouter.RoutingEngine 

If you did not use the wizard to create your routing rule set, then in the top half of the Message 

Routing Rule Editor screen you must enter basic information for the rule as follows: 

• Package Name — Similar in principle to the package name you use to organize host classes 

in Studio, this name may contain dot (.) separators, as in: 

MyClassPackage.Organization.Levels 

• Rule Name — A simple name that contains no dot (.) separators, as in: 

MyRule 

The combination of the Package Name and Rule Name identify the rule uniquely within the 

Ensemble namespace. The full name for any rule definition is the Package Name and Rule 

Name connected by a dot (.) as in: 

MyClassPackage.Organization.Levels.MyRule 

This full name, rather than the Rule Name, is the correct value to use in the BusinessRuleName 

field when configuring an HL7 routing process. 

• Routing Engine Class — This field tells the Message Routing Rule Editor which object 

properties to offer as drop-down choices in the Value Editor window while a user is editing 

a rule. For an HL7 routing rule set, use: 

EnsLib.HL7.MsgRouter.RoutingEngine 

4. Type a Description of the rule definition and its purpose. For example, you might list the types of 

message segments that travel over this interface. 

5. Do All Rules — If the Do All Rules check box is selected, Ensemble will begin at Rule 1 and evaluate 

all of the rules in sequence. In this case Ensemble executes every rule that evaluates to True. 

If the Do All Rules check box is clear, Ensemble stops evaluating rules immediately after executing 

the first rule in the sequence that evaluates to True. 

6. The bottom half of the Message Routing Rule Editor page contains fields that describe the logic 

of the routing rule using Rules, Conditions, and Actions. The following close-up views show 

details of this part of the user interface. 

On the left are the columns that identify Rules: 



On the right are the columns that define Conditions and their resulting Actions: 

7. If you expect many of your rules to share fields in common, for example a Message Class of 

EnsLib.HL7.Message, you can streamline the editing process by providing a Base rule for the set. 

A rule called Base always appears at the top of a list of routing rules. Base serves as a convenient 

template for creating new rules for the set. It is not a default value of any kind, but a starting point 

for editing rules. You can use it or leave it blank. 

Any part of the Base rule that you define appears automatically in every other rule in the set. 

Wherever text is italicized in the Message Routing Rule Editor display, this indicates that the 

value is inherited from the Base rule. As an example, see the Source and Message Class columns 

in the figures above. 

Any rule in the set may override the values it inherits from the Base rule. 



8. 

To add a rule to the set, in the Rules column, click . The Routing Rule Wizard displays. Use 

this dialog to configure the rule Source, Message Class, Document Name, Schema Category, and 

Schema Doc Type, as described in the following steps. 

9. Source is the configured name of one of the following items: 

• An HL7 business service (for a routing interface) 

• An HL7 routing process (if another rule chains to this routing rule set) 

Click the More (...) icon next to the Source field to see a popup list of possible Source items in 

the namespace, organized by production name. For example: 

Select an item and click OK to save your changes to the Source field. 

If you have not yet prepared the item you need as a Source, you may leave this field blank and 

return to it when the item is ready. 

If you leave the Source field permanently blank, Ensemble considers input from all sources to be 

a match for that rule. You can configure this case deliberately for any rule that needs it. 

10. Message Class identifies the Ensemble message object that is being routed by this rule. Click the 

More (...) icon next to the Message Class field to view a popup list of possible Message Class 

choices. 

To route HL7 Version 2 messages, choose EnsLib.HL7.Message. 

Important: 

The next three fields in the Routing Rule Wizard, and the next three steps in this 

procedure, apply only when the Message Class is EnsLib.HL7.Message or any 

other virtual document class, such as for X12 or ASTM. For other types of message, 

skip to Step 14. 

The next three fields in the Routing Rule Wizard are: 

• Document Name 



• Schema Category 

• Schema Doc Type 

The distinctions between these properties are as follows: 

• Document Name is the HL7 message structure that the source application identifies in the 

MSH:9 field, such as ADT_A08 or ORM_O01. To allow easy retrieval, this MSH:9 value 

resides in the EnsLib.HL7.Message property called Name. 

There is a problem with relying on the message header segment, MSH, for message validation. 

What the application says it is sending, and what the application actually sends, can be different. 

In theory, the values in MSH always correctly identify the contents of the message, but 

in practice, this is not always the case. 

For example, the message header MSH:12 field may state that the message is version 2.2, 

but the message contents may actually conform to the 2.3.1 standard or to some custom 

schema category. Thus, in addition to Document Name the Routing Rule Wizard also offers 

Schema Category and Schema Doc Type as values that the Ensemble validation sequence can 

attempt to match. These values should have been correctly assigned by the business service 

that accepted the message into Ensemble. If the values in the message DocType do not match 

those in the rule, then the rule does not execute. 

• Schema Category and Schema Doc Type represent the actual HL7 message structure. These 

values reside in the EnsLib.HL7.Message property called DocType. DocType is a two-part 

string separated by a colon, such as 2.4:ADT_A08. 

- At left is the Schema Category. This is the name of a built-in schema category such as 

2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, or the name of a custom schema definition. 

- At right is the Schema Doc Type. This is an HL7 message structure within the identified 

schema, such as ADT_A08 or ORM_O01. 

If validation is enabled for the routing process, and if values are provided for Schema Category 

or Schema Doc Type, Ensemble parses the message to determine if its structure matches the 

schema specified. The Schema Doc Type does not need to be the same as the Document Name 

for the message to be accepted as valid. 

Steps 11, 12, and 13 explain how to fill in these fields in the Routing Rule Wizard. 

11. For the Document Name, you can: 

• Leave the field blank, to match any Document Name. 

• Enter a value, to cause the rule to match only messages with the specified Document Name. 

• Enter more than one value in the Document Name text entry field, pressing Enter between 

values to place one value on each line of text. This causes the rule to match any of the specified 

Document Name values, and no others. 



When viewing the rule after you have edited it, the value you entered in the Document Name field 

appears as the Message Type for the rule. 

12. For the Schema Category, you can: 

• Leave the field blank, to match any Schema Category. 

• Enter or choose a single value using the More (...) icon, to cause the rule to match only messages 

with the specified Schema Category. 

When viewing the rule after you have edited it, the value you entered in the Schema Category 

field appears as the Category for the rule. 

13. For the Schema Doc Type, you can: 

• Leave the field blank, to match any Schema Doc Type. 

• Enter a value, to cause the rule to match only messages with the specified Schema Doc Type. 

• Enter more than one value in the Schema Doc Type text entry field, pressing Enter between 

values to place one value on each line of text. This causes the rule to match any of the specified 

Schema Doc Type values, and no others. 

• Enter either a simple Schema Doc Type (ORM_O01) or a full value separated by a colon 

(2.3.1:ORM_O01). A full value in the Schema Doc Type field temporarily overrides whatever 

is in the Schema Category field. 

When viewing the rule after you have edited it, the value you entered in the Schema Doc Type 

field appears as the Schema Doc Type for the rule. 

Important: 

If you are uncertain how to use the Document Name (Step 11), Schema Category 

(Step 12), or Schema Doc Type (Step 13), return to Step 10 for an overview of 

these fields. 

14. Click OK to save changes in the Routing Rule Wizard. Click Cancel to discard them. 

15. Once you have created a new rule, you may add Conditions and Actions to it. For details, see the 

“Creating Rule Sets” chapter in Using Business Rules with Ensemble. As you add Conditions to 

each rule, remember these tips: 

• Conditions evaluate AND operators first, then OR. 

• Conditions can refer to properties of the HL7 message object. Within Conditions, the special 

variable Document represents the HL7 message object, as in the following examples. For 

HL7 batch documents, you can use the special variable Document.Parent to represent the 

parent message object. 

Document.Name 

Document.Parent.DocType 



Document.{PIDgrp.PV1grp.PV1:18} 

Document.{PIDgrp.PID:PatientName.familylastname} 

Document.{ORCgrp(1).OBRuniongrp.OBRunion.OBR:4.3} 

Note: 

For compatibility with past releases, the special variables HL7 and HL7.Parent 

are supported as alternatives to Document and Document.Parent. 

A dot separates the Document variable from the property name. This name may be: 

- Any of the class properties: DocType, TypeCategory, BuildMapStatus, or Name. 

- A virtual property, referenced using any of the following conventions: 

• Curly brackets 

{segmentPath:field} 

• Square brackets 

[segmentName:field] 

• Round brackets or parentheses 

(multi-valued-property-path) 

• Angle brackets 

 

Details are available in the “Virtual Property Syntax” section in the chapter “Syntax 

for a Routing Production.” However, you do not need to enter properties by typing; you 

can browse for properties as described in the “Creating Rule Sets” chapter in Using 

Business Rules with Ensemble. 

16. To specify an Action for a rule, click the Add or Send buttons in the Action column. The Routing 

Rule Wizard displays a dialog in which you can configure Action details as follows: 

• Type — Choose an option, one of the following: 



Type 

send 

delete 

stop 

continue 

Meaning 

Send the message to the target.This is appropriate for most cases. 

Discard the message. 

If the Do All Rules check box is selected, Ensemble evaluates every 

rule in the set, and all rules that are True have their actions 

executed. On the other hand, if any rule that is True provides a final 

action of stop, this overrides the Do All Rules setting and causes 

Ensemble to stop evaluating rules immediately. All subsequent 

rules in the set are skipped. 

If the Do All Rules check box is clear, Ensemble stops evaluating 

rules after executing the actions provided by the first rule that 

evaluates to True. However, if one of the actions in the rule is 

continue, this overrides the Do All Rules setting and causes 

Ensemble to continue evaluating more rules, in sequence, until it 

finds the next rule that evaluates to True, and then stop. 

• Target — For send you may enter the configured name of one or more of the following items. 

- An HL7 business operation, to route the message to an external application 

- An HL7 routing process, to chain to another routing rule set 

Click the More (...) icon next to the Target field to see a list of possible Target items in the 

namespace, organized by production name. You may select items from this list, one at a time. 

If you need to enter multiple items in the Target field, separate each name with a comma. 

This happens automatically when you select multiple items from the list. 

• Transform — To transform the HL7 message before sending it to the Target, enter the full 

package and class name of one or more DTL data transformations. 

Click the More (...) icon next to the Transform field to see a list of data transformation classes 

in the namespace. You may select items from this list, one at a time. If you need to enter 

multiple items in the Transform field, separate each name with a comma. This happens automatically 

when you select multiple items from the list. 

• Click OK to save your changes, Cancel to discard them. 

If you have not yet created the configuration items that you want to specify in the Target or 

Transform fields, you may leave the Action field blank and return to it when these items are ready. 

Note that the Target and Transform fields each support multiple values. Multiple data transformations 

are chained in the order in which they appear, from left to right. Any transformations listed 


after the first one should be defined with create="existing" so as not to discard the results 

of the previous transformation in the chain. 

If you leave the Action, Transform, and Target fields permanently blank, Ensemble takes no action 

when this rule is true. You can configure this case deliberately for any rule that needs it. 

17. To save changes to the routing rule set, click Save. If you wish to discard changes and return to 

the previously saved version of the rule set, click Revert. 

18. Complete the instructions in the next several topics for creating any Source, Target, or Transform 

items that your routing rule set needs. The items might be: 

• An HL7 business service, to route messages to the rule 

• A DTL data transformation, to transform the message before sending it 

• An HL7 business operation, to route the message to an external application 

• An HL7 routing process may be either a Source or a Target 

As you create items, return to the Message Routing Rule Editor to add them to the appropriate 

fields of the rule definition. 

19. Repeat from step 5 as needed to refine the logic of the routing rule set. 

DTL Data Transformations for HL7 

20. Return to the configuration diagram on the [Ensemble] > [Productions] page. Select the corresponding 

HL7 routing process. In the BusinessRuleName field enter the full name of the new routing 

rule set. 

2.8 DTL Data Transformations for HL7 

Each data transformation invoked by the production must be an instance of a Ensemble Data Transformation 

Language (DTL) class — that is, a subclass of Ens.DataTransformDTL. Each interface may 

require more than one data transformation. 

Data transformations are used to modify an HL7 message or create a new message from an existing 

message. You can edit a DTL data transformation in Ensemble Studio using the DTL Visual Editor 

or by editing the class code directly. 



Ensemble DTL Visual Editor 

To build a DTL data transformation for use in an HL7 message routing production: 

1. Start Studio and change to an Ensemble-enabled user namespace. 

Important: 



time you upgrade Ensemble. Any new namespace that you create to hold your 

work is preserved across Ensemble upgrades. 

2. Find an existing Ensemble data transformation that seems similar to the one you are converting. 

After converting several interfaces, you might discover a specific data transformation that tends 

to be useful as a starting point when nothing else is similar. Use this class, or use the data transformation 

class Demo.HL7.Router.SampleTransformation from the ENSDEMO namespace of sample 

classes. This class is illustrated above. 

3. Choose Tools, then Copy Class. A dialog pops up. Edit it using the following sequence of steps: 

• In the Copy Class Definition From field, browse to the data transformation class that you chose 

as a starting point. 

• In the To field, enter the full package and class name for the new data transformation. 



Important: 

InterSystems recommends that you do not use the package names Demo, 

Ens, EnsLib, EnsPortal, or CSPX. This causes your work to be deleted the 

next time you upgrade Ensemble. 

• Select the Add New Class to Project check box. 

• Click OK. 

4. Have the Ensemble Data Transformation Language Reference handy. This book lists and explains 

the available DTL elements. 

5. Be clear about the value you want for the create attribute of the element. create may 

have one of the following values: 

• “new” — Create a new object of the target type, before executing the elements within the 

data transformation. Any source segments that you do not explicitly assign to the target object 

are ignored. This is the default. 

• “copy” — Create a copy of the source object to use as the target object, before executing the 

elements within the transform. 

• “existing” — Use an existing object, provided by the caller of the data transformation, as the 

target object. 

To create a target object that is an exact copy of the source, do not use: 

 

Instead use the create='copy' attribute in the containing element. 

6. Ensure that the DTL element identifies the correct schema category for: 

• The sourceDocType attribute 

• The targetDocType attribute 

The schema category may be the same or different for the source and target objects. 

7. Ensure that the DTL element sets the scripting language that you want to use for all 

of the conditional expressions and elements within that data transformation. ObjectScript 

is the default language. If you want Caché Basic, you can specify it as follows: 


If you want to type elements into the DTL code directly, you may do so. Your changes 

in the DTL code view become visible each time you click on the DTL diagram view in the DTL 

Visual Editor. 

Possibly, you will want to use a combination of techniques. You can first generate a line of code 

by dragging, then fine-tune the code by editing the text. 

9. The data transformation can refer to properties of the HL7 message object, including: 

• The class properties DocType, TypeCategory, BuildMapStatus, and Name. 

• Virtual document properties as described in “Curly Bracket {} Syntax” in the “Virtual 

Property Syntax” section in the chapter “Syntax for a Routing Production.” 

Within the data transformation class code, the special variables source and target represent 

the respective HL7 message objects, as in the following examples: 

source.Name 

target.DocType 

source.{PIDgrp.PV1grp.PV1:18} 

target.{PIDgrp.PID:PatientName.familylastname} 

source.{ORCgrp(1).OBRuniongrp.OBRunion.OBR:4.3} 

10. Assign any literal string values, or make conditional assignments, as described in the “Literal 

String Syntax” section of the chapter “Syntax for a Routing Production.” Highlights include: 

• The syntax required to assign a literal string in DTL is as follows: 

value='"string"' 

• Do not insert a literal HL7 separator string for MSH 2 in the target. HL7 separators are handled 

in the HL7 business operation. 

• Do not manually change HL7 escape sequences such as \F\ or \S\ in the data transformation. 

The HL7 business operation handles these appropriately. 

• Be aware of XML entities and other special characters. If you run into trouble with quotes 

you can use the entities " and ' 

• A value can be a simple literal string, as in: 


A value can be a complex string expression in the language being used for the data transformation. 

The language for this expression depends on the value of the language attribute for 

the DTL element. If not specified, the default language is ObjectScript. 

• The ObjectScript concatenation operator is the underscore character, as in: 

value='"string1"_"string2"' 


In Caché Basic, the concatenation operator is & (ampersand). 

• To learn about useful ObjectScript string functions, such as $CHAR and $PIECE, see the 

Caché ObjectScript Reference. For Basic equivalents, see the Caché Basic Reference. 

• The HL7 null mapping code "" requires special handling. The following example tests for 

the null mapping code in the source message and replaces it with a blank string in the target 

message: 

 

 

 

 

 

For details, see “Null Mapping Codes” in the “Literal String Syntax” section in the chapter 

“Syntax for a Routing Production.” 

11. For simple calculations, the DTL data transformation can: 

• Invoke Ensemble utility functions 

• Use ObjectScript or Caché Basic expressions in the DTL element 

• Invoke the DTL element 

For more complex calculations, you can write utility class methods and invoke them from the 

DTL element, or from the value string in another DTL element. 

12. You can comment your DTL code. For your comments to be permanently visible in both class 

code and DTL Visual Editor views, you must provide comments within a block. 

For details and examples, see the section “Documentation and Comments” in the “Ensemble 

Productions” chapter of Developing Ensemble Productions. 

13. Compiling the data transformation also saves it. 


14. To use the DTL data transformation in the production, simply enter its full package and class 

name in the Transform field of a routing rule set. 

2.8.1 Utility Functions 

Ensemble provides a large number of built-in utility functions that include mathematical or string 

processing functions such as you may be accustomed to using in other programming languages. These 

functions are available for use in business rules or DTL data transformations. 

For example, the following DTL statement uses the built-in function ToUpper to convert a 

string to all uppercase characters. This statement references ToUpper using double-dot 

syntax, as if it were a method in the DTL data transformation class: 



 

For syntax details and a list of functions, see the section “Utility Functions” in the “Creating a New 

Production” chapter of Developing Ensemble Productions. The topic also explains how to extend the 

list of built-in utility functions by adding custom code. 

2.8.2 Utility Class Methods 

Instead of invoking a utility function from DTL directly, as shown above for ToUpper, for more 

complete calculations you can provide utility class methods and then invoke them from a DTL 

element. The steps are: 

1. Write the methods in a utility class in the same package as the other Ensemble element; for 

example: 

MyPackageName.TransformUtils 

2. Invoke these methods from the DTL data transformation using the element. 

2.9 HL7 Business Operations 

An HL7 business operation constructs an outgoing HL7 message and relays it to an outbound adapter 

along with all of the information necessary to transmit the message. The adapter knows nothing about 

the contents of the outgoing message and simply relays it to a specific external system using the 

information provided. 

To build an HL7 business operation for use in an HL7 message routing production, you must create 

it, configure it, and integrate it into the production. This topic explains each step. 

2.9.1 Creating an HL7 Business Operation 

To send HL7 messages outside Ensemble, you must add an HL7 business operation to the production 

configuration. Ensemble provides built-in business operations that take care of these tasks over TCP, 

File, FTP, and HTTP connections. Generally, you will choose one of these built-in business operations 

rather than write your own. 

For your convenience in working with HL7 productions, two simple business operations are also built 

into Ensemble: EnsLib.File.PassthroughOperation and EnsLib.FTP.PassthroughOperation. You can 

choose either of these business operations if you simply need to send a file out from the HL7 routing 

production, and do not want to parse or format it in any special way. 


Additionally, you might want to send data outside Ensemble that is not an HL7 message. This can be 

accomplished by creating a business operation class that communicates with an adapter as described 

in Developing Ensemble Productions and in each of the Ensemble Adapter Guides. 

To add a business operation to an HL7 routing production: 


2. Add an FTP, File, or TCP business operation for HL7 as follows: 

• Start the Business Operation Wizard in one of the following ways: 

HL7 Business Operations 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Operation. 




Click Add Operation. 


Operation. 

• Choose HL7 Output. 


- Choose TCP, File, or FTP to determine the host class. Each class already exists and requires 

no programming. Simply choose one. 



3. Add other types of HL7 business operation as follows: 

• Start the Business Operation Wizard in one of the following ways: 

- On the [Ensemble] > [Productions] > [Production Model] page, click Add Business Operation. 




Click Add Operation. 


Operation. 





- Choose the host class. Each class already exists and requires no programming. Choices 

include: 

• EnsLib.File.PassthroughOperation 

• EnsLib.FTP.PassthroughOperation 

• EnsLib.HL7.Operation.HTTPOperation 

• EnsLib.HL7.Operation.HTTPAckOutOperation 

• EnsLib.HL7.Operation.TCPAckOutOperation 

• Any other business operation class in the namespace 



4. To add a business operation of any type, by copying another business operation: 


• Select the business operation in the diagram. 


• Enter a unique name and click OK. Your new business operation appears in the diagram 


name is different. You must make the new copy different by configuring it. 

Note: 

The Copy button works only within the same production. You cannot copy a business 

operation from one production to another. 

2.9.2 Configuring an HL7 Business Operation 

You can configure an HL7 business operation by clicking on it while viewing the configuration diagram 

on the [Ensemble] > [Productions] page. The following fields display below the diagram; you can edit 

these fields to configure the routing process. 

Note: 




You may configure an HL7 business operation by entering values in the following fields. When you 

are done editing, click Apply to save your changes, or Cancel to ignore them. 

• General Settings — This column of settings appears at left. These are settings that configure the 

HL7 business operation as a production item. The most important of these for HL7 are as follows. 

For descriptions of the other General Settings, see the section “Business Operation Settings” in 

“The Configuration Page” chapter of Managing Ensemble Productions. 

- PoolSize — The default PoolSize value of 1 ensure FIFO (First In, First Out) processing. 

FIFO processing is important to ensure correct data in the receiving applications. Multiple 

patient demographic updates must be received in order; otherwise, obsolete, incorrect data 

may appear in the receiving application. Also, many applications require receipt of an ADT 

Registration message before they can process an Order message, an Order message must be 

received before a Result message, and so on. 

- FailureTimeout — The number of seconds during which to continue retry attempts. After this 

number of seconds has elapsed, the business operation gives up and returns an error code. 

HL7 business operations automatically set this value to –1 for “never time out” to ensure that 

no HL7 message is skipped. 

- Category — This text label permits configuration items to be sorted in the configuration diagram. 

For example, you can assign the same Category name to all items in the same interface. 

You may enter multiple category names separated by commas. Space characters count (do 

not use them around the commas). 

• Specific Settings — This column of settings appears at right. The column is organized into settings 

that configure the HL7 business operation (at top) and settings that configure its associated adapter 

(at bottom). The specific settings will be different depending on which HL7 business operation 

you are configuring, and which adapter that business operation is using. The following list describes 

how to configure the most important of these settings. For details about which class provides 

which settings, see the “HL7 Business Operation Classes” section in the chapter “Settings for 

a Routing Production.” 

The Specific Settings for an HL7 business operation are as follows: 

Adapter Class 

Alert On Error 

Identifies the TCP, File, or FTP outbound adapter for HL7. 


If True, the HL7 business operation automatically triggers an alert upon encountering errors 

connecting with its external target. See the “Pager and Email Alerts” section in this chapter. 



Alert Retry Grace Period 

Archive IO 

Business operations can be configured with an Alert Retry Grace Period during which errors 

relating to external connections do not trigger alerts, even if Alert On Error is True. This grace 

period accommodates a business operation that attempts an external connection with a configured 

Retry Interval and Failure Timeout. During its retry sequence, the business operation 

may encounter connection failures that become unimportant after one of its retry attempts 

succeeds. Thus, if a business operation first encounters an error, but later achieves success 

within the time allotted by the Alert Retry Grace Period, no alert is triggered even though an 

error occurred. Setting Alert Retry Grace Period to 0 disables this feature for the business 

operation. 

If True, the adapter associated with this business operation will log in the Ensemble I/O 

archive each input and output communication it shares with the external system. See the 

section “Working with the I/O Archive” in the “What to Manage” chapter of Managing 

Ensemble Productions. 

AutoBatchParentSegs 

(File and FTP only) If True, when writing a message that has a batch parent, output the batch 

headers first, then child documents, then follow up with the batch trailers when triggered by 

the final batch header message or by a file name change. If False, omit headers and trailers 

and output child documents only. The default is False. 

For more about batch handling, see the “HL7 Batch Messages” section in the chapter 

“Settings for a Routing Production.” 

DefCharEncoding 

File Name 

The default character encoding to use when reading or writing HL7 messages. If any incoming 

HL7 message has an empty MSH:18 (Character Set) field, Ensemble uses the DefCharEncoding 

value in its place. Supported values are UTF-8 or any member of the Latinn family. The 

value Native means to use the native default encoding installed on the Ensemble server. 

The default value for DefCharEncoding is Latin1. Placing a ! (exclamation point) character 

at the beginning of the encoding name forces Ensemble to use the DefCharEncoding value 

and ignore any value found in MSH:18. For example: !UTF-8 

(File and FTP only) The target file name. The File Path adapter setting determines the path 

for this file; File Name determines the name. File Name can include Ensemble time stamp 

specifiers. If you leave File Name blank, the default uses the time stamp specifier %f_%Q 

where: 

• %f is the name of the data source, in this case the input filename 


• _ is the literal underscore character, which will appear in the output filename 

• %Q indicates ODBC format date and time 


In substituting a value for the format code %f, Ensemble strips out any of the characters 

|,,\,/,:,[,],,&,,,;,NUL,BEL,TAB,CR,LF, replacing spaces with underbars (_) and slashes 

(/) with hyphens (-). When the output file is being saved on an OpenVMS system, Ensemble 

replaces colons with hyphens (-). Otherwise, colons (:) become dots (.). 

For full details about time stamp conventions, including a variety of codes you can use instead 

of the default %f_%Q, see the section “Time Stamps in Filenames” in the “Creating a New 

Production” chapter of Developing Ensemble Productions. 

Framing 

Controls how the HL7 business operation constructs the outgoing HL7 message packet. For 

a list of framing options, see the “HL7 Message Framing Types” section in the chapter 

“Settings for a Routing Production.” If you are unsure what value to use, accept the default 

of MLLP framing for HL7 business operations. 

NoFailWhileDisconnected 

(TCP only) If True, suspend counting seconds toward the Failure Timeout while disconnected 

from the TCP server. The NoFailWhileDisconnected setting does not apply if Failure Timeout 

is –1 or if StayConnected is 0. 

PartnerAckTimeout 

(TCPAckOut or HTTPAckOut only) The EnsLib.HL7.Operation.TCPAckOutOperation is a specialized 

HL7 TCP business operation that sends ACKs on behalf of a paired HL7 TCP business 

service. There is also an EnsLib.HL7.Operation.HTTPAckOutOperation. For details, see the 

“Dual Acknowledgement Sequences” section in the chapter “Settings for a Routing Production.” 

When EnsLib.HL7.Operation.TCPAckOutOperation or 

EnsLib.HL7.Operation.HTTPAckOutOperation is the business operation class, PartnerAckTimeout 

tells the business operation the number of seconds to wait for its partner business service to 

supply an ACK that corresponds to the normal outbound message that the business operation 

sent. The default PartnerAckTimeout is 600 seconds (10 minutes). 

ReplyCodeActions 

(TCP only) When the adapter setting Get Reply is True, ReplyCodeActions allows you to 

supply a comma-separated list of code-action pairs, specifying which action the business 

operation will take on receipt of various types of ACK response messages. The format of the 

list is: 



Retry Interval 

code=action,code=action, ... code=action 

For possible code and action values, see the “HL7 Acknowledgement (ACK) Mode” section 

in the chapter “Settings for a Routing Production.” 

Number of seconds to wait between attempts to connect with a destination outside Ensemble. 

Search Table Class 

Separators 

The package and class name of a search table class that you have defined in this Ensemble 

namespace. A search table class is a specialized tool that you can create to work with virtual 

documents, such as HL7 messages. A virtual document is efficient because it contains a large 

amount of raw data but no instantiated properties. Creating a search table enables Ensemble 

to efficiently index a few of the fields in a virtual document so that these fields are available 

to be searched as if they were properties in a standard message body. 

To create a search table class, see the “HL7 Search Tables” section in this chapter. For further 

background information, see the book Ensemble Virtual Documents. 

HL7 separator characters to use in the outgoing message. If you leave this field blank, the 

default is: 

|^~\& 

For further details, see “HL7 Separator Characters” in the “Literal String Syntax” section 

in the chapter “Syntax for a Routing Production.” 

The remaining entries in the Specific Settings column are determined by the type of adapter: FTP, File, 

TCP, or HTTP. The following adapter settings are especially important for HL7 business operations: 

Reconnect Retry 

(TCP only) Number of retries at which to drop the connection and try reconnecting again. A 

value of 0 (zero) means never disconnect. The default is 5. 

StayConnected 

A zero value means to disconnect immediately after every input event. The default of –1 

means to stay permanently connected, even during idle times. Adapters are assumed idle at 

startup and therefore only auto-connect if they are configured with a StayConnected value of 

–1. The only StayConnected values that are useful in the normal case are 0 and –1. However, 

StayConnected can also be a positive number. If the StayConnected time is longer than the 

CallInterval, the adapter stays connected all the time. If the StayConnected time is shorter than 

the CallInterval, the adapter disconnects and reconnects at each CallInterval. 


Pager and Email Alerts 

For further information about any setting, hovering the cursor over the setting name, or consult these 

references: 

• “Adapter Settings” in the “FTP Outbound Adapter” chapter of Using FTP Adapters with 

Ensemble 

• “Adapter Settings” in the “File Outbound Adapter” chapter of Using File Adapters with 


• “Adapter Settings” in the “TCP Outbound Adapter” chapter of Using TCP Adapters with 

Ensemble, which describes the settings for the general-purpose TCP outbound adapter. The difference 

for the special-purpose adapter called EnsLib.HL7.Adapter.TCPOutboundAdapter is that it 

has the following settings configured appropriately for HL7: 

- GetReply is set to True. This means the adapter will wait to read a reply message back from 

the socket before returning. 

- ConnectTimeout has its usual default of 5 seconds, but has a maximum limit of 30,000 seconds. 

- ResponseTimeout has a default of 30 instead of its usual 15, and has a maximum limit of 

30,000 seconds. 

• The “Using the HTTP Outbound Adapter” chapter in Using HTTP Adapters with Ensemble 

2.9.3 Integrating an HL7 Business Operation 

To integrate a new HL7 business operation into an Ensemble production, simply identify it as a target 

that receives messages. To do this, you must configure the item that sends messages to the HL7 business 

operation and enter the configured Name of the HL7 business operation into the appropriate field: 

• For a routing interface, enter the name in the Target field of the routing rule set. 

• If your design uses a pass-through interface that simply relays messages from the incoming business 

service to the outgoing business operation, enter the name in the TargetConfigNames field of the 

HL7 business service. 

2.10 Pager and Email Alerts 

Alerts provide the ability to send notification to a user device while an Ensemble production is running. 

The intention is to alert a system administrator or service technician to the presence of a problem. 

Alerts may be sent via email, text pager, or another mechanism. Alerts may be sent using: 

• The SendAlert method from Caché Basic or ObjectScript code 

• The element from a BPL business process 



• The Alert On Error setting to enable automatic alerts from business hosts 

All alert messages are automatically written to the Ensemble event log as entries of type Alert. However, 

the real purpose of an alert is to contact an external entity, such as a human user (via email or page) 

or a management tool (via WMI or SNMP). A production does this by directing all alert messages to 

a configuration item called Ens.Alert, which has been set up with all the information necessary to 

contact user devices outside Ensemble. For details, see the section “Alerts” in the “Ensemble Productions” 

chapter of Developing Ensemble Productions. 

The starter HL7 routing production provides the following elements to support alerts: 

• Ens.Alert — The starter HL7 routing production provides a built-in Ens.Alert element. This 

Ens.Alert is a routing process with an associated routing rule set called AlertRule. 

You can configure AlertRule to route alert messages to different business operations depending 

on the source of the alert message (that is, which element is in trouble) and various conditions 

(such as time of day). 

Tip: 

To view time-of-day function examples, start Studio and change to the ENSDEMO 

namespace. Look at the sample functions in the class Demo.HL7.MsgRouter.Functions. 

To configure AlertRule, follow a similar procedure to the one for HL7 routing rule sets, except: 

- For the Message Class, choose Ens.AlertRequest 

- In the Target field, choose or type the configured name of an email business operation. 

• PagerAlert and EmailAlert — These are ordinary email operations that can be configured to send 

a text message (such as the body of an alert) to a pager or email address. PagerAlert and EmailAlert 

are initially identical, other than their names. Both are provided to emphasize the fact that alerts 

have different priorities. Generally the higher-priority alerts go to a pager, lower-priority to email. 

You can configure any number of destinations that copy these starter operations. At runtime, your 

AlertRule routing rule set determines which destination is appropriate to use. 

2.11 HL7 Search Tables 

In writing a search table class, your goal is to provide one search table entry for each virtual property 

that you want to search and filter in the Message Browser, Rules Editor, and other parts of the 

Ensemble Management Portal. 

The built-in search table class EnsLib.HL7.SearchTable already provides entries for popular HL7 

properties. When you choose EnsLib.HL7.SearchTable as your search table class, it enables Ensemble 

to search HL7 messages for the following virtual properties. 


HL7 Search Tables 

Built-in Search Table Entries for HL7 

Choose... 

MSHTypeName 

To refer to this value... 

The message structure name. To construct this string, Ensemble concatenates 

the following values from the HL7 message: 

• The MSH message header segment 

Field 9 (message type) 

Subfield 1 (message type: ADT, ORM, etc) 

• The literal character _ 


Field 9 (message type) 

Subfield 2 (trigger event: A01, A12, O01_2, etc) 

The result is a message structure name in the format ADT_A01, 

ADT_A12, ORM_O01_2, etc. 

MSHControlID 

The unique identifying number for this message. Ensemble retrieves 

this value from: 


Field 10 (message control ID) 

Ensemble interprets this value as a case-sensitive string. 



Choose... 

PatientID 

To refer to this value... 

The patient identifier for this message. This is a field whose location 

has shifted as the HL7 standard has evolved. For this reason, Ensemble 

looks for this value in all of the following locations. That way, the patient 

identifier can be found regardless of which HL7 schema category the 

message conforms to: 

• The PID patient identifier segment 

Field 2 (patient external identifier) 

Subfield 1 (patient identifier) 


Field 3 (patient identifier list), all entries in the list 



Field 4 (patient identifier list), all entries in the list 


PatientName 

PatientAcct 

The PID patient identifier segment 

Field 5 (patient name) 

The PID patient identifier segment 

Field 18 (patient account number) 

Subfield 1 (ID) 

If you need more than this minimal list of virtual properties, you may subclass EnsLib.HL7.SearchTable 

to create new search table classes. Any subclass of EnsLib.HL7.SearchTable inherits the entries described 

in the previous table, plus the infrastructure that makes search tables work. 

To create a new search table class for your message routing production: 

1. Start Studio and choose an Ensemble-enabled user namespace. 

Important: 



time you upgrade Ensemble. Any new namespace that you create to hold your 

work is preserved across Ensemble upgrades. 

2. Choose File, then New. A dialog pops up. Edit it as follows: 


• Click on the General tab. Select the Caché Class Definition icon and click OK. 

• Enter a package and class name and click Next. 


Important: 

InterSystems recommends that you do not use the package names Demo, 

Ens, EnsLib, EnsPortal, or CSPX. This causes your work to be deleted the 

next time you upgrade Ensemble. 

• For Class type, choose Extends. 

• Beside the Name of super class field, click the Browse button. Choose the EnsLib package 

and under HL7, choose SearchTable. Click OK. 

• Click Finish. 

The result is a template class like the following: 

Class Susan.Test.NewClass2 

Extends EnsLib.HL7.SearchTable 

{ 

} 

3. Position the cursor in the line between the curly brackets and select Class, then Add, then New 

XData. A dialog pops up. 

When prompted to enter a name, type: 

SearchSpec 

Click Finish. The result is a template XData SearchSpec block: 



{ 

XData SearchSpec 

} 

{ 

} 

4. Place an empty container inside the XData SearchSpec block: 



{ 


} 

{ 

 

 

} 

5. Now you may add entries inside the container. 

The XData SearchSpec block lists the virtual properties whose values you want users to be able to 

search. 



The following code excerpt shows the XData SearchSpec block that defines the entries in 

EnsLib.HL7.SearchTable. These are the entries described in the previous table, “Built-in Search Table 

Entries for HL7.” You do not need to repeat any of these entries in your search table subclass, because 

it inherits them from EnsLib.HL7.SearchTable: 


{ 

 

{1:9.1}_"_"_{1:9.2} 

{1:10} 

[PID:2.1] 

[PID:3().1] 

[PID:4().1] 

[PID:5] 

[PID:18.1] 

 

} 

As you can see from the above example, an XData SearchSpec block contains one block, 

which may contain one or more elements. Each element contains a string expression, 

such as {1:10} in the above example. This string expression may include the following components 

in any combination: 

• Literal characters within double quotes. 

• Virtual property syntax within {} or []. This resolves to the value of the specified field in the HL7 

message. Square brackets differ from curly brackets in that square brackets enclose a segment:field 

combination that does not require you to identify its containing message structure. 

• ObjectScript string operators, such as the underscore (_) for concatenation. 

• ObjectScript string functions, such as $PIECE or $EXTRACT. 

The following example consists of one virtual property path that uses {} syntax. This element 

refers to the value at Segment 1, Field 10 of the HL7 message: 

 

{1:10} 

 

The following more complex element uses the ObjectScript _ operator to concatenate three 

strings. From left to right, these are: 

• The value within Segment 1, Field 4 

• A literal | character 

• The value within Segment 1, Field 3 



 

{1:4}_"|"_{1:3} 

 

The following example uses most of the possible syntax options: concatenation, virtual properties, 

a literal hyphen character (-), and the ObjectScript string function $PIECE: 


{ 

 

 

$P( 

{ORCgrp(1).OBRuniongrp.OBRunion.OBR:UniversalServiceID.text},"-",1,2 

)_"-"_{MSH:12} 

 

} 

The element has the following attributes. 

Attributes for the Element in Search Tables 

Attribute 

DocType 

Description 

Required. A valid schema category name 

and message structure name, separated 

by a colon. If the category is missing, any 

schema is matched; if the structure is 

missing; any structure is matched. A value 

of "" (a blank string) matches any schema 

category and any message structure, as in 

the example above. For valid DocType 

strings, see “The DocType Property” in 

the “HL7 Message Class” section of the 

chapter “Syntax for a Routing Production.” 

Value 

A string that includes any of 

the following combinations: 

• "category:structure" 

• "category:" 

• ":structure" 

• "" 



Attribute 

PropName 

PropType 

Description 

Required. An arbitrary name that you wish 

to assign to this virtual property. This is the 

name that Ensemble will present for you to 

select from a list when configuring the 

Message Browser, Rules Editor, and other 

parts of the Ensemble Management Portal. 

If you assign the same PropName to different 

elements, this has an additive 

effect: When the user selects this 

PropName for a search, all of the entries 

with the same PropName are searched. 

The built-in search table entry PatientID 

uses this convention. 

Optional. All fields are assumed to be 

case-insensitive strings unless you specify 

a PropType value. If your data type is a 

case-insensitive string, you may omit 

PropType. 

Value 

Any string that you expect to 

be unique and meaningful, 

when viewed with others in 

the list. 

The PropType may be one of 

the following literal strings: 

• String:CaseSensitive 

• String:CaseInsensitive 

• Integer 

• Numeric 

• Boolean 

• DateTime:ODBC 

• DateTime:HL7 

StoreNulls 

Optional. Controls what happens when a 

search encounters an empty field in the 

HL7 message. If true, the search returns a 

valid pointer to an empty string. If false, it 

returns a Not Found status and a null 

pointer. 

A Boolean value: 1 (true) or 0 

(false).The default is 0 (false). 

The following sample search table class provides several examples of valid entries. This class 

inherits from EnsLib.HL7.SearchTable, as is required for HL7 search tables. Comments above each 

group of entries describe the purpose of that set of entries. For details about {} or [] syntax, 

see the “Virtual Property Syntax” section in the chapter “Syntax for a Routing Production.” 

Class Demo.HL7.MsgRouter.SearchTable 

Extends EnsLib.HL7.SearchTable [ ClassType = persistent, ProcedureBlock ] 

{ 




{ 

 

 

{1:4}_"|"_{1:3} 

{1:6}_"|"_{1:5} 

{1:7} 

 

[PID:5] 

[IN1:4] 

 

{3:5} 

 

 

 

 

{ORCgrp().OBRuniongrp.OBRunion.OBR:UniversalServiceID.text} 

 

 

{PIDgrpgrp().ORCgrp(1).OBR:UniversalServiceID.text} 

 

 

} 

} 


3 

Settings for a Routing Production 

This chapter explains the details of important configuration settings within an HL7 message routing 

production. Topics include: 

• HL7 Message Validation and Bad Messages 

• HL7 Acknowledgement (ACK) Mode 

• HL7 Dual Acknowledgement Sequences 

• HL7 Message Framing Types 

• HL7 Batch Messages 

• HL7 Business Service Classes 

• HL7 Business Operation Classes 

3.1 HL7 Message Validation and Bad Messages 

When a routing process receives an incoming HL7 message from its associated HL7 business service, 

it may or may not perform message validation before attempting to route the message. This topic 

describes the cascading list of conventions that Ensemble uses to validate a message. 

• Any message that is labeled a bad message during this sequence is routed to a bad message handler 

rather than to its usual destination. 

• Any message that survives this cascade without being declared a bad message is validated. The 

routing process sends a validated message to its usual destination. This could happen even if the 

message is not perfect, as long as you disable certain tests. For example, frequently you want to 

allow messages with “extra” segments such as Z-segments. 



An HL7 routing process has a configuration setting called Validation that controls the validation 

sequence. The following table lists the possible values for the Validation string: 

Values for the Validation Setting 

Value 

dm-z 

1 

(a blank string) 

Other combinations of 

the flags d, m, z, or –z 

Meaning 

This is the default setting. See the discussions of d, m, and z. 

Same as dm-z, for backward compatibility with previous 

releases. 

The routing process skips validation and routes all messages. 

Enables or disables various steps in the validation cascade. 

The flags may appear in any combination, except that z and 

–z are mutually exclusive, and m includes z, so m is the same 

as mz. 

The message validation sequence is as follows. If a flag is not present in the string, its associated step 

is disabled: 

1. Test for issues controlled by d (if present). 

2. Test for issues controlled by m (if present). Exclude issues controlled by z (if –z is present). 

3. Test for issues controlled by z (if z is present without m). 

If at any time during this cascade the message fails validation, the HL7 routing process passes the 

message to its bad message handler (if present). If there is no bad message handler, the routing process 

simply stops the validation sequence without routing the message. On the other hand, any message 

that does not explicitly fail validation is allowed through. You can use the various options to control 

how many tests you want applied by each HL7 routing process. 

3.1.1 The d Validation Flag 

If the d flag is present in the Validation string, validation examines the Message Schema Category 

defined in the HL7 business service and compares it with the message DocType. If the Message Schema 

Category in the business service configuration is blank, the message is automatically declared bad. 

However, if Message Schema Category is not blank, but does not match the message DocType, validation 

can continue, as long as there are more Validation flags defined, such as m or z. 

3.1.2 The m Validation Flag 

If the m flag is present in the Validation string, validation searches for a way to either validate the 

message, or declare it bad, by cascading through the following tests: 


1. In the DTL data transformation, the element has a sourceDocType attribute. If different 

from the Message Schema Category setting, the sourceDocType is used. 

2. If Message Schema Category is a standard category such as 2.3.1, the inbound message MSH:9 

value is matched against a message type defined in that HL7 Category. For example, if the Message 

Schema Category is 2.3.1 and the MSH:9 value in the message is ORU;R01 the message is verified 

against the ORU_R01 message type under the 2.3.1 category. If the message data is missing some 

required segments or fields, or if it has extra undefined segments or fields, as compared to the 

2.3.1 ORU_R01, then it is a bad message. Z segments may be an exception, depending on the 

presence or absence of the m, z, or -z flags. 

3. If the Message Schema Category is a custom schema (defined in Studio with a .HL7 extension), 

the same rules apply as in Step 4, except that the message is verified against the custom definition. 

Each custom schema has a base category defined (for example base="2.3.1"). If a message 

arrives that is not explicitly defined in the custom schema, the base category is used. 

In order to avoid a specious bad message condition, a custom schema is necessary when MSH:9 

does not contain a standard value. For example, if MSH 9 is just ORU instead of ORU^R01 a custom 

schema is required to specify that the message name ORU needs to be verified against the structure 

ORU_R01. 

The m flag also performs all the validation performed as a result of the z flag, unless the -z flag is 

present to stop this. Thus, m is the same as mz, and dm is the same as dmz. For example, the default 

Validation setting is dm-z, which includes d and m but excludes the validation indicated by z. 

3.1.3 The z Validation Flag 

HL7 Message Validation and Bad Messages 

If the z flag is present in the Validation string, or if the m flag is present without the -z flag, there may 

be error conditions relating to extra segments found in an incoming message. “Extra” segments are 

segments within the message data that parse reasonably well as HL7 message segments, but do not 

match the structure of the message as defined in the schema. These may be Z segments, or non-Z 

segments. Ensemble determines whether or not to declare bad message status based on extra segments 

as follows: 

• If the message contains extra Z segments, and the schema defines those Z segments, the message 

is accepted. 

• If the message contains extra trailing Z segments when the schema does not define any Z segments, 

the message is accepted. However, extra Z segments in the middle of the message are not accepted. 

• If the message contains extra Z segments, and the schema defines Z segments, but the Z segments 

found in the message do not match the Z segments defined in the schema, it is a bad message. 

• If the message contains extra non-Z segments, then regardless of Z segments, it is a bad message. 



3.1.4 Bad Message Handlers 

If the message is bad, and if the HL7 routing process has a configured Bad Message Handler, it sends 

the bad message to this business operation instead of its usual target for validated messages. 

For example, the starter HL7 message routing production is configured with a file business operation 

called BadMessageHandler. When this business operation is configured as the Bad Message Handler 

for an HL7 routing process, the BadMessageHandler handles any bad messages it receives as follows: 

• It writes the contents of the message to the output File Path and File Name defined in its configuration 

settings. The File Name can include time stamp specifiers. For details, see the section “Time 

Stamps in Filenames” in the “Creating a New Production” chapter of Developing Ensemble 

Productions. 

• If the configuration setting Alert On Error is True, the business operation automatically triggers 

an alert whenever it encounters a bad message. 

3.1.5 Overriding the Validation Sequence 

The normal range of Validation options might not provide the type of validation that you need. If this 

is the case, you can subclass EnsLib.HL7.MsgRouter.RoutingEngine and override the OnValidate 

method in the subclass. Then, when adding a routing process, choose the subclass as your base class 

rather than the default EnsLib.HL7.MsgRouter.RoutingEngine. 

Subclassing EnsLib.HL7.MsgRouter.RoutingEngine to override OnValidate allows you to: 

• Extend or replace the list of accepted values for the Validation setting. 

• Determine how the routing process will validate messages, as controlled by your own Validation 

options. 

Whenever you override the OnValidate method, you must also override the Validation property definition 

in the same subclass. Pay careful attention to the following details: 

• Its InitialExpression value. This sets the default for the Validation configuration setting. 

• The comments that precede the Validation property definition. Use the /// convention and leave 

no white space lines between the last comment line and the property definition. This allows 

Ensemble Management Portal users to view your comments as hover-text help for the Validation 

setting. 

As an example, the following excerpt shows some of the comments that appear with the Validation 

property definition in the EnsLib.HL7.MsgRouter.RoutingEngine class: 


HL7 Acknowledgement (ACK) Mode 

/// 'd' - require DocType 

/// 'm' - don't tolerate BuildMap errors (includes 'z' by default; 

/// specify '-z' to tolerate unrecognized trailing Z-segments) 

/// 'z' - don't tolerate unrecognized trailing Z-segments 

Property Validation As %String(MAXLEN = 20) 

[ InitialExpression = "dm-z", Transient ]; 

3.2 HL7 Acknowledgement (ACK) Mode 

An HL7 acknowledgement (ACK) message acknowledges that a destination has received an HL7 

message. A negative ACK (NACK) message acknowledges that the destination is aware of the transmission 

but did not capture the message. 

The following figure illustrates how Ensemble upholds HL7 message conventions for sending of ACK 

and NACK messages: 

• Commit ACK — The Ensemble business service returns an ACK to the source application as 

soon as it commits the transaction that saves the data received from that source. It sends a NACK 

if this proves impossible for some reason. The Ensemble business operation may be set up to 

interpret an ACK or NACK from the target application, but it does not return those messages to 

the source. 

• Application ACK — The Ensemble business service does not send an ACK or NACK to the 

source application until one returns from the target application by way of the Ensemble business 

operation. The business service returns the ACK or NACK that it receives from the business 

operation. 

• Commit and Application ACK — Both of the above. The Ensemble business service returns an 

ACK upon transaction commit. It also subsequently returns the ACK or NACK that the Ensemble 

business operation returns from the target application. 



HL7 Message Acknowledgement (ACK) Types 

Any of these acknowledgement conventions can be used to send one of the three main types of ACK 

message content: 

• Accept — The message arrived, and was accepted. 

• Reject — The message arrived, but has been rejected. 

• Error — The message did not arrive successfully; try again. 



3.2.1 The AckMode Setting 

HL7 business services have an AckMode setting that can have one of the following values. 

Acknowledgement (ACK) Modes for HL7 Business Services 

AckMode 

Never 

Immediate 

Application 

MSH-determined 

Meaning 

Do not send back any ACK. 

Return a Commit ACK reply message immediately upon receipt of 

the inbound message. This is the default if nothing is specified. 

If message passes validation, wait for the ACK reply message from 

the target application and return this ACK when it arrives. 

Return ACK reply messages as requested in the MSH header fields 

15 and 16. Either field may contain one of the following four control 

codes: 

• AL — Always 

• NE — Never 

• ER — Error or reject conditions only 

• SU — Successful completion only 

MSH 15 (AcceptAcknowledgementType) controls Commit ACK. MSH 

16 (ApplicationAcknowledgementType) controls Application ACK. 

Depending on how they are set in the incoming message MSH segment, 

one, both or neither may occur. 

Byte 

Send back a single ACK-code byte instead of an ACK message, 

immediately upon receipt of the inbound message. ASCII 6 means 

OK; ASCII 21 means Error. This option is not available for any of the 

built-in HL7 business services (TCP, File, HTTP, and so on) but it is 

available if you write a custom business service that subclasses 

EnsLib.HL7.Service.Standard without overriding the AckMode setting. 

3.2.2 The UseAckCommitCodes Setting 

HL7 business services have a UseAckCommitCodes setting that applies if the Message Schema Category 

is 2.3 or higher. UseAckCommitCodes may be True or False. If True, when constructing an ACK 

message for HL7 messages version 2.3 or higher, the business service places one of the “enhanced- 



mode” ACK commit codes in the MSA segment AcknowledgmentCode field. This code may be one 

of the following two-letter sequences: 

Enhanced-Mode ACK Commit Codes for HL7 2.3 and Higher 

Code 

AA 

AE 

AR 

CA 

CE 

CR 

Meaning in Original Mode 

Application Accept 

Application Error 

Application Reject 

— 

— 

— 

Meaning in Enhanced Mode 

Application acknowledgment: Accept 

Application acknowledgment: Error 

Application acknowledgment: Reject 

Accept acknowledgment: Commit Accept 

Accept acknowledgment: Commit Error 

Accept acknowledgment: Commit Reject 

3.2.3 The IgnoreInboundAck Setting 

Setting IgnoreInboundAck to True causes a business service to ignore any inbound ACK messages to 

avoid creating an ACK feedback loop. 

3.2.4 The AckTargetConfigNames Setting 

Unlike TCP business services, File and FTP business services have no persistent connection on which 

to send ACK messages. For this reason, the default AckMode for File and FTP business services is 

Never, which is usually appropriate. However, when you do want to send ACKs from a File or FTP 

business service, use the AckTargetConfigNames setting to identify an Ensemble routing process or 

business operation that will receive the ACK messages. 

3.2.5 The GetReply Setting 

For TCP business operations only, if the adapter setting GetReply setting is True, the business operation 

waits to read an ACK or other reply message back from the socket before returning. It also applies 

any ReplyCodeActions that have been defined. 

3.2.6 The ReplyCodeActions Setting 

For TCP business operations only, if the adapter setting Get Reply is True, ReplyCodeActions allows 

you to supply a comma-separated list of code-action pairs, specifying which action the business operation 

will take on receipt of various types of response messages. The format of the list is: 

code=action,code=action, ... code=action 


Where code represents a literal value found in the MSA:1 (Acknowledgement Code) field of the 

response message, or one of the following special code values: 

Code Values for Reply Code Actions 


Code 

A 

E 

R 

~ 

_ 

* 

I 

T 

Meaning 

Matches AA or CA values (Accept) 

Matches AE or CE values (Error) 

Matches AR or CR values (Reject) 

The tilde character matches replies that do not contain an MSA segment 

The underscore character matches replies with an empty MSA:1 field. An empty 

or whitespace code value is the same as _ 

The asterisk character matches any MSA:1 value not matched otherwise 

(default=F) 

Matches where the reply MSA:2 ControlId does not match the ControlId of the 

original message 

Matches where the reply MSH:9 Type name does not match the schema’s 

declared reply type for the original message 

The following values for action may be used alone or combined to form strings. F is the default action 

if no other is given, except for A whose default action is C: 

Action Values for Reply Code Actions 

Action 

C 

W 

R 

S 

D 

F 

Meaning 

Treat the message as Completed OK. 

Log a warning but treat the message as Completed OK. 

Retry the message according to the configured RetryInterval and 

FailureTimeout; finally Fail unless a different action is also specified 

Suspend the message, log an error, and move on to try the next message 

Disable the Operation, log an error and restore the outbound message to the 

front of the Operation’s queue 

Fail with an error and move on to try the next message 

The default value for ReplyCodeActions is: 

R=RF,E=S,~=S,I=W,T=C 



This means that NACKs received with error code AR or CR retry, while codes AE or CE suspend the 

outbound message and move on to the next. 

3.2.7 The AddNackERR Setting 

If the AddNackERR setting is True, add ERR error code segment when generating NACK messages; 

otherwise do not embed internal error state information in NACK messages. 

3.3 HL7 Dual Acknowledgement Sequences 

Some systems require a dual acknowledgement sequence from Ensemble: an immediate 1–byte ACK, 

followed later by the full ACK message. One such system is the dual-channel iSoft iCM application. 

If your configuration includes a client system such as iCM that requires a dual acknowledgement 

sequence, you must set up a paired business service and business operation to enable Ensemble to 

provide the expected ACKs. Ensemble supports a dual acknowledgement sequence over TCP and 

HTTP. 

EnsLib.HL7.Service.TCPAckInService is a specialized HL7 business service that receives ACKs on 

behalf of a paired HL7 TCP business operation. It also depends on this partner to send ACKs on its 

behalf. EnsLib.HL7.Operation.TCPAckOutOperation is a specialized HL7 TCP business operation that 

sends out ACKs on behalf of a paired HL7 TCP business service. It also depends on this partner to 

collect ACKs on its behalf. Each of these configuration items plays its usual role in addition to the 

work it does for its partner item. 

An EnsLib.HL7.Service.HTTPAckInService and EnsLib.HL7.Operation.HTTPAckOutOperation are also 

available. 

3.3.1 Dual ACK Sequence for Incoming Messages 

For messages entering Ensemble, the dual acknowledgement sequence works as shown in the following 

figure: 

1. The client application sends a message into Ensemble. 

2. The inbound ACK business service sends an immediate 1–byte ACK to the client application. 

3. The inbound ACK business service sends the message to its routing process. 

4. The routing process routes the message to its target via a business operation. 

5. The target application returns an ACK message to the business operation. 

6. Ensemble relays the ACK to the inbound ACK business service. 

7. The business service relays the ACK to its paired business operation. 


HL7 Dual Acknowledgement Sequences 

8. The business operation relays the ACK to the client application. 

9. The client application acknowledges the ACK message by returning a 1–byte ACK. 

Paired Business Service and Business Operation for Incoming Dual ACK 

3.3.2 Dual ACK Sequence for Outgoing Messages 

For messages leaving Ensemble, the dual acknowledgement sequence works as shown in the following 

figure: 

1. A business service sends a message to its routing process. 



2. The routing process routes the message to the outbound ACK business operation. 

3. The outbound ACK business operation relays the message to the target application. 

4. The target application acknowledges the message by returning a 1–byte ACK. 

5. The target application returns an ACK message to the inbound ACK business service. 

6. The business service sends an immediate 1–byte ACK to the target application. 

7. The business service relays the ACK to its paired business operation. 

8. The business operation relays the ACK message back to the business service. 

9. The business service receives the ACK to its original message. 


HL7 Dual Acknowledgement Sequences 

Paired Business Service and Business Operation for Outgoing Dual ACK 

3.3.3 Configuring a Dual ACK Sequence 

To configure an Ensemble routing production to use the dual acknowledgement feature: 

1. Add a business service to the production. 

Choose EnsLib.HL7.Service.TCPAckInService or EnsLib.HL7.Service.HTTPAckInService as the 

business service class. It is not one of the standard HL7 Input options available from the Business 

Service Wizard, but you can choose it by selecting the Other option and identifying the class. 



2. Add a business operation to the production. 

Choose EnsLib.HL7.Operation.TCPAckOutOperation or EnsLib.HL7.Service.HTTPAckOutOperation 

as the business operation class. It is not one of the standard HL7 Output options available from the 

Business Operation Wizard, but you can choose it by selecting the Other option and identifying 

the class. 

3. When configuring the business service: 

• Set ImmediateByteAck to True. Then, in addition to forwarding a full ACK message according 

to the AckMode setting, the business service also returns an immediate 1-byte ACK on its 

TCP or HTTP connection. 

• For a PartnerOperation choose the business operation that you added in Step 2. Whenever 

you specify a PartnerOperation value, the business service ignores any inbound ACK messages 

that it receives directly, to avoid creating an ACK feedback loop. 

4. When configuring the business operation: 

• Identify a PartnerAckTimeout. This value tells the business operation the number of seconds 

to wait for its partner business service to supply an ACK that corresponds to the normal outbound 

message that the business operation sent. The default PartnerAckTimeout is 600 seconds 

(10 minutes). 

3.4 HL7 Message Framing Types 

Framing controls the kind of wrapper packets used to transport HL7 messages. The HL7 business 

services and business operations each have a configurable Framing setting. On the inbound side, it 

controls how the HL7 business service interprets the incoming HL7 message packet; on the outbound 

side, it controls how the HL7 business operation constructs the outgoing HL7 message packet. The 

following table lists the valid Framing values. If you are unsure what value to use, accept the defaults: 

• Flexible for HL7 business services 

• MLLP for HL7 business operations 

Note: 

ASCII values must be given as numeric values when you enter them in Framing fields. ASCII 

120 followed by some other ASCII character value is not allowed as an ASCII framing convention. 


Framing Types for HL7 Business Operations and Business Services 

HL7 Message Framing Types 

Framing Type 

Flexible 

None 

XML 

MLLP 

MLLP[nn]/[mm] 

AsciiLF 

AsciiCR 

Ascii[nn] 

Ascii[nn]/[mm] 

LLP 

Meaning 

Flexible framing means the service will accept messages using 

any kind of framing and will use the same framing style when 

replying with an ACK message. Flexible framing is not available 

for business operations. MLLP is the default for operations. 

No framing. Each line that begins with the string MSH is the start 

of a new message 

An XML envelope wraps each HL7 message. is 

added as a final wrapper tag if the message’s Envelope property 

contains none. 

Minimal Lower Level Protocol. Frame each HL7 message with 

an ASCII 11 prefix and a suffix that consists ASCII 28 followed 

by ASCII 13. 

Minimal Lower Level Protocol using non-standard ASCII values. 

Frame each HL7 message with a prefix that consists of the 

ASCII character value indicated by nn. Also provide a suffix that 

consists of the ASCII character value indicated by mm, followed 

by ASCII 13, the carriage return character. 

Frame messages with no MLLP, with ASCII 10, the line feed 

character, separating each message from the subsequent one. 

Frame messages with no MLLP, with an extra ASCII 13, the 

carriage return character, separating each message from the 

subsequent one. 

Frame messages with no MLLP, with a suffix separating each 

message from the subsequent one. This suffix consists of the 

ASCII character value indicated by nn. 

Frame messages with no MLLP, with a prefix character before 

each message.This suffix consists of the ASCII character value 

indicated by nn. Also provide a suffix that consists of the ASCII 

character value indicated by mm, but with no trailing ASCII 13. 

Lower Level Protocol. Frame each HL7 message in a redundant 

checksum block. 



Framing Type 

 

 

MsgEnvelope 

MLLPXML 

MLLP 

MLLP 

MLLPMsgEnvelope 

Meaning 

Use this literal XML envelope to wrap each HL7 message. The 

string if present in the block 

will be replaced with the message content. Otherwise the 

message will simply follow the envelope text and appropriate 

closing tags will be added, if the envelope contains open tags. 

An XML envelope wraps each HL7 message. is 

added as a final wrapper tag if the message’s Envelope property 

contains none 

Use the message’s Envelope property verbatim if it is present. 

The string if present in the envelope will be 

replaced with the Message content. Otherwise the Message 

will simply follow the envelope text 

Same as XML, but with an MLLP prefix and suffix also around 

the message inside the envelope. 

Same as , but with an MLLP prefix and suffix 

also around the message inside the envelope. 

Same as , but with an MLLP prefix and suffix also 

around the message inside the envelope. 

Same as MsgEnvelope, but with an MLLP prefix and suffix also 

around the message inside the envelope. 

When the framing type is MLLP, Ensemble automatically detects extra carriage returns (ASCII 13) 

that occur in the message before the close framing. This indicates to Ensemble that a blank line is not 

being used to separate messages, so it assumes that any blank line is part of the message content and 

can be safely ignored. 

3.5 HL7 Batch Messages 

Ensemble supports nested child documents in HL7. Each of the child documents is an Ensemble virtual 

document in its own right. Ensemble supports the following HL7 batch formats: 

• BHS MSH ... MSH ... BTS 

Ensemble recognizes BHS as a batch header segment, and BTS as a batch trailer segment. Within 

this container, Ensemble recognizes each MSH message header segment as the beginning of a 

child document. 


HL7 Batch Messages 

• FHS MSH ... MSH ... FTS 

Ensemble recognizes FHS as a batch header segment, and FTS as a batch trailer segment. Within 

this container, Ensemble recognizes each MSH message header segment as the beginning of a 

child document. 

• FHS BHS MSH ... MSH ... BTS BHS MSH ... MSH ... BTS FTS 

When FHS and BHS begin the message together, Ensemble recognizes FHS as the first-level 

parent document and each BHS as the beginning of a child document. BHS then becomes a secondlevel 

parent and the contents following each MSH segment become its child documents. 



Parent and Child Documents in HL7 Batch Messages 

There are two production settings that control HL7 batch processing. On the incoming side, HL7 

business services have a Batch Handling configuration setting that determines how to process incoming 

batch documents. The options are: 


• Whole Batch — Do not process child documents individually; accumulate and send the whole 

batch as one composite document. 

• Single-Session Batch — Forward all child documents in the batch together in one session; 

the session includes objects representing the batch headers and trailers. Single-Session 

Batch is the default if no Batch Handling value is specified. 

• Multi-Session Batch — Forward each child document in the batch in its own session, with 

a unique session ID. 

• Individual — Forward each child document in the batch in its own session; do not forward 

objects representing the batch headers and trailers. 

In responding to received messages, the default behavior is to send an acknowledgement to the sender 

as a batch document that contains an ACK message for each child document. This works for most 

situations. However, HL7 business services also have a property, not exposed as a configuration setting, 

called NoBatchReply. Its default value is 0 (false), which provides the default behavior. If you edit 

your business service’s OnInit method to include this statement: 

Set ..Adapter.NoBatchReply = 1 

HL7 Batch Messages 

Then batch replies are inhibited; each individual message gets a separate un-wrapped ACK. 

On the outgoing side, HL7 business operations have a AutoBatchParentSegs configuration setting. 

When AutoBatchParentSegs is False (the default) the business operation outputs child documents, but 

does not output the batch headers and trailers. When AutoBatchParentSegs is True, while outputting 

a message that has a batch parent, the business operation outputs the batch headers first, then the child 

documents, then follows up with the batch trailers when triggered by the final batch header message 

or by a file name change. 

The combination of Batch Handling and AutoBatchParentSegs enables the following modes of operation 

for HL7 batch documents. The ABPS column indicates values of AutoBatchParentSegs. Any combination 

of values not shown in this table is invalid. 



HL7 Batch Message Handling Options 

Batch Handling 

Whole Batch 

Single-Session 

or 

Multi-Session 

Single-Session 

or 

Multi-Session 

Individual 

ABPS 

(any) 

True 

False 

False 

Results 

Business service sends only the parent document; all 

child documents are referenced to it but not sent 

individually. Operation outputs entire batch at one time 

when it receives the parent document. 

Service sends each child document as it receives and 

parses it, followed by the parent document when all 

children have been sent.The business operation outputs 

parent headers when it receives the first child document, 

then finishes up with trailers when it receives the parent 

document object. Trailer segments automatically contain 

the correct child count values. 

This results in double output: the business operation 

sends out each child document individually, followed by 

the parent document containing each child document 

(again). 

Business service forwards each child document in the 

batch in its own session and does not forward objects 

representing the batch headers and trailers. On the 

outgoing side, the business operation does the same. 

If you wish to add custom code to your routing process to handle batch documents specially on the 

output side, you can do so. The following are two possibilities: 

• Your routing process code constructs new parent and child documents and links them, then sends 

each child to the business operation. The business operation must have AutoBatchParentSegs set 

to True. The business operation outputs parent headers when it receives the first child document, 

then finishes up with trailers when it receives the parent document object. Trailer segments automatically 

contain the correct child count values. 

• Your routing process code constructs new parent and child documents and links them, but sends 

only the parent object via the business operation. 


3.6 HL7 Business Service Classes 

HL7 Business Service Classes 

Ensemble provides external connectivity via built-in adapters for the major technologies used to 

exchange HL7 messages: FTP, TCP, HTTP, and File. Documentation for the FTP, TCP, HTTP, and 

File inbound adapters advises you to write a business service that invokes the adapter. This is not 

necessary for HL7 Version 2 message routing productions. HL7 poses complex message parsing issues 

that go beyond simple connectivity. For this reason, Ensemble provides built-in HL7 business services 

that parse HL7 messages in a consistent manner. This way, you do not need to write your own business 

service code. 

The following diagram shows the inheritance tree for the built-in HL7 business service classes. This 

tree indicates which configuration settings you should expect to be available in the [Ensemble] > 

[Productions] configuration diagram for each business service. The list of settings is cumulative, so 

for the EnsLib.HL7.Service.FTPService the settings are AlertOnError, ArchiveIO, AlertGracePeriod, 

TargetConfigNames, SearchTableClass, LocalFacilityApplication, Framing, AckMode, UseAckCommitCodes, 

IgnoreInboundAck, AddNackERR, BatchHandling, MessageSchemaCategory, 

DefCharEncoding, and AckTargetConfigNames. 

For detailed configuration instructions, see the “HL7 Business Services” section in the chapter 

“Elements of a Routing Production.” 



HL7 Business Service Class Hierarchy, Showing Inheritance of Settings 


3.7 HL7 Business Operation Classes 

HL7 Business Operation Classes 

Ensemble provides external connectivity via built-in adapters for the major technologies used to 

exchange HL7 messages: FTP, TCP, HTTP, and File. Documentation for the FTP, TCP, HTTP, and 

File outbound adapters advises you to write a business operation that invokes the adapter. This is not 

necessary for HL7 Version 2 message routing productions. HL7 poses complex message parsing issues 

that go beyond simple connectivity. For this reason, Ensemble provides built-in HL7 business operations 

that construct HL7 messages in a consistent manner. This way, you do not need to write your own 

business operation code. 

The following diagram shows the inheritance tree for the built-in HL7 business operation classes. This 

tree indicates which configuration settings you should expect to be available in the [Ensemble] > 

[Productions] configuration diagram for each business operation. The list of settings is cumulative, so 

for the EnsLib.HL7.Operation.FTPOperation the settings are AlertOnError, ArchiveIO, AlertRetryGracePeriod, 

RetryInterval, FailureTimeout, Framing, Separators, SearchTableClass, DefCharEncoding, 

Filename, and AutoBatchParentSegs. 

For detailed configuration instructions, see the “HL7 Business Operations” section in the chapter 




HL7 Business Operation Class Hierarchy, Showing Inheritance of Settings 


4 

Syntax for a Routing Production 

This chapter describes the programming and syntax details that support HL7 Version 2 routing productions. 

Topics include: 

• HL7 Message Class 

• Virtual Property Syntax 

• Literal String Syntax 

• Schema Category Syntax 

4.1 HL7 Message Class 

Ensemble provides a built-in class for HL7 Version 2 virtual documents. The class is 

EnsLib.HL7.Message. You do not need to change anything to make this class work with a particular 

HL7 Version 2 schema or even to make it work with custom HL7 message types. 

The following figure illustrates how EnsLib.HL7.Message inherits its virtual document features from 

other classes. While the figure does not list all the properties and methods in the class, it highlights 

those you most need to understand in order to work with HL7 messages. These are the properties and 

methods that allow you to efficiently handle HL7 Version 2 data within an Ensemble production. These 

include the class properties DocType, TypeCategory, BuildMapStatus, and Name. To refer to these 

properties from statements in BPL, DTL, routing rules, Caché Basic, or ObjectScript, use ordinary dot 

syntax, as in: 

 



HL7 Message Class Overview Showing Inheritance 

4.1.1 The DocType Property 

The DocType property is the document type, a string in two parts separated by a colon: 

category:structure 

Where: 

• category is the name of a schema category. This means that category must be the same as a 

name expressed in some schema category as follows: 

 


• structure is the name of a message structure within the referenced category. This means that 

structure must be the same as a name expressed somewhere inside the 

context as: 

 

HL7 Message Class 

For example: 

2.3.1:ORM_O01 

2.4:ORD_O04 

myCustomCategory:MFN_M03 

When using HL7 with Ensemble, you must supply document type values, using the syntax described 

in this topic, for the following items: 

• The DocType property of an HL7 message 

• The sourceDocType attribute of a DTL element 

• The targetDocType attribute of a DTL element 

• Source Doc Type in the Studio data transformation wizard 

• Target Doc Type in the Studio data transformation wizard 

• Message Type or DocType in the [Ensemble] > [EDI and HL7 Manager] > [EDI Document Viewer] 

page 

Tip: 

To browse examples of category:structure combinations, use “The Schema Structures Page” 

as described in the chapter “Viewing and Transforming Messages.” 

4.1.2 The TypeCategory Property 

The TypeCategory property contains an HL7 category name. Typically, the HL7 business service that 

receives HL7 data from outside Ensemble instantiates an HL7 message and assigns a TypeCategory 

value to it. Ensemble combines this TypeCategory with the message type declared in the MSH segment 

of the incoming message data; this combination identifies a within the HL7 schema 

definition. This has an associated that Ensemble uses as the 

DocType for the HL7 message, if no other DocType is assigned. 

4.1.3 The BuildMapStatus Property 

The BuildMapStatus property contains a %Status value that indicates the success or failure of the most 

recent effort to map the raw content of an HL7 message to a particular DocType. You can test 

BuildMapStatus in code as follows: 



• Use the macro $$$ISOK(myHL7Message.BuildMapStatus) in ObjectScript and the method 

$SYSTEM.Status.IsOK(myHL7Message.BuildMapStatus) in Basic. If the test returns 

a True value, BuildMapStatus contains a success value. 

• Use the macro $$$ISERR(myHL7Message.BuildMapStatus) in ObjectScript and the method 

$system.Status.IsError(myHL7Message.BuildMapStatus) in Basic. If the test returns 

a True value, BuildMapStatus contains a failure value. 

You can view details of any BuildMapStatus failure codes using “The Schema Structures Page” as 

described in the chapter “Viewing and Transforming Messages.” 

4.1.4 The Name Property 

The Name property is a read-only string that contains the HL7 message structure name (such as 

ADT_A08 or ORM_O02) that the external data source has provided in the MSH segment. The Name 

can be useful in determining the HL7 message structure that the clinical application thinks that it is 

sending, although this can differ from the actual message contents. 

4.1.5 The RawContent Property 

The RawContent property contains the 32 kilobytes of raw HL7 message data that came to Ensemble 

from an external source via an HL7 business service. The RawContent property is not indexed in any 

way, and is constructed “on the fly,” so for example, if you were to use this property in an SQL search 

query it would not execute very efficiently. It is unlikely that you would work with the RawContent 

property in creating an Ensemble production, but it can be useful in analyzing and reporting badly 

formed messages. RawContent does not contain the complete HL7 message data if it is larger than 32 

kilobytes in size. It contains the first 32KB of the message, which is usually the entire message because 

most are smaller than 32KB. 

4.1.6 The GetValueAt Method 

Any expression written in Caché Basic or ObjectScript can call the EnsLib.HL7.Message class method 

GetValueAt to get the value of a virtual property within an HL7 message body. BPL and DTL can 

use GetValueAt anywhere that a Caché Basic or ObjectScript expression is appropriate, for example 

within a BPL element or within a DTL condition like the following: 

 

Arguments 

GetValueAt has one argument, a %String that contains a virtual property path. To compose this string, 

see the section “Virtual Property Path.” 


Return Value 

GetValueAt returns the %String value of the virtual property named in the first argument. 

Shortcuts 

See “Curly Bracket {} Syntax” 

4.1.7 The SetValueAt Method 

Any expression written in Caché Basic and ObjectScript can call the EnsLib.HL7.Message class method 

SetValueAt to set the value of a virtual property within an HL7 message body. BPL and DTL can use 

SetValueAt anywhere that a Caché Basic or ObjectScript expression is appropriate, for example within 

a BPL element. 

Arguments 

SetValueAt accepts two arguments: 

• A %String value to assign to the virtual property. 

• A %String that contains a virtual property path. To compose this string, see the section “Virtual 

Property Path.” 

Return Value 

SetValueAt returns a value of type %Status that indicates success or failure. 

Shortcuts 

See “Curly Bracket {} Syntax” 

Virtual Property Syntax 

4.2 Virtual Property Syntax 

This section explains the correct syntax to use when referring to virtual properties from statements in 

BPL, DTL, ObjectScript, Caché Basic, business rules (including routing rules), search filters, or search 

tables. These syntax conventions provide the equivalent of various method calls that are either not 

possible in certain contexts (business rules) or that are so frequently used that a shortcut is helpful. 

The shortcuts are as follows. 

• Curly brackets 

{segment:field} 

• Square brackets 

[segment:field] 

• Round brackets or parentheses 



(multi-valued-property-path) 

• Angle brackets 

 

4.2.1 Curly Bracket {} Syntax 

Business rules, search tables, search filters, and certain BPL and DTL elements support the curly 

bracket {} shortcut in place of GetValueAt to access the value of a virtual property. The syntax is as 

follows: 

myHL7Message.{myVirtualPropertyPath} 

This is equivalent to the following method call, which returns the value of the specified virtual property. 

The specific message structure or document type must be known. 

msg.GetValueAt("segment:field") 

Note: 

The BPL and DTL elements and elements do not support curly bracket syntax. 

The segment:field string must be a valid virtual property path. Here is a BPL example: 

 

Or consider this DTL example: 

 

 

 

Here is an excerpt from a search table: 

{1:10} 

Curly bracket {} syntax is simpler than a method call, so you will generally use {} instead of calling 

GetValueAt. However, curly brackets are not supported is within or statements in BPL 

or DTL. Here you must use the appropriate method call (GetValueAt or SetValueAt) to work with 

virtual properties. 

For curly bracket syntax to resolve, the message structure must be known. If the message structure is 

unknown in the current context, you may use square bracket [] syntax to match the segment and field 

regardless of message structure. 



4.2.1.1 Virtual Property Path 

A virtual property path is a name in two parts, separated by a colon: 

segment:field 

Where: 

• segment identifies a message segment. 

• field identifies a field within that message segment. 

• A colon : separates segment and field. 

• A dot . separates hierarchical levels within segment or field. 

• Parentheses containing a number (n) provide an index into an array of repeating elements. 

For example: 

NK1(2):Address.streetaddress 

PR1grp(1).AUTgrp.CTD:ContactAddress.streetaddress 

Note: 

A virtual property path is relative to a specific message structure, and might not be valid in 

any other message structure. For help in finding the correct virtual property names and 

numbers, use “The Schema Structures Page” as described in the chapter “Viewing and 

Transforming Messages.” 

You can use numeric or symbolic names in the segment address or field address portion of the virtual 

property path. Following are two sample statements such as might appear within a DTL data 

transformation: 

 

 

The target has a DG1 segment with a field number 16.2 named DiagnosingClinician.familylastname. 

That means the two statements in the above example are equivalent. 

You cannot mix numbers and names on the same side of the colon. For example {DG1(1):Diagnosing- 

Clinician(1).familylastname} is allowed but {DG1(1):16(1).familylastname} is not allowed. On the 

left side of the colon (in the segment portion) numerics are of limited use because the numeric index 

of a particular segment is usually not known. MSH is an exception because it is always the first segment. 

All of the following DTL statements are equivalent, and equally valid, because MSH is segment 1 and 

ReceivingApplication is field 5 of MSH: 

 

 

 

 



4.2.1.2 Repeating Field () Syntax 

When you are using curly bracket {} notation in BPL or DTL, the shortcut () iterates through every 

instance of a repeating field within an HL7 message structure. For example, the following single line 

of DTL: 

 

Is equivalent to the following three lines of equally valid DTL: 

 

 

 

The same () convention is also available in BPL. 

4.2.1.3 Wholesale Copy 

When you are using curly bracket {} notation in BPL or DTL, you can copy whole segments, groups 

of segments, or whole composite fields within a segment. Thus, the following DTL statements 

are all legal: 

 

 

 

Note: 

The last line of the above example uses the caret (^) as a component separator character. For 

details, see “HL7 Separator Characters” in the section “Literal String Syntax.” 

To create a target object that is an exact copy of the source, do not use: 

 

Instead use the create='copy' attribute in the containing element, as in the following 

example: 

 

The create option may have one of the following values: 

• “new” — Create a new object of the target type, before executing the elements within the data 

transformation. This is the default. 

• “copy” — Create a copy of the source object to use as the target object, before executing the 

elements within the transform. 

• “existing” — Use an existing object, provided by the caller of the data transformation, as the 

target object. 



4.2.2 Square Bracket [] Syntax 

Square bracket [] syntax is available for business rules, search tables, and search filters only. Square 

brackets: 

[segment:field] 

Equate to this method call: 

msg.FindSegmentValues("segment:field") 

This means to find values in named segments regardless of message structure. If there is more than 

one instance of the segment type in the message, this syntax returns a string that contains all matching 

values, each value enclosed in angle brackets. The segment:field combination inside the square 

brackets follows the same rules as the virtual property path for curly brackets {} except that the field 

must be in numeric format. 

When square brackets are used, Ensemble can resolve the numeric path without knowing the specific 

message structure or schema. This is different from curly brackets {} which require the message 

structure to be identified somehow. For example, a DTL data transformation identifies the message 

structure of the source and the target messages with attributes of the element 

(sourceDocType and targetDocType) so that curly bracket syntax can be used. 

Square bracket syntax supports the repeating field shortcut () only in the field portion of the property 

path (segment:field). There is no way to specify that a segment might repeat; in fact this is not necessary. 

If multiple segments of the same type exist in the message, square bracket syntax matches all segments 

of that type in the message. The string returned by square bracket syntax encloses each value in 

angle brackets. 

The following excerpt from a search table class shows two valid ways to match all the FT1 segments 

found in a message that contains several FT1 segments: 

 

[FT1:12.1] 

[FT1:6] 

 

In each case if the syntax returns multiple values a, b, and c they appear in a single string like this: 

 

4.2.3 Parenthesis () Syntax in Business Rules 

Parenthesis or “round bracket” syntax is available for business rules only. A pair of parentheses can 

be used as brackets in an HL7 routing rule as follows: 

HL7.(multi-valued-property-path) 

This equates to: 



msg.GetValues("multi-valued-property-path") 

A multi-valued property path is one that uses the repeating field shortcut () to iterate through every 

instance of a repeating field within an HL7 message structure. You can use this in combination with 

round bracket syntax to return all values from all repetitions of a field. If the syntax returns multiple 

values a, b, and c they appear in a single string enclosed in angle brackets, like this: 

 

For example, in an HL7 routing rule, the syntax HL7.(NK1():1) finds the values of the first field 

in all of the multiple NK1 segments in the HL7 message object represented by the special variable 

HL7. 

4.2.4 Angle Bracket Syntax in Business Rules 

Angle bracket syntax is available for business rules only. An XPath expression in angle brackets 

such as the following 

 

Equates to: 

GetXPathValues(msg.stream,"context|expression") 

GetXPathValues is a convenience method in the rules engine. It operates on a message that contains 

a stream property whose contents are an XML document. The method applies an XPath expression to 

the XML document within the stream property, and returns all matching values. If the context| part 

of the XPath argument is missing, Ensemble searches the entire XML document. If the syntax returns 

multiple values a, b, and c they appear in a single string enclosed in angle brackets, like this: 

 

The following is an example of angle bracket syntax in an HL7 routing rule: the syntax 

HL7. results in a match if the XML document in the message stream property contains 

the word “fracture.” 

4.3 Literal String Syntax 

Often a DTL data transformation copies existing HL7 message data from fields within a source message 

to fields within a target message. The following DTL statement shows an example of this: 

 

In cases like this Ensemble preserves all of the special characters within the HL7 message data, such 

as separator characters and escape sequences, and handles them automatically, even if the specific 

conventions regarding these characters are different on the source (incoming) and target (outgoing) 


sides. The business services and business operations that handle the incoming and outgoing sides of 

HL7 message transmission handle all of these issues elegantly without needing any adjustments to 

occur within the data transformation. 

However, sometimes a DTL data transformation needs to assign a literal string value to a field, as in 

the following DTL statement: 

 

Literal String Syntax 

Important: 

In BPL and DTL, a literal string value must provide its own enclosing quotes, distinct 

from those that enclose the entire value, and of a different type. Thus, in the example 

above, value='"ULTRA"' inserts the string ULTRA into the ReceivingApplication 

field of the target message. value='ULTRA' or value="ULTRA" are not effective. 

When a DTL data transformation assigns a literal string value to a target message field, it is providing 

HL7 message data directly, rather than copying it from the source message. In constructing a DTL 

statement like this, you need to be aware of the HL7 separators and escape sequences that apply in the 

source (incoming) message, so that your literal string matches these conventions correctly. 

It does not matter which HL7 separators and escape sequences apply on the target (outgoing) side; 

they may be different. What matters within the data transformation is that any literal strings you create 

must match the HL7 separators and escape sequences of the source message. Then, after the data 

transformation constructs the target message object, the HL7 business operation automatically adjusts 

the HL7 separators and escape sequences to those expected by the target. 

You should also be aware that, because BPL and DTL are extensions of XML, whenever you construct 

a literal string for a BPL or DTL statement there are certain characters you can only represent using 

XML entities. A limited number of numeric character codes are also supported in constructing BPL 

or DTL strings. The next several topics explain the requirements for various types of special character. 

Finally, remember that the value attribute in a DTL statement can be a simple string, as in 

most of the examples in this book: 


Or the DTL value can be a complex string expression using the scripting language specified by the 

containing element. This language can be either Caché Basic or ObjectScript; if not 

specified it is ObjectScript. The same is true for a BPL statement, which uses the scripting 

language specified by the containing element; otherwise it uses ObjectScript. 

When constructing complex literal strings, keep in mind: 

• In ObjectScript, the concatenation operator is the _ (underscore) character, as in: 

value='"prefix"_source.{MSH:ReceivingApplication}_"suffix"' 

In Basic, the concatenation operator is & (ampersand). 



• To learn about useful ObjectScript string functions, such as $CHAR and $PIECE, see the Caché 

ObjectScript Reference. For Basic equivalents, see the Caché Basic Reference. 

• For a general introduction see Using Caché ObjectScript or Using Caché Basic. 

4.3.1 HL7 Separator Characters 

An HL7 message uses special characters to organize its raw contents. These characters may vary from 

one clinical application to another. For this reason, the HL7 standard requires that each HL7 message 

list the five specific characters that it is using as separators at the start of the MSH segment, in order 

from left to right: 

1. Field separator (FS) 

2. Component separator (CS) 

3. Repetition separator (RS) 

4. Escape character (ESC) 

5. Subcomponent separator (SS) 

A sixth character, the segment terminator character, is not specified in MSH and is generally assumed 

to be a carriage return (ASCII 13). 

4.3.1.1 Business Operations 

When configuring a routing production, you have the option of specifying a set of HL7 separator 

characters, as well as a segment terminator, for outgoing HL7 messages. 

The way to do this is to set the value of the Separators setting for the HL7 business operation. For 

Separators, you must supply a string of characters which Ensemble assigns to HL7 separators in left 

to right order: FS, CS, RS, ESC, SS as described in the previous list. If you do not specify a value for 

Separators, the business operation uses the following defaults for positions 1 through 5: 

|^~\& 

Beyond positions 1 through 5 of the Separators string, you can supply additional characters to override 

the default segment terminator character, the carriage return (ASCII 13). After position 5, use \r for 

the carriage return (ASCII 13) and \n for the line feed (ASCII 10). 

You can use \x in positions 1 through 5 if you need to specify segment terminators in positions 6 and 

higher but want your output messages to use fewer than 5 separators. Separators designated by \x in 

positions 1 through 5 are not used. The purpose of \x is simply to extend the length of the list of separators 

so that position 6 is interpreted correctly as the first segment terminator. 



4.3.1.2 Data Transformations 

Within a DTL statement, any HL7 separator character that you use appropriately in a literal string will 

act as a separator character within the resulting HL7 message object. For example: 

 

This statement sets fields 2 and 3 of DG1(1):DiagnosingClinician by providing a literal string 

that contains the appropriate arrangement of subcomponent separator characters (^ in this case) to 

indicate field positions within the DG1(1):DiagnosingClinician component. 

Note: 

In order for this convention to work, ^ must actually be the subcomponent separator. 

4.3.2 HL7 Escape Sequences 

When separator characters need to appear within the data contents of an HL7 message, HL7 provides 

escape sequences to replace the separator characters. 

The character most likely to require this feature is the & (ampersand) character. & is often used as an 

HL7 separator. At the same time, & is likely to appear in HL7 document data, either within the legal 

names of employers (Parker & Sons) or as shorthand in treatment orders (XR CHEST PA&LAT). 

Thus, within the HL7 data stream you will often see & characters replaced by an escape sequence, 

such as the \T\ in the following samples: 

Parker \T\ Sons 

XR CHEST PA\T\LAT 

The following table lists the six standard HL7 escape sequences and their meanings. HL7 escape 

sequences begin and end with the escape character as defined in the MSH segment. HL7 escape 

sequences are case-sensitive, and they use the specific characters F R S T E or .br as shown in the 

table. In the examples shown, the \ (backslash) is the escape character. 



HL7 Escape Sequences Using Backslash as Escape Character 

This character sequence... 

\.br\ 

\F\ 

\R\ 

\S\ 

\T\ 

\E\ 

If found within HL7 data, indicates... 

Carriage return 

Field separator character 

Repetition separator character 

Component separator character 

Subcomponent separator character 

Escape character 

For example... 

| 

~ 

^ 

& 

\ 

It is not necessary to provide any special processing in a DTL data transformation to handle the separator 

characters or escape sequences that already exist within the source message data. The business 

services and business operations that handle the incoming and outgoing sides of HL7 message transmission 

know which separator characters to expect on each side. Prior to being sent, the whole text of 

the message is automatically “un-escaped” relative to the incoming set of separators, and then “reescaped” 

relative to the outgoing set of separators. All of these HL7 issues are handled automatically 

when you use a DTL data transformation to simply fields in the source message to fields in 

the target message. 

On the other hand, if you a literal string to a target field using DTL, and that string needs to 

include HL7 separator characters, either as separators or as literal characters, some special handling 

is required. The procedures are as follows. 

Suppose you have a source message in which ^ & and \ are separators as listed in the MSH segment: 

MSH|^~&\ 

Now suppose that, for all ADT_A01 messages that arrive from a certain clinical source, your DTL 

data transformation needs to assign a literal value to the InsuranceCompanyName field. The correct 

value has been agreed upon by all concerned parties, including the insurance company, whose name 

is Pierre DuRhône & Cie. The value is to appear in the HL7 data stream as follows: 

Pierre DuRho^ne & Cie 

In this case, you need HL7 escape sequences to replace ^ and & within the data, as follows: 

 

The only other case in which you need to be concerned about separator characters is if you wish to 

migrate data into or out of an Ensemble HL7 virtual document without using a data transformation at 

all. The EnsLib.HL7.Segment class provides explicit Escape and Unescape methods that you can 


invoke to accomplish manually what a DTL data transformation does automatically to “un-escape” 

and “re-escape” HL7 messages. A replace method also exists. 

4.3.3 XML Entities 

When you a literal string value to a property using BPL or DTL, you must substitute XML 

entities for certain characters. This has nothing to do with HL7. The restriction exists because BPL 

and DTL are extensions of XML. Within all BPL or DTL statements (aside from the contents of 

or statements) certain characters must be represented by XML entities. The following table lists 

them. 

XML Entities for Use in BPL and DTL Strings 


Character 

> 

< 

& 

' 

" 

XML Entity 

> 

< 

& 

' 

" 

Description 

Right angle bracket or “greater than” symbol. 

Left angle bracket or “less than” symbol. 

Ampersand. 

Single quotation mark or apostrophe. A string enclosed in 

single quotes needs the ' entity to represent the ' 

character. 

Double quotation mark. A string enclosed in double quotes 

needs the " entity to represent the " character. 

To encode a literal string for the employer named Joe’s "Good Time" Bar & Grill, a BPL or DTL 

statement needs this syntax: 

 

As a general rule, you must use the appropriate XML entity in place of the characters >,


• When & is an HL7 separator character and the string needs to include that character as a separator 

use & 

• When & is an HL7 separator character and the string needs to include that character as a literal 

character use the appropriate HL7 escape sequence for that separator. 

• In all other cases, whether or not & is an HL7 separator, use & 

Suppose & and " are in use as the HL7 component and subcomponent separators. For an employer 

called Joe’s "Good Time" Bar & Grill, a DTL statement would need this syntax: 

 

4.3.4 Numeric Character Codes 

Decimal or hexadecimal representations of characters are permitted within literal strings in BPL and 

DTL. 

The string &#n; represents a Unicode character when n is a decimal Unicode character number. One 

example is é for the Latin e character with acute accent mark (é). 

Alternatively, the string &#xh; represents a Unicode character when h is a hexadecimal Unicode 

character number. One example is ¿ for the inverted question mark (¿). 

Important: 

Due to the limitations of single-byte encoding format for HL7, the numeric value in 

character codes in literal strings placed in HL7 messages can be no higher than the 

decimal value 255 or hexadecimal x00FF. 

4.3.5 Null Mapping Codes 

There are HL7 applications that use a null mapping convention. According to this convention, the 

source application can send a field that consists of two consecutive double-quote characters: 

"" 

This value means “If you have data in this field, delete it from your application.” 

Many target applications do not expect these instructions and are not designed to respond to them. If 

this is the case, and the double quotes are saved in the target application as actual patient data, the 

application users will see double-quote characters on their screens. This can be annoying and misleading. 

When your source application uses a null mapping convention, your HL7 data transformation can 

check for null mapping entries in HL7 fields and replace them with empty strings, or otherwise fill in 

data for the benefit of the target application. 


The following statement represents the simplest case. It checks for a null mapping in the source 

and replaces it with an empty string in the target. The condition tests for the null mapping code 

"" using a string of 2 quoted quotes. This results in a total of 6 double-quote characters, not including 

the single quotes that wrap the entire condition value. (Count carefully!) 

 

 

 

 

 

In the above example, the value indicates a empty string using 2 consecutive double-quote 

characters, with single quotes wrapping the entire value. 

The following syntax is equally valid: 

Schema Category Syntax 

 

 

 

 

 

You can achieve more sophisticated goals for handling null mappings. The following example takes 

alternative actions based on whether there is actually a value in {PV1:3}. If the field contains a null 

mapping code the element executes. Otherwise the element executes. 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

4.4 Schema Category Syntax 

A schema category definition can be viewed in XML format by opening its *.HL7 file in Ensemble 

Studio. Each *.HL7 file is an XML document whose top-level container is the element. 

Statements within the element define HL7 message structures. 



When viewed in Ensemble Studio, an *.HL7 file resembles the following figure. The actual text is 

longer and wider than the example, which contains ellipses (...) for omitted items and is truncated at 

right. This example is the schema category definition for HL7 Version 2.5. 

Ensemble Studio View of a Built-in HL7 Category Definition 

Inside the element, the example begins with two sets of XML elements that you do not 

need to work with: and . These elements group HL7 messages into 

functional categories. The example ends with two other XML elements that you do not need to work 

with: and . These elements define the range of possible values for certain 

fields in certain messages. 

When you create a custom schema category, you supplement an existing schema by defining custom 

segments (Z-segments) and then stating which message types and message structures may contain 

those segments. To accomplish this, you only need to work with the XML elements , 

, and . 



Important: 

Never edit the built-in schema category definition files. When you need to use custom 

message types that contain Z-segments, create a custom schema category definition 

that uses a built-in schema category definition as its schema base. 

A custom schema category definition is simpler than a built-in definition and contains fewer statements. 

Everything in the base category is included in the custom schema category definition. There is no need 

to repeat the definitions of standard message types. You only need to define custom message types. 

The conventions for doing this are as follows: 

What to Define 

Custom schema category definition. 

Custom segments (Z-segments). 

Any message structures that include custom segments. 

Any message types that include message structures with custom 

segments. A message type identifies: 

How to Define It 

 

 

 

 

• The message structure to send 

• The message structure to expect in response 

When viewed in Ensemble Studio, a custom schema category definition resembles the following figure. 

The actual text is wider than the example, which is truncated at right. You can view the complete 

example by opening the schema definition file Demo.HL7.MsgRouter.Schema.HL7 in the ENSDEMO 

namespace. 



Ensemble Studio View of a Custom HL7 Category Definition 

4.4.1 

The element is the top-level container for the XML document that describes the custom 

schema category. The following is an example of syntax for a custom schema category 

definition: 

 

 

 

The following table describes the attributes. 

Attributes for the Element in Schema Category Definitions 

Attribute 

name 

std 

Description 

Name displayed in the Schema Structures 

page in the list of available schema 

categories. 

When 1 (true), this block 

describes a standard HL7 schema 

category. The default is 0 (false). 

Value 

String. For convenience, use 

the name of the .HL7 file. 

For standard schema 

category definitions only. Do 

not use std in a custom 

schema. 



Attribute 

base 

Description 

Identifies the schema category that is the 

base for this custom schema category. 

Every definition in the schema base is 

automatically included in the custom 

category; statements in the custom schema 

category simply add to the base. 

Value 

The name of a standard or 

custom schema category 

defined using a 

block in another .HL7 file. 

4.4.2 

A element may contain one or more elements. Each 

element defines the structure of a custom segment (Z-segment). The following is an example of 

element syntax: 

 

 

 

 

 

 

 

 

 

 

 



Attribute 

name 

description 

Description 


page in the list of available segment 

structures. 

Text description of the segment contents, 

displayed in the Schema Structures page 

and in hover-text help for the Document 

Viewer page. 

Value 

3–character string. By 

convention, custom 

segment names begin with 

the letter Z. 

String 



4.4.3 

A element may contain one or more elements. Each 

element describes one field of the custom segment, in sequential order from 

top to bottom. The following is an example of element syntax: 

 



Attribute 

piece 

codetable 

datastruct 

description 

Description 

Number displayed in the 

Schema Structures page when 

the user asks to view details of 

the segment that contains this 

field. This number can be used 

to identify the field in a virtual 

property path. 

Code table that enumerates a 

list of valid values for this field. 

This attribute is typically not 

used in a custom schema. 

Data structure that specifies 

how to interpret the values in 

this field. This attribute is 

typically not used in a custom 

schema. 

Text description of the field 

contents, displayed in the 

Schema Structures page and 

in hover-text help for the 

Document Viewer page. 

Value 

Integer. Each 

within a must use 

piece values in sequential order, 

beginning at 1 and incrementing by 1. 

The name of a code table defined 

using a block. 

The name of a data structure defined 

using a block. 

String 



Attribute 

symbol 

Description 

Symbol that indicates the 

requirements for presence, 

absence, or repetition of this 

field within the segment. 

This field is optional. It serves 

as an indicator on the Schema 

Structures page. It does not 

actually control the requirement 

or repetition of fields. See 

required and ifrepeating. 

Value 

A single character: 

• ! means 1 only. The field must 

appear, but only once. 

• means 0 or 1. The field may 

appear, but at most once. 

• + means 1 or more. The field may 

repeat one or more times. 

• * means 0 or more. The field may 

repeat zero or more times. 

• & means the field may be present, 

and may repeat, but only under 

certain conditions. 

length 

required 

Upper limit on the number of 

characters that can be present 

in this field. 

Whether or not this field must 

be present in the segment. 

Integer 

A single character: 

• C means conditional 

• O means optional 

• R means required 

ifrepeating 

Whether or not this field may 

repeat within the segment. 

Integer. 0 means no, 1 means yes. 

4.4.4 

A element may contain one or more elements. Each 

element provides a specification for the number and arrangements of segments in a message 

structure. The following is an example of element syntax: 

 





Attribute 

name 

definition 

description 

Description 


page in the list of available message 

structures. 

Specification for the number and 

arrangements of segments in the message 

structure. May include a mix of standard 

and custom message segments. See syntax 

rules below. 

Text description of the field contents, 

displayed in the Schema Structures page 

and in hover-text help for the Document 

Viewer page. 

Value 

3–character string, plus an 

underscore (_), plus a 

3–character string. 

String that includes the 

3–character name values 

for standard or custom 

message segments defined 

using 

String 

Syntax for the definition string work as follows: 

• Keep the entire string all on one line 

• List each segment sequentially from left to right 

• When listing a segment, use its name value as defined by a 

• Separate a segment from the next segment by a ~ (tilde) character 

• If a segment or block of segments repeats, enclose the repeating part in {~ and ~} 

• If a segment or block of segments is optional, enclose the optional part in [~ and ~] 

Within a definition, a name may be simple, in which case Ensemble assumes the value refers to a 

custom block within the same .HL7 file. Alternatively, a name may refer to a 

standard message structure from the schema base. This means it is defined in the .HL7 file identified 

by the base attribute in the containing element. To indicate this, the name must use the 

prefix: 

base: 

So that Ensemble can find the appropriate in the other file. No other external 

.HL7 file can be referenced; only the schema base. 

In the example at the beginning of this topic, only the ZSI segment is defined in 

the same .HL7 file. The other segments (MSH, MFI, MFE, OM1, and Hxx) are all defined in the schema 

base. 



4.4.5 

A element may contain one or more elements. entries 

define any message types that include message structures that have custom segments. A 

element is a simple list of two items: 

• A message structure to send 

• A message structure to expect in response 

The following is an example of element syntax: 

 



Attribute 

name 

structure 

returntype 

Description 


page in the list of available message types. 

The message structure to send. 

The message structure to expect in 

response. This must be a valid ACK 

message structure. Make sure the 

returntype has a value from the schema 

base. For example: 

returntype="base:ACK" 

Value 

3–character string, plus an 

underscore (_), plus a 

3–character string. 


custom message structure 

defined using 

 


custom message structure 

defined using 

 

structure values can be simple name values from the current .HL7 file. If a file contains syntax like 

the following, where the structure is MFN_M03: 

 

Then the same file must also contain syntax like the following, to define MFN_M03: 

 



Alternatively, structure or returntype values can refer to a standard message structures from the schema 

base. To indicate this, the values must use the prefix: 

base: 

So that Ensemble can find the appropriate entries, in the .HL7 file identified by 

the base attribute in the containing element. No other external .HL7 file can be referenced; 

only the schema base. 

The following example uses both styles of syntax. This example defines a custom message type 

MFN_M03 that sends a custom MFN_M03 and receives a standard MFK_M03 as a response. 

 


5 

Viewing and Transforming 

Messages 

This chapter describes the Ensemble Management Portal pages that allow you to view and transform 

HL7 messages. From the [Ensemble] home page, you may choose options as follows: 

• From the main menu, choose EDI / HL7 Manager. Click one of the following links: 

- HL7 Version 2 — Displays the Web site for the American National Standards Institute (ANSI) 

standards developing organization Health Level Seven (HL7). The URI is 

http://www.hl7.org/ 

- Schema Structures — Displays a list of the supported HL7 Version 2.x schema specifications. 

You can click on any link in the display to drill down for details. 

- Message Viewer — Allows you to preview the results of applying various parsing schemes 

or data transformations to HL7 message data. 

• From the main menu, choose Message Browser. The [Ensemble] > [Messages] page offers the 

following features for working with HL7 message data: 

- Filter Messages — Find archived HL7 messages that meet your filter criteria. You can specify 

detailed logical rules for the filter. 

- Compare Messages — Select two HL7 messages from the list on the [Ensemble] > [Messages] 

page. Click Compare Messages to display their contents side by side. 


Viewing and Transforming Messages 

5.1 Starting the Ensemble Management Portal 

To start the Ensemble Management Portal from the System Management Portal: 

1. 

Click on the Ensemble cube icon in the Windows system tray. Choose System Management 

Portal from the menu. A browser window opens and the [Home] page displays. 

2. At the bottom of the System Administration column on the left-hand side, click the Ensemble 

Management Portal option. The display changes to the Ensemble login page. Under the title bar 

is a display area that contains a dialog box and the prompt Please login. 

3. If you have more than one Ensemble namespace, the Ensemble login page includes a Namespace 

field. If you see the Namespace field, select a namespace from the drop-down list. If you have 

one Ensemble namespace, the Ensemble login page automatically selects that namespace and the 

Namespace field does not appear. 

4. In the Username and Password fields, enter the username and password for a user account defined 

in the namespace. The default login is _SYSTEM with the password SYS. 

5. Click Login. The [Ensemble] home page displays. 

To start the Ensemble Management Portal from Studio: 

1. Choose an Ensemble namespace: 

• Choose the File menu Change Namespace option. The Connection Manager displays. 

• Choose a Server Connection and Namespace (choose an Ensemble namespace). 

• If necessary, enter the Username and Password for that namespace and server. 

• Click OK to save your changes, Cancel to cancel them. 

2. Choose the Utilities menu Ensemble Management option. The Ensemble login page displays. 

3. Under the Ensemble login page title bar is a display area that contains a dialog box and a prompt 

to Please login. The dialog box provides Username and Password fields. Enter the username and 

password for a user account defined in the namespace you chose in Step 1. The default login is 

_SYSTEM with the password SYS. 

4. Click Login. The [Ensemble] home page displays. 


The Schema Structures Page 

5.2 The Schema Structures Page 

When you start the Ensemble Management Portal and select EDI / HL7 Manager, then Schema Structures, 

the [Ensemble] > [EDI and HL7 Manager] > [HL7 Schemas] page displays. This page allows you to view 

detailed information about HL7 Version 2 schema categories, including standard schemas and custom 

schemas. 

The Schema Structures page displays a table, with columns as follows: 

• Category — Identifies the schema category. 

The HL7 schema definitions loaded into Ensemble were generated directly from the respective 

standards (HL7 2.1, 2.2, 2.3, 2.3.1, 2.4, and 2.5). They faithfully replicate any errors, omissions, 

or discrepancies that exist in these standards as published by the Health Level Seven organization. 

There is one exception to this rule: In the HL7 2.3.1 standard, the data structure XCN is the 

“extended composite ID number and name for persons.” The standard leaves XCN field 3 undefined 

by mistake. The Ensemble schema definition for HL7 2.3.1 corrects this so that XCN field 3 is 

correctly identified as “given name.” 

HL7 Version 3 is not listed as an HL7 schema category, because it uses entirely different data 

conventions from HL7 Version 2. HL7 Version 3 defines messages in XML format. Ensemble 

does not use virtual documents to represent HL7 Version 3 message structures. Ensemble handles 

the XML data directly, using XPATH and XSLT. For details, see the Ensemble HL7 Version 3 

Development Guide. 

• Base — The standard category on which a custom category is based. 

• Links — Buttons you can click to drill down to various levels of each category: 

- Message Types identify two Message Structures as a request/response pair. 

- Message Structures/DocTypes identify the sequence and grouping of Segments within a 

Message Structure. 

- Segment Structures list the fields in each Segment of a Message Structure. 

- Data Structures list the contents of composite data fields. 

- Code Tables list the values that can be used within an enumerated field. 

At the bottom of the page, a dialog offers selections that allow you to: 

• Import or Export schema category definitions as XML files. 

• Choose a schema category from the drop-down list and Remove its definition from the Ensemble 

database. 



WARNING! 

You cannot undo the Remove operation. 

5.2.1 Viewing a List of Document Types 

Suppose you are viewing the [Ensemble] > [EDI and HL7 Manager] > [HL7 Schemas] page. If you click 

the Message Structures/DocTypes link in one of the rows, the display changes to list all the message 

structures in that category definition. This is the [Ensemble] > [EDI and HL7 Manager] > [HL7 Schemas] 

> [HL7 Schema Contents] page. 

This page is useful for supplying correct values for the DocType property of an HL7 message object. 

Remember that this value is a name in two parts, separated by a colon: 

category:structure 

Where: 

• category is the name of a schema category, such as 2.3.1. This name appear at the top of the 

[Ensemble] > [EDI and HL7 Manager] > [HL7 Schemas] > [HL7 Schema Contents] page. 

• structure is the name of a message structure within that schema category. The page contains a 

complete list of valid message structures. If you view this page online, you can see that valid 

DocType values for category 2.3.1 include 2.3.1:ACK, 2.3.1:ADT_A17, 2.3.1:BAR_P01, 

2.3.1:PEX_P07, and so on. 

5.2.2 Viewing a Message Structure 

To view the internal organization of a message structure, click on its name in any [Ensemble] > [EDI 

and HL7 Manager] > [HL7 Schemas] > [HL7 Schema Contents] page. Ensemble displays the segment 

structure of the message using the system of visual cues explained below. This is the [Ensemble] > 

[EDI and HL7 Manager] > [HL7 Schemas] > [HL7 Message Structure] page. The following example shows 

the 2.3.1:ORM_O01 message structure. 

Ensemble HL7 Message Structure Page, DocType 2.3.1:ORM_O01 

The visual conventions on this page are as follows: 


• The segments that comprise the message structure are listed in sequential order, from left to right. 

• The three-letter name of each message segment is displayed: MSH, NTE, PID, etc. This name 

indicates the type of segment that exists at this location in the HL7 message structure. 

• White lines enclose a single segment. The look is similar to a table cell (see MSH and the first 

NTE segment, above). 

• If segments are organized into a group, the entire group appears within the same table cell (see 

PID and ORC above). 

• Green dotted lines enclose segments, groups, or fields that are optional. 

• Red solid lines enclose segments, groups, or fields that, if present, may repeat several times. 

• Orange dashed lines enclose a choice: this is a union of segments. Only one segment from the 

union can appear at this location within the message structure. It may be any of the segments 

listed. 

• A segment, group, or field may be both repeating and optional (see any NTE above). 

• You can navigate back to higher levels in the schema using the buttons Show All Categories and 

Show All Message Structures. 

• To see the message structure you are currently viewing in a raw text format, click Show Raw 

Definition text. You can click Show Definition diagram to return to the segment diagram. 

When you are viewing a segment diagram, if you hover the cursor over a three-letter segment name, 

a hover-text help window displays the syntax for referring to this segment in a virtual property path. 

In the above example, the cursor is hovering over an ODS segment whose segment address is: 

ORCgrp().OBRuniongrp.OBRunion.ODS 

In the following example, the cursor is hovering over a PR1 segment whose segment address is: 

PR1grp().PR1 


This address is the segment portion of a virtual property path, which has the format segment:field. To 

discover valid values for the field portion of this path, click on the three-letter segment name in the 

diagram. The next several topics explore the results when you click on the PR1 segment in the message 

structure 2.3:ADT_A01. 



Ensemble HL7 Message Structure Page, DocType 2.3:ADT_A01 

5.2.3 Viewing a Segment Structure 

To view the structure of a message segment, click on its name in any page similar to the example 

shown in the previous section, “Viewing a Message Structure.” Ensemble displays a table that lists 

and describes all the fields in that segment. This is the [Ensemble] > [EDI and HL7 Manager] > [HL7 

Schemas] > [HL7 Segment Structure] page. 

The following sample page appears when you click the PR1 segment in the 2.3:ADT_A01 message 

structure. The page states that the category 2.3 segment PR1 describes “Procedures” and may consist 

of fifteen fields. Of these, only SetIDProcedure, ProcedureCodingMethod, and ProcedureType are 

required (1, 2, and 6). 

Ensemble HL7 Segment Structure Page 

The columns in the display have meaning as follows: 

• The Field column lists the numbers you can use to access fields within the segment (if you prefer 

numbers). 



• There may be a brief text Description of each field. 

• The Property Name column lists the names you can use to access fields within the segment (if you 

prefer names). 

• For more complex field values that use a data structure, you need further syntax details before 

you can complete the segment:field virtual property path. You can get this by clicking on a name 

in the Data Structure column 

• The Symbol column indicates the syntax rules for the field. The characters in this column indicate 

whether you can expect this field to be present, absent, or repeated within the message segment. 

Possible values are: 

Symbol 

! 

 

+ 

* 

& 

n* 

Meaning 

(1 only) The field is required; it must occur only once. 

(0 or 1) The field is optional, but if it occurs, it may occur only once. 

(1 or more) The field may repeat one or more times. 

(0 or more) The field may repeat zero or more times. 

The field may be present, and may repeat, but only under certain 

conditions. 

(0 to n) The field repeats a maximum of n times. 

• The Repeat Count is the maximum number of times the field can repeat (if it repeats, and if there 

is a maximum). 

• The Length is the maximum number of characters in the field. Each repeat of the field may contain 

this number of characters. 

• Required displays R for required, O for optional. 

• Repeating displays 1 for true, 0 for false. 

• Click on an entry in the Code Table column (if any) to view the valid codes that may be entered 


• There may be an Alternate Description of the field. 

You can use this information, particularly the Property Name column, to build virtual property paths 

for Ensemble in the format segment:field. The following are examples of virtual property paths 

involving simple field values from the PR1 segment in the 2.3:ADT_A01 message structure. The () 

shortcut syntax indicates all available instances of a repeating field, whereas (1) indicates the first 

instance: 



PR1grp().PR1:ProcedureType 

PR1grp().PR1:ProcedureCode() 

PR1grp().PR1:ProcedureCode(1) 

PR1grp().PR1:ProcedureCode(x) 

PR1grp().PR1:ProcedurePriority 

5.2.4 Viewing a Data Structure 

When you click on a name in the Data Structure column, Ensemble displays a table that lists and 

describes all the fields in that data structure. This is the [Ensemble] > [EDI and HL7 Manager] > [HL7 

Schemas] > [HL7 Data Structure] page. The following columns of the display are most useful: 

• The Component column lists the numbers you can use to access fields within the segments (if you 

prefer numbers). 

• The Property Name column lists the names you can use to access fields within the segments (if 

you prefer names). 

• Click on an entry in the Data Structure column (if any) to drill down for detail. 

• Click on an entry in the Code Table column (if any) to view the valid codes that may be entered 


The following sample page appears when you click the Data Structure item called 2.3:XCN in the 

segment structure page above. The page states that the category 2.3 data structure XCN describes an 

“Extended Composite ID number and name” and consists of fourteen fields. Of these, some are simple 

values, some are data structures, and some are codes. 

Ensemble HL7 Data Structure Page 

Given this information, you can construct virtual property paths for the complex PR1grp().PR1:Surgeon 

field in the message structure 2.3:ADT_A01 as follows: 



PR1grp().PR1:Surgeon.familyname 

PR1grp().PR1:Surgeon.degree 

5.2.5 Viewing a Code Table 

When you click on a name in the Code Table column, it lists and explains the valid codes for that field. 

This is the [Ensemble] > [EDI and HL7 Manager] > [HL7 Schemas] > [HL7 Code Table] page. The following 

sample page appears when you click the Code Table item called 2.3:200 in the data structure page 

shown in the previous section, “Viewing a Data Structure.” 

Ensemble HL7 Code Table Page 

The example above shows that the category 2.3 code table 200 describes a “Name type” that can have 

the value L, O, M, A, C, or D. You can arrive at this page by clicking on: 

1. The message structure 2.3:ADT_A01 

2. The message segment PR1, which has a segment address of PR1grp().PR1 

3. The data structure DS:2.3:XCN in the optional Anesthesiologist field 

4. The code table CT:2.3:200 in the nametype field 

This means that if you have an HL7 message with a DocType of 2.3:ADT_A01, it has an optional 

virtual property with the path PR1grp().PR1:Anesthesiologist.nametype that can contain one of the 

following values: L, O, M, A, C, or D. 

Note: 

For details, see “Virtual Property Path” in the chapter “Syntax for a Routing Production.” 

5.2.6 Choosing a Different Category 

It is a feature of the HL7 standard that a message structure can differ by HL7 version, even when the 

structure has the same name and number. For example, both HL7 2.4 and HL7 2.5 define a message 

structure called ORD_O04, but these definitions contain different segments. Ensemble provides the 

message structure definitions 2.4:ORD_O04 and 2.5:ORD_O04. The [Ensemble] > [EDI and HL7 Manager] 

> [HL7 Schemas] > [HL7 Message Structure] page makes it easy to see the differences between 

the two definitions, as the following two figures show. 



Ensemble HL7 Message Structure Page, DocType 2.4:ORD_O04 

Ensemble HL7 Message Structure Page, DocType 2.5:ORD_O04 

5.3 The Document Viewer Page 

When you start the Ensemble Management Portal and select EDI / HL7 Manager, the [Ensemble] > [EDI 

and HL7 Manager] page displays. From here you can display the [Ensemble] > [EDI and HL7 Manager] 

> [EDI Document Viewer] page as follows: 

• In the ASC X12 row, click Document Viewer. The page displays with “X12 Document” selected 

in the View box. For details, see “The Document Viewer Page” in the “Viewing and Transforming 

Messages” chapter of the Ensemble X12 Development Guide. 

• In the ASTM row, click Document Viewer. The page displays with “ASTM Document” selected 

in the View box. For details, see “The Document Viewer Page” in the “Viewing and Transforming 

Messages” chapter of the Ensemble ASTM Development Guide. 

• In the HL7 Version 2 row, click Message Viewer. The page displays with “HL7 Message” selected 

in the View box. This chapter describes the HL7 Version 2 features of the Document Viewer page. 

When “HL7 Message” is selected, the Document Viewer page allows you to retrieve HL7 message 

data from external files or the Ensemble message archives. You can: 

• Preview the results of applying various parsing schemes or data transformations to message data. 


• View an HL7 message as if it belonged to a particular category of HL7. 

• Preview the results of an Ensemble data transformation by looking at the before-and-after contents 

of an HL7 message. 

• Verify that you are using the correct category:structure syntax for the DocType of an HL7 message. 

• Verify that you are using the correct segment:field syntax to use to access a specific data item 

within an HL7 message. 

• Determine the DocType assignment that a particular business service would make for a particular 

message. 

• View the content of messages from the Ensemble persistent store. 

• View the content of messages from a file on disk. 

The Document Viewer Page 

The Document Viewer page allows you to try interpreting messages from a particular data source as 

version 2.1, or 2.2, etc., to determine which DocType is the right one to use when handling messages 

from that source. There are a variety of reasons why you might need to do this. For example, you might 

find when you update an external application that it has changed the actual version of the HL7 messages 

it sends, but has neglected to update the HL7 version declaration that it sends in these HL7 messages. 

It is also useful in determining which of the built-in categories to use as a schema base, when a message 

contains Z-segments. 

In the following example, the chosen Source is Filename and the chosen DocType/Schema is Category. 

The message being viewed is message number 33 within an archive file called XYZ120. No data 

transformation is being applied to the message at the moment. This example highlights some useful 

features of the Viewer: 

• The MSH segment declares that the message is of type 2.2:ADT_O01, but the user has chosen 

Schema Category / Version with the category 2.3.1. The reason for this (not shown) is that when 

the user tried the message with Schema Category / Version 2.2 none of the message fields parsed 

correctly. The user moved on to try categories 2.3 and 2.3.1 before finding that 2.3.1 fit the message 

best. 

• After the user clicks View HL7 Message, the bottom half of the page displays the results of parsing 

this message as a category 2.3.1 message. Links, such as for message segments 1 through 18, 

indicate that the message segments have parsed correctly using the selected Schema Category / 

Version. Clicking any of these links displays more specific information about the field. 

• Non-links, such as appear for segments 19 through 24 in the illustration, indicate that the parser 

is not able to understand these segments of the message using the selected Schema Category / 

Version. This is to be expected for Z-segments if you have chosen a standard schema like 2.3.1 

as the Schema Category / Version. 

• Just above the bottom half of the page, the parser reports that it has used a DocType of 

2.3.1:ADT_O01 to parse the messsage, and that there are Z-segments at the end of the message 

(ZPI and following) that do not conform to this DocType. If you find a Schema Category / Version 



choice that allows the parser to understand all but the Z-segments in the message, then you know 

this standard schema is a good choice to be the basis of the custom schema that you create to parse 

the complete message including Z-segments. 

• After you create a custom schema, it becomes available as a choice from the Schema Category / 

Version list. 

Document Viewer Page 

5.3.1 Viewing a Message 

To view a message using the Document Viewer page: 

1. Ensure that the View choice is HL7 Message. 



2. Click a radio button to choose a Source and enter the required details. 

3. Click a radio button to choose a DocType and enter the required details. 

4. Optionally, select the Apply Data Transform check box and enter the required details. 

5. Click View HL7 Message. 

6. View the display. 

The following discussion describes these steps in detail. 

Source for Message Data 

Click a radio button to choose a Source for Message Data. The choices are: 

• Filename — Click the Browse button to find a file that contains HL7 message data. Enter a number 

in the Message # inside file field. 

• Message Header Id — Enter the object identifier of an Ensemble message. 

• HL7 Message Id — Enter the object identifier of an HL7 message body object. 

DocType or Schema for Message Data 

Click a radio button to choose a Source for HL7 Message DocType. The choices are: 

• ProductionName || ConfigName | CommentOrClassname — Choose from the drop-down list of 

production items. 

• Schema Category / Version — Choose an HL7 category from the drop-down list. 

• HL7 Message Type (Version:Name) — Enter the name of an HL7 message type () 

in the format category:type. The parser uses the message structure associated with the given 

message type. 



• Use this DocType — Enter the name of an HL7 message structure () in the 

format category:structure. The parser uses this message structure. 

• MSH declared Version:Name — The parser uses the message structure associated with the message 

type declared in the MSH segment of the message. 

• Object’s saved DocType — The parser uses the DocType as declared in the HL7 message body 

object. (This option does not apply to stored messages loaded from a file.) 

• None — The parser does not use any DocType to parse the message. It displays the raw segments 

without transforming any of them into links. 

Applying a Data Transformation 

If you want to apply a data transformation to the HL7 message data, select the Apply Data Transform 

check box and enter the full package and class name of an Ensemble data transformation. From here 

you have two options: 

• View the transformation on the [Ensemble] > [EDI and HL7 Manager] > [EDI Document Viewer] 

page. To do this: 

- Click one of the following radio buttons to determine the display format for the resulting HL7 

message data: 

• Show Output Only — The transformed message appears in place of the original message 

on the page. 

• Show Input and Output side-by-side — The format is the same, but you must use horizontal 

scroll bars to see all the data. 

- Click the View HL7 Message button. 

• Save the transformed message to a file. To do this, enter a pathname in the field beside the Save 

To File button and click the button. 

5.3.2 Parsing the Message 

After you enter your choices and click View HL7 Message, the Document Viewer page page displays 

a summary report, followed by the message data in the bottom half of the screen. The report looks like 

the following example. It echoes the Source, DocType, and Data Transform choices and reports the 

BuildMapStatus that resulted from the attempt to parse the message. In the following example, the 

BuildMapStatus reveals that an unrecognized Z-segment was found in the message. 



Document Viewer Parsing Summary 

Following this report, the Document Viewer page displays the message data. This is the same view 

available on the [Ensemble] > [Messages] page when the Contents link is selected and the message 

contains HL7 data. There is one row in the display for each segment in the message structure. From 

left to right, the entries in each line reads as follows: 

• The segment number on a white background: 1, 2, 3, etc. 

• The segment name on a shaded background: MSH, PID, etc. 

• Field contents and separator characters, exactly as provided in the message. 

5.3.3 Displaying the Segment Address 

If you hover the cursor over a segment name in the shaded column, a hover-text help window displays 

the following information: 

• The segment address to use in a virtual property path. 

• The descriptive name of this segment. 

See the following close-up from a Document Viewer display of message contents. The cursor is hovering 

over the segment name NK1 which is segment number 5. The segment address is NK1(1) and 

the meaning of the segment is “next of kin / associated parties.” 

Document Viewer Showing Hover-Text Help for Segment Address 



5.3.4 Displaying the Field Address 

If you hover the cursor over a field anywhere within the message structure, a hover-text help window 

displays the following information: 

• The field address to use in a virtual property path (as a number) 

• The field address to use in a virtual property path (as a name) 

• Characters that indicate the syntax rules for this field. The characters can begin with: 

Symbol 

! 

 

+ 

* 

& 

n* 

(m) 

Meaning 

(1 only) The field is required; it must occur only once. 

(0 or 1) The field is optional, but if it occurs, it may occur only once. 

(1 or more) The field may repeat one or more times. 

(0 or more) The field may repeat zero or more times. 

The field may be present, and may repeat, but only under certain 

conditions. 

(0 to n) The field repeats a maximum of n times. 

m is the maximum number of characters in the field. Each repeat of the 

field may contain this number of characters. 

See the following close-up from a Document Viewer display of message contents. The cursor is hovering 

over the second data item in the NK1 segment, which contains the string “Taylor”. The field 

address is 2.1 or Name.familylastname. The field may repeat zero or more times. Each repeat of the 

field has a maximum length of 48 characters. 


Document Viewer Showing Hover-Text Help for Field Address 


5.3.5 Viewing Batch Messages 

Suppose you enter choices and click View HL7 Message as described in the section “Viewing a Message.” 

Now suppose the message you have chosen to view is not a single HL7 message but a group 

of HL7 messages in batch format. Rather than open each batch message directly, the Message Viewer 

allows you to walk through the batch message structure one level at a time. 

The following display is the result of asking to view a batch message that begins with an FHS segment. 

Ensemble parses the batch message and finds that it has 3 segments: FHS, FTS, and a block of child 

documents in between. The block contains two child documents; each beginning with BHS and ending 

with BTS. The message is a two-level batch message. 

The Message Viewer assigns the child documents the identifiers and . It displays the toplevel 

parent document, using links ( and ) to represent the two child documents. The display 

is as follows: 

HL7 Batch Message with FHS and BHS,Top-Level Parent Document 

When you click on a child document link in an HL7 batch message display, a new browser window 

opens to display the child document. The Message Viewer window, with the top-level parent, remains 

open in the original browser window. 



The next display is the result of clicking the child document link in the previous display. This 

example is a two-level batch message, so the child document has children of its own: child documents 

through . 

This example highlights a useful navigation feature of the Message Viewer. If there are more than 10 

child documents in a batch message, the Message Viewer displays links to the first five and last five 

child documents. Between the lists is a text field, into which you can enter any identifier number 

between the first and last numbers. After you enter a number, click Other. A new browser window 

opens to display the child document. 

HL7 Batch Message with FHS and BHS, Mid-Level Parent Document 

The next display is the result of clicking the child document link in the previous display. Since 

this is the lowest level of the batch message hierarchy, message is a normal HL7 Version 2 message 

that begins with an MSH segment. 


HL7 Batch Message with FHS and BHS, Child Document 


When you are done viewing messages in the batch message hierarchy, you can close all the pop-up 

browser windows until the top-level parent document remains in the original Message Viewer window. 

From here, you may return to other Ensemble Management Portal activities. 

5.3.6 Saving the Output to a File 

While viewing the Document Viewer summary and message data that result from clicking View HL7 

Message, you might want to save the message data to a text file. If so, enter a value in the Save to File 

field to the right of the data transformation selections, and click Save to File. 

• If you enter a full path and filename, the file is saved to that location. The path must already exist 

on the system. 

• If you enter only a filename, the file is saved in the management directory for the active namespace. 

For example, if you installed Ensemble into the directory C:\MyCache and your current namespace 

is ENSEMBLE, the file is saved as follows: 

C:\MyCache\Mgr\ENSEMBLE\filename 



5.4 Filtering HL7 Messages 

The Ensemble Management Portal [Ensemble] > [Messages] page allows you to filter the Ensemble 

message archive based on fields in the message data. Even virtual properties can be searched, as long 

as you follow specific rules. You can: 

• Apply basic filter criteria, such as the time of day when the message was sent. 

• Apply detailed filter criteria, such as the presence of a specific field or value in the data. 

• Archive a specific set of filter criteria and retrieve it for later use. 

• Display a list of messages that match your filter criteria. 

• View, compare, or resend the messages in the list. 

For detailed instructions, see the section “Message Filter” in the “Message Browser” chapter of 

Managing Ensemble Productions. 

5.5 Comparing HL7 Messages 

The Ensemble Management Portal [Ensemble] > [Messages] page allows you to compare the contents 

of two messages. Select the check box beside each of two messages in the list, then click the Compare 

Messages link at the top of the page. The two messages display side by side. To return to the 

[Ensemble] > [Messages] page, click the browser’s Back button. 

For detailed instructions, see the section “Message Contents” in the “Message Browser” chapter of 

Managing Ensemble Productions. 


6 

Converting Interfaces to Ensemble 

The following diagram shows some of the information technology required to run a typical hospital. 

The diagram reflects the complex challenges faced by hospital IT staff. In the diagram, the various 

end-user applications exchange HL7 messages with the lab information system and hospital information 

system (HIS). An interface engine routes HL7 messages between the systems. Not all hospital applications 

are shown; the focus is on the HL7 messages that enter and leave the interface engine. 

This chapter assumes that for each clinical application, you might need to define both inbound and 

outbound interfaces. The figure illustrates this by providing a circle at the source of each type of 

message and an arrow at each destination. Various combinations of inbound and outbound interfaces 

are shown. Within this chapter, an interface is inbound or outbound relative to the clinical application. 

An inbound interface receives messages from the HIS or lab system via the interface engine. An outbound 

interface sends messages to the HIS or lab system via the interface engine. Other interfaces 

within the hospital IT configuration are outside the scope of this chapter, even if they appear in the 

diagram. 

In the diagram, solid arrows represent real-time information exchange; dotted arrows represent batch 

transmissions. Variations in arrow color highlight the different categories of data: green for admitting, 

yellow for pharmacy, gold for patients, orange for scheduling, pink for master file notifications, purple 

for transactions, aqua for requisitions, blue for laboratory, gray for physicians, and black for vendors. 



Hospital IT Configuration Featuring an Interface Engine 


Often when you bring Ensemble into such a configuration, it is for the purpose of replacing an existing 

interface engine with Ensemble. In order to do this you must: 

1. Use an Ensemble production as a routing engine, as described in previous chapters. 

2. Convert each of the existing interfaces to use the Ensemble routing engine instead of the previous 

interface engine. 

3. Once all of the interfaces are converted, remove the previous interface engine from the configuration. 

The conversion approach in this chapter leaves the existing interface engine in place and converts the 

interfaces one by one to use Ensemble. Unconverted interfaces continue to use the previous engine 

while you test and confirm that the new interface works properly using Ensemble. As soon as the 

converted interface works correctly, you begin work on the next unconverted interface. This incremental 

change policy ensures the best chance of uninterrupted, error-free service during the conversion. 

You could take an approach that converts groups of related interfaces at the same time. That is, you 

could decide to convert all of the interfaces that convey messages to and from the Blood Bank application, 

then move on to Fetal Monitoring. Still, you may find that the work boils down to converting 

one interface at a time. 

This chapter explains how to convert one existing HL7 interface to use Ensemble. The general steps 

are as follows. Each section of this chapter describes one of these steps in detail: 

1. Back up the production 

2. Describe the interface 

3. Choose schema categories 

4. Create data transformations 

5. Define routing rules 

6. Add business operations 

7. Create or edit a routing process 

8. Add business services 

9. Test the interface 

10. Deploy the interface 

The procedure in this chapter reverses the order in which you would usually describe an Ensemble 

production. (“An HL7 business service receives an incoming message...”) However, experience with 

interface conversion shows that if you develop the elements top-down, beginning with the business 

service and working down to the custom schema, you must often backtrack to previous steps to fill in 

or correct the names of the lower-level items, in the various forms where you have configured higherlevel 

items. 



The procedure in this chapter takes a bottom-up approach, reducing backtracking to a minimum by 

creating the lower-level items first, so that their names are known when it is time to configure the 

higher-level items. Bottom-up order works as shown in this chapter: Steps 1 and 2; Steps 3, 4, 5, 6, 7, 

8; Steps 9 and 10. 

You might have success performing this procedure in top-down order, especially if you have wellestablished 

naming conventions, which reduce simple errors. Top-down order works as follows: Steps 

1 and 2; Steps 8, 7, 6, 5, 4, 3; Steps 9 and 10. 

6.1 Backing Up the Production 

The following steps outline a general-purpose backup procedure for Ensemble productions that use 

HL7. The exact steps will vary depending on your packaging and naming conventions for Ensemble 

classes, custom classes, routing rules, and custom HL7 category definitions. 

Note: 

Regarding XML backup files: If you use a UNIX system, never FTP a backup XML file in 

binary mode. Regular FTP will convert this file from DOS to UNIX properly, but binary 

FTP might not. 

6.1.1 Backup from Studio 

To perform a full backup from Studio: 

1. Start Studio and change to the Ensemble-enabled namespace that you are backing up. 

2. Export your own package(s) of classes from Studio. This should export all of your business service, 

business process, business operation, data transformation, and utility classes. To back up a package: 

• Select the package name in the Workspace window 

• Right-click and select Export from the context menu. 

• Select the Export in XML format check box, choose an appropriate file name, and click OK. 

If necessary, rather than choosing a package you can select individual classes for export from 

Studio: 

• Select Tools and Export, then click Add. 

• Choose Files of type All Files, enter File name *.cls, then click Open. 

• Select your classes from the list and click Open to add them to the Export list. 

• Select the Export in XML format check box, choose an appropriate file name, and click OK. 


Backing Up the Production 

3. Export your own business rules (File name *.rul). 

4. Export your own Custom Schemas (File name *.hl7). 

5. The resulting XML file(s) can be imported into any Ensemble-enabled namespace. 

6.1.2 Backup from ObjectScript 

The steps in the above procedure can be cumbersome if you need to repeat them often from Ensemble 

Studio. You should code them into an ObjectScript method as soon as is convenient. The exact code 

will vary, depending on your packaging and naming conventions for Ensemble classes, custom classes 

(including data transformations), business rules, and custom category definitions. The general idea is 

that an ObjectScript version of this procedure would create a single master list of all items to be 

exported, and then export everything on the list to a single XML file, appropriately dated. In detail: 

1. Use the $system.OBJ.GetPackageList method with the ObjectScript $ORDER or $O function to 

assemble a list of all classes (*.cls) in each of the packages of interest. The code for each 

package will look something like the following example for a custom package named Mutro: 

do $system.OBJ.GetPackageList(.tList,"Mutro","ars") 

set class="" for { 

set class=$o(tList(class)) quit:class="" 

set tFullList(class_".cls")="" 

} 

For more information about ObjectScript functions like $ORDER and $EXTRACT, see the 

“Caché ObjectScript Functions” chapter in the Caché ObjectScript Reference. 

2. Use the Êns.Rule.RuleDefinitionD global and the $ORDER function to assemble a list 

of all business rules (*.rul) within the Ensemble-enabled namespace, something like the following: 

set p="" for { 

set p=$o(Êns.Rule.RuleDefinitionD(p)) q:p="" 

set r="" for { 

set r=$o(Êns.Rule.RuleDefinitionD(p,r)) q:r="" 

set tFullList(p_"."_r_".rul")="" 

} 

} 

3. Use the ÊnsHL7.Schema global and the ObjectScript functions $ORDER and $EXTRACT to 

assemble a list of all custom schemas (*.hl7) within the Ensemble-enabled namespace. In the 

following example, the list is easily created because the customer used a naming convention for 

custom schemas; all names start with the prefix Mutro_: 

set cat="" for { 

set cat=$o(ÊnsHL7.Schema(cat)) quit:cat="" 

if $e(cat,1,6)="Mutro_" set tFullList(cat_".hl7")="" 

} 



4. Set the output directory, construct the XML filename using a time stamp, and export the files. 

Something like: 

; Normalize the directory name and figure the file name 

if pDir'="" set pDir=$tr(pDir,"\","/") 

if $e(pDir,$l(pDir))'="/" set pDir=pDir_"/" 

for count=1:1 { 

set filename=pDir_"backup_"_$zdate($h,8)_"_"_count_".xml" 

quit:##class(%File).Exists(filename)=0 

} 

; 

; Export all the items on the list 

Set tSC=$system.OBJ.Export(.tFullList,pDir_"backup_"_$zdate($h,8)_".xml") 

Do:('tSC) $system.Status.DisplayError(tSC) 

; 

Set tSC=$system.OBJ.Export(.tFullList,filename) 

Do:('tSC) $system.Status.DisplayError(tSC) 

; 

write !,"Backup to file "_filename_" done.",! 

The above example expects a parameter pDir to be passed to the method, but pDir can quite easily 

be set to a specific directory by the backup method. The example uses the ObjectScript functions 

$TRANSLATE, $EXTRACT, $ZDATE, and $HOROLOG as well as the %File.Exists and 

$system.OBJ.Export methods. 

6.2 Describing the Interface 

Each clinical application in use at the enterprise provides its own HL7 application specification document. 

The specification document explains which types of HL7 event the application can send (or 

receive), and which message segments and pieces of each segment the application sends (or expects) 

for these events. For example, for an MSH segment the HL7 application specification document shows 

exactly what the segment will look like, what will be hard-coded, what format will be used for strings, 

etc. The information is extremely detailed. The administrator of each clinical application can show 

you this document for his or her application. 

The source and target applications each have an HL7 application specification document. However, 

any single interface between these applications, such as the interface that you are converting, uses a 

small subset of the possibilities listed in the specification document. Your best source for a description 

of an interface is actually the interface definition that you are replacing. 

Open the existing interface definition (for example, in eGate, the collaboration rule). With this definition 

in view, open a text file and type into it a brief description of what the interface does. Do not try to 

reproduce the coding conventions of the existing definition (LOOP, CASE, etc.) in detail. Simply 

identify: 

• The message segments that you expect to arrive from the source 

• How the interface changes them before sending them to the target 


In preparing a description of an interface that you are converting to Ensemble, it can be helpful to 

compare terminology between the technology you are replacing and Ensemble. As an example, the 

following table lists analogies between SeeBeyond and Ensemble terminology. 

Sample Comparison of Interface Terms: SeeBeyond and Ensemble 

Describing the Interface 

SeeBeyond 

Collaboration rule 

COPY or DUPLICATE 

DISPLAY 

LOOP 

IF 

CASE 

FUNCTION 

CHANGE-PATTERN 


Interface definition 

statement in a DTL data transformation 


or the shorthand notation () in DTL 


Routing rule 

Code in business services or business operations; also 

Text replacement using functions like $CHAR and $PIECE 

6.2.1 The Inbound Interface 

Suppose you have a source application from which a variety of HL7 messages arrive. However, only 

ancillary orders are of interest, and then only for certain types of patients, certain types of orders, and 

when the message is genuine and not a test of the system. In describing which messages are of interest 

from this source, you might type something like: 

Send only: 

Message Type "ORM_O01 " 

PV1:18 Patient Type = "ER" or "ECM" or "ERQ" 

ORC:1 Order Control = "NW" or "CA" or "OC" 

PID:5 Last Name not "TEST" 

6.2.2 The Outbound Interface 

How the interface changes these message segments, before sending them, depends on what the target 

application needs to receive. Based on your knowledge of the interface and the sources of information 

listed above, you might type something like: 

Copy source MSH to target. 

Set target MSH:11 Processing ID = "P". 

Copy source MSH:10 Control ID to target MSH:13 Sequence Number. 

Copy source PID to target. 

Set target PID:1 Set ID = "1". 

Copy source PID:2 Patient External ID 

to the 2nd repetition of target PID:3 Patient Internal ID and 



set its Identifier Type = "PI". 

Null out target PID:2. 

Copy source ORC to target. 

If source ORC:1 Order Control = "CA" or "OC", 

then set target ORC:5 Order Status to "CA". 

If source ORC:2.1 Placer Order Number is empty, then 

copy source ORC:3.1 Filler Order Number 

to target ORC:2.1 Placer Order Number and 

set target ORC:2.2 Placer Application = "ULTRA". 

Set target ORC:3.2 Filler Application = "ULTRA". 

Copy source OBR to target. 

If source OBR:2.1 Placer Order Number is empty, then 

copy source OBR:3.1 Filler Order Number 

to target OBR:2.1 Placer Order Number and 

set target OBR:2.2 Placer Application = "ULTRA". 

Set target OBR:3.2 Filler Application = "ULTRA". 

Set target OBR:4.3 Coding Scheme (SIM Department) = "LAB". 

6.3 Choosing Schema Categories 

In this step, you must determine which HL7 schema will be used for the inbound and outbound sides 

of the interface. This begins with an approximate choice, which you refine by testing messages against 

that schema in the Ensemble Management Portal. 

Each clinical application has an HL7 application specification document that identifies the HL7 schema 

version that it uses when sending messages, and that it expects when receiving messages. You can 

confirm this version against the message data sent by the application. Its outgoing message MSH 

segment states an HL7 version number that (in theory) announces what HL7 version the application 

is using. 

You may discover that neither source of information is strictly accurate. Clinical applications can 

update their HL7 versions at different times so that one application uses a new HL7 version and another 

does not. Applications can upgrade HL7 versions or add or change Z segments or without changing 

the contents of the MSH segment or documenting the change. 

6.3.1 Choosing an Incoming Schema Category 

Choose a schema category for the inbound side of the interface (as the message enters Ensemble via 

an HL7 business service) as follows: 

1. Capture some sample messages from the source application in text files. You can use archived 

file copies of these messages, if you have them. 


3. Choose the EDI / HL7 Manager menu, Schema Structures option, browse, and choose an HL7 

standard schema that seems to match the structure of the message segments you are interested in. 


Creating Data Transformations 

4. Choose the EDI / HL7 Manager menu, Message Viewer option, and test your text file messages 

against your chosen schema. Try different choices of schema until you find the standard schema 

that most closely matches your message structure. 

Tip: 

Do not be concerned with the specific HL7 separator characters expected on each side of 

the interface. The HL7 business operation handles these appropriately. 

5. The messages from the source application might contain extra segments that are not in the schema. 

If so, when you parse the messages using the Message Viewer option, the messages may either 

accept the message, or generate a bad message error, as follows: 

• If the message contains extra Z segments, and the schema defines those Z segments, the 

message is okay. 

• If the message contains extra Z segments, but the schema does not define any Z segments, 

the message is okay. 

• If the message contains extra Z segments, and the schema defines Z segments, but the Z 

segments found in the message do not match the Z segments in the schema, it is a bad message. 

• If the message contains extra non-Z segments, then regardless of Z segments, it is a bad 

message. 

6. If the messages trigger one of the bad message error conditions, try choosing a different standard 

schema, and if that does not work, you must create a custom HL7 category definition to accommodate 

the non-standard message structure. 

6.3.2 Choosing an Outgoing Schema Category 

Repeat a similar procedure to choose a schema for the outbound interface. 

6.4 Creating Data Transformations 

Create DTL data transformations. For details, see the “DTL Data Transformations for HL7” section 

in the chapter “Elements of a Routing Production.” 

6.5 Defining Routing Rule Sets 

Create routing rule sets. For details, see the “Routing Rule Sets for HL7” section in the chapter 




6.6 Adding Business Operations 

The business operation for an HL7 interface controls the outgoing message transmission to the target 

application. For testing purposes, it is useful to configure a production with two HL7 business operations 

that have the same configuration name: 

• One is an FTP or TCP business operation that controls the FTP or TCP transmission of HL7 

messages across the interface when the production is running normally. 

• The other is a File business operation that sends HL7 messages to a file during testing or troubleshooting 

of the interface. 

By Ensemble convention (the items have the same configured name) only one of these configuration 

items can be enabled at a time. Enable one or the other depending on whether you want a “test” environment 

(the File operation) or a “live” environment (the TCP or FTP operation). 

The steps to create a “live” business operation and its “test” counterpart are as follows: 

1. Examine the target application to see which separators it expects HL7 messages to contain. 

2. Create the “live” (FTP or TCP) HL7 business operation as described in previous chapters. 

3. Use similar steps to create a “test” (File) HL7 business operation. 

Give the “test” (File) operation the same configuration Name as the “live” one. 

4. Use the Enabled field to enable and disable the “live” (FTP or TCP) or “test” (File) versions of 

the business operation. Only one business service of the same name can be active at one time. 

6.7 Creating or Editing a Routing Process 

To enable your new interface to work with the Ensemble routing engine, you must add a routing process 

to the production that: 

1. Tells how to interpret data from the source (identifies a routing rule) 

2. Tells where to send the interpreted data (identifies a business operation) 

You can create a new HL7 routing process as described in previous chapters. 


Adding Business Services 

6.8 Adding Business Services 

The business service for an HL7 interface receives the incoming messages from the source application. 

For testing purposes, it is useful to configure a production with two HL7 business services that have 

the same configuration name: 

• One is an FTP or TCP business service that receives HL7 messages from the source application 

via FTP or TCP when the production is running normally. 

• The other is a File business service that receives HL7 messages from a file during testing or 

troubleshooting of the interface. 

By Ensemble convention (the items have the same configured name) only one of these configuration 

items can be enabled at a time. Enable one or the other depending on whether you want a “test” environment 

(the File service) or a “live” environment (the TCP or FTP service). 

The steps to create a “live” business service and its “test” counterpart are as follows: 

1. Create the “live” (FTP or TCP) HL7 business service as described in previous chapters. 

2. Use similar steps to create a “test” (File) HL7 business service. 

Give the “test” (File) service the same configuration Name as the “live” one. 

3. Use the Enabled field to enable and disable the “live” (FTP or TCP) or “test” (File) versions of 

the business service. Only one business service of the same name can be active at one time. 

6.9 Testing the Interface 

Generally you need to maintain a separate “test” production that is an exact copy of the production 

that runs “live” at your health facility. Develop the new Ensemble interface within the “test” production. 

When that is done, you can migrate a copy of the new interface to the “live” production. 

To test a new interface: 

1. Capture some sample messages from the source application in files. 

2. In the “test” production, enable the File business service and the File business operation and send 

the messages as files. 

3. Examine the resulting HL7 message data in the output files to see if it meets the requirements for 

the target application. 

4. If necessary, adjust the interface elements and retest. 



5. Selectively disable the “test” (File) versions and re-enable the “live” (FTP or TCP) versions of 

the business service and business operation, still within the “test” production. 

6.10 Deploying the Interface 

Once you have completed testing the Ensemble interface in the test production, it is time to add the 

new Ensemble interface elements to the production that you are running live. To do this: 

1. Back up the complete live production as described in the first step of this procedure. 

2. Export the new elements of the test production, created in the previous steps: 

• Export the new classes for the interface: business process, data transformation(s), business 

operations, business services, and any utility classes. 

• Export the business rule(s) *.rul 

• Export the custom schema(s) *.hl7 

3. Copy the new XML elements that the new interface added to the XDATA section of the 

production class. For example: 

Configuration Item 

Business service (Test) 

Business service (Live) 

Business process (if new) 

Business operation (Test) 

Business operation (Live) 

Sample Start of Element 

Deploying the Interface 

5. Optionally, configure alerts for the new production elements: 

• HL7 business service and business operations have a configuration setting called Alert On 

Error. When Alert On Error is set to True, as soon as the item encounters any type of error 

condition it automatically triggers an alert. An alert writes a message to the Ensemble event 

log and can also send notification to a user via email or pager. Setting Alert On Error to False 

disables the option. 

• Alert Grace Period (for business services) and Alert Retry Grace Period (for business operations) 

offer useful constraints on the frequency of alerts when they are enabled. 

Note: 

This procedure describes how to add interfaces to the “live” production one by one. 

Alerts are easy to configure as described in this step, once they have been set up. To set 

them up for the “test” or “live” production, see the “Pager and Email Alerts” section 

in the chapter “Elements of a Routing Production.” 

6. Ensure that the new interface is processing all new messages. 

7. Disable or clean up the previous interface technology: 

• Ensure that all previously pending requests are satisfied and all queues are empty. 

• Disable the old interface. For eGate elements, disable the “start automatically” option.

Ensemble HL7 Version 2 Development Guide - InterSystems ...

Create successful ePaper yourself

Delete template?

Save as template?