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.

Note, 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 plugin
• description - 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 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

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

Attributes:

• @PluginProperty
  • name - the property identifier name
  • title - the property display name
  • description - descriptive text
  • defaultValue - default value
  • required - (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 chosen
  • freeSelect (boolean) whether the user can enter values not in the list. 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. These are the available scopes and how the property values can be resolved:

• Framework - Only framework properties
• ProjectOnly - Only Project properties
• Project - Project and Framework properties
• InstanceOnly - Only instance properties
• Instance - Instance and all earlier levels

The default effective scope if you do not specify it in the annotation is InstanceOnly.

When resolving a property in a Project or Framework scope, the following properties will be searched:

• Framework scope
  • file: $RDECK_BASE/etc/framework.properties
  • property: framework.plugin.[ServiceName].[providerName].[propertyname]
• Project scope
  • file: $RDECK_BASE/projects/[ProjectName]/etc/project.properties
  • property: project.plugin.[ServiceName].[providerName].[propertyname]