Managing Plugins

You can manage plugins using the Plugins management screen. From this one screen you can:

see all of the plugins that are currently installed
install a new plugin
configure a plugins which support configuration
uninstall a plugin

Accessing the plugin management screen🔗

To open the screen, go to Manage in the navigation panel and select Plugins.

The Plugins management screen is only available on the Open mSupply Central Server, and only to users who have the Access server administration permission (see the Permissions page).

The plugins list🔗

The main screen shows a table of every plugin currently installed on the central server. For each plugin you will see the following columns:

Column	Description
Code	The plugin's unique identifier (its name)
Version	The version of the plugin that is installed
Kind	Whether this is a `Backend` or `Frontend` plugin. A single plugin may add a row of each kind.
Types	The categories of functionality the plugin provides (for example forecasting)

At the end of each row there are two actions:

a settings (cog) icon — opens the plugin's configuration screen. This is only shown for plugins that have configurable settings.
a delete (trash) icon — uninstalls the plugin.

If no plugins are installed yet, the screen displays the message "There are no plugins installed".

Installing a plugin🔗

Plugins are distributed as a plugin bundle, which is a single .json file generated with the open-mSupply command line tools. To install one:

Click the Upload plugin button in the top right of the screen. The Upload plugin window opens.
Select the plugin bundle (.json) file to install. You can select more than one file to install several plugins at once.
Click OK to upload and install the selected plugin(s)

The upload window will only accept .json files. If you select a different type of file you will see the error "Invalid file type. Plugin bundles must be .json files." — make sure you are selecting the plugin bundle and not, for example, a zipped folder or the plugin's source code.

When the install completes successfully you will see the message "Plugin installed successfully", the window closes, and the new plugin appears in the list.

Configuring a plugin🔗

Some plugins expose their own settings, which you can edit from the management screen instead of editing files by hand.

For a plugin that supports configuration, click the settings (cog) icon on its row (or click the row itself)
The Configure plugin window opens, showing the form provided by that plugin
Make your changes and then either:
- click Save to save your changes and keep the window open for further editing, or
- click OK to save your changes and close the window

When the configuration is saved you will see the message "Plugin configuration saved".

Plugin configuration is stored centrally and synchronised to all sites, so the settings you enter here apply across your whole system. For this reason, configuration can only be edited from the central server.

Uninstalling a plugin🔗

To remove a plugin:

Click the delete (trash) icon on the plugin's row.
A confirmation window appears asking "Are you sure you want to delete plugin '...'? It will stay active until the server is restarted."
Confirm to remove the plugin.

When the plugin is removed you will see the message "Plugin deleted. It will stay active until the server is restarted."

Uninstalling a plugin does not take effect immediately. The plugin will continue to run until the server is next restarted. Plan to restart the server after uninstalling a plugin if you need it to stop working straight away.

Managing plugins from the command line🔗

The same install, list and uninstall actions are available on the server for administrators who prefer to work on the command line, using the yarn plugin helper commands. These are intended for developers and server administrators, and are documented in the Front-End Plugins developer documentation.