diff --git a/.vitepress/config.mts b/.vitepress/config.mts index ced8cfd..58a0903 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -13,6 +13,7 @@ export default defineConfig({ { text: 'Documentation', link: '/engine/' }, { text: 'Launchers', link: '/launchers/' }, { text: 'Examples', link: '/examples/' }, + { text: 'Contributing', link: '/engine/contributing' }, ], logo: 'https://raw.githubusercontent.com/OpenIntegrationEngine/governance/refs/heads/main/branding/logos/oie_logo_only_white_background.svg', @@ -31,19 +32,132 @@ export default defineConfig({ outline: [2, 3], sidebar: [ + { text: 'Overview', link: '/engine/' }, { - text: 'Engine', + text: 'Concepts', collapsed: false, items: [ - { text: 'Overview', link: '/engine/' }, + { text: 'Architecture', link: '/engine/architecture_overview' }, + { text: 'Message Lifecycle and Storage', link: '/engine/message_lifecycle' }, + { text: 'Threading and Ordering', link: '/engine/threading_and_ordering' }, + { text: 'Queueing', link: '/engine/queueing' }, + { text: 'Deploy, Start, and Channel State', link: '/engine/channel_state' }, + { text: 'Data Types and Formats', link: '/engine/data_types_and_formats' }, + ] + }, + { text: 'Glossary', link: '/engine/glossary' }, + { + text: 'Getting Started', + collapsed: true, + items: [ { text: 'Installation', link: '/engine/installation' }, { text: 'Server Process Management', link: '/engine/server_process_management' }, { text: 'Accessing the Administrator', link: '/engine/accessing_the_administrator' }, + ] + }, + { + text: 'Migrating from Mirth Connect', + link: '/engine/migrating_from_mirth_connect', + collapsed: true, + items: [ + { text: 'Linux', link: '/engine/migrating_linux' }, + { text: 'Windows', link: '/engine/migrating_windows' }, + { text: 'macOS', link: '/engine/migrating_macos' }, + ] + }, + { + text: 'Administrators', + collapsed: true, + items: [ + { text: 'Desktop Administrator', link: '/engine/desktop_administrator' }, + { text: 'Web Administrator', link: '/engine/web_administrator' }, + { text: 'Dashboard and Monitoring', link: '/engine/dashboard_and_monitoring' }, + ] + }, + { + text: 'Channels', + collapsed: true, + items: [ + { text: 'Channels', link: '/engine/channels' }, + { text: 'Channel Development Guide', link: '/engine/channel_development_guide' }, + { text: 'Filters and Transformers', link: '/engine/filters_and_transformers' }, + ] + }, + { + text: 'Connectors', + collapsed: true, + items: [ + { text: 'Sources', link: '/engine/connector_reference_sources' }, + { text: 'Destinations', link: '/engine/connector_reference_destinations' }, + { text: 'Polling Settings', link: '/engine/polling_settings' }, + ] + }, + { + text: 'Scripting', + collapsed: true, + items: [ + { text: 'Script Scope and User API', link: '/engine/script_scope_and_user_api' }, + { text: 'JavaScript Editor', link: '/engine/javascript_editor' }, + { text: 'Code Templates', link: '/engine/code_templates' }, + { text: 'Global Scripts', link: '/engine/global_scripts' }, + { text: 'Velocity Variable Replacement', link: '/engine/velocity_variable_replacement' }, + { text: 'Source Map Variables', link: '/engine/source_map_variables' }, + { text: 'Debugger', link: '/engine/debugger' }, + ] + }, + { + text: 'Configuration', + collapsed: true, + items: [ + { text: 'Server Configuration', link: '/engine/server_configuration' }, + { text: 'Database Support', link: '/engine/database_support' }, + { text: 'Configuration Properties Reference', link: '/engine/configuration_properties_reference' }, + ] + }, + { + text: 'Operations', + collapsed: true, + items: [ + { text: 'User Management', link: '/engine/user_management' }, + { text: 'Alerts and Notifications', link: '/engine/alerts_and_notifications' }, + { text: 'Logging', link: '/engine/logging' }, + { text: 'Data Pruning and Maintenance', link: '/engine/data_pruning_and_maintenance' }, + { text: 'Upgrade Guide', link: '/engine/upgrade_guide' }, + ] + }, + { + text: 'Security', + collapsed: true, + items: [ + { text: 'Security and Compliance', link: '/engine/security_and_compliance' }, + { text: 'Security Posture and Hardening', link: '/engine/security_posture_and_hardening' }, + ] + }, + { + text: 'Extensions', + collapsed: true, + items: [ { text: 'Plugin Guide', link: '/engine/plugins' }, - { text: 'Building from Source', link: '/engine/building_from_source' }, - { text: 'Contributing', link: '/engine/contributing' }, ] }, + { + text: 'CLI and API', + collapsed: true, + items: [ + { text: 'Command Line Interface', link: '/engine/command_line_interface' }, + { text: 'REST API', link: '/engine/rest_api' }, + ] + }, + { + text: 'Help and Reference', + collapsed: true, + items: [ + { text: 'Frequently Asked Questions', link: '/engine/frequently_asked_questions' }, + { text: 'Troubleshooting', link: '/engine/troubleshooting' }, + ] + }, + { text: 'Building from Source', link: '/engine/building_from_source' }, + { text: 'Contributing', link: '/engine/contributing' }, { text: 'Launchers', link: '/launchers/' }, { text: 'Examples', link: '/examples/' }, ], diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css new file mode 100644 index 0000000..080b7b4 --- /dev/null +++ b/.vitepress/theme/custom.css @@ -0,0 +1,26 @@ +/* Screenshots get an edge and a shadow so they stand apart from the page, and a cursor that shows they enlarge. */ +.vp-doc img:not([src^="http"]) { + border: 1px solid var(--vp-c-divider); + border-radius: 6px; + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 6px 20px rgba(0, 0, 0, 0.18); + cursor: zoom-in; +} + +.img-zoom { + position: fixed; + inset: 0; + z-index: 100; + display: flex; + align-items: center; + justify-content: center; + padding: 2vmin; + background: rgba(0, 0, 0, 0.8); + cursor: zoom-out; +} + +.img-zoom img { + max-width: 100%; + max-height: 100%; + border-radius: 6px; + box-shadow: 0 8px 40px rgba(0, 0, 0, 0.5); +} diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts new file mode 100644 index 0000000..b7f3124 --- /dev/null +++ b/.vitepress/theme/index.ts @@ -0,0 +1,38 @@ +import DefaultTheme from 'vitepress/theme' +import {inBrowser, type Theme} from 'vitepress' +import './custom.css' + +// Screenshots in a page; badges and other images from elsewhere are left alone. +const SCREENSHOT = '.vp-doc img:not([src^="http"])' + +// Shows the image at full size over the page. A click anywhere or Escape closes it. +function zoom(img: HTMLImageElement) { + const overlay = document.createElement('div') + overlay.className = 'img-zoom' + const large = document.createElement('img') + large.src = img.currentSrc || img.src + large.alt = img.alt + overlay.appendChild(large) + + const onKey = (e: KeyboardEvent) => { + if (e.key === 'Escape') close() + } + const close = () => { + overlay.remove() + document.removeEventListener('keydown', onKey) + } + overlay.addEventListener('click', close) + document.addEventListener('keydown', onKey) + document.body.appendChild(overlay) +} + +export default { + extends: DefaultTheme, + enhanceApp() { + if (!inBrowser) return + document.addEventListener('click', (e) => { + const img = e.target instanceof HTMLImageElement ? e.target : null + if (img?.matches(SCREENSHOT) && !img.closest('a')) zoom(img) + }) + } +} satisfies Theme diff --git a/docs/engine/accessing_the_administrator.md b/docs/engine/accessing_the_administrator.md index 30b3217..4a46877 100644 --- a/docs/engine/accessing_the_administrator.md +++ b/docs/engine/accessing_the_administrator.md @@ -13,63 +13,57 @@ After accepting the self-signed certificate in your browser, you will see this p From here there are two ways to administer the engine: a browser, or the desktop Administrator. -## Web administrator +## Web Administrator -[Web Support](https://github.com/gibson9583/oie-web-support-plugin) is a community extension by Chris Gibson that installs a browser-based administrator into the engine's own web server. It works read/write against the same REST API as the desktop client, covering channel editing, deployment, and the message browser. It requires OIE 4.6.0. +The Web Administrator is a browser-based administrator, developed separately from the engine as [oie-web-client](https://github.com/gibson9583/oie-web-client). It works read/write against the same REST API as the desktop client, covering channel editing, deployment, and the message browser. No launcher is involved. -Install it as you would any other extension, described in the [plugin guide](./plugins.md), then restart the engine and open `https://:8443/oie-webadmin/`. No launcher is involved. +It runs in one of three ways: as a standalone Node.js app, as a Docker container, or inside the engine's own web server. For the last, install the [Web Support](https://github.com/gibson9583/oie-web-support-plugin) community extension by Chris Gibson as you would any other extension (see the [plugin guide](./plugins.md)), restart the engine, and open `https://:8443/oie-webadmin/`. See [Web Administrator](./web_administrator.md) for what it covers and which engine versions it supports. ## Desktop Administrator -The desktop Administrator is a Java application and needs a launcher to start it. Copy the Administrator Launcher URL from the page above, then use one of the launchers below. See [Launchers](/launchers/) for the full list. - -### Ballista - -[Ballista](https://github.com/kayyagari/ballista/releases) is an open-source Administrator launcher for Open Integration Engine built on Tauri. +The desktop Administrator is a Java application and needs a launcher to start it. Copy the Administrator Launcher URL from the page above, then use Launcher, below. See [Launchers](/launchers/) for more about it, and [Desktop Administrator](./desktop_administrator.md) for a tour of the client. ### Launcher -[Launcher](https://github.com/diridium-com/launcher/releases) is a fork of Ballista, also built on Tauri and open source under MPL-2.0. +[Launcher](https://github.com/diridium-com/launcher/releases) is an open-source Administrator launcher for Open Integration Engine, built on Tauri and released under MPL-2.0. It is a fork of Ballista. -### MCAL +![Launcher's main window listing two connections, one online and one unreachable](images/launcher_connections.png) -The original Mirth® Connect Administrator Launcher by NextGen Healthcare (MCAL) works with OIE. Here is how you can use it to launch the OIE Administrator client GUI application. +Add a connection with the engine's address, `https://:8443`, and the Java home of a JavaFX-enabled JDK, then double-click the connection or click its play button to start the Administrator. -Open MCAL. If it's the first launch, the left panel with connections is empty. +![Launcher's New Connection dialog with the name, address, Java home, username and password filled in](images/launcher_new_connection.png) -![MCAL application window showing "no saved connections" in left panel](images/gs_mcal_step_1.png) +## Initial admin password -To work better with OIE, choose `Bundled Java 17` +A new database has one user, `admin`. Unless `server.initialadminpassword` in `conf/mirth.properties` is set before the server first starts, the server generates a random password for it and writes it once, at WARN level, to the console and to `logs/mirth.log`: -And just click on `Launch` at the top right screen. +```log +WARN ... com.mirth.connect.server.Mirth: +******************************************************************************** +************ Initial admin password is Aa1!xxxxxxxxxxxxxxxxxxxx ************ +******************************************************************************** +``` -You should see a progress bar that will load the files necessary to launch the Open Integration Engine client. - -## Logging in +The generated password is 24 characters long and starts with `Aa1!`. `server.initialadminpassword` is read only when the database is created. -::: info -On 4.6.0 a new instance starts with: +A database that already exists, after an upgrade or a migration from Mirth Connect, keeps its users and their passwords. -* login: **admin** -* password: **admin** +The CLI's shipped `conf/mirth-cli-config.properties` contains `user=admin` and `password=admin`. Put the real password there, or pass it with `-p`. See [Command Line Interface](./command_line_interface.md#configuration). -A future release replaces this with a password generated on first boot. -::: +## Logging in Enter your credentials and click `Login` when the login screen appears. After a brief loading screen, you will see the OIE dashboard. -If this is your first login, you are prompted to change the default password. +### First login -![Edit User screen requesting username, password, and optional demographic information](images/gs_oie_credential_update_step_1.png) +In the desktop Administrator, every user's first login opens a dialog titled **Welcome to Open Integration Engine** before the dashboard. -Fill the information, and don't forget to set the `New Password` (2 times) +![The Welcome to Open Integration Engine dialog, with New Password and Confirm New Password marked required and Finish disabled](images/welcome_dialog.png) -And click on `Finish` +Enter a password in `New Password` and `Confirm New Password`, then click `Finish`. `Finish` stays disabled until both are filled in, and the server refuses a password that does not meet the [password policy](./user_management.md#password-policy), which with the shipped settings means at least 15 characters. The other fields are optional. Closing the dialog logs you out. ![Application ready to use at the Dashboard screen showing no deployed channels and the server startup messages in the log section](images/gs_oie_dashboard.png) -It's finished. Now you can start to use your OIE server. - ::: warning Every account is an administrator All users are administrators by default, with privilege to write and execute channel scripts on the server. Grant access only to users who should be able to author and execute scripts, or install an RBAC plugin to create low-privileged roles. diff --git a/docs/engine/alerts_and_notifications.md b/docs/engine/alerts_and_notifications.md new file mode 100644 index 0000000..74eb9f6 --- /dev/null +++ b/docs/engine/alerts_and_notifications.md @@ -0,0 +1,150 @@ +--- +title: Alerts and Notifications +description: Configuring alert triggers and actions +--- + +# Alerts and Notifications + +An alert watches for chosen categories of errors on the channels and connectors you select. When a matching error occurs, the alert runs all of its actions: sending emails, notifying users, or dispatching a message to a designated channel. + +## How alerts work + +The **Alerts** view in the main navigation shows a summary table of all configured alerts: + +| Column | Description | +|---|---| +| **Status** | Whether the alert is currently enabled or disabled | +| **Name** | The alert name | +| **Id** | The alert's unique identifier | +| **Alerted** | How many times the alert has fired since it was last enabled | + +## Creating and editing an alert + +Click **New Alert** in the Alerts task panel, or select an existing alert and click **Edit Alert** (you can also double-click an alert row). The Edit Alert view has three main configuration areas: error types, channel selection, and actions. + +![The alert editor with the error type list, the regex field, the channel tree, the actions table, the template and the alert variables](images/alert_editor.png) + +### Error types and regex + +Choose which categories of error trigger the alert. Select one or more: + +| Error Category | What It Covers | +|---|---| +| **Any** | All error categories at once | +| **Source Connector** | Errors while the source connector receives or polls for messages, or delivers a response. A source connector that fails to start raises no alert | +| **Destination Connector** | Errors during message dispatch or response receipt | +| **Serializer** | Errors when converting a message to or from its internal representation (e.g. parsing HL7 to XML) | +| **Filter** | Errors thrown by a source or destination filter rule | +| **Transformer** | Errors thrown by a source or destination transformer step | +| **User Defined Transformer** | Errors dispatched by a manual call to `alerts.sendAlert(errorMessage)` from any script that has a channel in scope. The global deploy and undeploy scripts do not have the `alerts` object | +| **Response Validation** | Errors from destination response validation. For example, receiving an HL7 NACK | +| **Response Transformer** | Errors from a destination's response transformer step | +| **Attachment Handler** | Errors from the attachment handler | +| **Deploy Script** | Errors from a channel's deploy script | +| **Preprocessor Script** | Errors from a global or channel preprocessor script | +| **Postprocessor Script** | Errors from a global or channel postprocessor script | +| **Undeploy Script** | Errors from a channel's undeploy script | + +You can optionally provide a **regex pattern** that is searched for in the full error output, a composite string that includes the error type, error source line (if available), the custom error message, and the exception stack trace. The alert fires when the pattern is found anywhere in the combined output. + +### Channel and connector selection + +The channel tree sets which channels and connectors the alert monitors. Individual connectors within a channel can be enabled or disabled, for example to watch only the source connector. + +Two special entries are available: + +- **[New Channels]**. Automatically include any channel created after the alert was set up +- **[New Destinations]**. Automatically include any new destination added to an already-monitored channel + +Use the **Filter** field above the tree to search channels by name, and the **Enable** / **Disable** buttons to toggle selection in bulk. + +### Actions + +Each alert can have multiple actions that all fire when the alert triggers. For every action, you choose a **protocol** and a **recipient**: + +| Protocol | Behavior | +|---|---| +| **Email** | Sends an email to the address specified in the Recipient column. Uses the Subject and Template fields. | +| **User** | Sends an email to the email address on file for the selected OIE user account | +| **Channel** | Dispatches the Template content as a message to the channel specified in the Recipient column. The Subject field is ignored. | + +#### Subject and template + +The **Subject** line (used only for email-based protocols) and the **Template** body both support alert variables and Velocity replacement syntax. You can also reference any Global Map or Configuration Map entry. + +## Alert variables + +These variables can be used in the Subject and Template fields: + +| Variable | Description | +|---|---| +| `${alertId}` | The alert's unique ID | +| `${alertName}` | The alert's name | +| `${serverId}` | The server's unique ID | +| `${serverName}` | The configured server name (added in 4.6.0) | +| `${date}` | A Velocity DateTool object. Use `${date.get('yyyy-MM-dd HH:mm:ss')}` for formatted output | +| `${systemTime}` | The time the error occurred, as a Unix epoch value in milliseconds | +| `${error}` | The full error output including error type, source line, message, and stack trace | +| `${errorMessage}` | The exception message string, or "No exception message." if no exception is present | +| `${errorType}` | The error category (matches the categories listed above) | +| `${channelId}` | The ID of the channel where the error occurred | +| `${channelName}` | The name of that channel | +| `${connectorName}` | The name of the connector where the error occurred. Null for errors that have no connector, which include deploy, undeploy, preprocessor, postprocessor, and attachment handler errors, and `alerts.sendAlert()` called from the deploy, undeploy, or postprocessor scripts | +| `${connectorType}` | The connector protocol name (e.g. "TCP Sender", "HTTP Listener"), if available | +| `${messageId}` | The message ID associated with the error (only present when a message is involved) | + +Global Map and Configuration Map entries are also available by name. For example, `${myGlobalVar}` will resolve if a matching entry exists. + +### Example template + +This Template body uses only variables from the table above. + +```text +Channel: ${channelName} (${channelId}) +Connector: $!{connectorName} +Message ID: $!{messageId} +Date: ${date.get('yyyy-MM-dd HH:mm:ss')} + +${error} +``` + +Velocity runs in its default non-strict mode, so a reference whose variable is missing or null is written out as its own literal text, `${messageId}` for example. The `$!{messageId}` form writes nothing instead. That matters for errors with no connector (see `${connectorName}` above), and for deploy and undeploy script errors, which have no message either. + +## Email configuration + +For email-based alert actions to work, you need to configure the SMTP settings on the **Server** tab under **Settings**: + +| Setting | Description | +|---|---| +| **SMTP Host** | Your mail server hostname | +| **SMTP Port** | The mail server port | +| **Send Timeout** | How long to wait before giving up on a connection (in milliseconds) | +| **Default From Address** | The sender address for outgoing alert emails | +| **Secure Connection** | None, STARTTLS, or SSL | +| **Require Authentication** | Whether the mail server requires a username and password | +| **Username / Password** | SMTP credentials (when authentication is enabled) | + +You can test the configuration with the **Send Test Email** button. + +## Managing alerts + +### Alert tasks + +| Task | Description | +|---|---| +| **Refresh** | Reload the alerts table | +| **New Alert** | Create a new alert and open the editor | +| **Import Alert** | Load an alert from an XML file | +| **Export All Alerts** | Save all alerts as individual XML files | +| **Export Alert** | Save the selected alert as an XML file | +| **Delete Alert** | Permanently remove the selected alert | +| **Edit Alert** | Open the selected alert in the editor | +| **Enable Alert** | Activate the alert so it begins monitoring | +| **Disable Alert** | Deactivate the alert without deleting it | + +### Edit alert tasks + +While editing an alert, two additional tasks are available: + +- **Save Alert**. Commits your changes. If the alert is enabled, it immediately begins watching for matching errors. +- **Export Alert**. Saves the current alert to an XML file. diff --git a/docs/engine/architecture_overview.md b/docs/engine/architecture_overview.md new file mode 100644 index 0000000..bea8381 --- /dev/null +++ b/docs/engine/architecture_overview.md @@ -0,0 +1,167 @@ +--- +title: Architecture +description: How OIE is structured internally +--- + +# Architecture + +The Open Integration Engine (OIE) is an open source integration engine for healthcare. It receives messages from one system, filters and transforms them under rules you define, and delivers them to other systems, in the formats those systems speak (HL7, X12, EDI, DICOM, XML, among others). + +## Core concepts + +Filters, transformers, channel scripts and the JavaScript connectors all run JavaScript with access to the message, the maps and Java. Each part below has a usual job, and none is limited to it. + +### Channels + +A channel is an interface you configure to receive data from a source, take actions on that data (filter, transform, extract), and send it out to zero or more destinations. + +Each channel has general properties including a unique ID, name, and description. Channels can also be configured with code template library links, library resources, deploy/start dependencies (to control deployment order), attachment handler settings, message storage and pruning settings, and custom metadata columns. + +### Data types + +A data type is the format of the message a channel is handling: HL7 v2.x, X12, DICOM, JSON, and so on. Using the **inbound** data type, the engine **serializes** the incoming message into an internal representation that filters and transformers can work with. Using the **outbound** data type, it **deserializes** that representation into the format that leaves the channel. + +The internal representation varies by data type. For example, HL7 v2.x data is parsed into an [E4X](./glossary.md#e4x) XML object, JSON data becomes a JavaScript Object, and Raw data stays a string, unparsed. + +Supported data types include: +- Delimited Text +- DICOM +- EDI / X12 +- HL7 v2.x +- HL7 v3.x +- JSON +- NCPDP Telecom +- Raw +- XML + +See [Data Types and Formats](./data_types_and_formats.md) for details. + +### Connectors + +A channel consists of multiple **connectors**: + +- **Source Connector**. Gets data into the channel. Every channel has exactly one. +- **Destination Connectors**. Usually send the message somewhere, but need not: a Channel Writer left at its default channel, None, sends nothing, and a JavaScript Writer can run a script that only sets a map value. A channel is configured with at least one, and may have several. A given message may still reach none of them, if the source filter rejects it or destination set filtering removes them all. Each has an **enabled** flag and a **wait for previous destination** setting that decides its chain membership. + +For example, you may receive data over HTTP, then write it out to a file **and** insert pieces of it into a database. + +A connector's type decides its configuration. A TCP Listener asks for a local address and port, an HTTP Listener for a base context path, a Database Reader for a query and a polling schedule. + +Every source connector also carries a common block of **source settings**, though not all of them apply to every type: + +- a **source queue**, which when on accepts the message and responds immediately rather than waiting for processing to finish. Turning it on enables a queue buffer size and changes what the response can be set to +- a **response selector**, choosing which response goes back +- **batch processing**, splitting one inbound payload into several messages. Offered only by types that support batching +- **max processing threads**, controlling how many messages the channel processes at once + +An **attachment** is content stored with a message but apart from its body. The channel's **attachment handler** runs on the inbound message before the preprocessor and pulls attachments out of it, leaving a reference in their place. It can take the entire message, content matching one or more regular expressions, the pixel data of a DICOM message, or whatever a JavaScript script or a custom Java class extracts. A script can also create, read or update attachments at other stages with `addAttachment`, `getAttachments` and `updateAttachment`. By default a destination puts the content back in place of the reference before it sends. See [Message Lifecycle and Storage](./message_lifecycle.md#attachments). + +See [Channels](./channels.md), and [Source Connectors](./connector_reference_sources.md) and [Destination Connectors](./connector_reference_destinations.md) for what each type exposes. + +### Filters + +A filter decides whether a message should proceed to the next step or not. A filter returns **true** (accepted) or **false** (filtered). Filters are comprised of multiple **rules**, joined by **AND** or **OR** operators. + +- If the source connector filters out a message, it will not be processed by any destination connectors. +- If a destination connector filters out a message, other destinations may still process it. + +### Transformers + +A transformer modifies a message, converts it from one format to another, and extracts pieces for later use. A transformer has an **inbound data type** and an **outbound data type** (e.g., HL7 v2.x to XML). Transformers are comprised of multiple **steps**, each of which modifies or extracts data. + +See [Filters and Transformers](./filters_and_transformers.md) for details. + +### Response transformers + +Every destination can have a **response transformer**, which runs on what the destination got back. Its steps can do anything a transformer step can, and it can also set the status the message ends up with. It is the only transformer that runs after a connector rather than before one. Unless its inbound data type is Raw, it runs only when a response came back, so most failed sends skip it; see [Response transformers](./filters_and_transformers.md#response-transformers). + +### Channel scripts + +Four special scripts are associated with each channel: + +- **Deploy Script**. Runs once right before a channel is deployed. +- **Preprocessor Script**. Runs once for every message, after the attachment handler has optionally extracted data, but before the source filter/transformer. It can modify the incoming message. +- **Post Processor Script**. Runs once for every message, after the source connector and all destinations have completed (excluding asynchronous processes like the destination queue). Has access to responses from all executed destinations and can return a custom response for the source connector to use. +- **Undeploy Script**. Runs once after the channel has been stopped and its connectors undeployed. + +Global scripts of the same four kinds run around these for every channel. See [Global Scripts](./global_scripts.md#execution-order). + +### How a message moves + + + + + + +OIE Channel + + + + + + + + + + + + + +response + + + + + + + + +SourceSystem +DestinationSystem(s) +Source ConnectorPreprocessorSource Filter/Transformer +Destination 1 Filter/TransformerConnector 1Response Transformer 1 +Destination 2 Filter/TransformerConnector 2Response Transformer 2 +Postprocessor + + + +Destination 2 follows destination 1 in the diagram because it waits for the previous destination, which is the default. With that setting off, each destination starts a chain of its own and the chains run concurrently. + +Neither end of that diagram has to be outside OIE. A Channel Reader source receives from Channel Writers on other channels, a Channel Writer destination hands the message to another channel on the same engine, and a script can dispatch to one through `router`. + +A message moves through these steps: + +1. The **source connector** receives the message. +2. The **attachment handler**, if one is configured, pulls content out of the message and leaves a reference in its place. +3. The **preprocessor script** can modify the raw message before anything parses it. +4. The **source filter** decides whether the message goes on, and the **source transformer** converts and extracts from it. A message filtered here reaches no destination. +5. For each destination: its **filter and transformer** run, then its **connector** runs, which usually sends the message, either now or later from its queue. +6. That destination's **response transformer** handles whatever comes back. +7. The **postprocessor script** runs once every destination has finished, and can build the response itself. +8. If something is waiting on the other end, the response goes back to it. A listener source such as an HTTP, TCP, or Web Service Listener returns it to the caller. A polling source such as a Database Reader or File Reader has no caller, so the response is selected and stored on the message but sent nowhere. + +Four pages explain the mechanisms behind those steps: + +- [Message Lifecycle and Storage](./message_lifecycle.md), the processing path, statuses, content types, and what each storage mode keeps +- [Queueing](./queueing.md), the source queue and destination queues +- [Threading and Ordering](./threading_and_ordering.md), which thread does the work, chains, and response selection +- [Deploy, Start, and Channel State](./channel_state.md), what deploy does and what each state means + +The [Glossary](./glossary.md) collects the terms these pages use. + +## Administration interfaces + +- **Administrator**. A Java Swing desktop client for managing channels, viewing messages, configuring settings, and monitoring the system. Connects to the server over HTTPS using a RESTful API. Requires a compatible launcher; see [Desktop Administrator](./desktop_administrator.md) for the available options. +- **[Web Administrator](./web_administrator.md)**. A browser-based administrator. It is a separate application that uses the same REST API as the desktop client. +- **Command Line Interface (CLI)**. A terminal-based client for scripting and headless administration. Uses the same REST API as the Administrator. + +## Extensions + +OIE uses a plugin architecture where connectors, data types, and other features are loaded as extensions. Extension types include: + +- **Connectors**. Source and destination communication protocols +- **Data Type Plugins**. Message formats and the settings the engine uses to serialize and deserialize them +- **Server Plugins**. Background services and event handlers +- **Transmission Mode Providers**. Frame-level protocol handling (e.g., [MLLP](./glossary.md#mllp)) + +Extensions are loaded from the extensions directory when the engine starts. An extension can ship a desktop UI, a web UI, or both; the web administrator serves the web side. Open source extensions are available beyond those bundled with the engine. See the [Plugin Guide](./plugins.md), and [openintegrationengine.org/plugins](https://openintegrationengine.org/plugins/) for the community catalog. diff --git a/docs/engine/building_from_source.md b/docs/engine/building_from_source.md index 7b3aca5..978b072 100644 --- a/docs/engine/building_from_source.md +++ b/docs/engine/building_from_source.md @@ -13,7 +13,7 @@ The build is driven by Gradle through a wrapper committed to the repository, so ### Java -The repository pins the JDK it is built against in [`.sdkmanrc`](https://github.com/OpenIntegrationEngine/engine/blob/main/.sdkmanrc) at the root of the tree. At the time of writing that is a Java 17 Zulu build with JavaFX included, and the JavaFX part matters: the Administrator client will not compile against a plain JDK. +The repository pins the JDK it is built against in [`.sdkmanrc`](https://github.com/OpenIntegrationEngine/engine/blob/main/.sdkmanrc) at the root of the tree. At the time of writing that is a Java 17 Zulu build with JavaFX included, and the JavaFX part matters when you run the Administrator client. The client compiles on a plain JDK, because the repository carries the JavaFX classes it compiles against. The least error-prone way to get exactly that JDK is [SDKMAN](https://sdkman.io/), which reads the pin for you: @@ -56,7 +56,7 @@ java -version ./gradlew build -PdisableSigning=true ``` -`-PdisableSigning=true` turns off jar signing. Signing is for published releases and needs a key you do not have, so leave it off for local work. It also takes a long time, which you will notice if you forget the flag. +`-PdisableSigning=true` turns off jar signing. Without it the build signs with a self-signed development certificate kept in the repository, so no key of yours is needed. Signing is slow, though, and contacts a timestamp service over the network. Leave it off for local work. The first run downloads the Gradle distribution and every dependency, so expect several minutes. Later runs are much faster. A successful build ends with `BUILD SUCCESSFUL` and leaves a complete server layout in `server/setup`. @@ -89,7 +89,7 @@ You can also start the same staged server through Gradle: ``` ::: warning `:server:devRun` does not currently work -`CONTRIBUTING.md` also lists `:server:devRun`, which runs the server straight from the compiled classes rather than from `server/setup`. On current `main` it fails at startup with `Could not find resource SqlMapConfig.xml` and then retries in a loop, because the `dbconf` directory that holds that file is packaged into the distribution but is not on the task's classpath. This is tracked in [issue #416](https://github.com/OpenIntegrationEngine/engine/issues/416). Use `server/setup/oieserver` until it is fixed. +`CONTRIBUTING.md` also lists `:server:devRun`, which runs the server straight from the compiled classes rather than from `server/setup`. On current `main` it fails at startup with `Could not find resource SqlMapConfig.xml` and then retries startup twice, 10 seconds apart, before aborting, because the `dbconf` directory that holds that file is packaged into the distribution but is not on the task's classpath. The reporter closed [engine issue #416](https://github.com/OpenIntegrationEngine/engine/issues/416) after finding that `:server:devLauncher` works, and `:server:devRun` itself still fails. Use `server/setup/oieserver` until it is fixed. ::: A successful startup ends with lines like these. Versions, addresses and dates will differ: @@ -101,7 +101,7 @@ INFO [Main Server Thread] com.mirth.connect.server.Mirth: Web server running at ``` ::: warning Stop any other engine first -The server binds ports 8080 and 8443. If you already have OIE running as a service, or a container publishing those ports, start nothing until you have stopped it. Two engines on one port produce confusing results rather than a clear error, and you can end up administering the wrong one without noticing. +The server binds ports 8080 and 8443. If you already have OIE running as a service, or a container publishing those ports, start nothing until you have stopped it. A second engine logs `http.port port is already in use: 8080` and `https.port port is already in use: 8443` and does not serve, but its process keeps running while the first engine keeps answering, so you can end up administering the wrong one without noticing. ::: ### First login @@ -126,9 +126,9 @@ The property is read only when the database is first created; if it is left empt ## Connect to it -Open `https://localhost:8443/` in a browser. The server presents a self-signed certificate, so you will have to accept a warning the first time. You should land on the engine's home page, which links to the Administrator launcher and the client API. +Open `https://localhost:8443/` in a browser. The server presents a certificate signed by the engine's own generated certificate authority, so you will have to accept a warning the first time. You should land on the engine's status page, which links to the launcher documentation and the client API. -From there, [Accessing the Administrator](./accessing_the_administrator.md) covers the browser-based administrator and the desktop Administrator launchers, including [Ballista](https://github.com/kayyagari/ballista/releases). +From there, [Accessing the Administrator](./accessing_the_administrator.md) covers the browser-based administrator and the desktop Administrator's launcher. The Gradle build also exposes `:client:devClient`, which launches the desktop Administrator from the tree you just compiled. It connects to `https://localhost:8443` and will only reach the server you intended if nothing else is bound to that port. diff --git a/docs/engine/channel_development_guide.md b/docs/engine/channel_development_guide.md new file mode 100644 index 0000000..483e883 --- /dev/null +++ b/docs/engine/channel_development_guide.md @@ -0,0 +1,258 @@ +--- +title: Channel Development Guide +description: Building channels end-to-end +--- + +# Channel Development Guide + +## Planning a channel + +Before building, identify: + +1. **Source system**: Where messages come from +2. **Message format**: HL7 v2.x, XML, JSON, etc. +3. **Protocol**: TCP/[MLLP](./glossary.md#mllp), HTTP, file, database, etc. +4. **Transformation requirements**: What needs to change +5. **Destination system(s)**: Where messages go +6. **Error handling**: What happens when delivery fails +7. **Volume**: Expected message throughput + +## Creating a channel + +1. In the Channels view, click **New Channel** in the Channel Tasks pane +2. Enter a channel name and optional description on the **Summary** tab +3. Configure the **Source** tab (connector type and settings) +4. Configure the **Destinations** tab (one or more destination connectors) +5. Optionally configure **Scripts** (deploy, undeploy, preprocessor, postprocessor) +6. Save with `Ctrl+S` (`Cmd+S` on macOS) + +## Setting data types + +1. In the **Summary** tab, click **Set Data Types** +2. For each connector, set: + - **Inbound** data type (how the engine serializes the received message). On a destination connector it is not set by hand; it follows the source connector's Outbound type. + - **Outbound** data type (how the engine deserializes the message for output) + +## The msg and tmp objects + +When a message enters a filter or transformer, the engine hands it to the script as a JavaScript variable called **msg**, serialized first unless the data type is Raw. Depending on the data type, `msg` may be an E4X XML object (for XML-based data types like HL7 v2.x), a JavaScript object (for JSON), or a JavaScript String object (for raw data types). Under the HL7 v2.x data type the element names follow segment, field, and component: `msg['PID']['PID.5']['PID.5.1']` is the first component of PID-5, and a field with no components still gets a `.1` child, apart from MSH.1 and MSH.2, which hold the field separator and the encoding characters directly with no component child. Neither an E4X node nor the raw String object is a string primitive, so `msg['PID']['PID.8']['PID.8.1'] === 'M'` is false even when the field is `M`; call `.toString()` on the node, or on the raw `msg`, before comparing it with `===` or storing it in a map. Every sample on this page assumes the HL7 v2.x data type. + +The **tmp** variable is similar to `msg`, except it represents the outbound template rather than the inbound message. It is only available in the transformer when an outbound template is configured. Use `tmp` when you want to convert a message from one format to another (e.g. HL7 v2.x to JSON) or selectively include pieces of the inbound message in the outbound message. + +## Building transformers + +A transformer is made up of **steps**, and each step runs as JavaScript. A step usually modifies the message or pulls a value out of it. Transformers have an **inbound data type** and an **outbound data type**, which the engine uses to serialize the message on the way in and deserialize it on the way out. + +### Step types + +| Type | What it does | +|---|---| +| **Mapper** | Extract a value from the message and store it in a variable map | +| **Message Builder** | Map a value into a field of `msg` or `tmp` | +| **JavaScript** | Runs a script you write | +| **External Script** | Reference an external JavaScript file on the server | +| **XSLT** | Apply an XSLT stylesheet to an XML document | +| **Destination Set Filter** | Control which destinations receive the message (source transformer only) | +| **Iterator** | Loop over repeating segments or array elements | + +### Mapper step + +Extracts data from a field in the message (or an expression) and places it into a variable map. + +| Field | Description | +|---|---| +| **Variable** | The variable name / key to store the value under | +| **Add to** | Which map to place the variable in (Channel Map, Connector Map, Response Map, etc.) | +| **Mapping** | The value to extract: a message field or any JavaScript expression | +| **Default Value** | Fallback value if the Mapping is not found or evaluates to empty. It is a JavaScript expression, so literal text needs quotes, for example `'N/A'`; an unquoted word is read as a variable name and the step errors | +| **String Replacement** | Optional regex-based find/replace applied to the value before it is stored. Both fields are JavaScript expressions, so quote them: `'[0-9]+'` and `'N'`. An unquoted regular expression is a syntax error, and the channel does not deploy | + +The Mapping field is a JavaScript expression evaluated inside the transformer step, with `msg` in scope. Example mapping expression, the first component of PID-5: +```javascript +msg['PID']['PID.5']['PID.5.1'].toString() +``` + +Once stored, read the variable in JavaScript with the map's `.get()` method or the matching shorthand function. For example, if you add to Channel Map under the variable name `patientName`: `channelMap.get('patientName')` or `$c('patientName')`. The shorthands `$co`, `$c`, `$s`, `$gc`, `$g`, `$cfg`, and `$r` read the connector, channel, source, global channel, global, configuration, and response maps with one argument. With two arguments they write the map, except `$s` and `$cfg`: the source map and the configuration map are read-only, and writing to them throws an error. + +### Message Builder step + +Maps a value from the message (or an expression) into a field of `msg` or `tmp`. Use it to modify a field in place, copy a field from one location to another, or map data from the inbound message into the outbound template. + +| Field | Description | +|---|---| +| **Message Segment** | The target field in `msg` or `tmp` (drag from the message tree) | +| **Mapping** | The value to assign: a message field or any JavaScript expression | +| **Default Value** | Fallback value if the Mapping is not found or evaluates to empty. It is a JavaScript expression, so literal text needs quotes, for example `'N/A'`; an unquoted word is read as a variable name and the step errors | +| **String Replacement** | Optional regex-based find/replace applied to the value before it is inserted. Both fields are JavaScript expressions, so quote them: `'[0-9]+'` and `'N'`. An unquoted regular expression is a syntax error, and the channel does not deploy | + +Example, copying a field from the inbound message to the outbound template. The step assigns to `tmp`, so the transformer needs an outbound template for `tmp` to exist: +- **Message Segment:** `tmp['PV1']['PV1.9']['PV1.9.1']` +- **Mapping:** `msg['OBR']['OBR.16']['OBR.16.1'].toString()` + +### JavaScript step + +The step runs inside the transformer with the same `msg` and `tmp` as the other steps. The sample below reads from the inbound message and writes into the outbound template, so the transformer needs an outbound template; without one `tmp` is never defined and the first assignment throws a ReferenceError. Both are E4X XML objects under the HL7 v2.x data type. + +```javascript +// Read a field from the inbound message, write the mapped value into the outbound template +var gender = msg['PID']['PID.8']['PID.8.1'].toString(); +if (gender === 'M') { + tmp['PID']['PID.8']['PID.8.1'] = 'Male'; +} else if (gender === 'F') { + tmp['PID']['PID.8']['PID.8.1'] = 'Female'; +} else { + tmp['PID']['PID.8']['PID.8.1'] = 'Unknown'; +} +``` + +### Destination Set Filter step + +A source transformer step that removes destinations from the current message's destination set, so they do not process it. It does not mark the source message as filtered. + +| Field | Description | +|---|---| +| **Behavior** | Whether to filter "the following", "all except the following", or "all" destinations | +| **Destinations** | The destinations to include or exclude based on the behavior | +| **Field** | The message field or expression to test | +| **Condition** | Exists, Not Exist, Equals, Not Equal, Contains, or Not Contain | +| **Values** | One or more values to test the field against. Each is a JavaScript expression, so literal text needs quotes: `"ADT"`. Values are compared as text, not as regular expressions: Equals needs an exact match and Contains a substring | + +### Iterator step + +Loops over repeating segments or array elements, executing child steps for each iteration. + +| Field | Description | +|---|---| +| **Iterate On** | The element to iterate over: a list of E4X XML nodes or a Java/JavaScript array (e.g. `msg['PID']`) | +| **Index Variable** | The loop variable name (default `i`) used to index into the element | +| **Drag-and-Drop Substitutions** | Prefixes that will have the index variable injected when dragging fields into child steps | + +When you drag a field from the message tree into a child step, the index variable is automatically inserted. For example, if **Iterate On** is `msg['PID']` and the index variable is `i`, then dragging `msg['PID']['PID.3']['PID.3.1'].toString()` into a child step produces `msg['PID'][i]['PID.3']['PID.3.1'].toString()`. + +You can create iterators automatically by dragging a repeating node from the inbound message tree onto a node in the outbound tree. OIE will prompt you to set up an iterator with the correct substitutions. + +## Building filters + +The filter decides whether a message should proceed to the next step. It returns **true** (accept) or **false** (filter). A filter is made up of multiple **rules**, each joined by an **AND** or **OR** operator. + +- If the **source** filter filters a message, it will not flow through the source transformer or to any destination. +- If a **destination** filter filters a message, it will not flow through that destination's transformer or be dispatched outbound, but other destinations may still process the message. + +### Filter rule types + +| Rule Type | What it does | +|---|---| +| **Rule Builder** | GUI-based conditions against a message field | +| **JavaScript** | Custom filtering logic (return `true` to accept, `false` to filter) | +| **External Script** | Reference an external JavaScript file on the server | +| **Iterator** | Loop over repeating elements to decide whether to accept or filter | + +### Rule Builder + +| Field | Description | +|---|---| +| **Behavior** | Always set to **Accept**. If the expression evaluates to true, the message is accepted | +| **Field** | The message field or expression to test (drag from the message tree) | +| **Condition** | **Exists**, **Not Exist**, **Equals**, **Not Equal**, **Contains**, or **Not Contain** | +| **Values** | One or more values to test the field against. Each is a JavaScript expression, so literal text needs quotes: `"ADT"`. Values are compared as text, not as regular expressions: Equals needs an exact match and Contains a substring | + +When the Values table has multiple entries, conditions like Equals and Contains return true if the field matches **any** of the values. Not Equal and Not Contain return true if the field matches **none** of the values. + +### JavaScript filter + +The engine wraps a JavaScript rule's script in its own function, so the script ends with `return` and a boolean: `true` accepts the message, `false` filters it. `msg` is the parsed inbound message, an E4X XML object under the HL7 v2.x data type. + +```javascript +// Accept only ADT^A01 messages +var messageType = msg['MSH']['MSH.9']['MSH.9.1'].toString(); +var triggerEvent = msg['MSH']['MSH.9']['MSH.9.2'].toString(); +return (messageType === 'ADT' && triggerEvent === 'A01'); +``` + +### Combining rules +- Each rule is joined by an **AND** or **OR** operator (click the operator icon next to the rule name to toggle) +- Standard logical precedence applies: **AND** is evaluated before **OR** + +## Channel scripts + +Four scripts can be configured on the **Scripts** tab of the Edit Channel view. Each runs inside a scope the engine builds for it. The objects the samples below use come from that scope: + +| Object | In scope for | What it is | +|---|---|---| +| `channelId`, `channelName` | All four | The channel's id and name. | +| `globalChannelMap` | All four | A map private to this channel, shared by every script and thread of the channel and kept across messages. `globalChannelMap.get(key)` or `$gc(key)` reads it, `globalChannelMap.put(key, value)` or `$gc(key, value)` writes it. It is cleared when the channel deploys if **Clear global channel map on deploy** (Summary tab, on by default) is set, and it is never cleared on undeploy. | +| `globalMap`, `configurationMap` | All four | The server-wide map shared by every channel, and the configuration map. Shorthands `$g` and `$cfg`. | +| `logger` | All four | A Log4j logger named after the script: `deploy`, `undeploy`, `preprocessor`, or `postprocessor`. | +| `message` | Preprocessor, postprocessor | In the preprocessor, the raw inbound data as a string. In the postprocessor, the completed message as an `ImmutableMessage`; `message.getMessageId()` returns its id. | +| `sourceMap`, `channelMap`, `responseMap` | Preprocessor, postprocessor | The message's maps, shorthands `$s`, `$c`, `$r`. In the postprocessor `channelMap` is read-only: `channelMap.put(key, value)` or `$c(key, value)` throws `UnsupportedOperationException`. | +| `connectorMap` | Preprocessor | The source connector's map, shorthand `$co`, writable. Not in the postprocessor scope. | +| `SENT`, `ERROR`, `QUEUED`, `FILTERED`, `RECEIVED`, `TRANSFORMED`, `PENDING` | Postprocessor | The `Status` values, usable as bare names when building a `Response`. | + +No message exists when the deploy and undeploy scripts run, so none of the message objects are in scope there. + +### Deploy script +Runs once while the channel deploys, before it starts. If it throws, the deploy fails. For example, it can initialize variables or load resources. + +```javascript +// Seed a value that every script in this channel reads back with $gc('sendingFacility') +globalChannelMap.put('sendingFacility', 'HOSP'); +``` + +### Preprocessor +Runs once for every message, after the source connector receives the data and after attachment extraction, but before the message reaches the source filter/transformer. It can modify the raw inbound message. `message` is the raw inbound data as a string; nothing has been parsed yet, so there is no `msg`. The script must return the string the channel goes on to process: the returned value is stored as the message's processed raw content, which is what the source filter and transformer parse. Return `message` unchanged when there is nothing to change. A script that ends without a `return` leaves the message unchanged; see [Global Scripts](./global_scripts.md#global-preprocessor-script). `channelMap` and `connectorMap` are writable here, so a per-message fact belongs in `$c` or `$co`, where the Message Browser shows it on the message. + +```javascript +// Normalize line endings in the raw string, then return it +message = message.replace(/\r?\n/g, '\r'); +return message; +``` + +### Postprocessor +Runs once for every message after the source connector and all destinations have completed. With the source queue off, that is before the source connector sends its response. With it on, the response has already gone. The postprocessor has access to responses from all executed destinations and can return a custom response for the source connector to use. `message` is the completed message. `responseMap.get(name)` returns the `Response` a destination produced, looked up by the destination's name; a destination removed by a Destination Set Filter step has no entry and the lookup returns null. `channelMap` is read-only here and there is no `connectorMap`. If the script returns a `Response`, the engine stores it in the source response map under the key `Postprocessor`, which is what the source connector sends back when its **Response** setting is **Postprocessor**. The `Response` message is the payload the source connector sends, verbatim; a TCP Listener writes it to the socket as the reply, so a destination's ACK is passed through unchanged. The third constructor argument, `Response(status, message, statusMessage)`, is a status message that is kept on the `Response` and not sent. Return nothing and no postprocessor response is stored. + +```javascript +// Read the response one destination produced and return it unchanged as the response the source connector sends back +var ehrResponse = responseMap.get('Send to EHR'); +if (ehrResponse == null) { + return new Response(ERROR, 'Message ' + message.getMessageId() + ': no response from Send to EHR'); +} +return new Response(ehrResponse.getStatus(), ehrResponse.getMessage(), 'Message ' + message.getMessageId() + ': response from Send to EHR'); +``` + +### Undeploy script +Runs once while the channel undeploys, after it has stopped. For example, it can clean up what the deploy script set up. The global channel map is not cleared on undeploy, so an entry the deploy script seeded stays until the next deploy clears it or this script removes it. + +```javascript +// Remove what the deploy script seeded, then record the undeploy once +globalChannelMap.remove('sendingFacility'); +logger.info(channelName + ': undeployed, sendingFacility removed from the global channel map'); +``` + +## Response handling + +The source connector's **Response** dropdown controls what is sent back to the originating system. Options include: + +- **None**. No response is returned +- **Auto-generate (Before processing)**. OIE auto-generates a response from the inbound data type with a RECEIVED status, whatever happens during processing (for HL7 v2.x that is still an AA acknowledgement; only ERROR and FILTERED change the acknowledgement code). With the source queue on, it goes back as soon as the message is queued. With it off, it goes back after the message has gone through the channel +- **Auto-generate (After source transformer)**. OIE auto-generates a response from the inbound data type after the source filter/transformer runs +- **Auto-generate (Destinations completed)**. OIE auto-generates a response from the inbound data type after all destinations complete, reflecting overall processing status +- **Postprocessor**. Returns the `Response` the postprocessor script returned (see [Postprocessor](#postprocessor)) +- **A specific destination**. Returns the response payload received from that destination (e.g. an ACK from a downstream system) +- **A response map variable**. Returns the value a script put in the response map under that name. The dropdown lists the names it finds in the channel's scripts + +## Testing channels + +### Send test messages +1. Deploy the channel +2. In the Dashboard, select the channel and click **Send Message** in the Dashboard Tasks pane +3. Type a message directly, or load one from a file using **Open Text File** or **Open Binary File** +4. Optionally select which destinations to include and inject source map variables +5. Click **Process Message** +6. Check the Message Browser for results + +### Debug mode +Use the **Debug Channel** task to deploy a channel with breakpoints enabled and step through its scripts. The **Debug Channel** dialog asks you to select the channel scripts to debug: deploy, undeploy, preprocessor and postprocessor scripts; attachment and batch scripts; source connector scripts; source and destination filter/transformers; destination connector scripts; and destination response transformers. + +### Message storage +**Development** storage keeps every content type, so the Message Browser shows each stage of a test message. The other modes keep less; see [Message storage modes](./message_lifecycle.md#message-storage-modes). + diff --git a/docs/engine/channel_state.md b/docs/engine/channel_state.md new file mode 100644 index 0000000..e0cec08 --- /dev/null +++ b/docs/engine/channel_state.md @@ -0,0 +1,93 @@ +--- +title: Deploy, Start, and Channel State +description: What deploying a channel actually does, what each state means, what Start, Stop, Pause, and Halt do to connectors and queues, and which saved changes need a redeploy +--- + +# Deploy, Start, and Channel State + +Saving a channel stores its definition. Deploying it loads that definition into the engine: scripts are compiled, connectors are created and told they are deployed, the channel's database tables are reconciled, and the channel is started, paused, or left stopped according to its Initial State. Until a channel is deployed, the engine has not loaded it. After it is deployed, the engine runs what it loaded and does not re-read the saved definition until the next deploy, so a saved change to a connector, a transformer, a storage setting, or a code template does not reach the running channel. + +## What deploy does + +When one or more channels are deployed, the engine proceeds in this order. + +1. Any channel in the set that is already deployed is undeployed first, and the global undeploy script then runs once. A redeploy is an undeploy followed by a deploy. +2. The global deploy script runs once, before any channel. +3. Channels with dependencies are ordered so that a channel deploys before the channels that depend on it; channels without dependencies deploy in parallel. + +For each channel: + +4. The channel is skipped, without error, if it is disabled. +5. The engine builds the channel from the saved definition, creating its connectors. Filters, transformers, and response transformers are compiled at this point. +6. The four channel scripts are compiled. +7. The global channel map is cleared, if the channel's setting asks for it. +8. The deploy script runs. If it throws, the deploy fails and the channel is not deployed. +9. The storage mode is checked against the queue settings; a channel whose mode cannot support its queues fails to deploy. +10. The custom metadata columns are reconciled with the channel's definition, the queues are attached to their database queries, and every connector is told it is deployed. +11. **Initial State** decides what happens next. Started: the channel is started. Paused: everything starts except the source connector. Stopped: nothing starts and the channel stays deployed but stopped. + +Message recovery, which picks up messages that were mid-flight when the engine last stopped, happens during start, not deploy. A channel deployed with Initial State Stopped recovers nothing until it is started. + +## States + +A channel rests in one of these states. + +| State | Meaning | +|---|---| +| **Undeployed** | Saved, but not loaded in the engine | +| **Started** | The source connector is accepting input and every part of the channel is running | +| **Paused** | The source connector is stopped. Everything else, including the queues, is running | +| **Stopped** | Deployed but nothing is running. Queued messages wait in the database | + +The Dashboard shows the channel's state and, for each connector, whether it is running. While a task is in progress it can also show Deploying, Undeploying, Starting, Stopping, or Pausing. + +## Start, Stop, Pause, Resume, Halt + +| Action | What it does | +|---|---| +| **Start** | Starts the destination connectors, runs message recovery, starts the destination queues, starts the source queue, and starts the source connector last. Allowed from Stopped, or directly after deploy | +| **Stop** | Stops the source connector, then waits for every message currently in flight to finish, then stops the destination connectors and the queue threads. Nothing is abandoned. Queued rows stay in the database and resume on the next start | +| **Pause** | Stops the source connector and nothing else. In-flight messages finish, the source queue keeps draining, and the destination queues keep sending. Allowed from Started | +| **Resume** | Starts the source connector again. Allowed from Paused | +| **Halt** | Interrupts every processing and queue thread without waiting. A message interrupted mid-send may or may not have been delivered, and the engine cannot tell which; the sender gets an error or a dropped connection with no reply, although the message is stored and recovered when the channel starts again, so a duplicate is possible. The Dashboard offers Halt only while a channel, or one of its connectors, is Deploying, Undeploying, Starting, Stopping, Pausing, Syncing, or Unknown | + +### Single connectors + +The Dashboard allows a connector to be started or stopped on its own. For the source connector this is the same as resume and pause. A destination can be stopped on its own only if its queueing is enabled, because its messages have to go somewhere: while it is stopped, every message for that destination goes to its queue regardless of the queue mode, and sending resumes when it is started. + +## Undeploy + +Undeploying a channel stops it first, with the same wait for in-flight messages that Stop performs. The queues are not drained; their rows stay in the database and are picked up when the channel is deployed and started again. The connectors are told they are undeployed, the filter, transformer and response transformer objects are disposed, the undeploy script runs, and only then are the four compiled channel scripts discarded from the cache. A failure in the undeploy script is logged and recorded as an event but does not stop the undeploy. + +When several channels are undeployed together, a channel is undeployed before the channels it depends on, and the global undeploy script runs once at the end. + +## What a saved change needs + +A change to a deployed channel takes effect on the next deploy. The table also shows when changes outside the channel take effect. + +| Change | Takes effect | +|---|---| +| Any channel setting: connectors, filters, transformers, scripts, storage, threads, response, dependencies, initial state | On the next deploy | +| A code template used by the channel | On the next deploy. Code templates are copied into every compiled script at deploy time | +| The configuration map | Immediately. Every script run reads the current map | +| The global preprocessor and postprocessor | Immediately. They are recompiled when saved and looked up on every message | +| The global deploy and undeploy scripts | On the next deploy or undeploy, which is the only time they run | + +The Dashboard and the Channels view both carry a **Rev Δ** column: the number of times the channel has been saved since it was deployed, calculated as the saved revision minus the deployed revision. It is highlighted when it is above zero, and also when any code template linked to the channel has changed since the deploy, since that change needs a redeploy too but does not touch the channel's own revision. + +## Dependencies + +The **Set Dependencies** button on the Summary tab records that one channel depends on another. The dependencies form a directed graph, and the engine refuses one that contains a cycle. + +| Operation | Order | +|---|---| +| Deploy, Start, Resume | A channel goes before the channels that depend on it | +| Undeploy, Stop, Pause | A channel goes before the channels it depends on | + +Channels at the same level run in parallel, and the engine waits for a whole level before moving to the next. If a channel fails to deploy or start, every channel that depends on it, directly or through another channel, is left out of that operation, and the server log names them. + +## Server startup, enabled, and deployed + +On startup, when `server.startupdeploy` is true, which is the default, the engine deploys every channel it has. Disabled channels are skipped. Each deployed channel then follows its Initial State, so a channel with Initial State Stopped is deployed on startup but not running. + +Enabled and deployed are separate things. Enabled is metadata kept beside the channel rather than part of it; changing it does not change the channel's revision. A disabled channel is skipped by deploy, and **Deploy Channel** and **Debug Channel** leave it out, except that **Deploy Channel** in the channel editor offers to enable the channel and then deploys it. Disabling a channel that is already deployed does not undeploy it; it keeps running until it is undeployed or the server restarts. **Redeploy All** undeploys everything, clears the global map if the server setting asks for it, and then deploys every enabled channel. The global undeploy script still sees the global map values, and when the map is cleared the global deploy script sees it empty. diff --git a/docs/engine/channels.md b/docs/engine/channels.md new file mode 100644 index 0000000..ca9d49d --- /dev/null +++ b/docs/engine/channels.md @@ -0,0 +1,169 @@ +--- +title: Channels +description: The fundamental building blocks +--- + +# Channels + +A channel defines where data comes from and what is done with it. + +## Channel lifecycle + +You create and edit a channel in the channel editor. Your changes stay in the editor until you save. Saving stores the channel on the server. A saved channel does not process messages. + +Deploying loads the saved channel into the engine. The scripts are compiled, the connectors are created, and **Initial State** decides whether the channel comes up started, paused, or stopped. + +Start, pause, and stop apply to a deployed channel. Undeploying unloads it, and the saved channel stays on the server. Deleting removes the saved channel. + +[Deploy, Start, and Channel State](./channel_state.md) has the detail. + +## About channels and connectors + +A channel is made up of **connectors**. There are two kinds: a **source connector** brings data into the channel, and **destination connectors** usually send it on. Neither end has to be an external system. A Channel Reader receives messages from another channel. A Channel Writer sends messages to another channel. A JavaScript Writer runs a script, which need not send the message anywhere at all. Every channel has one source connector and one or more destinations. One channel can therefore receive an HL7 message over TCP, write it to a file, and insert selected fields into a database. + +```text +┌────────────────────────────────────────────────────────────┐ +│ Channel │ +│ │ +│ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ Source │───>│ Filters │───>│ Destination │ │ +│ │ Connector │ │ Transformers │ │ Connector(s) │ │ +│ └────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ Scripts: Deploy | Preprocessor | Postprocessor | Undeploy │ +└────────────────────────────────────────────────────────────┘ +``` + +The filters and transformers are drawn once here for simplicity. Every connector, source and destination alike, has its own filter and transformer; see [Connector components](#connector-components). + +## General channel properties + +These are configured on the Summary tab of the channel editor and cover the overall behavior of the channel. The Code Template Libraries, Library Resources and Deploy/Start Dependencies settings are on the tabs of the **Channel Dependencies** dialog, which opens from **Set Dependencies**: + +- **Name and description**. The channel's unique ID is assigned automatically, not entered +- **Code Template Libraries**. Controls which reusable JavaScript functions are accessible within the channel +- **Library Resources**. Specifies which custom Java classes can be referenced by the channel's connectors or scripts +- **Deploy/Start Dependencies**. Lets you define ordering relationships between channels so certain channels come online before others +- **Attachment**. Sets the channel's attachment handler, which pulls content out of the inbound message before the preprocessor and leaves a reference in its place. The attachment is stored once, apart from the copies of content kept for each connector message. See [Attachments](./message_lifecycle.md#attachments) +- **Message Storage**. Governs what message data gets persisted, whether encryption is applied, and whether connectors can use persistent queuing +- **Message Pruning**. Defines retention periods for message data with an option to archive messages to disk before they are removed +- **Custom Metadata**. Lets you pull specific values out of messages and store them as searchable columns in the Message Browser +- **Tags**. Labels for organizing channels into logical groups + +![The channel editor's Summary tab, with the Channel Properties, Message Storage, Message Pruning, Custom Metadata and Channel Description panels](images/channel_summary.png) + +## Source connector + +Each channel has exactly one source connector responsible for bringing data into OIE. Beyond the standard filter and transformer components, source connectors offer several additional features: + +- **Source Queue**. Sets when the source connector responds. When it is off, the source connector responds once the message has gone through the channel, with whatever the **Response** setting picks. When it is on, the source connector stores the message, puts it on the source queue and responds straight away, and a source queue thread processes the message later. **Response** can then only be None or Auto-generate (Before processing). For example, an HL7 sender on a TCP Listener with the source queue on gets its ACK as soon as the message is stored. If a destination fails afterwards, the sender has already been told the message was accepted. See [Queueing](./queueing.md). +- **Process Batch**. When set to Yes, a single inbound payload gets broken apart into individual messages, each of which travels through the channel independently. +- **Response**. Configures what gets sent back to the system that delivered the message. Options include auto-generating a response based on the source data type, forwarding the reply from a particular destination, or providing an entirely custom response. +- **Max Processing Threads**. Defaults to 1, meaning messages go through the channel one at a time. Above 1, messages are processed in parallel and their order is not guaranteed. This setting does not affect asynchronous processes such as destination queuing. + +## Destination connectors + +A channel has at least one destination connector, and at least one of them has to be enabled. A script anywhere in the channel can also send data out, and a script on the source side does so before any destination is reached. + +![The channel editor's Destinations tab, listing two destinations with their connector types and chain numbers above the selected destination's settings](images/channel_destinations.png) + +A message can reach none, some, or all of a channel's destinations. The [destination set](./glossary.md#destination-set) decides which ones it goes to, and each destination's own filter can still filter it out. Destinations have a few features beyond the standard filter and transformer: + +- **Enabled**. Whether the destination takes part in processing. A disabled one is skipped entirely. +- **Wait for previous destination**. Determines which **chain** the destination belongs to (see [Destination Chains](#destination-chains) below). +- **Response Transformer**. A second transformer that runs on what the destination got back. It has its own inbound and outbound data types. Its steps can do anything a transformer step can, and it can also set the response's status, status message, and error message. It runs when the response message is not empty, so a destination that failed to connect skips it. When the response inbound data type is **Raw**, it runs either way. + +## Channel scripts + +Each channel has four configurable scripts that run at specific points in the lifecycle: + +| Script | When It Runs | +|---|---| +| **Deploy Script** | Runs once while the channel deploys, before it starts. If it throws, the deploy fails | +| **Preprocessor Script** | Fires for each message, after the source connector receives it and after any attachment extraction, but before filtering and transformation begin. It can modify the raw message, for example to strip a byte order mark (BOM) from the front before the engine parses it. | +| **Postprocessor Script** | Fires for each message after the source and all destinations have finished (not counting asynchronous queue processing). With the source queue off, that is before the source connector sends its response. Has access to destination responses and can return a custom reply for the source to use. | +| **Undeploy Script** | Runs once while the channel undeploys, after it has stopped | + +## Connector components + +Every connector, whether source or destination, shares a common set of building blocks: + +### General connector properties + +Each connector is identified by a name and a **metadata ID**. The source connector is always named "Source" with a metadata ID of 0. Destination connectors have user-defined names and metadata IDs that start at 1 and increment from there. Renaming a destination does not change its metadata ID. + +### Connector-specific properties + +The configuration fields vary by connector type. See [Source Connectors](./connector_reference_sources.md) and [Destination Connectors](./connector_reference_destinations.md) for specifics. + +### Filter + +A filter decides whether a message goes on. Whatever you build in the filter editor becomes JavaScript, and the **Generated Script** tab shows what it built. The script must return true or false. + +A filter rule can also run any code a transformer step can. It can set a map variable, reshape the message, or call a code template. + +See [Filters and Transformers](./filters_and_transformers.md) for details. + +### Transformer + +A transformer is a list of steps that run on the message. They usually modify it, convert it between formats, or pull out values for later steps. Every transformer has an **inbound data type** and an **outbound data type**, which the engine uses to serialize the message on the way in and deserialize it on the way out. See [Filters and Transformers](./filters_and_transformers.md) for details. + +## Destination chains + +Chains are a byproduct of the **Wait for previous destination** checkbox on each destination. + +It sits on the **Destinations** tab beside the connector type dropdown, and applies to the destination selected in the table above it. If it is checked, the destination joins the chain of the destination above it. If it is cleared, the destination starts a new chain. On the first destination it is cleared and greyed out, because the first destination always starts the first chain. + +Chains run concurrently. Within a chain, destinations run one at a time, in order. + +The engine builds the chains when the channel deploys, reading the destination list from top to bottom and skipping disabled destinations. Reordering the list changes the chains. So does disabling a destination: disable the one that starts a chain and the destinations below it join the chain above. + +For example, with 5 destinations where Destination 3 does not wait on Destination 2 (starting a new chain): + +```text +Source Connector + │ + ▼ + Preprocessor + │ + ┌────┴────┐ + │ │ +Chain 1 Chain 2 + │ │ +Dest 1 Dest 3 + │ │ +Dest 2 Dest 4 + │ │ + │ Dest 5 + │ │ + └────┬────┘ + │ + Postprocessor +``` + +Here, Chain 1 (Dest 1 and 2) and Chain 2 (Dest 3, 4, and 5) run concurrently. If each destination takes 1 second, total processing time is 3 seconds (the longer chain) rather than 5. The source connector's filter and transformer, which run after the preprocessor and before the chains start, are left out of the diagram. + +## Channel groups + +Channels can be organized into **groups**. Groups have no effect on processing behavior. + +- Create groups in the Channels panel +- Drag and drop channels between groups +- Deploy a whole group at once from the Channels view; to undeploy, select its channels on the Dashboard + +## Channel states + +| State | Description | +|---|---| +| **Started** | Channel is actively processing messages | +| **Stopped** | Channel is deployed but not processing | +| **Paused** | Channel is deployed, source is paused (queued messages still process) | +| **Undeployed** | Saved on the server, not loaded in the engine | + +This table lists the states a channel rests in. The Dashboard also shows transitional states while a channel changes state. See [Deploy, Start, and Channel State](./channel_state.md#states) for the full list. + +## Connector types + +See [Source Connectors](./connector_reference_sources.md) and [Destination Connectors](./connector_reference_destinations.md) for every type and every setting it exposes. + +Additional connectors are available as community extensions, cataloged at [openintegrationengine.org/plugins](https://openintegrationengine.org/plugins/). See the [Plugin Guide](./plugins.md) for installing them. diff --git a/docs/engine/code_templates.md b/docs/engine/code_templates.md new file mode 100644 index 0000000..9fc68fc --- /dev/null +++ b/docs/engine/code_templates.md @@ -0,0 +1,149 @@ +--- +title: Code Templates +description: Reusable code libraries +--- + +# Code Templates + +Code templates are reusable code snippets and function libraries that can be shared across multiple channels. + +## Overview + +Code templates are organized into **libraries**. Each library is enabled for specific channels. Global scripts receive the matching templates from every library. + +```text +Code Template Library +├── Code Template 1 (Function) +├── Code Template 2 (Compiled Code Block) +└── Code Template 3 (Drag-and-Drop Code Block) +``` + +## Managing code templates + +### Code template panel +Click **Edit Code Templates** in the task panel of the **Channels** view: +- View all libraries and their templates +- Create, edit, and delete templates +- Assign libraries to channels + +![The Code Templates view with one library holding a function template, its code, and the script contexts it is available in](images/code_templates.png) + +### Creating a library +1. Open the code templates panel with **Edit Code Templates** +2. Click **New Library**. The library is named Library 1 (then Library 2, and so on) +3. Rename the library in the tree +4. Select which channels should have access to this library + +### Creating a code template +1. Select a library or a template in the tree +2. Click **New Code Template**. The template is named Template 1 (then Template 2, and so on); rename it in the tree +3. Configure: + - **Library**: The library the template belongs to + - **Type**: Function, Drag-and-Drop Code Block, or Compiled Code Block, plus one entry for each code template type that an installed extension adds + - **Context**: Where it can be used (see below) + - **Code**: The JavaScript implementation + +## Template types + +### Function +A named function that can be called from channel scripts. Functions are automatically added to the script context of assigned channels. + +The engine parses the comment block at the top of a Function template. The text before the first `@` tag becomes the template's description, and the `@param {type} name - text` and `@return {type} text` lines supply the parameter and return details that the Reference List and the editor's auto-complete show for the function. The format the engine expects is the one below, each line indented and without a leading asterisk. It is what a new Function template starts with, and what the **Generate JSDoc** / **Update JSDoc** button in the template editor writes. With a `*` at the start of each line no `@` tag is recognized: the whole comment, asterisks included, becomes the description, and every parameter shows as type `Any` with no description. The block is stripped from the code before the function is added to channel scripts. + +```javascript +/** + Formats a patient name from HL7 components. + + @param {String} lastName - Family name, PID.5.1 + @param {String} firstName - Given name, PID.5.2 + @return {String} The name as LAST, First +*/ +function formatPatientName(lastName, firstName) { + return lastName.toUpperCase() + ', ' + firstName; +} +``` + +The call below runs in the source or destination transformer of a channel whose inbound data type is HL7 v2, with the template's library assigned to the channel and the Filter / Transformer context selected on the template. `msg` is the inbound message, which the engine serializes into an E4X XML object before the transformer runs (see [Message (`msg`)](./script_scope_and_user_api.md#message-msg)); the `PID.5.1` and `PID.5.2` element names exist only under HL7 v2. No outbound template is needed. `$c` is the channel map shorthand the engine adds to every script: one argument reads a key, two arguments write one. + +```javascript +var patientName = formatPatientName( + msg['PID']['PID.5']['PID.5.1'].toString(), + msg['PID']['PID.5']['PID.5.2'].toString() +); +$c('patientName', patientName); +``` + +For a PID.5 of `DOE^JOHN` the channel map entry `patientName` holds `DOE, JOHN`, shown on the message in the Message Browser's Mappings tab. + +### Compiled code block +A block of code that is compiled and added to the script context, similar to a function. Unlike a function, it cannot be dragged from the reference list. For example, it can hold shared initialization code or constants. + +### Drag-and-drop code block +A code block that can be dragged from the reference list into the script editor. Unlike Functions and Compiled Code Blocks, Drag-and-Drop Code Blocks are **not** automatically added to the script context. + +## Execution contexts + +Code templates can be restricted to specific contexts. There are 15 contexts in four groups: + +| Group | Context | +|---|---| +| **Global Scripts** | Deploy Script | +| **Global Scripts** | Undeploy Script | +| **Global Scripts** | Preprocessor Script | +| **Global Scripts** | Postprocessor Script | +| **Channel Scripts** | Deploy Script | +| **Channel Scripts** | Undeploy Script | +| **Channel Scripts** | Preprocessor Script | +| **Channel Scripts** | Postprocessor Script | +| **Channel Scripts** | Attachment Script | +| **Channel Scripts** | Batch Script | +| **Source Connector** | Receiver Script(s) | +| **Source Connector** | Filter / Transformer Script | +| **Destination Connector** | Filter / Transformer Script | +| **Destination Connector** | Dispatcher Script | +| **Destination Connector** | Response Transformer Script | + +A template is available only in the contexts selected for it. + +## Library assignment + +A library applies to the channels it is assigned to. The assignment does not apply to global scripts, which receive the matching Function and Compiled Code Block templates from every library. + +1. Select the library in the tree +2. Check the channels that should have access +3. Check **[New Channels]** to include every channel not explicitly unchecked, including channels created or imported later +4. Save and redeploy affected channels + +A channel's own assignments are also editable from the channel editor: **Set Dependencies** opens the Channel Dependencies dialog, whose **Code Template Libraries** tab lists every library with Select All and Deselect All links. + +A change to a code template reaches a channel only when the channel is redeployed, because templates are compiled into the channel's scripts at deploy. The Dashboard highlights **Rev Δ** for a channel whose code templates have changed since it was deployed. + +## Import / export + +### GUI +- Right-click a library or template to export as XML +- Use **Import** to load from XML files + +### CLI +These commands are typed at the prompt of the CLI shell, which connects to a running server (see [Launching the CLI](./command_line_interface.md#launching-the-cli)); they are not operating-system commands. `path` is quoted when it contains spaces. Each command is described under [Code templates](./command_line_interface.md#code-templates) on that page. + +```text +codetemplate library list [includecodetemplates] +codetemplate list +codetemplate import "path" [force] +codetemplate library import "path" [force] +codetemplate export id|name "path" +codetemplate library export id|name|* "path" +codetemplate remove id|name +codetemplate library remove id|name|* +``` + +## Reference list + +The script editor has a **Reference List** panel that lists: +- Available code template functions +- Built-in utility functions (`ChannelUtil`, `DateUtil`, `FileUtil`, etc.) +- Variable references (`msg`, `tmp`, `channelMap`, etc.) +- Example code snippets + +See [Reference list](./javascript_editor.md#reference-list) on the JavaScript Editor page. diff --git a/docs/engine/command_line_interface.md b/docs/engine/command_line_interface.md new file mode 100644 index 0000000..c455508 --- /dev/null +++ b/docs/engine/command_line_interface.md @@ -0,0 +1,320 @@ +--- +title: Command Line Interface +description: CLI commands and scripting +--- + +# Command Line Interface + +The OIE CLI is a terminal-based interface for managing the server. It connects over the same REST API as the desktop and web administrators. + +## Configuration + +The CLI configuration file is located at: +```text +OIE_HOME/conf/mirth-cli-config.properties +``` + +Default contents: +```properties +address=https://127.0.0.1:8443 +user=admin +password=admin +version=0.0.0 +``` + +These are not the credentials of a new database, whose `admin` password is generated at first start, so set `user` and `password` to the account the CLI logs in as, or pass `-u` and `-p`. See [Initial admin password](./accessing_the_administrator.md#initial-admin-password). + +The CLI reads `address`, `user`, and `password` from this file, plus an optional `script` key (see [Scripting](#scripting)). The `version` line is never read, and neither is the `-v` flag. + +### Environment variable substitution + +As of 4.6.0 the config file is read through Apache Commons Configuration2, which performs variable interpolation. Environment variables can be referenced with `${env:VARIABLE_NAME}`: + +```properties +address=${env:OIE_SERVER_URL} +user=${env:OIE_USER} +password=${env:OIE_PASSWORD} +``` + +With these references the file holds no credentials; without them, the CLI config stores the password in plain text. + +An unset variable is not an error. The literal `${env:OIE_SERVER_URL}` text becomes the value, and the CLI fails when it tries to connect or log in with it, not when it loads the file. + +::: info +If you point at a config file explicitly with `-c` and it cannot be loaded, the CLI reports the failure and exits with status 2. If you rely on the default path and that file cannot be loaded, the CLI continues silently, and you will only find out when it reports that address, user, password, and version must be supplied. Only the first three matter. +::: + +## Launching the CLI + +Run the launcher from the installation directory. It builds its classpath from `cli-lib/` and the shared libraries under `extensions/`, and the CLI looks for `conf/mirth-cli-config.properties`, all relative to the working directory. + +```bash +cd + +# Address, user, and password come from the config file +java -jar mirth-cli-launcher.jar + +# Command-line options override the config file +java -jar mirth-cli-launcher.jar -a https://host:8443 -u +``` + +`-p` overrides the password the same way. Anything not given on the command line is taken from the config file. + +### Command-line options +| Flag | Description | +|---|---| +| `-a
` | Server address (e.g., `https://localhost:8443`) | +| `-u ` | Username | +| `-p ` | Password | +| `-s