Design your Interface Structure

Identify the Interface Structure

 

There are two types of interface structure: Simple and Complex.

Simple Interface

Use a single channel to connect one source to one target.

Complex Interface

Use a channel pipeline to connect a single source to multiple targets. This consists of a single “source channel” that reads the from the message source, and then feeds multiple “destination channels” (one for each target).

Identify the Structure to Use [top]

Identifying the type is quite simple, just answer two questions and choose from the structures.

Questions:

  1. How many Sources are you messages coming from?
  2. How many Targets are your messages going to?

Structures:

Sources Targets Interface Type Channel Structure
1 1 Simple Single channel
1 Many Complex Channel pipeline
Many 1 Multiple simple interfaces Multiple single channels (one per source)
Many Many Multiple complex interfaces Multiple channel pipelines (one per source)

Advantages of Simple versus Complex Interface Structure [top]

Simple:

  • Simplicity

Complex:

  • Flexibility
  • Copy a single message source to multiple message targets
    Note: You could also use multiple Simple Interfaces, but this would need a multiple duplicate message sources, one for each interface.
  • Stop transmitting to all target systems by stopping the Pipeline Source channel
    Note: If you were using multiple Simple Interfaces you would need to stop every interface
  • You can continue reading and queueing messages while one or more target interfaces are stopped
    Note: This is not possible with Simple Interfaces, as any stopped interfaces will not be reading messages

The last point is actually a valid reason to consider a Complex Structure for a simple interface.

Choose Channel Components [top]

Once you have identified the channel structure that you need, you must choose the components for your channel or channels (if you are using a pipeline).

These recommendations are guidelines designed to help you use the Translator effectively, and in most cases they will serve you well. However they are not are not set in concrete, and on some occasions a different structure may be more suitable. If you have a special requirement or just need more help please feel free to contact support at support@interfaceware.com.

Note: If you are using a Channel Pipeline (Complex interface), you will need to choose components for each of the source and target Channels individually.

Recommended Components [top]

Choose the incoming message source (first column), then use the target (second column) to select our recommended source and destination components.

Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
HL7 LLP feed Outgoing HL7 LLP feed LLP Listener LLP Client
HL7 LLP feed Database LLP Listener To Translator
HL7 LLP feed Web Service LLP Listener To Translator
HL7 LLP feed File or FTP LLP Listener To File To Translator: io.open/net.ftp
HL7 LLP feed Iguana Channels LLP Listener To Channel
Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
Database Outgoing HL7 LLP feed From Translator LLP Client
Database Database From Translator
Database Web Service From Translator To Translator
Database File or FTP From Translator To File To Translator: io.open/net.ftp
Database Iguana Channels From Translator To Channel
Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
File or FTP Outgoing HL7 LLP feed From File From Translator: io.open/net.ftp LLP Client
File or FTP Database From File From Translator: io.open/net.ftp To Translator
File or FTP Web Service From File From Translator: io.open/net.ftp To Translator
File or FTP File or FTP From File From Translator: io.open/net.ftp To File To Translator: io.open/net.ftp
File or FTP Iguana Channels From File From Translator: io.open/net.ftp To Channel
Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
Web Service Outgoing HL7 LLP feed From HTTPS From Translator: net.http.get LLP Client
Web Service Database From HTTPS From Translator: net.http.get To Translator
Web Service Web Service From HTTPS From Translator: net.http.get To Translator
Web Service File or FTP From HTTPS From Translator: net.http.get To File To Translator: net.http.get
Web Service Iguana Channels From HTTPS From Translator: net.http.get To Channel
Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
Iguana Channel Outgoing HL7 LLP feed From Channel LLP Client
Iguana Channel Database From Channel To Translator
Iguana Channel Web Service From Channel To Translator
Iguana Channel File or FTP From Channel To File To Translator: io.open/net.ftp
Message Source Message target Source Component Alternative Source Destination Component Alternative Destination
Other Outgoing HL7 LLP feed From Translator LLP Client
Other Database From Translator To Translator
Other Web Service From Translator To Translator
Other File or FTP From Translator To File To Translator: io.open/net.ftp
Other Iguana Channels From Translator To Channel

Choose Script Placement [top]

  1. Choose Single Stage or Two Stage processing, see the note below.
  2. Choose your components from the first two columns, then choose the recommended script placement from the last two columns:
    Source Component Destination Component Single Stage Script Two Stage Script
    LLP Listener To Translator Source or Destination Source and Destination or
    Filter and Destination [1]
    LLP Listener Other component Source or Filter Source and Filter
    From Translator To Translator Source Source and Destination
    From Translator Other component Source Source and Filter
    From File To Translator Destination Filter and Destination
    From File Other component Filter Not possible
    From HTTPS To Translator Source or Destination Source and Destination or
    Filter and Destination [2]
    From HTTPS Other component Source or Filter Source and Filter
    From Channel To Translator Destination Filter and Destination
    From Channel Other component Filter Not possible
    1. Use the Filter for your script when you are using the unscripted From LLP “Fast” ACK From LLP setting, or the Source for the scripted “Translator” ACK From LLP setting.
    2. Use the Filter for your script when you are using the unscripted “Legacy” From HTTPS setting, or the Source for the recommended scripted “Translator” From HTTPS setting.

Important Notes [top]

These notes are designed to help you to understand the recommendations in the tables, and to explain our reasoning for some of the (less obvious) choices.

Single Stage and Two Stage Processing

For simple requirements you can use single stage processing but there are some definite advantages to using two stages, particularly with more complex requirements.

So what do you mean by Single Stage Processing? This simply means doing the processing for a simple task in one step (or stage). In the Translator we do this by putting the code for the stage in a single channel component.

So what do you mean by Two Stage Processing? This means breaking the processing for a complex task into two steps (or stages). In the Translator we do this by putting the code for each stage in two separate components within a channel.

Single Stage Advantages:

  • Works well for a simple examples
  • The code is easy to find because it all in one place

Two Stage Advantages:

  • Works well for more complex examples
  • Takes better advantage of the Iguana Queue
  • Allows you to use the Iguana Logs to resubmit messages when using a To Translator Component

    Note: You cannot use the logs to resubmit messages to a To Translator Component, but if you queue the messages and do the processing in a Filter component you can then resubmit the messages to the Filter.

  • Lets you partition the code into a cleaner more logical structure

    Tip: This is a “soft” advantage as you can do all the processing in one component, but it is just not as clean.

Two Stage Scenario: Read messages from a database and forward them as HL7 messages

Use a channel with the following structure:

  • Use a From Translator component to poll the database for messages to be processed.
    • Read the message ID from the database
    • Queue the message ID
  • The Filter component then uses the ID to read the message data from the database and maps it to the message.
  • Finally an LLP Client component is used to send out the HL7 messages.

The main advantage of this approach is that you can easily reprocess messages by using the Iguana Logs to resubmit the message IDs to the Filter component. If you had done all the processing in the To Translator component it would be much more difficult to reprocess messages, as you cannot resubmit them using the Iguana Logs (See the Translator FAQ “Why can’t I resubmit messages to my From Translator component?“). To reprocess messages using the To Translator you would need to modify the database to resubmit the message IDs (which probably requires dealing with a client to make the database updates).

This scenario is the basis for our our Database to HL7 Tutorial.

Tip: If we change the scenario slightly and send the data to a database or a web service, then we would need to use a To Translator destination (instead of an LLP Client). This presents us with a quandary, where to do the processing and where to write to the database or web service?

There are three options:

  1. Recommended: Process and write in the To Translator
  2. Process and write in the Filter
  3. Process in the Filter and write in the To Translator

Option 1 is the cleanest and most logical (in our opinion). The issue with option 2 is that a filter is just not the logical place to write data. Option 3 introduces a much more complex “three stage process” with no practical advantages.

Where should I do processing, in the Source, Filter or Destination component? [top]

Generally we recommend using the Filter component for processing and filtering messages, though this is more of a style issue rather than a technical one. And if you choose to do processing or filtering in the Source or Destination Component it will work just as well (though it may be a bit less obvious where to find the code).

The one case where there is a major “technical advantage” to using the Filter instead of the Source is when you are using a From Translator component. The advantage is that messages are queued for a Filter component but not for a From Translator (See the Translator FAQ “Why can’t I resubmit messages to my From Translator component?“).

There are two occasions when we don’t recommend using the Filter:

  1. When using a From Translator to read data with single stage processing you must also do the processing in the From Translator (using Filter processing would make it a two stage process).
  2. When using two stage processing with a From Translator and a To Translator, then you should do the processing (and writing of data) in the To Translator.

Why is there no processing in a pipeline source channel (“Iguana Channels” target)? [top]

We generally recommend that a “pipeline source” channel is simply used to pass messages/data to its target channels. The processing and filtering should be performed in the target channels. Doing it this way is a much more versatile solution, as it allows for different processing and filtering in each target channel (a common requirement).

Possible Exceptions:

  1. Good Idea: Adding extra data from a database (or web service etc), you could use the pipeline filter component for this.
  2. Reasonable idea: Reformatting data (like dates) into a correct/standard format.
    • For any targets that want a custom format, just reformat again in the target channel.
  3. Use with caution: Basic data cleanup like changing custom/incorrect codes to standard ones
    • Issue: One of the targets (or a new target) decides they want the uncleaned data
  4. Bad Idea: Removing data that none of the targets need.
    • Issue: One of the targets (or a new target) decides they want the removed data
  5. Bad Idea: Filtering out unwanted messages that none of the targets need.
    • Issue: One of the targets (or a new target) decides they want the removed data

Basically anything that filters out messages or removes data in a pipeline channel has the potential to cause problems down the road. If in the future you need the removed data or messages you will need to update the pipeline (to add the data message back in) and then add the filtering to all the target channels. This is not the end of the world, but it would probably have been easier to just put the filtering in the target channels originally.

Leave a Reply