Retrieving Jenkins Build Parameters and Perforce Plugin Properties Using the Groovy API

Fundamentals of Parameter Retrieval in Parameterized Builds

In Jenkins automation workflows, parameterized builds allow dynamic input of parameters at execution time, which can be accessed and utilized during the build process. Retrieving these parameters via the Groovy API is a common requirement in script development. According to best practices, the most straightforward method is using build.buildVariableResolver.resolve("parameterName"). This approach is simple and efficient, particularly suitable for scenarios requiring only a single parameter value. For example, if a build has a parameter named BRANCH_NAME, its value can be obtained with:

def branch = build.buildVariableResolver.resolve("BRANCH_NAME")

This method is directly available in Groovy system script build steps, without needing additional plugins or complex configuration.

Accessing Complete Parameter Lists via ParametersAction

When all parameters in a build need to be retrieved, a more comprehensive approach involves using ParametersAction. Each parameterized build includes a ParametersAction object in its actions, encapsulating all parameter information. This can be accessed and iterated as follows:

def parameters = build.getActions(hudson.model.ParametersAction)
if (parameters) {
    parameters.each { paramAction ->
        paramAction.parameters.each { param ->
            println "Parameter ${param.name}: ${param.value}"
        }
    }
}

This method not only provides parameter names and values but also allows access to metadata such as type descriptions and default values. It is more appropriate for scripts that require batch parameter processing or generating parameter reports.

Retrieving Perforce Plugin Properties

For builds utilizing the Perforce plugin, the plugin may set additional properties like p4.change. These properties are typically stored in build actions but may not belong to standard parameter types. To retrieve such properties, first determine their storage location by inspecting all build actions in the Jenkins Groovy console:

build.actions.each { action ->
    println action.getClass().name
}

Once the action class storing p4.change is identified, its value can be retrieved via appropriate methods. For instance, if the property is found in PerforceChangeAction, the code might be:

def p4Action = build.getActions(PerforceChangeAction)
if (p4Action) {
    def changeValue = p4Action.change
    println "Perforce change: ${changeValue}"
}

This approach requires adjustment based on the plugin's specific implementation, but the general idea is to locate plugin-specific properties by examining action types.

Version Differences and Best Practices

In Jenkins 2.x and later, parameter retrieval has become simpler. In Pipeline DSL, parameters can be directly accessed via the params map, e.g., params.'FOOBAR' or params.get('FOOBAR'). This method works for both scripted and declarative Pipelines and automatically handles parameter type conversion. For Jenkins 1.x, the aforementioned buildVariableResolver or ParametersAction methods are still necessary.

In practical applications, it is advisable to choose the appropriate method based on requirements: use buildVariableResolver for simple parameter retrieval; use ParametersAction for complex parameter handling; and for plugin properties, locate them via action inspection. Additionally, always incorporate error handling in scripts to manage cases where parameters are absent or plugins are not installed.