Help Center

Menu

Providing configuration options for a plugin

Plugins should be designed to be reusable and read configuration options from the data source or results page.

Plugins support two types of configuration:

Configuration supplied via configuration keys

Configuration keys can be defined within data source or results page configuration, which are available to the plugin via a Java map. These configuration keys are key-value pairs that are stored with the other configuration for the data source or results page and are service the configuration needs of the majority of plugins.

Configuration supplied via a configuration file

A plugin-specific configuration file can be defined to capture complex configuration for a plugin. This is appropriate when plugin configuration requirements are not satisfied by simple key-value pairs, e.g. if you need a set of keys to define a single rule that the plugin uses.

Configuration files can be defined in two formats - plain text and JSON.

Supplying configuration to a plugin

Access to plugin configuration is via the plugin context object that is associated with the interface that you are implementing.

Configuration keys

Configuration keys defined in the data source or results page configuration can be accessed using a variety of methods that return single or multiple configuration keys.

Please refer to the Plugin shared Javadoc documentation for the interface that you are implementing for the specific methods available. The methods below vary depending on the requirements of the interface.

For example, the gather and index interfaces provide the following methods for accessing configuration keys:

  • Map<String, List<String>> getConfigKeysMatchingPattern(String pattern): Provides config settings which match the given key pattern.

  • Set<String> getConfigKeysWithPrefix(String prefix): Provides a list of configuration setting keys which have a common prefix.

  • String getConfigSetting(String key): Provides access to configurations settings from the current Funnelback installation and data source/results page.

Configuration files

Access to a plugin-specific configuration file is provided using a method in the plugin context object for the interface that you are implementing.

Please refer to the Plugin shared Javadoc documentation for the interface that you are implementing for the specific methods available. The methods below vary depending on the requirements of the interface.

For example, the gather and index interfaces provide the following methods for accessing configuration files:

  • Optional<String> pluginConfigurationFile(String filename): Reads a configuration file for the currently running plugin as a UTF-8 String.

  • Optional<byte[]> pluginConfigurationFileAsBytes(String filename): Reads a configuration file for the currently running plugin as binary data.

Example: Read a configuration key and fall back to a default value

/*
Note: this will require you to add an import to the top of your java file.

import java.util.Optional;
*/


/*
  For boolean values

  Example: Read the plugin.example-gatherer.debug configuration key
   from the data source configuration, and set to false if it's not set.
*/
Boolean debug = Optional.ofNullable(context.getConfigSetting("plugin.example-gatherer.debug")).map(Boolean::parseBoolean).orElse(false);

/*
  For string values

  Example: Read the plugin.example-gatherer.debug configuration key
   from the data source configuration, and set to false if it's not set.
*/

String example = Optional.ofNullable(context.getConfigSetting("plugin.example-gatherer")).orElse("default value");

Dynamically updating the configuration for a plugin

Custom gatherer plugins provide a method that enables the plugin to set or update configuration keys.

Updating of configuration files is not supported.

The gather interface provides the following method:

  • void setConfigSetting(String key, String value): Set the value of configuration key to value in the data source configuration for the running plugin, including the setting of encrypted keys.

The plugin can only set/update configuration keys that directly relate to the plugin (limited to the plugin’s name space). It will throw a run-time exception if it attempts to set a key outside this scope.

Example: Set a configuration key to a specified value

try {
    // Update the last-update-time so that the next plugin execution can perform an incremental update.

    context.setConfigSetting("plugin.example-gatherer.last-update-time", "2022-06-01 13:21:04");

} catch (runTimeException e) {

    // If the the plugin attempts to update a key outside it's namespace then the method will throw a
    // run-time exception containing the message stating that the given key is not allowed for change.

    <Code that implements what to do if the key was unable to be set.>
}

See also