plugins

Plugin Manager Window

Contents:

1. Plugin Framework Overview
2. Management Of Installed Plugins
3. Installation of New Plugins

1. Plugin Manager Overview

Robot contains open Java interfaces known as the Plugin API which allow to build and install custom functionality. We call these functionality extensions feature plugins.

A feature plugin is a feature or a piece of functionality which can be installed to a binary release of T-Plan Robot Enterprise without having to rebuild the product or modify its code. Feature plugins must be written in Java or have at least a Java wrapper. They are typically delivered in form of a JAR file (Java ARchive) or a class path (directory structure) containing Java classes compiled into the byte code (.class format). Should you be interested in how to write new features refer to the Feature Plugin Framework document.

Feature plugins should not be confused with so called installable plugins. These are generic packages of a particular format which can be installed into a Robot instance using the Update & Upgrade window. A feature plugin can be easily packaged as an installable one. This process is described in details in the Plugin Framework document.

The Plugin Manager window provides a front end GUI for the Plugin Manager class. It deals with feature plugins only. We will call them simply "plugins" in the following text.

The window recognizes two types of plugins:

  1. Internal plugins (also called "built-in" or "default" plugins) are those that come bundled with the binary distribution of T-Plan Robot Enterprise. As a result of the open architecture most significant features were turned into plugins so that they can be easy to replace, upgrade or customize. Internal plugins can not be uninstalled. They also can not be disabled unless you provide another plugin which replaces the internal plugin functionality.
  2. External plugins represent additional functionality or modified existing features. They may be written and distributed by anyone. External plugins may be freely installed, uninstalled, enabled and disabled.

Capabilities of the Plugin Manager window are subject to the Java version it runs on:

  • Java 8 enables full functionality. It can install and manage plugins contained even in JAR files which are not on the Robot class path. This is possible due to an internal Java API allowing to load Java code dynamically (on the fly).
  • Java 9 and higher disabled dynamical loading. The window can be used only for listing and eventual enabling or disabling of plugins. To enable installation of a plugin you must put the plugin JAR onto the Robot class path, i.e. to one of the directories scanned by Robot for JAR files on startup. It is recommended to put the plugins to the <Robot_home>/plugins directory because Robot will auto install and enable all features discovered there.

Since Java 8 is in the maintenance mode only and most users rely on the most recent Java versions the Plugin Manager became obsoleted. It is useful for information purposes only. We highly recommend to package all feature plugins as installable ones which can place the JAR file to the class path as part of the installation process. The Plugin Framework document describes the steps on a simple feature plugin example.

2. Management Of Installed Plugins

Already installed plugins are listed in the Installed Plugins tab of the window as is shown on the following picture. The list hides internal plugins by default. To get them displayed set on the Display internal plugins check box.

The plugin list shows the plugin name, version, group and status for each individual plugin. Selection of a plugin in the list populates the panel on the right with additional plugin details.

Plugin group describes the functional interface the plugin implements and provides a general hint on what the feature is like. For example, the plugin selected on the picture, Connect Command is an internal plugin belonging to the group of Script Commands. As the group name already indicates it provides functionality of the Connect scripting language command.

Plugin status may be either "enabled" or "disabled". Disabled plugins are invisible to the product (except the Plugin Manager) but they remain listed in the plugin map and may be enabled back any time.

External plugins may be disabled through the Disable button. This makes the plugin invisible for its plugin factory which provides instances of the feature whenever someone requests it. This however doesn't have any effect on any already created feature instances and an application restart may be needed. Though the restart is not forced by the window, it is highly recommended. The same applies to enabling of plugins.

Both internal and external plugins may be also disabled through installation of a plugin which identifies itself as delivering the same functionality. The Plugin Manager displays a warning on installation of such a plugin and disables the already installed one if user's response is affirmative. The only difference between internal and external plugins is that when the plugin gets uninstalled, the internal plugin is enabled back automatically.

If the plugin declares any configurable parameters, it may be configured through the Configure button. This is basically just a shortcut to the plugin preferences in the Preferences window and the parameters may be modified any time outside of the Plugin Manager window.

JAVA 8 ONLY: To uninstall a plugin simply hit the Uninstall button. This will permanently remove the plugin mapping from the plugin map. Though application restart is not forced after uninstallation, it is highly recommended to do so. Internal plugins can not be uninstalled.

3. Installation of New Plugins

Installation of plugins through the Available Plugins tab is possible on Java 8 only. For newer Java it is recommended to auto install the plugins by putting them to the <Robot_home>/plugins directory or turning them into installable plugins.

To install a plugin or plugins from one binary follow these steps:

  1. Download the plugin binary (JAR, ZIP or a folder with .class files) and save it to a stable location on the hard drive. As there's no support of online plugin lists at the moment, you will have to do this manually.
  2. Start T-Plan Robot Enterprise GUI and open the Plugin Manager Window.
  3. Under the Available Plugins tab select the Add JAR, ZIP or Classpath... button and open the plugin binary. The window should display list of available plugins.
  4. To install a plugin select it in the list and hit the Install button.
    • Some plugins have dependencies (other plugins to be installed first) and must be installed in a particular order. If the Plugin Manager displays a dependency warning, install the described dependency first.
    • As most plugins require application restart, you are likely to be asked to restart. If you want to install additional plugins, you may cancel the message and perform the restart later on.
    • Repeat this step for all plugins available in the plugin binary. There's no support of mass plugin installation at the moment.
  5. Finally restart Robot. It is recommended to do so even if the "Restart Required" message was not displayed after plugin installation. The plugins you've installed should be now visible under the Installed Plugins tab and their functionality should be available in the product.