# Job Lifecycle Plugin

# About

Job Lifecycle Plugins add custom logic to be executed before a job is saved, and before an execution is started. They can also modify the Options of the Job and input values.


To enable the Job Lifecycle Plugin add: rundeck.feature.jobLifecyclePlugin.enabled=true to your rundeck-config.properties or equivalent file.

The lifecycle points currently supported:

Before Save
Job definition has been submitted for validation, either for new Job creation or an existing Job being updated.
Before Execution
Input for option values (user submitted, or scheduled) has been received for validation, but the Execution has not yet been created

Job Lifecycle plugins are configured at the Project level.

# Use

After installation, Job Lifecycle Plugins can be enabled in the Project Configuration. The enabled plugins will be used for all Jobs in the project.

# Configuration

Select the Job Lifecycle Plugins to enable win the "Project > Edit Configuration" page under the tab named "Job Lifecycle Plugins", or in the project configuration file.

Job Lifecycle Plugins Tab
Job Lifecycle Plugins Tab

Enable a Job Lifecycle plugin named example:

# project.properties example


Currently, configuration values for individual plugins must be manually added to the project.properties file. GUI support will be added in a future release.

Project and Framework properties can also be used to configure the plugin.

Framework scope property definition in framework.properties


Project scope property definition in project.properties


# Java Plugin


Refer to Java Development for information about developing a Java plugin for Rundeck.

Implement the JobLifecyclePlugin interface:

Define your class with the @Plugin annotation, with a service name of JobLifecycle

Your class can implement two optional methods: beforeJobExecution and beforeSaveJob:

import com.dtolabs.rundeck.core.jobs.*;
import com.dtolabs.rundeck.core.plugins.JobLifecyclePluginException;
import com.dtolabs.rundeck.core.plugins.Plugin;
import com.dtolabs.rundeck.plugins.ServiceNameConstants;
import com.dtolabs.rundeck.plugins.project.JobLifecyclePlugin;

@Plugin(service = ServiceNameConstants.ExecutionLifecycle, name = "MyPlugin")
class MyPlugin implements JobLifecyclePlugin{
	    public JobLifecycleStatus beforeJobExecution(JobPreExecutionEvent event) throws JobLifecyclePluginException {
            return null;

	    public JobLifecycleStatus beforeSaveJob(JobPersistEvent event) throws JobLifecyclePluginException {
            return null;

The beforeJobExecution method will be called before the execution is created. The JobPreExecutionEvent (opens new window) type allows access to information about the Job, and includes the option values that will be used for the execution. The return value from your method can modify the option values used in the execution, or prevent the execution from occurring.

You can use JobLifecycleStatusImpl.builder() (opens new window) to build the JobLifecycleStatus result.

  • if isSuccessful() returns false, the execution will be prevented. The value in errorMessage will be logged as an error.
  • otherwise, if isUseNewValues() returns true:
    • if getOptionValues() is not null, the values returned will be added to the Map used for the execution.

The JobPersistEvent (opens new window) type allows access to information about the Job before it is persisted.

  • if isSuccessful() returns false, the create/update will be prevented. The value in errorMessage will be returned as a validation error.
  • otherwise, if isUseNewValues() returns true:
    • if getOptions() is not null, the options defined will be replaced by the options returned here. If you want to preserve the initial values, you will have to include them in the result as well.

You can use JobOptionImpl.builder() (opens new window) to create new JobOption values.

# Example Code

A full example is available on Github: https://github.com/rundeck/rundeck/tree/main/examples/example-java-job-lifecycle-plugin (opens new window)