Configuring the Production for HL7
This page describes how to configure a production to include an HL7 routing interface. It also describes how to create a new HL7 routing production, if you do not yet have a production.
This page discusses tasks that you perform on the Production Configuration page. Also see Defining Routing Rule Sets for HL7.
Creating a New HL7 Routing Production
You can create a new HL7 routing production as follows:
-
In the Management Portal, switch to the appropriate namespace.
To do so, select the name of the current namespace in the title bar, then click the name of the appropriate namespace in the resulting list.
-
Select Interoperability > List > Productions.
-
Select New to invoke the Production Wizard.
-
Enter a Package Name, Production Name, and Description.
-
Choose the HL7 Messaging production type and select OK.
The starter production has one interface, whose elements are:
-
HL7FileService — A disabled HL7 file service with default settings
-
MsgRouter — An HL7 routing process with an empty routing rule set
-
HL7FileOperation — A disabled HL7 file operation with default settings
When you build an HL7 routing production, you create and configure many such interfaces. You can start by enabling these starter elements, copying them, renaming them, and modifying them to suit your needs. As you build an interface, it frequently happens that while configuring one item you must enter the name of another item that you have not yet created. A clear naming convention is essential to avoid confusion. For suggestions, see Naming Conventions. For rules, see Configuration Names.
In addition to interface elements, the starter production provides several elements that do not route HL7 messages, but that provide supporting functionality for the production:
-
Bad Message Handler — A built-in destination for messages that fail validation.
-
Ens.Alert — A routing process with a routing rule set that you can configure to route alert messages to different email business operations depending on the source of the alert (that is, which element is in trouble) and various conditions (such as the time of day) to suit your corporate schedules and procedures.
-
PagerAlert and EmailAlert — Email business operations that can be configured to send a text message (such as an alert) to a pager or email address.
Adding HL7 Business Services
For your production to receive HL7 messages from outside your InterSystems product, you must add an HL7 business service to the production configuration. To add HL7 business service to a production, you must create it, integrate it into the production, and configure it as needed. The following subsections provide the details.
Creating an HL7 Business Service
To add an HL7 business service to a production:
-
Display the production in the Production Configuration page of the Management Portal (select Interoperability > Configure > Production from the Home page).
-
In the Services column, click the Add button (a plus sign).
-
Click the HL7 Input tab.
-
Click one of the following from the Input type list:
-
TCP
-
File
-
FTP
-
HTTP
-
SOAP
This choice selects the host class for your business service.
-
-
For HL7 Service Name, type the name of this business service. The name should be unique among the business services. Do not use periods or spaces.
The default is the name of the class on which this service is based.
-
For HL7 Service Target, select one of the following:
-
Create New Router — InterSystems adds a routing process to the production and configures the business service to use that process as a target. You can edit the details later.
-
None for Now — No target is specified for this business service.
-
Choose From List — In this case, also select an existing business host from the drop-down list.
-
-
Click OK.
In addition to the HL7 business services used here, InterSystems provides two simple business services: EnsLib.File.PassthroughServiceOpens in a new tab and EnsLib.FTP.PassthroughServiceOpens in a new tab. You can select either of these if you simply need to pass a file through the production, and do not want to parse or format the file as HL7.
If you want the production to receive data that is not an HL7 message, see Defining Business Services. Also see Connectivity Options.
Integrating and Configuring an HL7 Business Service
To integrate a new HL7 business service into a production, you must associate it with the routing process or business operation to which it relays messages. Additionally, if you expect the business service to receive nonstandard message structures you will need to create a custom HL7 schema definition to parse and validate these messages. To do this:
-
Complete the instructions for creating any Target Config Names or Message Schema Category items that your HL7 business service needs. The items might be:
-
An HL7 routing process (for a routing interface). See the next section.
-
An HL7 business operation (if your design bypasses a routing process for this interface and simply relays messages from the incoming business service to the outgoing business operation). See Adding HL7 Business Operations.
-
A custom HL7 schema definition, to parse the incoming HL7 messages. For information on creating custom schema categories, see Creating Custom Schema Categories.
-
-
Return to the diagram on the Production Configuration page. Select the new HL7 business service. If the Target Config Names and Message Schema Category fields were previously blank, configure them now, and click Apply.
-
Configure additional settings of the business service, as needed. For details, see Settings of an HL7 Business Service.
Adding HL7 Routing Processes
To add an HL7 routing process to a production, you must create it, integrate it into the production, and configure it as needed. The following subsections provide the details.
Creating an HL7 Routing Process
To add an HL7 routing process to a production:
-
Display the production in the Production Configuration page of the Management Portal (select Interoperability > Configure > Production from the Home page).
-
In the Processes column, click the Add button (a plus sign).
-
Click HL7 Message Router for the business process option; the router class defaults to EnsLib.HL7.MsgRouter.RoutingEngineOpens in a new tab.
-
For HL7 Router Name, type the name of this business process. The name should be unique among the business processes. Do not use periods or spaces.
The default is the name of the class on which this process is based.
-
For Routing Rule Name, do one of the following:
-
Select an existing routing rule from the Routing Rule Name drop-down list.
-
Select Auto-Create Rule and type a rule name into Routing Rule Name. In this case, the wizard creates the routing rule class in the same package as the production.
-
-
Click OK.
Integrating and Configuring an HL7 Routing Process
To integrate a new HL7 routing process into a production, you must associate it with the business service that receives its incoming messages, and with the routing rule set that determines its actions based on those messages. To do this:
-
Select the HL7 business service. In the menu to the right of the screen, click the Settings tab and open the Basic Settings menu. In the Target Config Names field, enter the name of the new HL7 routing process.
-
Create a routing rule set. Select the routing process in the configuration diagram. In the Business Rule Name field, enter the full name of the new routing rule set.
-
Configure additional settings of the routing process, as needed. For details, see Settings for HL7 Routing Processes.
Adding HL7 Sequence Managers
HL7 messages can become out of sequence for various reasons, particularly when multiple processors are handling them. In some cases, it is desirable to ensure that HL7 messages are processed in the correct sequence. In such cases, you can add an HL7 sequence manager to the appropriate part of the production.
An HL7 sequence manager is a business process that accepts incoming HL7 messages (possibly from multiple sources), then forwards the messages to a target configuration item in the order specified by the MSH:13 SequenceNumbers field in the messages.
The sequence manager can detect duplicate messages and timing gaps between messages. It also determines when the timing gaps between sequential messages are sufficiently large to indicate a problem. Its level of sensitivity can be adjusted using its configuration settings.
To build an HL7 sequence manager for use in an HL7 message routing production, you must create and configure it and then integrate it into the production. This topic explains each step.
The HL7 Sequence Manager is a HL7-compatible store-and-forward application and does not support the HL7 Sequence Number Protocol as defined in Chapter 2, section 2.10.1 of the HL7 Standard.
Creating an HL7 Sequence Manager
To add an HL7 sequence manager to a production:
-
Display the production in the Production Configuration page of the Management Portal (select Interoperability > Configure > Production from the Home page).
-
In the Processes column, click the Add button (a plus sign).
-
Select EnsLib.HL7.SequenceManagerOpens in a new tab from the ProcessClass list.
-
For Name, type the name of this business process. The name should be unique among the business processes. Do not use periods or spaces.
The default is the name of the class on which this process is based.
-
Click OK.
A production can have multiple sequence managers, if needed.
Integrating and Configuring an HL7 Sequence Manager
To integrate a new HL7 sequence manager into a production, you must associate it with the business service that receives its incoming messages, and with the target destination for the messages that it sends, once it has sorted out their proper sequence. To do this:
-
Select the HL7 business service. In the Target Config Names field, enter the name of the new HL7 sequence manager.
-
Return to configuring the HL7 sequence manager. Provide it with a list of Output Target Config Names for successful messages.
-
If you want the sequence manager to check for duplicate messages, set Enable Duplicated Message Check to True.
If you want to save the duplicate messages for troubleshooting purposes, create a HL7 business operation to receive them. In the Duplicated Message Target field enter the name of the new HL7 business operation.
-
If you want the sequence manager to check for out-of-sequence messages, set Perform Sequence Number Check On to Sender or Receiver and configure the details of sequence checking by setting values for Large Gap Size and Message Wait Timeout. Otherwise, set Perform Sequence Number Check On to None.
If you want to save the out-of-sequence messages for troubleshooting purposes, create a HL7 business operation to receive them. In the Out Of Sequence Message Target field, enter the name of the new HL7 business operation.
-
If you want the sequence manager to transform messages before sending them outside your InterSystems product, set Perform Output Transformation On to Sender or Receiver and set a value for the Output Facility Application. Otherwise, set Perform Output Transformation On to None.
-
Identify any Passthrough Message Types that the sequence manager should simply send to the Output Target Config Names without checking or transforming them.
-
Configure additional settings of the sequence manager, as needed. For details, see Settings for HL7 Sequence Managers.
Accessing HL7 Sequence Data Programmatically
You can access the runtime data of the Sequence Manager via SQL. To do so, execute a query on the table EnsLib_HL7.SM.RuntimeData.Thread. This table provides the following string fields:
The name of the sending or receiving application, as taken from the HL7 messages.
The name of the sending or receiving facility, as taken from the HL7 messages.
One of the following strings:
-
main
-
resend
One of the following strings:
-
Sender
-
Receiver
Identifies the next number in the sequence for the given facility, application, thread, and type.
A sample SQL query might be as follows:
SELECT Application,Thread,Type,NextSequenceNumber FROM EnsLib_HL7.SM.RuntimeData.Thread WHERE Facility = 'mine'
Adding HL7 Business Operations
To send HL7 messages from a production, you must add an HL7 business operation. To add an HL7 business operation to a production, you must create it, integrate it into the production, and configure it as needed. The following subsections provide the details.
Creating an HL7 Business Operation
To add an HL7 business operation to a production:
-
Display the production in the Production Configuration page of the Management Portal (select Interoperability > Configure > Production from the Home page).
-
In the Operations column, click the Add button (a plus sign).
-
Click HL7 Output.
-
Click one of the following from the Output type list:
-
TCP
-
File
-
FTP
-
HTTP
-
SOAP
This selection determines the host class for this business operation.
-
-
For Operation Name, type the name of this business operation. The name should be unique among the business operations. Do not use periods or spaces.
The default is the name of the class on which this operation is based.
-
Click OK.
In addition to the HL7 business operations used here, InterSystems provides two simple business operations: EnsLib.File.PassthroughOperationOpens in a new tab and EnsLib.FTP.PassthroughOperationOpens in a new tab. You can select either of these if you simply need to pass a file through the production, and do not want to parse or format the file as HL7.
If you want the production to send data that is not an HL7 message, see Defining Business Operations. Also see Connectivity Options.
Integrating and Configuring an HL7 Business Operation
To integrate a new HL7 business operation into a production, simply identify it as a target that receives messages. To do this, you must configure the item that sends messages to the HL7 business operation and enter the configured Name of the HL7 business operation into the appropriate field:
-
For a routing interface, enter the name in the Target field of the routing rule set.
-
If your design uses a pass-through interface that simply relays messages from the incoming business service to the outgoing business operation, enter the name in the Target Config Names field of the HL7 business service.
-
Configure additional settings of the business operation, as needed. For details, see Settings for HL7 Routing Operations.
Pager and Email Alerts
Alerts provide the ability to send notification to a user device while a production is running. The intention is to alert a system administrator or service technician to the presence of a problem. Alerts may be sent via email, text pager, or another mechanism. For details, see Configuring Alerts.
The starter HL7 routing production provides the following elements to support alerts:
-
Ens.Alert — The starter production provides a built-in Ens.Alert element. This Ens.Alert is a routing process with an associated routing rule set called AlertRule.
You can configure AlertRule to route alert messages to different business operations depending on the source of the alert message (that is, which element is in trouble) and various conditions (such as time of day).
To configure AlertRule, follow a similar procedure to the one for HL7 routing rule sets, except:
-
For the Message Class, choose Ens.AlertRequestOpens in a new tab
-
In the Target field, choose or type the configured name of an email business operation.
-
-
PagerAlert and EmailAlert — These are ordinary email operations that can be configured to send a text message (such as the body of an alert) to a pager or email address. PagerAlert and EmailAlert are initially identical, other than their names. Both are provided to emphasize the fact that alerts have different priorities. Generally the higher-priority alerts go to a pager, lower-priority to email.
You can configure any number of destinations that copy these starter operations. At runtime, your AlertRule routing rule set determines which destination is appropriate to use.