There are two types of steps in a workflow:

  1. Node Steps - executed on multiple nodes
    • example: a command or script execution
  2. Workflow Steps - only executes once in a workflow
    • example: a Job-Reference step

When there are multiple Nodes to execute on, the Node Steps execute multiple times, although the Workflow Steps will execute only once. Workflow steps are always executed in order, so any sequence of steps will be completed before the next step is executed even if they run on multiple nodes or threads.

You can create a plugin to execute either type of step.

Use cases

There are several reasons to create a Step Plugin:

  • You want to take the set of nodes defined for a Job, and use them with some other batch processing system, such as another kind of remote dispatcher or orchestration tool, rather than executing commands on them directly.
  • You want to interact with another system on a per-node basis, such as for updating or reporting the state of a Node or process, rather than executing a command on the node
  • You want to wrap a command or script in a simplified user interface and have it executed remotely on nodes
    • You would implement a RemoteScriptNodeStep Plugin which allows you to define a command or script and declare a custom set of input fields.

Java Plugin Type

Define a plugin provider class

Refer to the Plugin Development - Java Plugins section for information about correct definition of a Plugin class, including packaging as a Jar and annotation.

Be sure to use the @Plugin annotation on your provider implementation class to let it be recognized by Rundeck (See Plugin Annotations).

Your service name should be one of the three listed below. The class ServiceNameConstants contains static definitions of all Rundeck Service names.

Workflow Step Types

Your plugins can be one of three types.

Each plugin type has an associated Java interface.

Plugin properties

See Plugin Development - Java Plugins - Descriptions to learn how to create configuration properties for your plugin using Java annotations.

WorkflowStep Plugin

Annotate your class with @Plugin and use the service name WorkflowStep.

Implement the interface StepPlugin:

Your implementation should throw a StepException if an error occurs.

WorkflowNodeStep Plugin

Annotate your class with @Plugin and use the service name WorkflowNodeStep.

Implement the interface NodeStepPlugin:

Your implementation should throw a StepException if an error occurs.

RemoteScriptNodeStep Plugin

These are a specialized use-case of the Node Step plugin. They allow you to simply define a command or a script that should be executed on the remote nodes, and Rundeck will handle the remote execution of the command/script via the appropriate services.

Annotate your class with @Plugin and use the service name RemoteScriptNodeStep

Implement the interface RemoteScriptNodeStepPlugin:

Your implementation should return a GeneratedScript object. You can make use of the GeneratedScriptBuilder class to generate the appropriate return type using these two factory methods:

Step context information

Each plugin is passed a PluginStepContext instance that provides access to details about the step and its configuration:

Example code

See the source directory examples/example-java-step-plugin for examples of all three provider types.

Script Plugin Type

Note: Currently these type of plugins can be implemented as script-based plugins:

  • Node Steps - the plugin will execute the script locally on the Rundeck server for each node
  • Remote Script Node Steps - the plugin will execute the script remotely on each node

See the Script Plugin Development for the basics of developing script-based plugins for Rundeck.

Use the service name for the plugin type:

  • WorkflowNodeStep
  • RemoteScriptNodeStep

For configuration properties, see the Resource Model Source Plugin - Plugin Properties.

Two additional provider metadata properties are available for RemoteScriptNodeStep plugins:

  • use-original-extension - (true/false, default true), whether to force the remotely copied script to have the same file extension as the original specified by script-file.
  • script-file-extension - A file extension to use for the remotely copied script.

To define property scopes, add a scope entry in the map for a configuration property: