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.26 (archives)
Mar 07, 2015
1.580.1
conditional-buildstep (version:1.3.1, optional)
matrix-project (version:1.4, optional)
promoted-builds (version:2.10, optional)
subversion (version:1.38, optional)
Source Code
Issue Tracking
Pull Requests
Maintainer(s)
GitHub
Open Issues
Pull Requests
Tom Huybrechts (id: huybrechts)
Kohsuke Kawaguchi (id: kohsuke)
Usage Installations 2014-May 22560
2014-Jun 23589
2014-Jul 25051
2014-Aug 25616
2014-Sep 27080
2014-Oct 28565
2014-Nov 28862
2014-Dec 29037
2015-Jan 30607
2015-Feb 31615
2015-Mar 33818
2015-Apr 34396

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.26 (Mar 7, 2015)

  • Trim file names in property file lists
  • Updated the version of depending subversion-plugin to 1.38 with svnkit-1.3.6-jenkins-2 that supports TLS. (issue #25772)
  • Add FAILURE_OR_BETTER Trigger Threshold. (issue #26029)
  • Rely on archived artifacts to trigger (parameterized) build fallback to workspace for backward compatibility. (issue #25192)
  • Added export of triggered builds and jobs to XML/JSON API. (issue #26031)
  • Updated required core version to 1.580.1 - the plugin requires now Java 6 (the same as Jenkins Core itself)

2.25 (Jun 1, 2014)

  • FIXED: useMatrixChild in FileBuildParameters cannot be configured at all. (issue #22705)
  • Support absolute paths in "Parameters from properties file". (issue #23084)
  • Allow using parameter files even if no workspace exists. (issue #22229)
  • Output more informative logs when failing converting parameter values in compatibility mode. (issue #22281)
  • FIXED: Checking project names in configuration page works wrong with Cloudbees Template plugin. (issue #22856)

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.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

Open issues (50 issues)
Type Priority Key Summary
Improvement Minor JENKINS-28354 Add Fixed build trigger
Improvement Minor JENKINS-27740 Add "Abort downstream jobs" to "Block until finished" build step options
Bug Major JENKINS-27714 Maven Passsword Parameters
Bug Major JENKINS-27679 Issue when parallelizing parametrized jobs from a multi-project jobs
Bug Critical JENKINS-27604 Error communicating to server! Server Error
Improvement Minor JENKINS-27536 Add option for "back to normal" build result to trigger a build in the Parameterized Trigger Plugin
Bug Blocker JENKINS-27440 Cannot restrict job running on one node
Bug Major JENKINS-26984 Plugin doesn't resolve variables during form validation
Bug Major JENKINS-26877 Manual trigger ignores properties file if the build node doesn't exists anymore
Bug Minor JENKINS-26646 Items.fromNameList is being called with a null parameter
Improvement Minor JENKINS-26563 BlockableBuildTrigger invokes build timeout
New Feature Major JENKINS-26050 Workflow integration for Parameterized Trigger
Improvement Major JENKINS-25794 Possibility to trigger a job with all available parameters
Improvement Minor JENKINS-25685 Parameterized Trigger - Delivery Pipeline compatibilety
Bug Minor JENKINS-25645 Plugin writes out "Triggerin projects: myproject" even if no project succeeds to be triggered.
Bug Major JENKINS-24622 Upstream jobs have disapeared from job main page
Bug Major JENKINS-24257 Guessed downstream build # in console log can be wrong in Parameterized Trigger Plugin
Improvement Major JENKINS-23927 Parameterized trigger should be able to optionally retry failed blocked builds
Improvement Major JENKINS-22980 be able to execute concurrent builds with separate parameters
Bug Major JENKINS-22600 Sub-projects appeared as "Static" and "Other executed recently" at job main page
Improvement Major JENKINS-22030 Show list of 'Is Subproject of' where a job is listed in the Subprojects section of another one
Task Minor JENKINS-21975 Add notice about the combination of ivy plugin and parameterizrd-trigger plugin
Improvement Major JENKINS-21829 Console output should print build number when adding a build to the queue
New Feature Major JENKINS-20957 Add support for RunParameter to parameterized-trigger
Bug Major JENKINS-20260 Sequential triggering of jobs sometimes fails when the file parameter is read-only
Bug Major JENKINS-19276 Escape characters such as "\" for filepaths are being removed from variables loaded from properties file.
Improvement Major JENKINS-19255 Do not silently drop build steps that fail the triggering build when removing the triggered job
New Feature Major JENKINS-18536 Remove downstream job from queue before new triggers
New Feature Minor JENKINS-18486 When providing multiple jobs to run, support running them one after another and not all together
New Feature Major JENKINS-18363 macro token support
New Feature Major JENKINS-17286 Triggered jobs should run synchronously as mentioned or listed when using the "Trigger/Call builds on another project" item
Improvement Major JENKINS-17279 I need better documentation for how to use the SVN parameter
Bug Major JENKINS-17009 Parameters with newlines should be stored as TextParameterValue
New Feature Minor JENKINS-15520 Option for displaying or hiding the project in the downstream graph
Improvement Minor JENKINS-15299 support spaces inside parameters
Bug Major JENKINS-14329 SCM Sync Configuration plugin conflicts with Parameterized Trigger plugin. (stuck on waiting for the completion of OtherBuild)
New Feature Minor JENKINS-13966 Parameter Factories on Trigger parameterized build
Improvement Minor JENKINS-12621 Give the option to pass either the last changed rev or the current latest rev when triggering downstream builds.
New Feature Major JENKINS-12480 Build step that runs multiple jobs in parallel, and blocks until all are complete
Improvement Minor JENKINS-12479 Add checkbox to add an executor when blocking
Improvement Major JENKINS-12290 Lockup when using "trigger/call builds on other projects" and "Block until the triggered projects finish their builds" is used with only 1 executor
Bug Major JENKINS-11280 Downstream project name is not accepting env variable/build parameters
Improvement Major JENKINS-11257 Stopping a parent job doesn't stop the triggered child jobs
New Feature Minor JENKINS-10861 Copy artifacts from downstream job run via synchronous Trigger Build step
Improvement Major JENKINS-10779 Non-existing parameters are not empty but replaced with parameter name
New Feature Minor JENKINS-10147 Add 'poll SCM' option to build step
Improvement Minor JENKINS-9793 Use expandable text box for jobs list configuration
New Feature Major JENKINS-9622 Add build selector to parameterized trigger
New Feature Minor JENKINS-9105 Parameterized plugin should have an option to support "block until downstream projects finish"
Bug Major JENKINS-7557 Overlapping parameterized builds gets confused on downstream jobs

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