T2.3: Applies Configuration Settings

Overview

All production components in InterSystems HealthConnect share a common set of configuration settings that control fundamental operational behavior.

Enabled Setting

• Determines whether the component is active (On) or inactive (Off)
• Disabling a component stops it from processing any messages
• Useful during maintenance or troubleshooting without removing the component

Pool Size

A critical setting controlling concurrent instances:

• Pool Size of 1: Only one message processed at a time, ensuring strict sequential processing
• Higher Pool Size values: Allow parallel processing, improving throughput but may affect message ordering
• Interacts with queue management and FIFO requirements

Schedule Setting

Provides time-based control over component activation:

• Configure component to be enabled only during specific hours or days
• Useful for batch processing windows, maintenance schedules, or business hours integrations
• Uses flexible syntax allowing daily, weekly, and custom time ranges

Alert on Error

• Automatically generates an alert message when component encounters an error
• Alerts sent to the special Ens.Alert component in the production
• Can be forwarded to administrators via email or other notification mechanisms
• Essential for proactive monitoring and rapid response

Log Trace Events

Controls logging verbosity:

• When enabled, detailed event information is written to the Event Log
• Invaluable for troubleshooting
• Can impact performance and storage in high-volume environments
• Enable during development and troubleshooting; consider carefully for production use

Overview

Message Schema Category is arguably the most critical Business Service configuration setting for HL7 integrations. Often overlooked, making it a frequent exam trap.

What It Does

Defines which HL7 schema (version and structure definitions) the Business Service uses:

• Value is typically an HL7 version like "2.3.1", "2.5", or "2.7"
• Can also be a custom schema category if you've defined custom message structures

Four Essential Functions

1. DocType Definition

• System uses the schema to determine exact message structure
• Determines types like ADT_A01 or ORU_R01 based on MSH segment content

2. Proper Parsing and Display

• Shows all fields in blue in the message trace details
• Makes the message structure navigable in the viewer

3. Message Validation in Message Router

• Router validates incoming messages against the schema
• Without this setting, validation fails even though Business Service appears to process successfully
• Creates confusing troubleshooting scenario where error appears in Message Router but root cause is in Business Service

4. HL7 Property Access in Routing Rules

• Enables access to HL7 message properties in routing rule conditions
• When using HL7.{} syntax, rule engine relies on docCategory from this setting
• Without it, routing rules cannot access message content
• Causes routing failures or forces use of less elegant alternatives

Overview

FIFO (First In, First Out) message ordering is essential for many healthcare integrations where messages must be processed in the exact order they were generated.

Why FIFO Matters

• Example: Bed management system requires patient admission message before transfer-to-new-room message
• If messages arrive out of order, system might reject the transfer
• Patient not recognized as admitted yet

FIFO Configuration Requirements

Requires every component in the message processing chain to process only one message at a time:

Business Services and Business Operations

• Set Pool Size = 1
• Ensures only one instance of the component can run at a time
• Processes messages sequentially from the queue in arrival order

Business Processes

• Use Actor Pool Size rather than Pool Size
• Set Actor Pool Size = 1 for sequential processing
• Controls how many concurrent instances of the Business Process can be active
• With Actor Pool Size = 1, only one message processed at a time

Pool Size = 0 Gotcha

A complex scenario involving Pool Size = 0:

• Does NOT mean the process doesn't run
• Means the process uses instances from the production-level Actor Pool Size setting
• If production-level Actor Pool Size > 1, this can inadvertently break FIFO ordering
• Multiple instances can process messages in parallel
• For strict FIFO: Ensure Business Process has explicit Actor Pool Size = 1

Overview

The Failure Timeout setting in Business Operations controls how long the component continues attempting to deliver a message when the target system is unavailable or rejecting messages.

Failure Timeout = -1 (Indefinite Retry)

• Default value for many HL7 TCP Business Operations
• Component will retry indefinitely until message is delivered or manually suspended
• FIFO behavior: Maintains strict FIFO ordering because it never gives up on a message
• If message 1 cannot be delivered, keeps retrying indefinitely
• Messages 2, 3, 4 queue up behind message 1 and wait
• Risk: Can cause queue buildup if target system remains unavailable

Positive Failure Timeout

Setting to a positive value (like 10 or 60 seconds):

• When timeout is reached, Business Operation fails the current message
• Moves on to process the next message in the queue
• Improves system responsiveness and prevents indefinite queue buildup
• FIFO impact: Breaks FIFO ordering
• Message 1 might fail and be suspended while messages 2, 3, 4 are delivered
• Target system receives messages out of order

The Trade-off

Fundamental trade-off in integration design:

• Strict FIFO requirements: Typically demand Failure Timeout = -1
• Accept the risk of queue buildup if target systems become unavailable
• Systems tolerating out-of-order messages: Can use positive timeout values
• Improves overall throughput and system responsiveness

InterSystems HealthConnect provides comprehensive alerting capabilities to enable proactive monitoring of production health and rapid response to integration issues. Every production includes a special component called Ens.Alert (the name is fixed and cannot be changed) that automatically receives all alerts generated by production components. This central alert receiver can then forward alerts to administrators via email, to monitoring systems, or to other notification mechanisms.

Alert on Error is the most commonly used alert setting, available on all Business Services, Business Processes, and Business Operations. When enabled, this setting automatically generates an alert whenever the component encounters an error during message processing. These alerts include information about the error type, the message that triggered the error, and relevant context to help administrators quickly identify and respond to problems.

Queue Count Alert provides a different monitoring perspective by alerting when too many messages are queued waiting for processing by a component. You configure a threshold (like 100 messages), and when the queue exceeds this length, an alert is generated. This is useful for detecting system capacity issues, target system slowdowns, or unexpected message volume spikes that could lead to processing delays even if no actual errors are occurring.

Queue Wait Alert monitors message latency rather than queue depth. This setting alerts when messages wait in queue longer than a specified duration (like 30 minutes or 1 hour). This can detect different problems than Queue Count Alert - you might have only 2 messages in queue, but if they've been waiting 2 hours because the target system isn't responding, Queue Wait Alert will trigger even though Queue Count Alert wouldn't.

Alert Retry Grace Period is a more sophisticated setting that prevents alert storms during message retry scenarios. When a Business Operation is retrying a message delivery, it might fail multiple times before succeeding or reaching the Failure Timeout. Without Alert Retry Grace Period, each failure could generate a separate alert, overwhelming administrators with notifications about the same issue. Setting a grace period (like 5 minutes) postpones alert generation while retries are occurring, sending an alert only if the issue persists beyond the grace period.

Secure credential management is essential for enterprise integrations where Business Operations connect to external systems that require authentication. InterSystems HealthConnect provides a centralized credential management system that stores usernames and passwords securely and allows multiple components to reference the same credential definition. This approach is far superior to hardcoding credentials in code or configuration settings.

Credentials are managed through the Interoperability menu, navigating to Configure → Credentials. This interface allows you to create credential definitions, each with a unique identifier (the credential name), a username, and a password. The password is encrypted when stored, protecting it from casual viewing in the database or configuration exports. You can create as many credential definitions as needed for different systems or different authentication levels.

When configuring Business Operations that require authentication (like HTTP connections, database connections, FTP servers, or SOAP services), you reference the credential by its identifier rather than entering the username and password directly. The Business Operation setting is typically called "Credentials" and uses a dropdown to select from defined credentials. At runtime, the Business Operation retrieves the username and password from the credential definition and uses them for authentication.

The reuse capability is particularly valuable in large productions. If you have multiple Business Operations connecting to the same external system with the same authentication, they can all reference the same credential definition. When the password needs to be changed (as part of regular security rotation), you update it once in the credential definition, and all Business Operations automatically use the new password without requiring individual component configuration changes.

Default Site Settings (also called System Default Settings) provide a powerful mechanism for managing environment-specific configuration outside of the production definition itself. This capability is essential for maintaining consistent production code across Development, Test, and Production environments while allowing each environment to use appropriate resource connections like different database servers, SMTP servers, file paths, or IP addresses.

The key behavior of Default Site Settings is that they override values imported during production deployment. When you export a production from Development and import it into Production, all configuration settings come with their Development values. However, if a Default Site Setting is configured in the Production environment for a particular component and setting, that default value takes precedence over the imported value. The production uses the environment-specific default rather than the imported Development value.

Default Site Settings support wildcard notation using the asterisk (*) character. For example, you could define a file path setting that applies to all Business Services using File adapters, or a pool size setting that applies to all Business Operations. The wildcard can be used in the component name portion of the setting definition, allowing a single default setting to control configuration across multiple components. This is particularly useful for applying consistent environment-wide policies.

In the production configuration portal, settings that are controlled by Default Site Settings display in blue rather than the standard black text. This visual indicator helps administrators quickly identify which settings are being controlled by defaults versus which are using values from the production definition. When troubleshooting configuration issues, checking for blue-colored settings can reveal whether a Default Site Setting is unexpectedly overriding the production definition.

An important characteristic of Default Site Settings is that they are not included in production exports. They remain environment-specific and survive production deployments. This is actually the desired behavior - it ensures that Production environment default settings continue to control Production-specific configuration even after deploying new versions of the production from Development. However, it means you must configure Default Site Settings separately in each environment; they don't automatically propagate during deployment.

Beyond the common settings shared by all components, each adapter type has specific configuration settings that control how it connects to external systems and processes messages. Understanding these adapter-specific settings is essential for configuring functional integrations and troubleshooting connectivity issues.

File adapters, used for reading HL7 messages from files or writing messages to files, have a critical setting called FilePath. Despite the name suggesting a file path, this setting actually specifies a directory path. For inbound File adapters (in Business Services), FilePath specifies the directory where the adapter looks for files to read. For outbound File adapters (in Business Operations), FilePath specifies the directory where the adapter writes files. Note that on the exam, this setting might be incorrectly called "FileDirectory" - be aware that the correct setting name is "FilePath" even though it contains a directory path.

TCP adapters are used for real-time, connection-oriented HL7 messaging. The Port setting is critical - it specifies which TCP port the adapter listens on (for inbound adapters in Business Services) or connects to (for outbound adapters in Business Operations). TCP adapters also have settings for connection timeout, read timeout, and whether to maintain persistent connections versus connecting for each message. Understanding these settings is important for configuring reliable TCP-based HL7 interfaces.

FTP adapters enable remote file transfer for HL7 messages. Key settings include the FTP server address, credentials for authentication (often referencing a credential definition), the directory path on the remote server, and connection parameters like timeout and passive mode. FTP adapters can both retrieve files from remote servers (inbound) and send files to remote servers (outbound), with setting variations depending on the direction.

HTTP and SOAP adapters for web service integrations have their own specific settings including the URL endpoint, SSL/TLS configuration for secure connections, credentials for HTTP authentication, and timeout settings for request/response cycles. These adapters are increasingly common in modern healthcare integrations as systems move toward web service APIs rather than traditional file or TCP-based HL7 messaging.

Business Services have several critical settings beyond the common component settings and adapter settings. TargetConfigNames specifies where the Business Service sends messages after receiving them. This setting contains the configuration name of a Business Process or Business Operation in the production. Without this setting configured, the Business Service receives messages but doesn't send them anywhere, resulting in messages that appear to be processed but never reach their destination.

Call Interval is a Business Service-specific setting that controls polling frequency. It specifies the number of seconds the Business Service waits between checks for new messages. For File adapters, this is how often the adapter scans the directory for new files. For FTP adapters, it's how often the adapter connects to the remote server to check for files. Lower values mean more frequent polling and faster message processing, but higher system overhead. Higher values reduce system load but increase latency. Typical values range from 5 seconds to 60 seconds depending on message urgency and volume.

Reply Code Actions, also found in Business Operations and Business Processes, controls how the component handles different types of acknowledgment responses. For Business Services that can return acknowledgments (like TCP, HTTP, and SOAP Business Services), this setting determines what type of ACK to send and what to do when receiving different types of responses. This is covered in more detail in the ACK/NACK functionality topic but is important to recognize as a Business Service setting.

These Business Service settings work together to control message flow through the production. TargetConfigNames determines the destination, Call Interval controls the timing of message receipt, Message Schema Category enables proper message interpretation and routing, and Reply Code Actions controls acknowledgment behavior. Missing or misconfigured Business Service settings are common causes of integration failures and frequent exam topics.