Plugin Annotations
Plugin Annotations
About
Some Rundeck Plugins allow you to use annotations to add description metadata about your plugin to the class definition itself, and Rundeck will extract that metadata for use in displaying the plugin information and configuration properties in the GUI, as well as for applying the runtime configuration values to your plugin class instance when it is being executed.
Warning
ResourceModelSource, NodeExecutor and FileCopier plugins currently do not support description annotations.
Plugin Description
You can define the display name, and descriptive text about your plugin by adding a PluginDescription annotation to your plugin class.
Attributes of @PluginDescription
:
title
- the display name for your plugindescription
- descriptive text shown next to the display name
Example:
@Plugin(name="myplugin", service=ServiceNameConstants.WorkflowStep)
@PluginDescription(title="My Plugin", description="Performs a custom step")
public class MyPlugin implements StepPlugin{
...
}
Note: If you do not add this annotation, the plugin display name will be the same as the provider name, and will have no descriptive text when displayed.
Plugin Provider Metadata
You can supply additional metadata about the plugin implementation, using the @PluginMetadata annotation. You can provide multiple metadata entries with a @PluginMeta annotation, which can contain multiple @PluginMetadata values.
Example:
@Plugin(name="myplugin", service=ServiceNameConstants.WorkflowStep)
@PluginMetadata(key="anykey", value="anyvalue")
public class MyPlugin implements StepPlugin{
...
}
// or with multiple entries:
@Plugin(name="myplugin", service=ServiceNameConstants.WorkflowStep)
@PluginMeta(
{
@PluginMetadata(key="anykey", value="anyvalue"),
@PluginMetadata(key="otherkey", value="othervalue")
}
)
public class MyPlugin implements StepPlugin{
...
}
See Provider Metadata for information about what metadata keys may be used.
Plugin Properties
You can annotate individual fields in your class to define the configuration properties of your class. These are the supported Java types for annotated fields:
- String
- Boolean/boolean
- Integer/integer, Long/long
Set
,List
,String[]
(if used with@SelectValues(multiOption = true)
)
When your plugin is executed, the fields will be set to the appropriate values based on their default value, scope, and any value set by the user in the workflow configuration.
These annotation classes are used:
- PluginProperty - Declares a class field as a plugin configuration property
- SelectValues - Declares a String property to be a "Select" property, which defines a set of input values that can be chosen from a list. Can be used with
multiOption
attribute to declare aSet
,List
orString[]
and allow multiple values to be chosen. IfmultiOption
is used with a String, the value will be the values joined with a,
(comma). - TextArea - Declares a String property to be rendered as a multi-line text area in the Rundeck GUI.
Attributes:
@PluginProperty
name
- the property identifier nametitle
- the property display namedescription
- descriptive textdefaultValue
- default valuerequired
- (boolean) whether the property is required to have an input value. Default: false.scope
(PropertyScope) the resolution scope for the property value
@SelectValues
values
(String[]) the set of values that can be chosenfreeSelect
(boolean) whether the user can enter values not in the list. Default: false.multiOption
(boolean) whether multiple values can be selected as checkboxes, cannot be used with freeSelect. Default: false.
Examples:
@PluginProperty(title = "Name", description = "What is your name?", required = true)
private String name;
@PluginProperty(title = "Age", description = "How old are you?")
private int amount;
@PluginProperty(title = "Favorite Fruit",
description = "What is your favorite fruit?",
defaultValue = "banana")
@SelectValues(values = {"banana", "lemon", "orange"}, freeSelect = true)
private String fruit;
Property Scopes
You can define the scope for a property by adding scope
to the PluginProperty annotation. Refer to the class PropertyScope.
The default effective scope if you do not specify it in the annotation is InstanceOnly
.
For more information see Property Scopes.