Skip to content

Your First Message

Nityan Khanna edited this page Apr 9, 2017 · 1 revision

Everest contains a 1:1 mapping of .NET/Java classes to the underlying HL7v3 message structure. This decision makes debugging easier and more intuitive (i.e.: if a remote system tells you something is wrong with X, it is called X in the class model).

What’s in an Instance?

An instance is the term used to describe an instantiation of an RMIM class in memory. RMIM classes are generated from MIF files provided by various standards development organizations. RMIM classes in Everest are more than just empty class structures; they contain vital meta-data about how the instance “looks” in the wire.

Your RMIM instance contains the data that will ultimately be serialized and sent somewhere, be it a file, remote system or another function. HL7v3 instances contain all the necessary data for a remote system to process the message in a reliable manner.

Complex structures in Everest are comprised of simple data types, .NET/Java collections (such as List/ArrayList respectively) and other complex structures. The following properties are pre-populated for you whenever you create a structure with Everest:

· Any .NET/Java collection is pre-initialized so you can simply call the Add method on the property. You can also overwrite this property with your own instance of a collection.

· Any fixed values in the message instance are populated to their fixed value and getters are provided (they are hidden in Everest .NET as to not confuse developers). Fixed values can be reset (i.e.: the Code property can be set to something different); however, these are usually not interpretable by remote systems.

· Any properties that have a default value assigned in the MIF will be populated with the default value. Developers can override the default by setting a new value.

RMIM structures also contain a variety of constructors, creator methods and utility functions that make your life easier. Each of these concepts is covered in the “Everything about RMIM Structures” section (page 127) of this chapter.

Choose a Structure

Any structure in Everest can be the “root” of serialization. What does that mean? Well any class in the MARC.Everest.RMIM.X namespace can be graphed to the wire and parsed by the Everest Framework. However, not that doesn’t mean that all structures should be serialized in this manner.

There are two types of classes that should be used as the root of graphing:

· HL7v3 Interactions – These are messages that are triggered in reaction to an event that has occurred. These classes can be found in the RMIM.XX.YYYY.Interaction namespace and have names like REPC_IN000000UV (..rmim.xx.yyyy.interaction package in Java).

· Entry Point Structures – These are special RMIM structures that have been marked as appropriate for the start of serialization. An example of this is the ClinicalDocument class in the MARC.Everest.RMIM.UV.CDAr2 assembly (org.marc.everest.rmim.uv.cdar2.jar for Java). These are identified by the IsEntryPoint property on the Structure attribute attached to the class definition.

Of course, choosing a structure depends entirely on the task at hand. If serializing some data for future reference, then any class may be selected. If the application is attempting to send a CCD, Referral or other clinical document, the ClinicalDocument class from the CDA assembly might be appropriate.

This chapter will use the PRPA_IN201305UV02 message (find candidates) to illustrate the construction of an instance.

This guide doesn’t make an assumption about the development environment being used, so all examples provided will simply assume a program with one class named Program in .NET or Java.

Code the Instance

Add References

Using any development environment, create a new project. The first step to creating an instance in Everest is to let your program know where the Everest code is located on your hard drive.

In most programming environments this is known as a reference. Everest libraries are installed in the “lib” folder of your Everest installation. In order to use Everest, the libraries listed below will need to be referenced by your project.

Component

Assembly (.NET)

Everest Core

MARC.Everest.dll

HL7v3 Structures

MARC…RMIM.UV.NE2008.dll

Data Types R1 Formatter

MARC...ters.XML.DataTypes.R1.dll

XML ITS 1.0 Formatter

MARC...Formatters.XML.ITS1.dll

 

Once these references are created for your project, you’ll need to import the necessary namespaces into your program file. The example below illustrates the necessary code for referencing namespaces.

using MARC.Everest.DataTypes; // Everest Data Types 
using MARC.Everest.RMIM.UV.NE2008; // Normative Ed. 2008

using MARC.Everest.RMIM.UV.NE2008.Interactions; // Interactions

using MARC.Everest.RMIM.UV.NE2008.Vocabulary; // Vocabulary

using MARC.Everest.Connectors.File; // File Connector

using MARC.Everest; // Everest Namespace

using MARC.Everest.Formatters.XML.Datatypes.R1; // DT R1 formatter

using MARC.Everest.Formatters.XML.ITS1; // XML ITS1 Formatter

Visual Studio Wizards

When creating a new project in Microsoft Visual Studio 2008, 2010 or 2012, the manual adding of references and namespaces can be skipped. The Everest Framework contains several project templates that can greatly simplify the creation of an Everest project.

To create a new Everest project in Visual Studio, start a new project and select the Everest template parameters.

image

Select the “Everest Console Application Wizard” option and name your project. After clicking the “create” button, an Everest Wizard will appear which will let you select the release and supporting assemblies to reference.

image

After selecting the message type assembly and supporting libraries, click finish. You’ll notice that Everest’s wizard has automatically selected the most appropriate assemblies and added them to your project.

image

 

Create the Instance

After the references and imports are completed the instance needs to be constructed. The interaction that is being created is a PRPA_IN201305UV02 interaction which should be shown in the help window as a find candidate query.

To create an instance of the interaction, a simple call to the constructor can be used. The “Everything About RMIM Structures” chapter (page 127) discusses more advanced methods of creating RMIM structures). The example below illustrates using the full constructor to create the instance.

PRPA_IN201305UV02 instance = new PRPA_IN201305UV02(

   Guid.NewGuid(), // Every message needs a unique identifier

   DateTime.Now, // Identify when the message was created

   PRPA_IN201305UV02.GetInteractionId(), // Identify the interaction

   ProcessingID.Training, // Identify the process mode for the receiver

   "I", // Identify the receive mode for the interaction

   AcknowledgementCondition.Always // Identify when we want a response

);

Setup a Formatter

The process of formatting in Everest is flexible and permits the mixing of formatters into hosts and graph aides. In short, a host formatter is a stand-alone formatter that is used to graph any type of instance to the wire and has the capability to classify a type based on wire format data (i.e.: if root element is X then parse into Y). An example of a stand-alone formatter is the XML ITS 1.0 formatter.

Graph aides are formatters that cannot be used on their own and exist only to help the primary formatter. Graph aides are usually intended for data types or very few types that require special graphing considerations.

Formatters are covered in more depth in Chapter 5 of the Everest Developer’s Guide. The example below illustrates the setting up of the XML ITS1 formatter with the Data Types R1 formatter aiding in the graphing process of data types.

var xmlIts1 = new XmlIts1Formatter();

xmlIts1.ValidateConformance = false;

xmlIts1.GraphAides.Add(new DatatypeFormatter());

Save the Instance

Everest is flexible in the facilities it provides for saving instances. Formatters can be used directly to save instances using streams, or they can be appended to a connector and instances can be “sent” via the connector to a file store (connectors are covered in more detail in Chapter 6 of the Everest Developer’s Guide book).

The example below shows how to use the formatter to graph directly to the console window

Stream output = Console.OpenStandardOutput();

try
{
   
xmlIts1.Graph(output, instance);

}

finally

{

     output.Close();

    xmlIts1.Dispose();

}