1. Business Service Functionality
Key Points
- Primary role: Receives inbound data from external systems
- ACK capability: Can return acknowledgments to calling applications
- Single source constraint: One BS processes from one source
- One TCP port
- One directory for file input
- One FTP location
- Schema limitation: Can only be assigned ONE HL7 schema version
- Multi-message support: Can receive different message types (ADT, SIU, ORM) from same application
- Version restriction: Cannot mix HL7 2.3 and 2.5 in same BS
- Message forwarding: Sends to target via TargetConfigNames setting
Detailed Notes
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
Documentation References
2. Business Operation Functionality
Key Points
- Primary role: Sends outbound data to external systems
- Single destination constraint: One BO connects to one destination
- One IP address and port combination
- One FTP server
- One file system directory
- Adapter type: Uses OutboundAdapter for protocol handling
- Multiple destinations: Requires multiple Business Operations
- Rare pattern: Non-HL7 BO can call another BO (though BP is preferred)
- Cannot call: Business Processes (can only return responses)
Detailed Notes
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
Documentation References
3. Business Process Functionality
Key Points
- Two main types:
- HL7 Message Router (most common for HL7)
- Custom BPL (Business Process Language) for complex logic
- Message Router capabilities:
- Message validation (via Validation setting)
- Routing rule execution (RuleSet)
- Alert generation
- Bad message handling (BadMessageHandler setting)
- Validation timing: Occurs before routing rules execute
- Can orchestrate: Calls other BPs and multiple BOs
- Cannot call: Business Services (can only return responses)
- Best practice: One Message Router per Business Service
Detailed Notes
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
Documentation References
4. Adapters Used by Built-in HL7 Components
Key Points
- The HL7 logic lives in the business host, not the adapter: the built-in EnsLib.HL7.Service.* and EnsLib.HL7.Operation.* classes parse, frame and acknowledge HL7; the adapter only handles the transport
- Only two HL7-specific adapters exist, both for TCP:
- EnsLib.HL7.Adapter.TCPInboundAdapter (used by EnsLib.HL7.Service.TCPService)
- EnsLib.HL7.Adapter.TCPOutboundAdapter (used by EnsLib.HL7.Operation.TCPOperation)
- File, FTP, HTTP and SOAP components reuse the generic adapters:
- EnsLib.File.InboundAdapter / EnsLib.File.OutboundAdapter
- EnsLib.FTP.InboundAdapter / EnsLib.FTP.OutboundAdapter
- EnsLib.HTTP.InboundAdapter / EnsLib.HTTP.OutboundAdapter
- EnsLib.SOAP.InboundAdapter / EnsLib.SOAP.OutboundAdapter
- Watch the spelling: TCPInboundAdapter is one word; there is no EnsLib.HL7.Adapter.TCP.InboundAdapter, and no HL7 File, FTP, HTTP or SOAP adapter at all
- Most common: TCP for real-time, File and FTP for batch
Detailed Notes
Overview
The exam topic is "Identifies adapters used by built-in HL7 components". InterSystems ships five HL7 business service classes and five HL7 business operation classes, one per transport, and each declares its adapter in its ADAPTER class parameter. The HL7-specific work (parsing segments, applying the Message Schema Category, framing, building ACKs) is done by the HL7 business host classes, so for most transports they reuse the same generic adapter as any other production component.
Built-in HL7 Business Services and Their Adapters
| Business service class | Transport | Adapter (ADAPTER parameter) |
|---|---|---|
EnsLib.HL7.Service.TCPService | TCP (MLLP) | EnsLib.HL7.Adapter.TCPInboundAdapter |
EnsLib.HL7.Service.FileService | Local directory | EnsLib.File.InboundAdapter |
EnsLib.HL7.Service.FTPService | Remote FTP or SFTP server | EnsLib.FTP.InboundAdapter |
EnsLib.HL7.Service.HTTPService | HTTP POST | EnsLib.HTTP.InboundAdapter |
EnsLib.HL7.Service.SOAPService | SOAP web service | EnsLib.SOAP.InboundAdapter |
Built-in HL7 Business Operations and Their Adapters
| Business operation class | Transport | Adapter (ADAPTER parameter) |
|---|---|---|
EnsLib.HL7.Operation.TCPOperation | TCP (MLLP) | EnsLib.HL7.Adapter.TCPOutboundAdapter |
EnsLib.HL7.Operation.FileOperation | Local directory | EnsLib.File.OutboundAdapter |
EnsLib.HL7.Operation.FTPOperation | Remote FTP or SFTP server | EnsLib.FTP.OutboundAdapter |
EnsLib.HL7.Operation.HTTPOperation | HTTP POST | EnsLib.HTTP.OutboundAdapter |
EnsLib.HL7.Operation.SOAPOperation | SOAP web service | EnsLib.SOAP.OutboundAdapter |
Why Only TCP Has an HL7 Adapter
The two EnsLib.HL7.Adapter classes are subclasses of the generic EnsLib.TCP.InboundAdapter and EnsLib.TCP.OutboundAdapter, with defaults suited to HL7:
- TCPInboundAdapter: Job Per Connection is False (the generic TCP adapter defaults to True), "which is usually appropriate for HL7"
- TCPOutboundAdapter: Get Reply is True, so it waits for the reply (the ACK) on the socket, and Response Timeout defaults to 30 seconds instead of the generic 15
- MLLP framing is not an adapter feature: Framing, ACK Mode and Message Schema Category are settings of the HL7 business service or operation, which is why the same settings appear on the File and FTP HL7 components too
TCP: Real-Time Messaging
- The service listens on a port; the operation connects to the remote system and waits for its ACK
- Use cases: patient admission notifications, orders and critical results that must arrive immediately
File: Local Directory
EnsLib.File.InboundAdapterpolls the File Path directory and can move processed files to an Archive PathEnsLib.File.OutboundAdapterwrites messages to files in a directory- Use cases: scheduled batch transfers, historical data loads, offline processing
FTP: Remote Server
EnsLib.FTP.InboundAdapterdownloads files from an FTP server and can delete or archive them there;EnsLib.FTP.OutboundAdapteruploads files- The Protocol setting selects FTP or SFTP (FTP can also run over TLS)
- Use cases: insurance companies, health information exchanges and reference labs that publish an FTP drop box
HTTP and SOAP: Web Services
EnsLib.HL7.Service.HTTPServiceusesEnsLib.HTTP.InboundAdapter; the documentation notes that "The HL7 HTTP service can either use the CSP port or a special port"EnsLib.HL7.Service.SOAPServiceusesEnsLib.SOAP.InboundAdapter, which spawns its own TCP listener; with Enable Standard Requests it also accepts calls through the Web Gateway port, where FIFO processing is not supported- Outbound,
HTTPOperationandSOAPOperationuseEnsLib.HTTP.OutboundAdapterandEnsLib.SOAP.OutboundAdapter
Choosing Adapters
When selecting the transport 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
Common Trap
Answer options such as EnsLib.HL7.Adapter.File.InboundAdapter, EnsLib.HL7.Adapter.FTPInboundAdapter or EnsLib.HL7.Adapter.HTTPInboundAdapter name classes that do not exist. When asked which adapter a built-in HL7 File, FTP, HTTP or SOAP component uses, the answer is the generic EnsLib.File, EnsLib.FTP, EnsLib.HTTP or EnsLib.SOAP adapter; only the TCP pair lives in EnsLib.HL7.Adapter.
Documentation References
5. Component Naming Conventions
Key Points
- Follow InterSystems naming conventions for maintainability
- Message structure naming:
- Use general class names (ADT, ORM, SIU) for simple integrations
- Use specific DocTypes (ADT_A01) when precision needed
- The documented convention assembles names from short keywords:
- `From` for incoming, `To` for outgoing, `Router` for routing processes, `Rules` for rule sets
- A short application name, plus a message-class keyword (ADT, ORM) when needed
- Patterns:
- Business services: `FromSourceAppName` → `FromEMR`, `FromERChart`
- Business operations: `ToTargetAppName` → `ToBilling`, `ToImagit`
- Routing processes: `SourceAppNameRouter` → `EMRRouter`, `ERChartRouter`
- Routing rule sets: `SourceAppNameRules` → `EMRRules`
- When one application is split by message type, insert a MessageTypes keyword:
- DTL naming: `SourceAppNameSourceMessageTypeToTargetAppNameTargetMessageType`
- Benefits: Clear ownership, easier troubleshooting, self-documenting architecture
Detailed Notes
Overview
Consistent naming conventions for production components are essential for:
- Maintainability
- Team collaboration
- Operational support
- Self-documenting architectures
Component Naming Elements
InterSystems recommends establishing a full set of naming conventions at the start of a project rather than letting them grow interface by interface. Names are assembled from short (3-6 character) segments:
- Keywords:
From(incoming),To(outgoing),Router(routing),Rules(rule sets),
and a base schema category number (2.1 … 2.7.1) for schemas
- A short name for each application (EMR, ERChart, Billing)
- A message-class keyword (ADT, ORM, ORU) or a full message structure name (ADT_A01)
Names are case-sensitive.
> The documentation notes that *any* convention which clearly identifies components by > function is acceptable — the set below is the one InterSystems publishes, and the one the > exam expects.
Business Service Naming
Convention: FromSourceAppName
- Examples: "FromERChart", "FromFineOR", "FromDeskAdm"
- Variation: when one application sends in through more than one business service, add a
MessageTypes keyword (typically the first three letters of the message structure): FromSourceAppNameMessageTypes → "FromEMRADT"
Routing Process Naming
Convention: SourceAppNameRouter
- Examples: "ERChartRouter", "FineORRouter", "DeskAdmRouter"
- Variation:
SourceAppNameMessageTypesRouter→ "ERChartADTRouter", "ERChartORMRouter",
"ERChartOtherRouter"
Routing Rule Set Naming
Name each rule set to match its routing process: for every SourceAppNameRouter call the rule set SourceAppNameRules, and for every SourceAppNameMessageTypesRouter call it SourceAppNameMessageTypesRules.
- Examples: "DeskAdmRules", "DeskAdmORMRules"
Business Operation Naming
Convention: ToTargetAppName
- Examples: "ToImagit", "ToFineOR", "ToPindex"
- Variation: when one application receives through more than one business operation, add a
MessageTypes keyword: ToTargetAppNameMessageTypes → "ToBillingADT"
- The transport is not encoded in the name — the adapter settings already record it
Custom Schema Category Naming
Convention: ApplicationNameBaseSchemaNumber (e.g. "EMR2.5"), where the application name can be the sending or the receiving application.
> Note on prefix schemes. Component-prefix conventions such as BS_EMR_ADT_TCP, > MR_EMR_ADT and BO_Billing_ADT_TCP are widely used at customer sites and satisfy the > "clearly identifies by function" test, but they are not the convention documented by > InterSystems. Exam questions asking for the recommended pattern expect the > From/To/Router/Rules set above.
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
Documentation References
Exam Preparation Summary
Critical Concepts to Master:
- Business Service Constraints: One source per BS, one HL7 schema version per BS
- Business Operation Constraints: One destination per BO (IP/port, FTP location, directory)
- Business Process Role: Orchestration, routing, transformation between BS and BO
- Message Router: Most common BP type for HL7; handles validation and routing rules
- TargetConfigNames: Setting that defines where BS sends messages (typically to Message Router)
- Adapter Types: TCP (real-time), File (batch), FTP (remote), HTTP/SOAP (web services); only TCP has HL7-specific adapters (EnsLib.HL7.Adapter.TCPInboundAdapter / TCPOutboundAdapter), the rest reuse EnsLib.File, EnsLib.FTP, EnsLib.HTTP and EnsLib.SOAP adapters
- Naming Conventions: SystemName.Direction.Protocol.MessageType pattern
Common Exam Scenarios:
- Selecting appropriate component type for given requirements
- Understanding single-source and single-destination constraints
- Configuring TargetConfigNames for message flow
- Choosing correct adapter type for integration patterns
- Applying naming conventions to production components
- Troubleshooting component configuration issues
Hands-On Practice Recommendations:
- Create Business Services with different adapter types
- Configure Business Operations for various destinations
- Set up Message Router with validation and routing rules
- Practice naming components using conventions
- Test message flow from BS through BP to BO
- Explore component settings and understand their impact