Ensemble Best Practices
Converting Interfaces to Ensemble
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

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.
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:
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 higher-level 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 well-established 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.
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.
Backup from Studio
To perform a full backup from Studio:
  1. Start Studio and change to the 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:
    If necessary, rather than choosing a package you can select individual classes for export from Studio:
  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.
Backup from ObjectScript
The steps in the above procedure can be cumbersome if you need to repeat them often from 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 ObjectScript Functions chapter in the Caché ObjectScript Reference.
  2. Use the ^EnsHL7.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(^EnsHL7.Schema(cat)) quit:cat=""
      if $e(cat,1,6)="Mutro_" set tFullList(cat_".hl7")=""
      }
    
  3. Set the output directory, create 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.
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 hardcoded, 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:
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.
SeeBeyond Ensemble
Collaboration rule Interface definition
COPY or DUPLICATE <assign> statement in a DTL data transformation
DISPLAY <trace> statement in a DTL data transformation
LOOP <foreach> or the shorthand notation () in DTL
IF <if> statement in a DTL data transformation
CASE Routing rule
FUNCTION Code in business services or business operations; also <code>
CHANGE-PATTERN Text replacement using functions like $CHAR and $PIECE
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"
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".
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 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.
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.
  2. In the Management Portal, use the HL7 Schema Structures page to find an HL7 standard schema that seems to match the structure of the message segments you are interested in.
  3. Use the Message Viewer page to 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.
  4. 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:
    For background, see Controlling Message Validation in Ensemble Virtual Documents. For HL7 details, see the reference for the Validation setting in the Ensemble HL7 Version 2 Development Guide.
  5. If the messages trigger one of the bad message error conditions, try choosing a different standard schema.
    If that does not work, create a custom HL7 category definition to accommodate the nonstandard message structure. See Creating Custom Schema Categories in Ensemble Virtual Documents.
Choosing an Outgoing Schema Category
Repeat a similar procedure to choose a schema for the outbound interface.
Defining Routing Rule Sets
Create routing rule sets. For information, see Defining Routing Rule Sets for HL7 in the Ensemble HL7 Version 2 Development Guide.
Creating Data Transformations
Create DTL data transformations. For information, see Defining DTL Data Transformations for HL7 in the Ensemble HL7 Version 2 Development Guide.
Adding Business Operations
The business operation for an HL7 interface controls the outgoing message transmission to the target application. For information on adding HL7 business operations, see Configuring the Production in the Ensemble HL7 Version 2 Development Guide.
For testing purposes, it is useful to configure a production with two HL7 business operations that have the same configuration name:
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.
  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.
For additional details, see Working with Multiple Versions of a Business Host in Configuring Ensemble Productions.
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. For details, see Configuring the Production in the Ensemble HL7 Version 2 Development Guide.
Adding Business Services
The business service for an HL7 interface receives the incoming messages from the source application. For information on adding HL7 business services, see Configuring the Production in the Ensemble HL7 Version 2 Development Guide.
For testing purposes, it is useful to configure a production with two HL7 business services that have the same configuration name:
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.
  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.
For additional details, see Working with Multiple Versions of a Business Host in Configuring Ensemble Productions.
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.
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:
  3. Copy the new XML <Item> elements that the new interface added to the XDATA section of the production class. For example:
    Configuration Item Sample Start of <Item> Element
    Business service (Test) <Item name="App1toApp2_In"
    Business service (Live) <Item name="App1toApp2_In"
    Business process (if new) <Item name="App1toApp2"
    Business operation (Test) <Item name="App1toApp2_Out"
    Business operation (Live) <Item name="App1toApp2_Out"
  4. Transfer the new interface elements to the live production as follows:
  5. Optionally, configure alerts for the new production elements:
    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 Pager and Email Alerts in the Ensemble HL7 Version 2 Development Guide.
  6. Ensure that the new interface is processing all new messages.
  7. Disable or clean up the previous interface technology: