The Connexion engine operates on the concept of channels and devices. A typical device performs a specific operation or set of operations. By chaining together a series of devices into a channel, input messages can be manipulated and directed to specific outputs. Connexion ships with many built-in devices and has native support for user-created devices.

For example, if the Inbound HL7 Device (receives HL7 via MLLP), HL7 Transform Device (modifies HL7 messages), and Outbound HL7 Device (sends HL7 via MLLP) are added to a channel, that channel will receive, transform, and send HL7 messages.

By varying the device types, device ordering, and individual device configuration, an extremely broad spectrum of workflows are possible.

Channel Operations

Connexion ships with one built-in channel, the System Channel. This channel contains specialized system-wide devices for documentation, email, eventing, databases, and change-tracking. In addition, you can create custom channels to handle a wide variety of processing needs.

To start, launch the client application. If the client application successfully connects to the Connexion service, it should appear as follows: 

In the above illustration, no channels have yet been created. If channels did exist, Connexion would display the Dashboard tab.

The two warning links appear if you have not configured administrator email settings or database backup settings. These can be set now, by clicking each link and entering the required information or set at a later time.

Creating a channel

Below are the steps for creating a basic channel. Note that you can select many more devices than described in the example, depending on the complexity of your processing needs.

First, click the Create New Channel button to display the Channel Properties dialogue. (Note: This button is also available on the Server Bar.)

Enter a name for your channel, and then click the first (top) drop-down control which displays <Select Device>. Navigate to the HL7 category and select the HL7 Inbound Device.

Then choose the last (bottom) drop-down control, navigate to the File IO category and select the File Writer Device. Your Channel Properties dialogue should appear as follows:

Click the Save Channel button to save and close the Channel Properties window. Congratulations! You just created your first channel.

Before you can run this channel, you may need to configure device-specific information (for example, the File Writer Device in the example above). See Configuring a Device below for additional information.

Once the channel is created, it will appear in the Channel pane, along with its own set of toolbar options and information. The heading will display the name of the channel (e.g., My first channel) as well as the channel status (Stopped, Running, etc.).

The Channel toolbar

Each channel contains its own toolbar.

Use the options on the toolbar to:

• Start Channel
• Pause Channel
• Edit Channel Settings (add/remove devices from the channel)
• Deploy Channel Changes (i.e, save changes made to device settings within the channel)
• Revert Channel Changes (i.e., discard changes made to device settings and restore the original channel)
• Lock the channel (against changes by others)

Channel statistics

Next to the toolbar is a channel-specific message count. These messages are categorized the same way as they are for the server message counts.

Configuring a channel

Before a channel can be configured (or the existing configuration can be edited), the channel must be stopped. Click the Stop icon to pause channel processing.

To edit channel configuration:

1. Stop the channel.
2. Right-click on the header and select Edit Channel or click the Edit Channel Settings icon.
3. Make changes as required to the channel (add/edit/delete devices).
4. Click Save.

When you are finished, resume channel processing by clicking the Play icon.

Importing a channel

From a file

Channels can be imported from 'channel files' (.cxn). Channel files can contain multiple user-defined channels as well as the system channel (which contains information about channel grouping). Channel files automatically carry dependencies such as custom devices, referenced assemblies, and resources. This means that a channel file from one system can be easily and quickly copied to another.

Double-clicking a file with a .cxn extension, or dragging a .cxn file into the client will trigger the import process.

Channel files use the Zip format, and as such, can be viewed by external zip viewers such as 7Zip. They can also be optionally encrypted using AES-256.

To import a channel from within Connexion:

1. Click on the Import Channel(s) from the File icon in the channel toolbar.
2. Navigate to the location of the *.cxn file on your computer.
3. Click Open.

Using Package Manager

The Package Manager allows you to import devices and channels that may have been created by others (such as Inner Harbor) and are stored somewhere other than your local system.

To use the Package Manager:

1. Click on the Open Package Manager icon in the channel toolbar.
2. Click on the Connexion tab. You will see various sub-tabs containing elements that can be imported into your installation of Connexion (channels, devices, etc.).
3. Click on the Channel tab, select the desired channel, and click Install.

If all of the required elements exist, the channel will be installed. If not, you may first need to install any devices used by the channel that are missing from the Connexion installation. See Device Operations for more information.

Exporting a channel

Channels can also be exported to .cxn files. This allows channels to be easily moved to other Connexion installations.

To export a channel:

1. Select the channel you want to export in the Channel pane.
2. Right-click and choose Export Channel.
3. Specify a destination path for the exported file. If there is an existing file, choose whether to overwrite it or append information to the existing file.
4. If desired, specify a password for the exported file.
5. Choose whether you want to exclude anything from the exported file (such as custom device assemblies). By default, all information associated with the channel (including custom device assemblies) is included.
6. Click Export.

Deleting a channel

If a channel is going to be temporarily out of use, it can be stopped for as long as necessary. However, if a channel becomes permanently obsolete, it can be deleted. Only delete a channel if you are absolutely sure it will not be needed again. You may want to export the channel for safekeeping, prior to deletion, in case it is needed again.

To delete a channel:

1. Select the channel in the Channel pane.
2. Right-click on the channel and select the delete channel button from the drop-down menu as shown in the figure below.

Device Operations

Connexion ships with many standard devices. Additionally, you can code your own custom devices.

Available devices

When you install Connexion, you will have access to several standard devices, as well as the ability to code your own devices. These include devices to send and receive messages, write files, transform messages, or perform database operations. All of these devices contain their own configuration options. See Configuring a device for more information on setting device options.

The Queue device

The Queue is a special built-in device that is an integral part of almost all channels. At the server level, messages received via one or more devices (for example, an Inbound HL7 device) are stored pending further processing. As processing time is available, messages are removed from the queue and processed by downstream devices. This allows Connexion to receive large volumes of messages independent of channel complexity or available processing time.

The queue also provides a convenient "gateway" mechanism which allows a channel to receive messages but not process them. If the queue is paused, it will receive messages but not forward them to the next device. Starting the queue will then cause any stored messages to be processed by downstream devices.

On the client, the queue provides a mechanism to filter and view messages, message modifications, and processing histories for received messages.

There are four queue states available:

• Queued (Q): The message has been received and stored on the queue.
• Processed (P): The message has been successfully processed.
• Errored (E): An error was encountered and the message could not be processed.
• Filtered (F): During processing, a specific user-defined condition was met and the message was removed from processing. 

Configuring a device

Within a channel, select a device to see the available configuration options.

<screen shot>

It is not necessary to pause a channel to change a device's configuration.

Available device configuration options will be loaded in the Device pane. Each type of device will have different configuration options. Most of these options are self-explanatory but contact Inner Harbor support with any questions.

Configuring in the example channel

In our channel example above, we must configure the options for saving our message files. Click the File Writer Device icon and in the Destination field, enter a path where your HL7 messages will be saved. Please note that the Connexion service may require write permissions on your destination directory (The default Connexion service account is __cnx_user__). 

Next, we need to add a condition that will trigger our file to be written. Select the Conditions tab, click the Add button and select Maximum Message Count. 

Enter a value of 10, and then click the Save button (or use the keyboard shortcut CTRL + S). 

Pausing a device

Some devices, such as the Queue, can be paused independently of the channel. If a device can be paused, it will display a play/stop button as illustrated below:

Pausing a device halts processing for that specific device, but will not halt processing for the channel. In the case of the Queue, pausing means that messages will be received (e.g., from the HL7 In device), but will not be sent on for further processing (e.g., to a transform or file writer device). When a Queue is paused, you will see the Queued (Q) statistic increase, but the other statistics (P, E, and F) will not change.

In the case of an inbound device (such as the HL7 Inbound device above), pausing the device means that messages will not be accepted and passed to the queue. In this instance, the queue may be running, but the Inbound device is not accepting and passing messages, so the Queued (Q) statistic will not change.

Importing a device

Like channels, devices can be imported from files (*.dll) or from the Package Manager.

Importing from file

If you have built a custom device, you can import that *.dll into Connexion.

1. Click the Import Custom Device button in the System Toolbar.
2. You will see a message reminding you that the device and all dependent dlls must be included. Acknowledge the message by clicking Continue.
3. Navigate to the local of the *.dll file(s) on your computer and select it/them.
4. Click Open.

Once the *.dlls are imported, the device can be used within Connexion channels.

Using the Package Manager

As with channels, you can import/import devices from the Package Manager. Remember, there are instances where devices must be installed before installing channels

1. Click the Open the Package Manager icon.
2. Click the Connexion tab.
3. Click the Devices tab.
4. Select the desired device and click Install.

Testing the channel

If you've been following the sample, you now have a running channel which will receive messages via MLLP, store them in a queue, and, once the queue is un-paused, save them to files in a specific folder. Let's send in some messages. Make sure your Queue is paused. Open a copy of HL7Spy [Evaluation Version], click Tools > Send Messages (MLLP) or press CTRL+ALT+S. Click the Add a new destination icon (the green "+") to add a new destination (localhost, port 11000). 

In HL7Spy, click the All button to send the messages to localhost:11000, which your channel is listening on. You should notice your channel's queue Q (queued) count increasing. 

Now un-pause the queue by clicking the stop button in the top-left corner of the queue icon. You may need to wait up to 30 seconds for processing to begin, but once it does, you should see the Q (queued) count decrease and the P (processed) count increase. 

Let's confirm that we wrote files with 10 HL7 messages each. 

Okay, good. Now let's take a closer look at the messages we received. Click the Execute Filter button in the device bar to populate the queue with messages. The queue device contains many features to let you filter and correlate messages, re-process, purge, export etc. See The Queue device section for an in-depth look at queues. 

Modifying messages

Most channels have some sort of message modification requirement. Let's update this channel to modify the HL7 messages before we write them to disk. First, stop the channel. Only stopped channels can be edited (editing device configurations does not require your channel to be stopped). Then click the edit channel button to open the Channel Properties dialogue. 

Let's insert an HL7 Transform Device after the queue. Click the Insert icon after the queue, and then select the HL7 Transform Device from the HL7 category in the newly created device placeholder. 

Click the Save Channel button and select the HL7 Transform Device on your channel. 

Click the MSH-3 field in the Input Message Viewer, then click the Add Expression Transformer button in the device bar. 

Notice how the Output Message Viewer displays the result of the transformation. Now let's re-process our messages so that they contain the 'Change_Me' text. First, save your changes by clicking the save button or using the CTRL + S keyboard shortcut. Then right-click on the queue device icon and select the Bulk Reprocess Messages... item. 

A confirmation dialogue will be displayed, as re-processing previously processed messages is atypical in a production environment. Notice that your P count (processed) all moved to Q. Now start your channel, wait 30 seconds, and check the output folder for new files. 

Now you're ready to explore other devices as well as the more advanced functionality in Connexion.