docs: correct the Administrator documentation and restructure getting started - #13
Conversation
… started The Administrator documentation describes a UI that does not match the product, and getting started never covered running the server. Plugin guide ------------ Extensions was documented as Settings > Extensions with an Uninstall button beside each plugin and an Enabled toggle. None of that exists. Extensions is a task in the Engine pane (Frame.java:1020-1030), the Status column is read-only (ExtensionManagerPanel.java:43, and the two tables at :514 and :572), and Enable, Disable and Uninstall are menu items under Extension Tasks (Frame.java:1235-1243). f0f8788 corrected two of the navigation references and missed five. Startup troubleshooting pointed at logs/oie-server.log, which does not exist. log4j2.properties:17 writes logs/mirth.log. The guide never said where a plugin's own configuration appears. An extension implementing SettingsPanelPlugin adds a tab under Engine > Settings (SettingsPane.java:54 and :68), which is likely how Settings and Extensions were conflated in the first place. Getting started --------------- Split into Installation, Server Process Management and Accessing the Administrator, which is the order these happen in. The old page gave a foreground "sudo oieserver" command, macOS-only, and never mentioned the service. It also implied a fresh install is running. The installer registers the service with automatic startup but does not start it, so nothing listens until someone starts it or reboots. Server Process Management covers all three platforms. The registered name differs on each: "Open Integration Engine Service" on Windows, the oieservice unit on Linux, com.oie.oieservice on macOS (oie-installer-config.install4j:427). oieserver stays as the foreground option, which also writes logs/mirth.log rather than replacing it. Also on those pages: the with-JRE and without-JRE builds explained rather than listed, the tar.gz and zip archives named up front, the headless console install documented, the unsigned installers set against the signed jars (signSetupJars in server/build.gradle), the privileged service account recorded, and the fact that every authenticated account is an administrator (DefaultAuthorizationController.isUserAuthorized returns true at :45, doesUserHaveChannelRestrictions returns false at :53). MariaDB was listed as a backend in its own right. mirth.properties:77 accepts derby, mysql, postgres, oracle and sqlserver, and MariaDB appears nowhere in the engine source, so it is folded into the MySQL line item. Version numbers are out of the startup log sample, which showed 4.5.2. Ten of the fourteen screenshots were pictures of the installer wizard, a Spotlight search, a login form and a progress bar. An eleventh file was already orphaned. A meta-refresh stub with noindex keeps /engine/getting_started.html alive, since it is published. Site ---- Links to index pages built to .html files that do not exist, so /engine.html and /examples.html both return 404. The SPA hides it from a browser, but crawlers and link checkers see the status code. Index pages need a trailing slash. Launchers is in the top nav, Launchers and Examples were single-entry collapsible groups and are now plain links, outline is [2, 3], and sidebarFromRemote() is removed; it read a docs.json that does not exist and was never called. Added Launcher after Ballista. The JNLP Launcher Project was described as cross-platform and has never shipped a macOS build, so its entry now says what it ships; the same unearned rating came off Ballista. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
mgaffigan
left a comment
There was a problem hiding this comment.
I think it moves us in the right direction with/without further edits.
Pin the default credentials to 4.6.0 and note that a future release generates the password on first boot. That change is on main but not in any release, so an installer today still ships admin/admin. Rewrite the administrator warning in mgaffigan's words. Mine led with two method names and a return value, which proves the claim without explaining why it matters. Widen the promised securing-the-install guide to cover permissions on conf, appdata and the executable directories, not just the service account. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
|
Generated password. Pinned to 4.6.0 with a note that a future release generates it. Density. Used your wording. Directory permissions. Out of scope here. The guide the page promises now covers Service not started. You and I are discussing this out of band. Local system. We have to sort out network access permission with whatever becomes the standard here, perhaps a named local or domain account. Worth more discussion for future releases.
|
mgaffigan
left a comment
There was a problem hiding this comment.
Still looks better than before, but much of this speaks to installer bugs. Also: setting privileges on directories for a .tar.gz manual install is required.
The foreground section listed only oieserver.ps1, under a tab labelled PowerShell, so a reader at a command prompt had no working instruction. Windows installs also carry oieserver.exe, the install4j console launcher (tools/install4j/oie-installer-config.install4j, launcher id 39, included in every Windows media set). Show both, each under the prompt it belongs to. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
Thirty-six pages from pacmano1/unofficial-oie-wiki, under docs/engine, with the sidebar grouped the way the wiki's was. Three wiki pages overlapped pages that landed in OpenIntegrationEngine#13 and were folded in rather than duplicated: the Installation Guide's directory layout and heap default into Installation, the Administrator GUI's interface tour as Desktop Administrator with launching and login left to Accessing the Administrator, and Plugins and Extensions as Extension Catalog with its install and enable sections replaced by a link to the Plugin Guide. Headings across the whole site are now sentence case, which was deferred from OpenIntegrationEngine#13 until the page count justified the churn. Corrections made on the way through: - User Management called role-based access control a commercial extension. It is a community one, diridium-com/role-based-access-control, MPL 2.0. - Channels and Connectors said additional connectors are commercial. They are community extensions; the catalog lists them. - The Help task was described as opening the wiki. It opens the engine's GitHub discussions (BrandingConstants.java:31). Directory layout entries checked against the source before they moved: custom-lib (MirthLauncher.java:98), webapps (oie-installer-config.install4j:26), the appdata files (mirth.properties:33, :73, :89; ExtensionStatusFile.java:38; DefaultConfigurationController.java:334), docs/javadocs (server/build.gradle:495), the 256 MB heap (base_includes.vmoptions:6), and the oiecommand, oieserver and oieservice executables (install4j launchers 140, 39 and 25). The oiemanager launcher, id 56, is excluded from every media set, so no Server Manager is documented. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
Thirty-six pages from pacmano1/unofficial-oie-wiki, under docs/engine, with the sidebar grouped the way the wiki's was. Three wiki pages overlapped pages that landed in OpenIntegrationEngine#13 and were folded in rather than duplicated: the Installation Guide's directory layout and heap default into Installation, the Administrator GUI's interface tour as Desktop Administrator with launching and login left to Accessing the Administrator, and Plugins and Extensions as Extension Catalog with its install and enable sections replaced by a link to the Plugin Guide. Headings across the whole site are now sentence case, which was deferred from OpenIntegrationEngine#13 until the page count justified the churn. Corrections made on the way through: - User Management called role-based access control a commercial extension. It is a community one, diridium-com/role-based-access-control, MPL 2.0. - Channels and Connectors said additional connectors are commercial. They are community extensions; the catalog lists them. - The Help task was described as opening the wiki. It opens the engine's GitHub discussions (BrandingConstants.java:31). Directory layout entries checked against the source before they moved: custom-lib (MirthLauncher.java:98), webapps (oie-installer-config.install4j:26), the appdata files (mirth.properties:33, :73, :89; ExtensionStatusFile.java:38; DefaultConfigurationController.java:334), docs/javadocs (server/build.gradle:495), the 256 MB heap (base_includes.vmoptions:6), and the oiecommand, oieserver and oieservice executables (install4j launchers 140, 39 and 25). The oiemanager launcher, id 56, is excluded from every media set, so no Server Manager is documented. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
Thirty-five pages from pacmano1/unofficial-oie-wiki under docs/engine, with the sidebar grouped in reading order. The site is a reference manual for the engine plus explanation of the concepts people misunderstand. Content that fails that test did not make the move: the Quick Start tutorial, the FAQ, Troubleshooting and Glossary pages, and the best-practice and tips sections. Facts from those pages that state engine behaviour were folded into the pages that own them. Three wiki pages overlapped pages that landed in OpenIntegrationEngine#13 and were folded in rather than duplicated: the Installation Guide's directory layout and heap default into Installation, the Administrator GUI's interface tour as Desktop Administrator with launching and login left to Accessing the Administrator, and Plugins and Extensions as Extension Catalog with its install and enable sections replaced by a link to the Plugin Guide. Headings across the whole site are now sentence case, deferred from OpenIntegrationEngine#13. Four concept pages are new writing, verified against the engine source (main; citations are path:line). Message Lifecycle and Storage replaces Message Processing and the duplicated lifecycle walk in Architecture Overview. Statuses and where each is set (Status.java:18-40, Channel.java:1456, FilterTransformerExecutor.java: 104-143, DestinationConnector.java:449-450, :949-959, :1010-1015); the per-channel tables (JdbcDao.java:2166-2178, donkeydbconf/postgres.xml:4-138); destination Raw read back from the source Encoded row (default.xml:274-280, Channel.java:1803); the storage mode flags (DonkeyEngineController.java: 1270-1345) and the passthrough DAO for Disabled (PassthruDao.java:173-266); asynchronous commit commands (JdbcDao.java:2388-2403, PostgresqlDaoFactory .java:22-56, OracleDaoFactory.java:26-62); remove content on completion (Channel.java:2055-2155); the pruner's fixed skip statuses and its two thresholds (DataPruner.java:94-99, :247-304, :449-554, :701-725); custom metadata lookup order and column reconciliation (MetaDataReplacer.java: 29-59, Channel.java:2268-2316, MetaDataColumnType.java:79-108); the no-filter-transformer shortcut (FilterTransformerExecutor.java:78-143). Queueing. A queue is a status query with a buffer (ConnectorMessageQueue .java:24-116, Channel.java:517, :548, default.xml:318-354); the source queue setting stored inverted as respondAfterProcessing (SourceConnectorProperties .java:73, SourceSettingsPanel.java:252, :322-327); the two paths in Channel.java:1294-1314; source queue thread count (Channel.java:655-673); queue modes as queueEnabled and sendFirst (DestinationSettingsPanel.java: 136-145); On Failure sends only when the queue is empty (DestinationConnector .java:261-263); dispatchers start at QUEUED and fixStatus turns that into ERROR with queueing off (Response.java:229-243, DestinationConnector.java: 531, :736); Retry Count applies before queueing only (DestinationConnector .java:517-533) and the queue loop has no limit (DestinationConnector.java: 615-895); thread buckets and the null bucket (DestinationQueue.java:68-83, :273-329, MessageMaps.java:20-36); rotation as an id window (ConnectorMessageQueueDataSource.java:87-120); the storage gate (Channel.java:481-497) and the client-side save block (ChannelSetup.java: 1242-1245); pause keeps queues draining (Channel.java:890-901, :756-763); stop (Channel.java:1016-1105); halt's duplicate risk (Channel.java: 1354-1363); recovery before queues start (RecoveryTask.java:86-156, Channel.java:739); initial state handling (DonkeyEngineController.java: 1997-2032); stopping one destination (Channel.java:1205-1230); the pruner never removes QUEUED (DataPruner.java:97); buffer size setting (ServerSettings.java:40, DonkeyEngineController.java:382-390, :1187-1192, :1567-1572). Threading and Ordering. Max Processing Threads is a fair semaphore (DefaultChannelProcessLock.java:22-45, Channel.java:1283, SourceConnector .java:419-422, DonkeyEngineController.java:1238-1244); the Web Service Listener pool (WebServiceReceiver.java:160-166); chain formation from waitForPrevious (DonkeyEngineController.java:1207-1229, Connector.java:50, ChannelSetup.java:2402, :2444); chains in parallel with the last inline (Channel.java:1829-1868); errored versus filtered chain stop (DestinationChain.java:126-129, :150); what the next destination receives (DestinationChain.java:170-174); merged view ordering (Message.java: 116-170); Respond From values, storage as d<id>, and precedence (SourceConnectorProperties.java:30-70, SourceSettingsPanel.java:156-161, ResponseSelector.java:24-105, Channel.java:1316-1322); batch sequencing (SourceConnector.java:201-295, BatchAdaptorFactory.java:31-44); potential sending threads (DestinationConnector.java:97-123); thread names (Channel.java:667, :1270-1272, :1836; DestinationChain.java:121; DestinationConnector.java:311; RecoveryTask.java:44; ChannelTask.java: 56-58; PollConnectorJob.java:48; DonkeyStatisticsUpdater.java:36); pools per channel (Channel.java:723, DonkeyEngineController.java:1699-1704, Channel.java:131). Deploy, Start, and Channel State. The deploy sequence and Initial State (DonkeyEngineController.java:294-452, :1844-2045, ChannelProperties.java: 41-53); recovery in start (Channel.java:738-752); the states (DeployedState.java:16); start, stop, pause, resume, halt (Channel.java: 697-797, :1016-1105, :890-935, :825-888); single connectors (Channel.java: 1175-1230); undeploy (DonkeyEngineController.java:2073-2155); the configuration map read on every script run (JavaScriptScopeUtil.java:174, DefaultConfigurationController.java:923-938); global scripts recompiled on save (DefaultScriptController.java:247-256, JavaScriptUtil.java:180-198); code templates inlined at compile time (JavaScriptBuilder.java:103-115, :539-565); Rev delta (DonkeyEngineController.java:899-907, ChannelTableColumnFactory.java:108); dependency ordering and failure propagation (ChannelDependencyUtil.java:31-53, DonkeyEngineController.java: 351-356, :408-443, :477-503, :574-622); startup deploy and the enabled flag (DonkeyEngineController.java:285-291, :1839-1851, DefaultChannelController .java:261-284, ChannelMetadata.java:22-45, ChannelPanel.java:878-891). Corrections made on the way through: - PENDING was described as waiting to begin processing. It means the response is stored and the response transformer has not finished. - Message Processing said Retry Count bounds queue retries and marks messages ERROR. It bounds the attempts before queueing; a queued message is retried without limit. - Message Processing said a connector without a filter or transformer has no encoded content. It has no transformed content; the encoded content is the raw content. - User Management called role-based access control a commercial extension. It is a community one, diridium-com/role-based-access-control, MPL 2.0. - Channels and Connectors said additional connectors are commercial. They are community extensions; the catalog lists them. - The Help task was described as opening the wiki. It opens the engine's GitHub discussions (BrandingConstants.java:31). - The Java lookup order for oieserver.ps1 is recorded on Server Process Management (server/basedir-includes/oieserver.ps1:18-27). Directory layout entries checked against the source before they moved: custom-lib (MirthLauncher.java:98), webapps (oie-installer-config .install4j:26), the appdata files (mirth.properties:33, :73, :89; ExtensionStatusFile.java:38; DefaultConfigurationController.java:334), docs/javadocs (server/build.gradle:495), the 256 MB heap (base_includes.vmoptions:6), and the oiecommand, oieserver and oieservice executables (install4j launchers 140, 39 and 25). The oiemanager launcher, id 56, is excluded from every media set, so no Server Manager is documented. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
Thirty-five pages from pacmano1/unofficial-oie-wiki under docs/engine, with the sidebar grouped in reading order. The site is a reference manual for the engine plus explanation of the concepts people misunderstand. Content that fails that test did not make the move: the Quick Start tutorial, the FAQ, Troubleshooting and Glossary pages, and the best-practice and tips sections. Facts from those pages that state engine behaviour were folded into the pages that own them. Three wiki pages overlapped pages that landed in OpenIntegrationEngine#13 and were folded in rather than duplicated: the Installation Guide's directory layout and heap default into Installation, the Administrator GUI's interface tour as Desktop Administrator with launching and login left to Accessing the Administrator, and Plugins and Extensions as Extension Catalog with its install and enable sections replaced by a link to the Plugin Guide. Headings across the whole site are now sentence case, deferred from OpenIntegrationEngine#13. Four concept pages are new writing, verified against the engine source (main; citations are path:line). Message Lifecycle and Storage replaces Message Processing and the duplicated lifecycle walk in Architecture Overview. Statuses and where each is set (Status.java:18-40, Channel.java:1456, FilterTransformerExecutor.java: 104-143, DestinationConnector.java:449-450, :949-959, :1010-1015); the per-channel tables (JdbcDao.java:2166-2178, donkeydbconf/postgres.xml:4-138); destination Raw read back from the source Encoded row (default.xml:274-280, Channel.java:1803); the storage mode flags (DonkeyEngineController.java: 1270-1345) and the passthrough DAO for Disabled (PassthruDao.java:173-266); asynchronous commit commands (JdbcDao.java:2388-2403, PostgresqlDaoFactory .java:22-56, OracleDaoFactory.java:26-62); remove content on completion (Channel.java:2055-2155); the pruner's fixed skip statuses and its two thresholds (DataPruner.java:94-99, :247-304, :449-554, :701-725); custom metadata lookup order and column reconciliation (MetaDataReplacer.java: 29-59, Channel.java:2268-2316, MetaDataColumnType.java:79-108); the no-filter-transformer shortcut (FilterTransformerExecutor.java:78-143). Queueing. A queue is a status query with a buffer (ConnectorMessageQueue .java:24-116, Channel.java:517, :548, default.xml:318-354); the source queue setting stored inverted as respondAfterProcessing (SourceConnectorProperties .java:73, SourceSettingsPanel.java:252, :322-327); the two paths in Channel.java:1294-1314; source queue thread count (Channel.java:655-673); queue modes as queueEnabled and sendFirst (DestinationSettingsPanel.java: 136-145); On Failure sends only when the queue is empty (DestinationConnector .java:261-263); dispatchers start at QUEUED and fixStatus turns that into ERROR with queueing off (Response.java:229-243, DestinationConnector.java: 531, :736); Retry Count applies before queueing only (DestinationConnector .java:517-533) and the queue loop has no limit (DestinationConnector.java: 615-895); thread buckets and the null bucket (DestinationQueue.java:68-83, :273-329, MessageMaps.java:20-36); rotation as an id window (ConnectorMessageQueueDataSource.java:87-120); the storage gate (Channel.java:481-497) and the client-side save block (ChannelSetup.java: 1242-1245); pause keeps queues draining (Channel.java:890-901, :756-763); stop (Channel.java:1016-1105); halt's duplicate risk (Channel.java: 1354-1363); recovery before queues start (RecoveryTask.java:86-156, Channel.java:739); initial state handling (DonkeyEngineController.java: 1997-2032); stopping one destination (Channel.java:1205-1230); the pruner never removes QUEUED (DataPruner.java:97); buffer size setting (ServerSettings.java:40, DonkeyEngineController.java:382-390, :1187-1192, :1567-1572). Threading and Ordering. Max Processing Threads is a fair semaphore (DefaultChannelProcessLock.java:22-45, Channel.java:1283, SourceConnector .java:419-422, DonkeyEngineController.java:1238-1244); the Web Service Listener pool (WebServiceReceiver.java:160-166); chain formation from waitForPrevious (DonkeyEngineController.java:1207-1229, Connector.java:50, ChannelSetup.java:2402, :2444); chains in parallel with the last inline (Channel.java:1829-1868); errored versus filtered chain stop (DestinationChain.java:126-129, :150); what the next destination receives (DestinationChain.java:170-174); merged view ordering (Message.java: 116-170); Respond From values, storage as d<id>, and precedence (SourceConnectorProperties.java:30-70, SourceSettingsPanel.java:156-161, ResponseSelector.java:24-105, Channel.java:1316-1322); batch sequencing (SourceConnector.java:201-295, BatchAdaptorFactory.java:31-44); potential sending threads (DestinationConnector.java:97-123); thread names (Channel.java:667, :1270-1272, :1836; DestinationChain.java:121; DestinationConnector.java:311; RecoveryTask.java:44; ChannelTask.java: 56-58; PollConnectorJob.java:48; DonkeyStatisticsUpdater.java:36); pools per channel (Channel.java:723, DonkeyEngineController.java:1699-1704, Channel.java:131). Deploy, Start, and Channel State. The deploy sequence and Initial State (DonkeyEngineController.java:294-452, :1844-2045, ChannelProperties.java: 41-53); recovery in start (Channel.java:738-752); the states (DeployedState.java:16); start, stop, pause, resume, halt (Channel.java: 697-797, :1016-1105, :890-935, :825-888); single connectors (Channel.java: 1175-1230); undeploy (DonkeyEngineController.java:2073-2155); the configuration map read on every script run (JavaScriptScopeUtil.java:174, DefaultConfigurationController.java:923-938); global scripts recompiled on save (DefaultScriptController.java:247-256, JavaScriptUtil.java:180-198); code templates inlined at compile time (JavaScriptBuilder.java:103-115, :539-565); Rev delta (DonkeyEngineController.java:899-907, ChannelTableColumnFactory.java:108); dependency ordering and failure propagation (ChannelDependencyUtil.java:31-53, DonkeyEngineController.java: 351-356, :408-443, :477-503, :574-622); startup deploy and the enabled flag (DonkeyEngineController.java:285-291, :1839-1851, DefaultChannelController .java:261-284, ChannelMetadata.java:22-45, ChannelPanel.java:878-891). Corrections made on the way through: - PENDING was described as waiting to begin processing. It means the response is stored and the response transformer has not finished. - Message Processing said Retry Count bounds queue retries and marks messages ERROR. It bounds the attempts before queueing; a queued message is retried without limit. - Message Processing said a connector without a filter or transformer has no encoded content. It has no transformed content; the encoded content is the raw content. - User Management called role-based access control a commercial extension. It is a community one, diridium-com/role-based-access-control, MPL 2.0. - Channels and Connectors said additional connectors are commercial. They are community extensions; the catalog lists them. - The Help task was described as opening the wiki. It opens the engine's GitHub discussions (BrandingConstants.java:31). - The Java lookup order for oieserver.ps1 is recorded on Server Process Management (server/basedir-includes/oieserver.ps1:18-27). Directory layout entries checked against the source before they moved: custom-lib (MirthLauncher.java:98), webapps (oie-installer-config .install4j:26), the appdata files (mirth.properties:33, :73, :89; ExtensionStatusFile.java:38; DefaultConfigurationController.java:334), docs/javadocs (server/build.gradle:495), the 256 MB heap (base_includes.vmoptions:6), and the oiecommand, oieserver and oieservice executables (install4j launchers 140, 39 and 25). The oiemanager launcher, id 56, is excluded from every media set, so no Server Manager is documented. Signed-off-by: Finnegan's Owner <44065187+pacmano1@users.noreply.github.com>
This is the first of two PRs. The second ports my unofficial OIE wiki into this site, around 37 pages.
Rendered preview of this branch: https://pacmano1.github.io/docs-website/
The Administrator documentation does not match the product, and getting started never covered running the server.
Plugin guide. The Extensions section described a screen that does not exist. f0f8788 fixed two of the navigation references and missed the rest. The guide also now says where a plugin's configuration appears.
Getting started. Split into Installation, Server Process Management and Accessing the Administrator. The page said a fresh install is already running. The installer registers the service with automatic startup but does not start it, so nothing is listening until someone starts it or reboots. Server Process Management covers all three platforms and keeps
oieserveras the foreground option. Ten of the fourteen screenshots were pictures of the installer wizard and are gone. A meta-refresh stub keeps/engine/getting_started.htmlalive, since it is published.Site. Links to index pages build to
.htmlfiles that do not exist, so/engine.htmland/examples.htmlboth 404 today. The SPA hides this from a browser, but crawlers and link checkers see the status code.I added my Launcher after Ballista. The JNLP entry claimed cross-platform and that project has never shipped a macOS build.
bun run docs:buildpasses, every internal link resolves.