Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 118 additions & 4 deletions .vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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/' },
],
Expand Down
26 changes: 26 additions & 0 deletions .vitepress/theme/custom.css
Original file line number Diff line number Diff line change
@@ -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);
}
38 changes: 38 additions & 0 deletions .vitepress/theme/index.ts
Original file line number Diff line number Diff line change
@@ -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
54 changes: 24 additions & 30 deletions docs/engine/accessing_the_administrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -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://<host>: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://<host>: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://<host>: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.

Expand Down
Loading