Design Model for a Routing Production
This chapter describes a design model that Ensemble customers have used successfully to build interface routing solutions. As such, it can be thought of as a collection of best practices for developing an Ensemble routing production.
This chapter describes only one approach. Other implementation strategies can be successful as well. Each organization has its own standards for writing code and conducting programming projects. This chapter simply describes those aspects of a routing production that are unique to Ensemble and that benefit from a carefully structured approach.
In general, the key to a good design is clarity and simplicity. Simplicity does not mean a small number of parts. Simplicity means that each part within the model has a clear function and is intuitively easy to find.
An Ensemble production consists of configuration items. There are three types of configuration item:
Business services accept incoming messages.
Business operations send outgoing messages.
Business processes direct all the work in between. There are some specialized types of business process:
A routing process routes and transforms messages by invoking these key components of a routing production:
Routing rules direct messages to their destinations based on message contents.
Schema categories provide a means to validate and access message contents.
Data transformations apply changes to prepare messages for their destinations.
A sequence manager ensures that related messages arrive at their targets with the proper sequence and timing
The following figure expands the diagram of a routing process to show how it uses routing rules to direct the flow of information through the interface. The following figure includes details about the routing rules and data transformations that are only implied by the dotted circle in the diagram above.
A routing process has a routing rule set associated with it. Depending on how the rule set is defined, and depending on the type of message that arrives from the source application, the rule set identifies which of its rules should execute. More than one rule can execute, in sequence, but for simplicity the following figure shows the case where the rule set chooses only one rule. From this point, as shown, a rule can either delete the message or it can send the message to a destination within Ensemble. If this destination is a business operation, the message then leaves Ensemble on its way to the target application.
Ideally, a clinical application provides an HL7 application specification document, or implementation guide, that explains which types of HL7 event the application can send (or receive), and which message segments and pieces of each segment the application sends (or expects) for these events.
A formal document of this kind is extremely detailed, and extremely useful. If a specification document is available, the administrator for the clinical application can show it to you, and can explain to you which of the many possible events are actually in use in the enterprise. This is usually a small subset of the full list of events.
Even if there is no application specification document, there is usually some informal documentation. Ask the application administrator to see any notes that are available.
As an alternative to documentation, or to validate that the existing documentation is correct, you can examine the messages themselves to determine which types of HL7 event the application sends or expects to receive. Ask the application administrator to provide you with a sampling of the message data, saved in files.
Once you have the HL7 message files, you can use the Document Viewer to view and parse them using various schema definitions. In this way you can quickly determine whether or not the application is using a standard HL7 schema. If not, you can use the Message Viewer to refine and test a custom HL7 schema for the application.
Background information that supports these tasks can be found in subsequent chapters of this book, and in other books:
It is helpful to maintain a spreadsheet that organizes your information system, application by application. You can create the spreadsheet on paper, or using any software tool that you prefer.
As a general guideline, you should provide a row for each application that provides an incoming or outgoing data feed. In each row, the following columns are useful:
Feed — An interface engine or server often feeds messages from several applications into the routing production. When this is the case, note the engine or server name here.
Application — Briefly identify a specific application, its role in your system, and the person to contact about any issues or problems with this application. Ideally, this description makes sense to members of your organization who do not use Ensemble, but who are generally familiar with how the system works.
Name — A unique 3– to 6–character name for this application.
Type — The protocol that the application uses for external communications.
Connection — Connection details, such as an IP address and port number.
Sends — The HL7 Version 2 message structures that this application contributes to the information system.
Consider the incoming message structure after it enters the information system. Does it need to be routed or transformed differently depending on the destination system or other factors? If so, list it multiple times, with a note regarding the differences. This way, your spreadsheet can serve as a checklist while you create the necessary routing rules, data transformations, and custom schemas for each case.
Receives — The HL7 Version 2 message structures that this application consumes from the information system.
ACKs — Acknowledgment details. Are ACK and NACK messages expected? Is there a separate interface for sending and receiving them? Should Ensemble generate the ACKs and NACKs, or will the receiving application do so?
When you begin the project, your initial spreadsheet does not need to describe every application in the information system. You can add to the spreadsheet as you deploy each new interface.
This topic outlines an effective way to keep interface designs modular so that your Ensemble production remains easy to understand, scale, and maintain at each stage of its development:
Provide one business service for each application that sends HL7 messages into Ensemble. This is an application that has at least one entry in the Sends column of the production spreadsheet.
One business service can receive all of the message structures for the same application. This is usually the appropriate design. When you set up a business service for this purpose you generally intend for it to stay connected to its application system all the time.
There might be aspects of the configuration that require you to provide additional business services connected to the same application. For example, if the source application is already configured to send messages to two different TCP/IP ports, you could set up one business service to receive all the messages from one port, and another business service for the other port. This is generally consistent with the model of one business service per application, since there is one business service per communication source.
Alternatively, when hundreds of users of the same clinical application are sending data into the enterprise, it can be useful to route all of these messages into Ensemble via one business service that may or may not stay permanently connected to any single instance of the application.
Provide one routing process for each business service. The routing process can route messages based on the contents of the message itself, or information stored in Ensemble. If the routing depends on the contents of other messages, or requires invocation of external applications to determine the routing, the routing process should be a BPL business process that calls out to other classes. However, in most cases a routing process based on the built-in routing rule engine is sufficient.
Consider using a sequence manager when it is vital that related messages arrive at their targets in the proper sequence. For details, see “Configuring the Production” in the Ensemble HL7 Version 2 Development Guide.
Provide one business operation for each application that receives HL7 messages from Ensemble. This is an application that has at least one entry in the Receives column of the production spreadsheet.
One business operation can send all the different message structures for the same application. This is usually the appropriate design. When you set up a business operation for this purpose you generally intend for it to stay connected to its application system all the time. However, as for business services, there might be variations on this model.
The guiding principle is to keep your design modular. That is, develop one interface at a time and use one routing process for each interface. This contrasts with a model in which a single large routing process serves as the routing engine for all interfaces. There are a number of reasons why many routing processes are better than one:
Each routing rule set is simpler and easier to maintain because it only covers the cases required by one interface. It is easier to share and reuse work that is self-contained and solves a simple set of problems.
Interfaces become easy to develop, replace, and maintain individually. If the enterprise must remove or upgrade a particular application, only those routing processes that deal with that application need to be touched. If an interface goes down, only that interface needs to be disabled, diagnosed, repaired, and retested before you can bring it back up.
This is much cleaner than requiring you to retest and validate all of the rules in one large routing process every time you need to add, remove, or repair one interface. These considerations become especially important as some of your interfaces go live, while others are still in development. Each addition to a routing process that is already in production might require you to retest and validate hundreds of existing rules. The following figure shows a routing production with multiple interfaces:
Each configuration item in the production has a specific role to play. Keep each item to its role:
Keep business services and business operations simple. In general, it is not necessary to write your own code for business services or business operations. Choose the built-in classes that Ensemble provides. This choice gives you the correct adapters automatically. Configure these classes using Management Portal settings.
Place all complex activities under control of a routing process. If an interface is simple, its routing processes need not be complex, but if complexity exists, it belongs in a routing process, not in a business service or business operation. To accomplish tasks, a routing process can chain to other routing processes, or it can invoke business rules, routing rules, data transformations, business processes, or custom code.
This topic explains the importance of naming conventions and provides examples.
Typically you will develop your Ensemble production incrementally, one interface at a time. There is a temptation to name items “as you go,” and to allow naming conventions to grow incrementally along with the project. InterSystems recommends you do not take this incremental approach to naming conventions.
Remember that a full HIS system can involve hundreds of interfaces. Anticipate the task of managing the routing production once all of these interfaces are included. The name of each component should clearly identify its purpose. This way, developers and system administrators can easily predict a component’s name based on its function.
InterSystems recommends that you establish a full set of naming conventions at the start of the project, and then stick with them. This alleviates the need to backtrack into your production configuration just to correct names.
Any convention that clearly identifies components by function is fine. The following is a full set of naming conventions that several Ensemble customers have used successfully:
For rules on configuration item names, see “Configuration Names,” in Configuring Ensemble Productions.
List the individual segments that you will assemble to create names. These might include:
From for incoming
To for outgoing
Router for routing
Rules for rule sets
A base schema category number — 2.1, 2.2, 2.3, 2.3.1, 2.4, 2.5, 2.5.1, 2.6, 2.7, or 2.7.1— for schemas
A short name for each application
Keywords that identify a general class of message structures (ADT, ORM, etc.)
Full message structure names (ADT_A01, ADT_A04, ORM_O01, etc.)
Keep each segment of the name brief (3–6 characters)
Remember that names are case-sensitive
For each element of the production, assemble a name from the segments that you have defined:
Business services: FromSourceAppName
Business operations: ToTargetAppName
Routing processes: SourceAppNameRouter
Routing rule sets: SourceAppNameRules
Custom schema categories: SourceAppNameBaseSchemaNumber
For more complex designs:
Business services: FromSourceAppNameMessageTypes
Business operations: ToTargetAppNameMessageTypes
Routing processes: SourceAppNameMessageTypesRouter
Routing rule sets: SourceAppNameMessageTypesRules
The following topics provide explanations and examples for these naming conventions.
FromERChart, FromFineOR, FromDeskAdm
If you have decided to organize an interface so that one application sends messages into Ensemble via more than one business service, also include a keyword that classifies the MessageTypes that pass through each business service. A typical MessageTypes keyword uses the first three letters of the HL7 Version 2 message structure, such as ADT, ORM, or ORU. In this case the convention for the business service name is FromSourceAppNameMessageTypes.
FromERChartADT, FromERChartORM, FromERChartOther
ERChartRouter, FineORRouter, DeskAdmRouter
If you have decided to organize an interface so that one application sends messages into Ensemble via more than one business service, also include a keyword that classifies the MessageTypes that pass through each business service to its routing process. In this case the format for the routing process name is as follows:
ERChartADTRouter, ERChartORMRouter, ERChartOtherRouter
Routing Rule Sets for HL7
Each routing process has an associated rule set whose rules determine message destinations. The rules direct the messages to data transformations or business operations based on message type, message contents, time of day, or other factors. Name each rule set to match its routing process. That is, for each SourceAppNameRouter, call the rule set SourceAppNameRules. For each SourceAppNameMessageTypesRouter, call the rule set SourceAppNameMessageTypesRules.
ToImagit, ToFineOR, ToPindex
If you have decided to organize an interface so that one application receives messages from Ensemble via more than one business operation, also include a keyword that classifies the MessageTypes that passes through each business operation. A typical MessageTypes keyword uses the first three letters of the HL7 Version 2 message structure, such as ADT, ORM, or ORU. In this case the convention for the business operation name is as follows:
ToMainLabADT, ToMainLabORM, ToMainLabOther
Remember that the SourceMessageType and TargetMessageType may have the same name, but represent the same message structure in different schema categories.
Custom Schema Categories
The ApplicationName can represent a sending application or a receiving application.
ERChart2.2, Imagit2.3.1, OurFavorite2.5