T1.2: Chooses Production Architecture

Overview

Business Services serve as the entry point into your HL7 production, acting as the bridge between external healthcare systems and your InterSystems integration environment. Understanding the capabilities and constraints of Business Services is fundamental to production design.

Primary Responsibility

The primary responsibility of a Business Service is receiving inbound data from external systems:

• When an external application (EMR, lab system, radiology system) needs to send HL7 messages to IRIS for Health, it connects to a Business Service
• The Business Service uses an InboundAdapter to handle the communication protocol:
• TCP: For real-time messaging
• FTP: For file-based transfers
• File adapter: For local filesystem monitoring
• HTTP: For web service calls
• SOAP: For SOAP-based web services

ACK Handling Capability

A critical capability of HL7 Business Services:

• When an external system sends an HL7 message, it expects an acknowledgment confirming receipt
• The Business Service can automatically generate and return ACKs to the calling application
• This immediate acknowledgment satisfies the sending system's need for confirmation
• The message can be processed asynchronously within the production

Single-Source Constraint

Business Services operate under a single-source constraint:

• Each Business Service processes data from one source
• TCP: Listens on one specific port
• Files: Monitors one specific directory
• FTP: Reads from one FTP location
• This simplifies configuration and troubleshooting with clear ownership
• For multiple sources, create multiple Business Services

Schema Version Limitation

A significant architectural limitation:

• Each Business Service can only be assigned one HL7 schema version (Message Schema Category)
• This enables the Business Service to parse inbound messages according to correct structural definitions
• A single Business Service cannot handle a mix of HL7 versions
• If lab sends HL7 2.5 and radiology sends HL7 2.3, you must create separate Business Services

Multiple Message Types

Within a single HL7 version, a Business Service can receive multiple message types from the same application:

• Example: One Business Service using schema version 2.5 might receive ADT_A01, ADT_A08, SIU_S12, and ORM_O01
• All from the same hospital information system
• The unifying factor is that they all use HL7 2.5 structure

Message Forwarding

After receiving and optionally acknowledging a message:

• The Business Service forwards it to the next component in the production chain
• The destination is specified in the TargetConfigNames setting
• Typically points to an HL7 Message Router (Business Process)
• The Business Service's job is complete once it has handed off the message

Overview

Business Operations represent the exit boundary of your production, handling outbound communication to external healthcare systems. They are the counterpart to Business Services, managing the final delivery of messages that have been received, routed, and potentially transformed within your production.

Primary Responsibility

The primary responsibility of a Business Operation is sending outbound data to external systems:

• When a routing rule or Business Process determines that a message should be sent, it forwards to the appropriate Business Operation
• The Business Operation uses an OutboundAdapter to handle the communication protocol:
• TCP: For real-time messaging
• FTP: For file uploads
• File adapter: For writing to local filesystem
• HTTP: For web service calls
• SOAP: For SOAP-based web services

Single-Destination Constraint

Business Operations operate under a single-destination constraint:

• Each Business Operation connects to one destination
• TCP: One IP address and port number combination
• FTP: One FTP server and directory path
• File-based output: One file system directory
• This one-to-one relationship simplifies configuration, security management, and troubleshooting

Multiple Destinations

If you need to send messages to multiple destination systems:

• Create multiple Business Operations
• Example: Sending ADT messages to three systems (EMR, billing, reporting) requires three separate Business Operations
• Each configured with connection details for its specific destination
• Routing rules in the Message Router send messages to one, two, or all three based on business logic

Architectural Constraint

An important architectural constraint:

• Business Operations cannot call Business Processes
• Data flow in productions is unidirectional from Services through Processes to Operations
• A Business Operation can return response messages to the calling Business Process or Service
• It cannot initiate calls to Business Processes
• This maintains clear architectural boundaries and prevents circular dependencies

Exception to Strict Layering

While uncommon, there is one exception:

• A non-HL7 Business Operation can call another Business Operation
• Used in complex integrations where one operation performs preprocessing then delegates to another
• Best practice: Create a Business Process to orchestrate multiple Business Operations instead
• This makes orchestration logic more visible and maintainable

Architecture Translation

Understanding Business Operation capabilities and constraints is essential:

• Each destination system in your integration landscape requires its own Business Operation
• The adapter choice depends on how that destination system prefers to receive data

Overview

Business Processes provide the orchestration, routing, and transformation logic at the heart of HL7 integrations. They sit between Business Services and Business Operations, making decisions about where messages should go and what transformations should be applied.

HL7 Message Router

The most commonly used Business Process type for HL7 integrations, providing three core capabilities:

• Message validation: Controlled by the Validation setting
• Routing rule execution: Based on the RuleSet
• Error handling: Through the BadMessageHandler setting

Message Validation

• Validates messages against schema definitions before routing rules execute
• Default validation (dm-z) checks:
• Message has a DocType assigned
• Segment structure matches schema definition
• Allows Z-segments at the end
• Validation failures prevent the message from being routed, protecting downstream systems

Error Handling

The BadMessageHandler setting:

• Specifies another component (typically a Business Operation) for error messages
• Could be a file output that writes errors to disk for manual review
• Or an operation that sends alerts to a monitoring system
• Without BadMessageHandler configured, failed messages are simply logged

Routing Rules

After successful validation, the Message Router executes its routing rules (RuleSet):

• Rules determine where messages are sent based on constraints (message type, source, field values)
• Can apply data transformations during routing
• Can have complex logic with many rules or simple logic routing to one destination
• Can generate alerts based on configurable conditions

Custom Business Processes (BPL)

Beyond the standard Message Router, you can create custom Business Processes using BPL:

• Define complex workflows with conditional logic, loops, parallel processing
• Synchronous and asynchronous calls
• Error handling and compensating transactions
• Used for multi-step orchestrations, external system queries, complex aggregation patterns

Calling Other Components

Business Processes capabilities:

• Can call: Other Business Processes (multi-stage orchestration)
• Can call: Multiple Business Operations (fan-out patterns)
• Cannot call: Business Services (unidirectional flow from Services through Processes to Operations)

Best Practice

InterSystems recommends associating each Business Service with its own dedicated HL7 Message Router:

• Provides isolation - changes to routing logic for one integration don't affect others
• Improves maintainability and troubleshooting
• Keeps routing logic focused and cohesive

Overview

InterSystems IRIS for Health provides a comprehensive set of built-in HL7 adapters supporting five communication protocols. These adapters handle the technical details of communication, allowing Business Services and Operations to focus on message processing logic.

TCP Adapters

The most commonly used adapters for HL7 integrations:

• Class names: EnsLib.HL7.Adapter.TCP.InboundAdapter and EnsLib.HL7.Adapter.TCP.OutboundAdapter
• Provides real-time, connection-oriented communication
• Use cases: Patient admission notifications, critical test results requiring immediate delivery
• InboundAdapter: Listens on a specified port for incoming connections
• OutboundAdapter: Initiates connections to remote systems
• Handles connection management, message framing (MLLP), and acknowledgment processing automatically

File Adapters

Commonly used for batch processing scenarios:

• Class names: EnsLib.HL7.Adapter.File.InboundAdapter and EnsLib.HL7.Adapter.File.OutboundAdapter
• InboundAdapter: Monitors a directory for new files, reads messages, optionally moves to processed directory
• OutboundAdapter: Writes HL7 messages to files in a specified directory
• Use cases: Scheduled batch transfers, historical data loads, offline processing scenarios

FTP Adapters

Similar batch processing capabilities for remote systems:

• Class names: EnsLib.HL7.Adapter.FTP.InboundAdapter and EnsLib.HL7.Adapter.FTP.OutboundAdapter
• InboundAdapter: Connects to FTP server, downloads files, processes them, optionally deletes/moves on server
• OutboundAdapter: Uploads files to an FTP server
• Use cases: Exchanging data with insurance companies, health information exchanges, reference labs

HTTP Adapters

Support web service-based integration:

• Class names: EnsLib.HL7.Adapter.HTTP.InboundAdapter and EnsLib.HL7.Adapter.HTTP.OutboundAdapter
• InboundAdapter: Receives HL7 messages via HTTP POST requests
• OutboundAdapter: Sends HL7 messages to web service endpoints
• Increasingly common as healthcare systems adopt RESTful API patterns

SOAP Adapters

Support legacy SOAP web service integration:

• Class names: EnsLib.HL7.Adapter.SOAP.InboundAdapter and EnsLib.HL7.Adapter.SOAP.OutboundAdapter
• Less common in new implementations (superseded by REST/HTTP)
• Still used with older enterprise systems
• Provides SOAP message handling, WSDL processing, and web service security features

Choosing Adapters

When selecting adapters for a new integration, consider:

• Communication capabilities: What the external system supports
• Latency requirements: Real-time vs. batch
• Network architecture: Firewalls, DMZ considerations
• Operational preferences: Organizational standards and practices
• TCP: Preferred for real-time clinical messaging
• File and FTP: Common for batch administrative data transfers
• HTTP: Increasingly used for modern API-based integrations

Overview

Consistent naming conventions for production components are essential for:

• Maintainability
• Team collaboration
• Operational support
• Self-documenting architectures

Component Naming Elements

Component names should clearly identify:

• The component type (BS, BP, BO)
• The system or application it integrates with
• The message type or function it handles
• The communication protocol used

Business Service Naming

Common pattern: BS_{SystemName}_{MessageType}_{Protocol}

• Example: "BS_EMR_ADT_TCP" - Business Service receiving ADT messages from EMR via TCP
• Example: "BS_Lab_ORU_FTP" - Business Service receiving lab results via FTP
• This clarity is invaluable when troubleshooting message traces

Business Process Naming

For Message Routers: MR_{SystemName}_{MessageType}

• Example: "MR_EMR_ADT" - Message Router for EMR ADT messages

For custom BPL processes: BP_{FunctionName}

• Example: "BP_OrderOrchestrator" or "BP_PatientMergeProcessor"

Business Operation Naming

Pattern similar to Business Services: BO_{SystemName}_{MessageType}_{Protocol}

• Example: "BO_Billing_ADT_TCP"
• Example: "BO_Archive_All_File"
• Makes it clear where messages are being sent and how

Message Structure Naming

Choice between general class names and specific DocTypes:

• General names (ADT, ORM, SIU): Work well when you don't need to distinguish between specific events
• Specific DocTypes (ADT_A01): Use when different events route differently or require different transformations

Data Transformation (DTL) Naming

Include source and target schemas:

• Version conversion: "DTL_ADT_A01_2.5_to_2.3"
• System mapping: "DTL_EMR_to_Billing_ADT"
• Subtransformations: "SubDTL_PID_Standard" or "SubDTL_PV1_AddFacilityCode"

Routing Rule Naming

Describe the purpose:

• "Route_ADT_to_Billing"
• "Filter_OutpatientOnly"
• "Transform_Version_2.5_to_2.3"

Organizational Extensions

Many organizations extend base conventions with:

• Environment prefixes: DEV_, TEST_, PROD_
• Department identifiers: ADT_, LAB_, RAD_
• Versioning suffixes: _v1, _v2
• Key principle: Establish conventions and follow them rigorously