The Template device allows you to take any incoming HL7 message and transform it into CDA (or HTML) document using a template, as defined by your organization. The transformation is handled by C# or VB code. It is just like any other custom code device, except it comes pre-populated with template code. You can write your own or use the provided samples.

Understanding the UI

The Template Device panel is divided into three main areas.

The area in the upper left displays the code that is currently being edited, as well as a toolbar with the following activities:

• Set code language: Set the code language to either C# or VB. Note that changing the code language will discard the current code document and load a blank template.
• Run the start method
• Find text within the code
• Comment out the selected lines of code (meaning that the lines will not be executed when the device is run)
• Uncomment out the selected lines of code (meaning that the lines will be executed when the device is run)
• Collapse to definitions: collapse the code so that only the highest level definitions are visible.
• List available code snippets: display a list of code snippets that are available for use.
• Copy device to Visual Studio: copy all device code so it can be pasted into Visual Studio and edited.
• A drop-down that shows the methods available for editing (choosing a method will jump directly to that code in the device)

At the bottom of the screen, are two panes that will let you preview the results of the Template device file creation (located on the Run Transform tab). The pane on the right displays the incoming file; the one on the left will preview the finished document. If there are files in the queue, click Start to preview the HTML/CDA file creation results using the template code and context as defined in the device setup. At the very bottom of the preview panels are several tabs that can be used for troubleshooting/debugging the device code (see "Troubleshooting the device" below).

The panel on the right lists the external files and references to be used with the device. If any references are present, you can expand the tree node to view and configure them.

To manage a reference:

1. Right-click on the appropriate tree node and choose Manage References.
2. A pop-up window will appear, listing all .NET and Device references available. If you see the reference you want to use, check the box in the Include column.
3. To add a reference, click Browse, navigate to the location of the reference DLL, select it, and choose Open.

To add a resource:

1. Right-click on the Resources tree node and select Add Resource.
2. Navigate to the location of the resource file, select it, and choose Open.

To add a data connection:

1. Right-click on the Data Connections tree not and select Add Database Connection.
2. Configure the connection and click OK.

The tree contains three other nodes.

Viewing the Code node

The Code tree node displays all of the code currently associated with the device and is pre-populated with two types of Code: the Template Code and the Template Context. Select one of these to view and edit the associated code (see Editing Code below). You can also add a new code object:

1. Right-click on the Code tree node and choose Add Code File.
2. A new tree node will appear with a default class name (e.g., Class1). To rename this class, right-click and choose Rename File.
3. Select the new class to edit the associated code.

The right-click context menu also provides options for deleting the class and locking the file so that other users cannot edit the code.

Viewing Event Publications

Each device in a Connexion channel fires off an "event" when it processes. Using a custom code device (such as the Template device), you can create custom validation routines for messages. For example, you may receive messages in a non-standar format. Using custom validation, you can accept these messages for processing even if they don't conform to an HL7 standard.

The Template device ships with two standard Event Publications: BeforeDecideProcessMessage and AfterDeviceProcessMessage.

To use the event in your code:

1. Select the code item you want to add the even to.
2. Drag the event into the proper place in the code OR right-click on the event and choose Copy Event Subscription Code. The locate the place in the code where you want to insert the event, right-click, and choose Paste.
3. Modify the event code as necessary and save the device.

As you modify, the device will check the compile. Any errors will be displayed on the Compile Errors tab of the Input pane.

Viewing Templates

The templates associated with the device will dictate how the HL7 message will be transformed into the target file. The device ships with two standard templates: one for HTML and one for CDA. Select the template in the tree node to view the template code. The standard templates include some basic help text (highlighted in yellow).

You can add a new template or modify the existing templates.

1. Right-click on the Templates node and choose Add template.
2. The new template appears in the tree (e.g., Template1).
3. Select the template to edit it in Connexion. Right-click to rename the template or delete it.

Editing the device

You can edit Template Code, Template Context, or individual templates within Connexion. Each of these components plays a role in the processing of the device.

Editing template code

The Template Code identifies variables that will be passed to the template, as well as identifying the specific template to use with the device. The Template Code contains one public class called CustomDevice. The name of this public class cannot be changed. From the code, you will call the name of your template.

You can edit the sample Template Code that is standard with the device or create your own code. Code can be written in either C# or VB.

Above is a sample of Template Code. Code can be written directly in Connexion, or copied to Visual Studio for editing.

Editing template context

The template context is an object that the Razor engine uses to get the values for the template. In essence, the Template Context is called by the Template Code and tells the Razor engine where to pull the values that are inserted into the template. The device must include at least one Template Context, which is created by the user. You can use the sample context provided or create your own.

As with the Template Code, you can edit the sample provided with the device, or write your own. The Template Context can be coded in either C# or VB.

Above is a sample Template Context. Code can be written directly in Connexion, or copied to Visual Studio for editing.

Editing the template

The template used by the device will map segments and fields in the HL7 message to the target output. Templates can be written for HTML or CDA documents. At the top of the template, you will specify the context to use by the "@model <name>. If you use one of the sample templates provided with the device, you will not need to change this. If you create your own template, you must include this context call.

As with the Template Code and Context, you can choose to modify the sample templates included in the device or create your own. The template will be called by the device based on the Template Code and Template context. Any variables that must be passed to the template are defined in those two areas. Because the template device uses the Microsoft Razor templating engine, there are tutorials available online that can assist with template creation.

As a general abstraction, each segment/field of the HL7 message must be mapped to a section of the template by defining the variable in the Template Context and passing that variable to the template. In the below illustration, you can see how the elements of the Attending Physician Name are defined in the Template Context and then passed to the template, where they are written to the appropriate element in the CDA document layout.

For additional information on coding the template, see the highlighted notations in the provided template samples.