Parameterized Trigger Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID parameterized-trigger Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
2.24
Mar 16, 2014
1.480
conditional-buildstep (version:1.3.1, optional)
promoted-builds (version:2.10, optional)
subversion (version:1.25, optional)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Tom Huybrechts (id: huybrechts)
Kohsuke Kawaguchi (id: kohsuke)
Usage Installations 2013-Apr 10388
2013-May 11192
2013-Jun 12005
2013-Jul 13590
2013-Aug 14128
2013-Sep 15087
2013-Oct 16305
2013-Nov 17035
2013-Dec 17249
2014-Jan 18704
2014-Feb 19668
2014-Mar 20940

This plugin lets you trigger new builds when your build has completed, with various ways of specifying parameters for the new build.
You can add multiple configurations: each has a list of projects to trigger, a condition for when to trigger them (based on the result of the current build), and a parameters section.

There is also a Parameterized Remote Trigger Plugin in case you want to trigger a build on a different/remote Jenkins Master.

The parameters section can contain a combination of one or more of the following:

  • a set of predefined properties
  • properties from a properties file read from the workspace of the triggering build
  • the parameters of the current build
  • Subversion revision: makes sure the triggered projects are built with the same revision(s) of the triggering build. You still have to make sure those projects are actually configured to checkout the right Subversion URLs.
  • Restrict matrix execution to a subset: allows you to specify the same combination filter expression as you use in the matrix project configuration and further restricts the subset of the downstream matrix builds to be run.

The parameter section is itself pluggable, and other plugins can contribute other sources of parameters.

This triggering mechanism can be used both as a post-build step or as a build step, in which case you can also block for the completion of the triggered builds. This lets you create a "function call" like semantics.

Usage as a Build step

When using the "Trigger/Call builds on another project" item.
If the trigger is configured with the "Block until the triggered projects finish their builds" enabled, the following Environment variables are made available for further build steps

Env variables for future build steps

  • LAST_TRIGGERED_JOB_NAME="Last project started"
  • TRIGGERED_BUILD_NUMBER_<project name>="Last build number triggered"
    from version 2.17 onwards
  • TRIGGERED_JOB_NAMES="Comma separated list of all triggered projects"
  • TRIGGERED_BUILD_NUMBERS_<project name>="Comma separated list of build numbers triggered"
  • TRIGGERED_BUILD_RESULT_<project name>="Last triggered build result of project"
  • TRIGGERED_BUILD_RESULT_<project name>RUN<build number>="Result of triggered build for build number"
  • TRIGGERED_BUILD_RUN_COUNT_project name>="Number of builds triggered for the project"
From 2.17 onwards
All Project names have characters not a-zA-Z or 0-9 replaced by
_(multiple characters are condensed into a single _).

Please submit bugs and feature requests to the issue tracker and not (only) in the comments.

Use of the plugin in a Matrix job

Post build task

When using the trigger parameterized build as a post build task for a matrix job the triggering will be be done
once when all of the different matrix configurations have completed.
In this case some of the Environment variables may not be resolvable as passing them to downstream jobs will fail.

Environment variables that should be available are the the default shell ones (<yourserver:port>/env-vars.html) and ones defined as Parameters.
Variables added by the other plugins as a buildwrappers may not be available.

Build step

When using the trigger parameterized build as a buildstep it will be called for every different configuration, so if triggering another project with no parameters it will be done the same number of times as you have configurations, possible causing the triggered job to run more than once.

However this also allows you to trigger other jobs with parameters relating to the current configuration, i.e. triggering a build on the same node with the same JDK.

Plugins contributing additional parameter types to this plugin

Page: Git Plugin — This plugin allows use of Git as a build SCM. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Plugin is only tested on official git client. Use exotic installations at your own risks.
Page: NodeLabel Parameter Plugin — This plugin adds two new parameter types to job configuration - node and label, this allows to dynamically select the node where a job/project should be executed.

Backward compatibility with version 2.22

  • Since Parameterized Trigger 2.23, there are cases that Parameterized Trigger fails to trigger downstream builds that can be successfully triggered with Parameterized Trigger <= 2.22.
    • This is caused by the new behavir introduced in Parameterized Trigger 2.23. It gets to pass parameter values not directly to the downstream build, but to parameter definitions of downstream projects. This enables parameter definitions perform its specific process, for example, selecting nodes with NodeLabel Parameter Plugin.
  • Example: There is a project with a choice parameter with choices A, B, C. When you triggered that project with parameter value D, it fails with following output in the upstream:
    java.lang.IllegalArgumentException: Illegal choice: D
    	at hudson.model.ChoiceParameterDefinition.checkValue(ChoiceParameterDefinition.java:72)
            ...
    
  • This is taken as a designated behavior.
    • As those failures are ones designed by parameter definitions. For example, the choice parameter is designed not to accept unexpected values.
    • You will face same problem when you triggered those builds with Jenkins CLI or Remote access API.
  • It is recommended to fix your project configuration to have parameter definitions not fail.
  • As backward compatibility, you can make it work without fix by setting Java system property hudson.plugins.parameterizedtrigger.ProjectSpecificParametersActionFactory.compatibility_mode to true.
    • It can be done with launching Jenkins as followings:
      java -Dhudson.plugins.parameterizedtrigger.ProjectSpecificParametersActionFactory.compatibility_mode=true -jar jenkins.war
      
    • In RedHat Linux systems, you can modify /etc/sysconfig/jenkins as following:
      -JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true"
      +JENKINS_JAVA_OPTIONS="-Djava.awt.headless=true -Dhudson.plugins.parameterizedtrigger.ProjectSpecificParametersActionFactory.compatibility_mode=true"
      
    • In Debian Linux systems, you can modify /etc/defaults/jenkins as following:
      -JAVA_ARGS="-Djava.awt.headless=true"  # Allow graphs etc. to work even when an X server is present
      +JAVA_ARGS="-Djava.awt.headless=true -Dhudson.plugins.parameterizedtrigger.ProjectSpecificParametersActionFactory.compatibility_mode=true"  # Allow graphs etc. to work even when an X server is present
      
    • In Windows system, you can modify jenkins.xml placed in the installed folder.
      -<arguments>-Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
      +<arguments>-Xrs -Xmx256m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -Dhudson.plugins.parameterizedtrigger.ProjectSpecificParametersActionFactory.compatibility_mode=true -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
      

Changelog

2.24 (Mar 16, 2014)

2.23 (Mar 09, 2014)

  • Now attempts to convert parameter strings to the type defined in the project
    • When the parameter definition is subclass of SimpleParameterDefinition, Parameterized Trigger plugin tries to create a parameter value by calling SimpleParameterDefinition#createValue, which is used when triggering builds via CLI.
  • Avoid NPE by checking the getLastSuccessfulBuild() for null before calling resolveProject() (issue #20932)
  • Supports property files with non-ascii characters. This feature only works properly in Java 1.6, but Java 1.5 is still supported. (issue #19990, issue #20651)
  • Matrix project support for "Parameters from properties file". (issue #21013)
  • Added license notice (MIT) (issue #21270)

2.22 (Dec 13, 2013)

  • Fixed projects.size to projects.size() in groovy script. This caused exception with IBM Java 6. (issue #20719)
  • expand variable in project names looking for unresolved names
  • Triggered subprojects displayed in build status pages now preserves the triggered order.

2.21 (Oct 06, 2013)

  • Supported hierarchical job model (cloudbees folders)
  • Avoids NPE when used as a build step and the triggered job is deleted or renamed (issue #19793)

2.20 (Aug 26, 2013)

2.20 (Aug 26, 2013)

2.19 (Aug 11, 2013)

  • Bugfix: Check existence of all subproject(s) before launching
  • List configured and triggered subproject from project view (subprojects are grouped into static, dynamic and unresolved)
  • set upstream builds to original builds of promotions (issue #17751)

2.18 (Jun 2, 2013)

  • Added a new parameter factory type that takes multiple BLOB files and trigger one build each.

2.17 (Feb 26, 2013)

Fixed Issues

  • Parameterized trigger from a multi-configuration project triggers downstream jobs twice (issue #11669)
  • Allow speciying Git SHA1 commit id for next build(s) as Predefined parameter (issue #13852)
  • Counter/File Parameter Factories now can prevent triggering, skip adding parameteers or fail the build if errors occur. (issue #13872)
  • A parameterized buildstep in a matrix project causes IllegalArgumentException (issue #14278)
  • Unusable environment variable TRIGGERED_BUILD_NUMBER_jobname (issue #14545)
  • It's not possible to specify multiple property files in parametrised trigger (issue #15834)
  • Boolean parameter becomes string (issue #15920)
  • Define impllicit parameter: "build them on the same node" (issue #16334)
Note
Environment parameter names have changed from previous version, due to fix for (issue #14545) when using as a build step.
Project names are now alphanumeric only and all other consecutive chars replaced with _

2.16 (Oct 09, 2012)

  • Error validating project name in form (issue #15130)
  • clarify error when no parameter set and triggerWithNoParameter unchecked (unfiled)

2.15 (May 23, 2012)

  • Allow each parameter type to be selected only once (requires Jenkins core version 1.463!). (issue #8916)
  • Fix triggering projects based on variables (issue #13875)

2.14 (Apr 27, 2012)

  • Fixed infinite loop, when "Block until the triggered projects finish their builds" option is used and triggered projects are disabled. (issue #12923)
  • Added a new parameter definition in the trigger that lets the upstream controls which subset of the downstream matrix job to build.

2.13 (Feb 9, 2012)

  • Builds triggered as build steps will now appear as downstream builds. (issue #11082, issue #9263, issue #5184)
  • Info on builds kicked off as blocking build steps exposed. (issue #11345)
  • When multiple builds are launched as blocking build steps, all should be listed as "waiting to complete", and should be listed in launched order. (issue #11116, issue #11117)
  • Fixed a compatibility with hierachical jobs (such as the CloudBees folder plugin.)
  • Added a mechanism to repeatedly invoke jobs for each file that matches GLOB (pull #11)

2.12 (Oct 30, 2011)

  • Added a mechanism to repeatedly invoke the same project with different set of parameters.
  • Improved the default value of the blocking configuration.
  • Added hyperlinks to console output

2.11 (Aug 6, 2011)

2.10 (Jul 10, 2011)

  • Implemented issue #10028: Textbox for downstream projects should be validated as with the "Build other projects" text box.
  • Implemented issue #8788: When renaming a job, the parameterized trigger should reflect the new name if the job appears as a parameterized triggered job.

2.9 (Jul 10, 2011)

  • Fix subversion plugin dependency.
  • Multiple triggers between the same upstream/downstream project combo will now work, though this will also depend on Jenkins core 1.414. (issue #8985)
  • Implemented issue #9217: Added a new option to not run further build steps if triggered builds fail or are unstable
  • Implemented issue #9391: Allow triggering projects based on variables

2.8 (Mar 27, 2011)

  • Prevent IndexOutOfBoundsException, when no projects are specified.
  • Added new "Trigger build without parameters" option for post-action trigger builds.

2.7 (Mar 1, 2011)

  • Rerelease 2.6 to properly set required Jenkins version.

2.6 (Feb 17, 2011)

  • Improved the progress report to show what jobs are being executed when used as a builder.
  • Fixed NPE when the child build is called concurrently by other jobs.

2.5 (Feb 12, 2011)

  • Added a mechanism to call other builds synchronously and map their results.

2.4 (Jul 29, 2010)

  • Fix passing of parameters when a maven project is the upstream job. (issue #6141)
  • Add support for multiconfiguration(matrix) projects. (issue #5687)
  • Fix variable expansion in "predefined parameters" so backslashes in variable values are not lost. Add help text about backslash handling. (issue #6004)
  • File parameters are currently not reusable, so omit these when "current build parameters" is selected. (issue #6777)
  • Update trigger settings when other jobs are renamed or deleted. (issue #6483)
  • Add an "always trigger" option. (issue #6656)

2.3 (Jan 16, 2010)

  • NOTE: This release is built against Jenkins 1.341 but works with Jenkins 1.319 or higher.
  • Implement Jenkins API so connected jobs show in Upstream/Downstream Projects list on job pages with Jenkins 1.341 or higher. (issue #5184)
  • Merge together parameter lists from multiple sources to avoid multiple Parameters links on build pages (issue #5143) and failure to pass some parameters further along the downstream chain (issue #4587).

2.2 (Jan 11, 2010)

2.1 (Jan 9, 2010)

  • Implement Jenkins API so connected jobs show in Upstream/Downstream Projects list on job pages. (issue #5184)

2.0 (Aug 10, 2009)

Major refactoring. Now supports any combination of projects to build, result condition and set of parameter sources.

Should be backward compatible for configuration, except the 'batch condition' which was removed.

1.6 (Jul 18, 2009)

  • Removed downstream projects parameters duplication.

1.5 (Jul 5, 2009)

  • Added batch condition: a batch/shell script can be used to decide if project[s] built should be triggered.
  • If downstream project parameters values are not specified explicitly their default values are used now (empty values was used in previous versions).

1.4 (Jun 11, 2009)

  • Environment variables (including current build parameters) can now be used in the downstream build parameters and in parameters file name.

1.3 (Feb 28, 2009)

  • Trigger another build when the current is unstable

1.2 (Feb 27, 2009)

  • Fixes incompatiblity with Jenkins 1.285. Jenkins 1.286 is a minimum requirement for this version.

1.0, 1.1 (Feb 9, 2009)

  • Initial release

Labels

Edit
plugin-trigger plugin-trigger Delete
plugin-post-build plugin-post-build Delete
plugin-builder plugin-builder Delete
plugin-cluster plugin-cluster Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment