T1.1: Interprets Interface Requirements

Overview

Understanding the one-to-one relationship between active productions and namespaces is fundamental to HL7 integration architecture in InterSystems IRIS for Health. This architectural constraint means that regardless of how many external systems you're integrating with, you can only have one production running in a given namespace at any time.

Consolidation Strategy

In practice, this translates to a consolidation strategy where multiple HL7 circuits or integrations coexist within a single production:

• Even when connecting to dozens of different healthcare systems (EMRs, lab systems, radiology systems, billing applications), all these integrations typically reside in one production within one namespace
• Each integration is represented by its own set of components (Business Services, Business Processes, Business Operations) but they all belong to the same production

When to Separate Namespaces

The decision to separate integrations into multiple namespaces should be driven by scale and organizational needs:

• When managing hundreds of integrations, performance, maintenance complexity, and organizational boundaries may justify creating multiple namespaces
• Each namespace with its own production provides better isolation, easier troubleshooting, and clearer ownership boundaries
• However, for most healthcare organizations, a single production handles all HL7 interfaces effectively

Planning Considerations

When planning namespace and production architecture, consider:

• Production restart impact: Restarting production affects all integrations
• Component naming conflicts: Unique names required within a namespace
• Security boundaries: Each namespace can have different security settings
• Development vs production environments: Separate namespaces for different stages
• Organizational team structures: Clear ownership and deployment schedules

Overview

The three core component types in InterSystems HL7 productions form a unidirectional data flow architecture. Understanding which components can call which others is essential for both design and troubleshooting.

Business Services

Business Services represent the entry boundary of your production:

• Receive inbound data from external systems through various adapters (TCP, FTP, File, HTTP, SOAP)
• Process data from one source - one TCP port, one directory for file input, one FTP location
• Responsible for receiving the raw message, optionally sending an ACK back to the calling application
• Forward the message to the next component via the TargetConfigNames setting

Business Processes

Business Processes provide orchestration, routing, and transformation capabilities:

• Message Router: The most common type for HL7, performs message validation, executes routing rules, and optionally applies data transformations
• Can call other Business Processes for complex multi-stage orchestration
• Can call multiple Business Operations to implement fan-out patterns where one inbound message triggers multiple outbound messages

Business Operations

Business Operations handle outbound communication to external systems:

• Each connects to one destination - one IP address and port combination, one FTP server, one file directory
• While uncommon, a non-HL7 Business Operation can call another Business Operation
• Best practice suggests creating a Business Process to orchestrate multiple operations

Critical Architectural Constraints

• BP cannot call BS: Business Processes cannot call Business Services (they can only return responses)
• BO cannot call BP: Business Operations cannot call Business Processes (they can only return responses)
• InboundAdapters: Associated with Business Services
• OutboundAdapters: Associated with Business Operations

Overview

Translating interface specifications into production architecture requires understanding the relationship between external systems and InterSystems components:

• Each external application that sends data to IRIS requires one Business Service
• This Business Service represents the integration endpoint for that specific application

Multiple Message Types per Business Service

A single Business Service can handle multiple HL7 message types from the same application, provided they all use the same HL7 version:

• One Business Service might receive ADT messages for patient admissions, SIU messages for appointment scheduling, and ORM messages for orders
• All must be from the same hospital information system using the same HL7 version (e.g., 2.5)
• Critical limitation: Each Business Service can only be assigned one HL7 schema version
• If you need to receive HL7 2.3 from one application and HL7 2.5 from another, you must create separate Business Services

Best Practice: One-to-One Relationship

InterSystems best practices recommend associating each Business Service with its own dedicated HL7 Message Router:

• While not technically mandatory, this provides significant architectural benefits
• Simplifies evolution over time when modifying routing rules or adding new integrations
• Allows changes for one application without risk of affecting others
• Reduces testing burden and deployment risk

Outbound Communication

For outbound communication:

• Each external application that receives data requires one Business Operation
• Each Business Operation connects to a single destination (one TCP/IP address and port combination, one FTP server, one file system directory)
• To send messages to multiple destinations, create multiple Business Operations

Interface Specification Review

When reviewing interface specifications:

• Count source systems: Each requires a Business Service
• Identify HL7 versions: May require separate Business Services
• Count destination systems: Each requires a Business Operation
• Message Routers: Sit between BS and BO, providing validation, routing logic, and transformation

Overview

Determining data transformation needs from interface requirements involves identifying mismatches between what you receive and what you must send. The most common transformation scenarios in HL7 integrations are:

• Version conversion
• Structural mapping
• Value mapping

Version Conversion Transformations

Required when the sending system uses a different HL7 version than the receiving system:

• Example: Lab system sends results using HL7 2.5 (ORU_R01 2.5 structure), but EMR only accepts HL7 2.3
• While message types are conceptually the same, segment structures, field positions, and data types can differ between versions
• Requires explicit transformation using a Data Transformation Language (DTL) class

Structural Mapping Transformations

Address differences in how systems organize data:

• One system might include patient insurance information in the standard IN1 segment, while another requires it in a custom Z-segment
• Some systems include optional segments like PD1 (Patient Additional Demographic), others don't
• DTL handles these differences by extracting data from one structure and mapping it to another

Value Mapping Transformations

Convert codes and formats between systems:

• Gender codes: One system uses "M" and "F", another uses "Male" and "Female"
• Facility codes, provider identifiers, department codes: Often require mapping between different code systems
• DTLs provide lookup table capabilities for these conversions

Subtransformations

A powerful efficiency feature for reusable segment-level logic:

• Create one subtransform for a segment (like PID) that appears in multiple message types
• Call the same subtransform from multiple main DTLs (ADT_A01, SIU_S12, etc.)
• Benefits: Reduces duplication, ensures consistency, simplifies maintenance

Execution Context

Transformations execute in two ways:

• As part of routing rule "transform" actions
• Programmatically from BPL (Business Process Language) code in custom Business Processes

Overview

Message validation in HL7 Message Routers is controlled by the "Validation" setting, which determines how strictly messages are checked against their schema definitions before routing rules execute. Understanding validation settings is critical because validation failures prevent message processing - the message won't be routed to any destinations (except optionally to a BadMessageHandler component if configured).

Default Validation Setting

The default validation setting is "1", which is equivalent to "dm-z". This is the most commonly used validation configuration in production environments.

Validation Components Explained

• d (DocType): DocType must be assigned to the message
• The Business Service must have a Message Schema Category assigned in its settings
• Schema category (like "2.5") combined with message structure (like "ADT_A01") forms the complete DocType (like "2.5:ADT_A01")
• When using the Testing Service, you must fill in the DocType field or validation will fail
• m (Message structure): Validates message structure at the segment level
• Checks whether required segments are present
• Checks whether segments that should be unique are not repeated
• Checks whether extra segments that aren't defined in the schema are present
• Catches structural problems like a missing EVN segment in an ADT_A01 message
• -z (Negative z): Allows unrecognized Z-segments at the end of the message
• Even if they aren't defined in the Message Schema Category
• Useful for accepting messages with custom segments without defining custom schemas

What dm-z Does NOT Check

Field-level validations are not included:

• Whether fields exceed maximum length
• Whether required fields within segments are populated
• Whether values comply with code table constraints
• Whether data types are correct
• Additional options like "r" (required field checking) and "l" (length checking) are less commonly used

Validation Timing

• Validation executes before routing rule processing
• If validation fails, no routing rules execute
• Message is either discarded or sent to BadMessageHandler if configured
• This fail-fast approach prevents invalid messages from propagating

Overview

Routing rules form the decision logic in HL7 Message Routers, determining where messages are sent and what transformations are applied. Understanding routing rule structure is essential for both designing integrations and troubleshooting routing issues.

RuleSet Level Settings

At the RuleSet level, effectiveBegin and effectiveEnd dates control when the entire set of rules becomes active:

• Enables you to prepare routing changes in advance
• Deploy new routing rules to production but have them automatically activate on a specific future date and time
• Particularly valuable for scheduled upgrades, go-lives, or regulatory compliance changes

Individual Rule Components

Each individual rule has a disabled flag and a constraint section:

• Disabled flag: When true, the rule is completely skipped
• Constraint section: Acts as a filter determining which messages the rule applies to

Constraint Fields

• Source: Which Business Service or Business Process must have sent the message
• Important during testing: when using Testing Service, you must populate the Source field to match the constraint
• Schema Category: The HL7 version (like "2.5")
• DocType: The message structure (like "ADT_A01")
• Document Name: The specific event

Enabling Field-Level Conditions

Critical requirement for using "when" conditions that reference HL7 fields:

• You must specify the Schema Category and DocType in the constraint
• Without this information, the routing engine cannot parse the message structure to access individual fields
• Your condition will fail if these are not specified

Routing Rule Actions

• Send: Routes the message to one or more target components
• A single Send action can have multiple targets
• Can include a transform, applying a DTL to convert the message structure before sending
• For different transformations to different destinations, use separate Send actions
• Return: Critical for controlling rule execution flow
• When executed, no subsequent rules are evaluated for that message
• Allows exception-handling rules at the top that process special cases and return
• Without Return, all rules are evaluated and multiple Send actions could fire
• Continue: Explicitly indicates processing should continue to the next rule
• This is the default behavior when no Return is present
• Makes rule logic more readable and maintainable