Frequently Asked Questions
General
What is the relationship between OIE and Mirth Connect?
OIE is an open-source fork of Mirth Connect, created after Mirth Connect moved to a proprietary model. It continues under the Mozilla Public License 2.0. See Migrating from Mirth Connect to move an existing server.
What Java version is required?
Java 17 or later.
What databases are supported?
Apache Derby (embedded, the default), PostgreSQL, MySQL, Oracle, and SQL Server. See Database Support.
Is OIE free to use?
Yes, under MPL 2.0, which allows free use, modification, and distribution.
Installation and setup
What are the default login credentials?
admin / admin. Change it at first login.
What are the default ports?
8080 for HTTP (web server and launch page) and 8443 for HTTPS (REST API and Administrator connections). The Web Administrator, when installed, is served on the same 8443 rather than a port of its own.
Do I have to use the desktop Administrator?
No. As of 4.6.0 the Web Administrator provides the same administration in a browser, installed as the Web Support extension. Both clients work against the same engine at the same time, so there is no cutover. Scripted and headless administration goes through the CLI or the REST API.
Should I use Derby in production?
No. Derby is for development and evaluation. Use PostgreSQL, MySQL, Oracle, or SQL Server in production. See Database Support.
How do I change the database after installation?
Update database, database.url, database.username, and database.password in conf/mirth.properties and restart. See Server Configuration.
How do I reset the admin password?
From the CLI: user changepw admin "newpassword".
Channels
What is a channel?
The fundamental processing unit: how messages are received (source connector), how they are transformed, and where they are sent (destination connectors). See Channels.
How many destinations can a channel have?
No hard limit. Destinations process in order by default and can be configured to run in parallel.
What is the difference between Deploy and Start?
Deploying turns a saved channel definition into a running object: scripts are compiled, connectors created, tables reconciled. Whether the channel then runs is decided by its Initial State, so a deploy can leave it started, paused, or stopped. Start acts on an already-deployed channel. See Deploy, Start, and Channel State.
How do I pass data between channels?
Use the Channel Writer (destination) and Channel Reader (source) connectors, or router (a VMRouter) to route programmatically. The global map can share state, but it is not a message-passing mechanism.
What happens when a destination fails?
It depends on the queue settings: marked ERROR immediately with no queue, placed in the queue for retry with queue-on-failure, or already queued with always-queue. See Queueing.
What is the difference between the source filter and destination filter?
The source filter runs once and decides whether the message is processed at all. Destination filters run per destination and decide whether each one processes it.
How do I route a message to only some destinations?
Use destination filters, or remove destinations from the source filter or transformer with destinationSet. It exists on the source connector only:
// Source filter or source transformer
destinationSet.remove(['Destination 2']);remove also takes a single name or metadata id, and removeAllExcept inverts the selection.
Transformers and scripts
What is the difference between msg and tmp?
msg is the parsed inbound message. tmp is the parsed outbound template, and it exists only when the transformer has an outbound template configured. When it exists, the transformer's output is taken from tmp rather than msg. Both are modifiable.
Because a connector's filter and transformer are compiled into one script sharing one scope, tmp is reachable from the filter too, and a change made there survives into the transformer.
What JavaScript engine does OIE use?
Mozilla Rhino, configured for ES6 by default, set by rhino.languageversion in mirth.properties.
Can I use Java classes in my JavaScript?
Yes. Rhino runs on the JVM:
var uuid = java.util.UUID.randomUUID().toString();What is E4X?
ECMAScript for XML, the syntax used to read and modify message content when the data type is XML-based: HL7 v2.x, HL7 v3.x, XML, EDI/X12, NCPDP, Delimited Text, and DICOM. It is not universal. With the JSON data type msg and tmp are ordinary JavaScript objects, and with Raw they are Strings, so bracket paths do not apply. See Data Types and Formats.
// Transformer, HL7 v2.x inbound data type
var value = msg['PID']['PID.5']['PID.5.1'].toString();How do I add a segment to an HL7 message?
Use E4X to create and append segments in a JavaScript transformer step. See the JavaScript Scripting Reference.
How do I delete a segment from an HL7 message?
With the delete keyword:
// Transformer with an HL7 v2.x outbound template, so tmp exists
delete tmp['ZZ1'];Data types
What data types are supported?
HL7 v2.x, HL7 v3.x, DICOM, XML, JSON, EDI/X12, NCPDP, Delimited Text, and Raw. See Data Types and Formats.
Can I convert between data types in a single channel?
Yes. Set different inbound and outbound data types per connector; the engine converts at each boundary.
Performance
How do I improve channel throughput?
- Set Message Storage to the minimum level you need
- Use attachment handlers for large content
- Enable source queuing where an auto-generated ACK is acceptable
- Enable destination queuing where you do not need a synchronous response
- Raise Max Processing Threads where message order does not matter
- Raise Queue Threads where the downstream system tolerates parallel connections
- Uncheck Wait for previous destination unless ordering between destinations matters
- Use custom metadata columns for fields you search often
What Message Storage mode should I use?
| Environment | Mode |
|---|---|
| Development and testing | Development (stores everything) |
| Production, troubleshooting needed | Production (raw and encoded) |
| Production, high throughput | Raw or Metadata |
| Maximum performance | Disabled (no storage) |
Lower modes discard content you cannot get back, so a message that fails cannot be reprocessed from storage.
How do I handle large messages?
Use an attachment handler to extract large content from the message body and store it separately.
Security
How do I replace the self-signed TLS certificate?
Import a CA-signed certificate into the keystore with Java's keytool, or use a certificate management extension if you have one installed.
How do I encrypt the database password in mirth.properties?
The server can store encrypted values using the key in its keystore. See Security and Compliance.
Is OIE HIPAA compliant?
OIE provides technical controls that support HIPAA compliance (encryption, access control, audit logging). Compliance also requires organizational policies and procedures, and is a property of your deployment rather than of the software. See Security and Compliance.
Maintenance
How do I back up my OIE instance?
- Export the server configuration from the CLI:
exportcfg "backup.xml" - Back up the
appdata/directory, which holds the keystore and the embedded database if you use Derby - Back up
conf/mirth.properties - Back up the external database separately if you use one
Without the keystore, encrypted content in a restored database cannot be read.
How do I prevent the database from growing too large?
Enable the Data Pruner and configure per-channel policies, pruning content sooner than metadata. See Data Pruning and Maintenance.