Skip to content
Platform > Plugins

Plugins Quickstart

This guide installs one plugin bundle, restarts the server, and confirms the plugin was registered and enabled. It uses the Kafka feed handler bundle, amikafka.tar.gz, as the example; the steps are the same for any bundle.

Checking a plugin uses the admin console, the ssh command channel of the running server. Connect to it with the same user name and password as the Web UI, replacing demo with your user:

1
ssh -p 3285 demo@localhost

3285 is the shipped admin console port, set by f1.console.port. If more than one installation runs on the machine, use the port set in this installation's configuration, or the command reaches a different server. Once connected, this command confirms the console is working and lists the bundles the server has loaded:

1
ami.showPluginBundles();

Prerequisites

  • A 3forge Enterprise installation you can restart.
  • Write access to the installation directory.
  • The plugin bundle, as received from the client portal. This guide uses amikafka.tar.gz.

Steps

  1. Make sure the installation has a plugins/ directory. On Linux, the start script creates it at startup. On Windows, the launcher does not, so create it in the installation root if it is missing:

    1
    mkdir -p plugins

    1
    New-Item -ItemType Directory -Force plugins

  2. Copy the bundle into plugins/ without extracting it. The server reads the archive directly. Extracting it produces a plugin that appears to install and then fails when first used.

    1
    cp /path/to/amikafka.tar.gz plugins/

    1
    Copy-Item C:\path\to\amikafka.tar.gz plugins\

  3. Restart the server. Plugins are only read at startup; a bundle added while the server runs is not picked up.

    1
2
    scripts/stop.sh
scripts/start.sh

    Stop the server by renaming its process file. The server deletes the renamed file as it exits, so it has stopped once .amionemain.prc.kill is gone:

    1
    Rename-Item .amionemain.prc .amionemain.prc.kill

    Start it again from the installation root:

    1
    Start-Process .\amicore.exe

    The server is ready when output.log in the installation root shows Startup complete in:

    1
    Select-String -Path output.log -Pattern "Startup complete"

    On Linux, start.sh waits for the same line before it returns.

  4. Find the bundle in the startup log. Search log/AmiCore.log for the bundle's file name and the plugin it registers:

    1
    grep -E "amikafka|>KAFKA" log/AmiCore.log

    1
    Select-String -CaseSensitive -Path log\AmiCore.log -Pattern "amikafka",">KAFKA"

    For another bundle, use its file name and the plugin ID once known; before then, search for the file name and read the REGISTERED PLUGIN line.

    3 lines show the plugin passing through each stage:

    1
2
3
    LOADING BUNDLE ...\plugins\amikafka.tar.gz WITH NAME amikafka.tar.gz (4967 FILES, cksum 3573968038)
REGISTERED PLUGIN: RELAY_FEEDHANDLER>KAFKA (com.f1.ami.relay.fh.kafka.AmiKafkaFeedHandlerPlugin @ 31968.dev) FROM BUNDLE amikafka.tar.gz
CREATED PLUGIN: RELAY_FEEDHANDLER>KAFKA (com.f1.ami.relay.fh.kafka.AmiKafkaFeedHandlerPlugin @ 31968.dev)

    The text after > in the REGISTERED PLUGIN line is the plugin ID, here KAFKA. Configuration refers to the plugin by this ID, which is not always the same as the bundle's file name.

  5. Confirm the plugin is enabled from the admin console. Connect as shown above and run:

    1
    ami.showPlugins();

    The plugin appears as a row with its component and the property that controls it:

    1
2
    |Type  |Component|Manager          |ManagerProperty              |Plugin|Class                                             |Version  |
|RELAY |relay    |RELAY_FEEDHANDLER|ami.relay.feedhandler.plugins|KAFKA |com.f1.ami.relay.fh.kafka.AmiKafkaFeedHandlerPlugin|31968.dev|

    Enter quit to leave the console.

Result

The plugin is registered, and it is enabled in the component that uses it: the Kafka feed handler in the Relay. No configuration change was needed, because the shipped plugin list for feed handlers, ami.relay.feedhandler.plugins, is *, which enables every registered feed handler.

The plugin is now available but not yet doing anything. Setting it up for use, such as choosing the Kafka broker and topics to read, is specific to each plugin and is not part of this section.

Note

SHOW PLUGINS on the Center SQL console lists Center plugins only. A Relay plugin such as KAFKA does not appear there even when it is enabled, so use ami.showPlugins() to check any plugin that is not a Center plugin.

What this guide does not cover

  • Configuring the plugin itself: each plugin's own settings are specific to that plugin.
  • Plugins that must be added to a list by name: if the plugin list for your plugin type does not contain *, see Enabling and disabling plugins.
  • A plugin that did not appear in the log: see Troubleshooting plugins.