Token Macro Plugin

Skip to end of metadata
Go to start of metadata

This plugin adds reusable macro expansion capability for other plugins to use.

Plugin Information

Plugin ID token-macro Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
1.10 (archives)
Feb 13, 2014
1.509.3
Source Code
Issue Tracking
Pull Requests
Maintainer(s)
GitHub
Open Issues
Pull Requests
Kohsuke Kawaguchi (id: kohsuke)
Alex Earl (id: slide_o_mix)
Usage Installations 2014-May 34315
2014-Jun 36013
2014-Jul 38748
2014-Aug 39896
2014-Sep 42344
2014-Oct 44328
2014-Nov 45040
2014-Dec 45442
2015-Jan 47930
2015-Feb 49058
2015-Mar 52631
2015-Apr 53238

Motivation

In various Jenkins plugins, such as email-ext and description-setter, a user is asked to provide an "expression" that evaluates to text. For example, in the case of the email-ext plugin, the whole email content is one big expression, so is the subject. This often includes some kind of macro tokens, which evaluates to things like build number, cause, the current branch being built, etc. In the description-setter plugin, the user configures a similar expression that evaluates to the string that becomes a build string. In instant messenger plugin, one might configure the template that controls what messages the user will receive.

All these plugins share the common concept of token expansions, where something like ${SUBVERSION_REVISION} expands to some textual values, and since this notion is useful beyond any single use case, it makes sense to define it elsewhere. And this is exactly what this plugin does — to define the mechanism for plugins to define tokens (and their parameters) and their evaluation, and allow this mechanism to be reused by different plugins.

Token Expansion Model

Much of the definition of this is modeled after the email-ext plugin. In the general form, a token can have an arbitrary number of parameters, with multiple values allowed for a single parameter name:

${FOO}                             # no parameter
$FOO                               # alternative syntax for token with no parameter
${FOO,param1=value1,param2=value2} # 2 parameters
${FOO,param=v1,param=v2,param=v3}  # 1 parameter with 3 values

Those plugins that wish to define custom tokens can do so by providing implementations of the TokenMacro class that evaluates this into arbitrary string.

Using Token Expansion

Those plugins that evaluate an expression can call TokenMacro.expand to have all the occurrences of the macros expanded by the available definitions.

String template = "My revision is ${SUBVERSION_REVISION} at #${BUILD_NUMBER}"
String text = TokenMacro.expand( build, listener, template );
System.out.println(text); // something like "My revision is 125 at #12"

You can also ask to expand all Macros managed by the Token Macro plugin but also all environment and build variables using TokenMacro.expandAll.

String template = "My revision is ${SUBVERSION_REVISION} at #${BUILD_NUMBER} and was executed on node ${NODE_NAME}"
String text = TokenMacro.expandAll( build, listener, template );
System.out.println(text); // something like "My revision is 125 at #12 and was executed on node master"

Databinding Token Macro

The base TokenMacro class only defines a minimalistic contract between the user of the tokens. To simplify the development of custom tokens, a more convenient subtype called DataBoundTokenMacro is provided to simplify the parameter parsing. In this subtype, you get your parameters injected to your instance, so that your evaluate method can access parameter values in a type-safe manner. The following sample is taken from the Git plugin that defines GIT_REVISION macro that expands to the SHA1 commit ID used for a build, with a parameter that controls the length.

For example, this macro can be used like ${GIT_REVISION,length=8} to only show first 8 letters of the commit.

@Extension
public class GitRevisionTokenMacro extends DataBoundTokenMacro {
    /** Number of chars to use */
    @Parameter
    public int length = 40;

    @Override
    public boolean acceptsMacroName(String macroName) {
        return macroName.equals("GIT_REVISION");
    }

    @Override
    public String evaluate(AbstractBuild<?, ?> context, TaskListener listener, String macroName)
            throws MacroEvaluationException, IOException, InterruptedException {
        BuildData data = context.getAction(BuildData.class);
        if (data == null) {
            return "";  // shall we report an error more explicitly?
        }

        Revision lb = data.getLastBuiltRevision();
        if (lb == null) {
            return "";
        }

        String s = lb.getSha1String();
        return s.substring(0, Math.min(length, s.length()));
    }
}

Plugins that produce tokens

Page: DRY Plugin — This plugin generates the trend report for duplicate code checkers like CPD or Simian.
Page: Task Scanner Plugin — This plugin scans the workspace files for open tasks and generates a trend report.
Page: Favorite Plugin — This plugin allows you to mark a job a favorite.
Page: Git Parameter Plugin — This plugin allows you to choose between Git tags or sha1 of your SCM repository so Git Plugin installed is required.
Page: Robot Framework Plugin — This plugin collects and publishes Robot Framework test results
Page: FindBugs Plugin — This plugin generates the trend report for FindBugs, an open source program which uses static analysis to look for bugs in Java code. 
Page: Analysis Collector Plugin — This plug-in is an add-on for the plug-ins Checkstyle, Dry, FindBugs, PMD, Task Scanner, and Warnings: the plug-in collects the different analysis results and shows the results in a combined trend graph. Additionally, the plug-in provides health reporting and build stability based on these combined results.
Page: Checkstyle Plugin — This plugin generates the trend report for Checkstyle, an open source static code analysis program. 
Page: PMD Plugin — This plugin generates the trend report for PMD, an open source static code analysis program. 
Page: Warnings Plugin — This plugin generates the trend report for compiler warnings in the console log or in log files.
Page: Ownership Plugin — Plugin provides an ownership mechanism for jobs and slave nodes.
Page: CCM Plugin — This plug-in generates reports on cyclomatic complexity for .NET code.
Page: Delivery Pipeline Plugin — Visualisation of Delivery/Build Pipelines, renders pipelines based on upstream/downstream jobs. Full screen view for information radiators.
Page: Groovy plugin — This plugin adds the ability to directly execute Groovy code.
Page: Scriptler Plugin — Scriptler allows you to store/edit groovy scripts and execute it on any of the slaves/nodes... no need to copy/paste groovy code anymore.
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.

If your plug-in is not listed here, then simply add the label token-producer to your plug-in wiki page and it will be automatically listed.

Plugins that consume tokens

Page: Maven Info Plugin — This plugin add features related to Maven jobs info. Adds columns configurable in views (version, dependencies, modules, ...) and extract information from Maven jobs (update name and description from POM, ...)
Page: Project Description Setter Plugin — Set the project description from a file in the workspace (à la GitHub README.md)
Page: Build Name Setter Plugin — This plugin sets the display name of a build to something other than #1, #2, #3, ...
Page: Xcode Plugin — This plugin adds the ability to call Xcode command line tools to automate build and packaging iOS applications (iPhone, iPad, ...).
Page: Conditional BuildStep Plugin — A buildstep wrapping any number of other buildsteps, controlling their execution based on a defined condition.
Page: OpenShift Deployer Plugin — This plugin add the ability to create gears and deploy applications to OpenShift.
Page: Run Condition Plugin — Core conditions to select whether to execute a build step or publisher. Used by the Flexible Publish Plugin and the Conditional BuildStep Plugin.
Page: Delivery Pipeline Plugin — Visualisation of Delivery/Build Pipelines, renders pipelines based on upstream/downstream jobs. Full screen view for information radiators.
Page: Scriptler Plugin — Scriptler allows you to store/edit groovy scripts and execute it on any of the slaves/nodes... no need to copy/paste groovy code anymore.
Page: Email-ext Template Plugin — This plugin allows you to configure templates for email-ext that can be reused across multiple jobs.
Page: Email-ext plugin — This plugin allows you to configure every aspect of email notifications. You can customize when an email is sent, who should receive it, and what the email says.
Page: Repository Connector Plugin — Repository Connector adds features around resolving artifacts from a Maven repository like Nexus or Artifactory.

If your plug-in is not listed here, then simply add the label token-consumer to your plug-in wiki page and it will be automatically listed.

Release History

Version 1.10 (February 13, 2014)

  • Migrated tests to use JenkinsRule instead of HudsonTestCase
  • Added additional tests for the DataBoundTokenMacro
  • Added ADMIN_EMAIL token to retrieve the administrator email address
  • Added the ability to mark a parameter with an alias so that Java keywords can be used as macro arguments.
  • Updated pom.xml to include the MIT license

Version 1.9 (October 28, 2013)

  • Cleaned up the pom a bit
  • Fixed issue with private tokens accumulating over time (issue #18912)

Version 1.8.1 (Jul 20, 2013)

  • Added error message output instead of just letting the exception be caught and ignored

Version 1.8 (Jul 16, 2013)

  • Updated the way that macros are escaped so that it's more like Groovy (issue #18014)
  • Created macro (LOG_REGEX) to match against the log output and allow replacing it.
  • Fix issue with PROPFILE token that would hang the build if the PROPFILE was not found.
  • Updated to depend on a newer LTS (1.509.1) in the pom.
  • Disallow tokens that begin with a number to follow identifier constraints in programming languages.

Version 1.7 (May 23, 2013)

  • Fixed issue with long string parameters and backslash escaped items.

Version 1.6 (Feb 25, 2013)

  • Added nested token support
  • Added ability to escape tokens
  • Added ability to have private macros

Version 1.5.1 (Nov 29, 2011)

  • New method TokenMacro.expandAll( build, listener, template ) was broken (issue #11914)

Version 1.5 (Nov 28, 2011)

  • New method TokenMacro.expandAll( build, listener, template ) that supports to expand all macros, but also all environment and build variables.

Version 1.4

  • Magnifying plugin name.
  • Fixing inaccurate documentation

Version 1.3

  • Added macro for retrieving build environment variables.
  • Added macro for retrieving properties from property files in the build workspace.

Version 1.2

  • Added description for update center

Version 1.1

  • Fixed exception

Version 1.0

  • Initial release
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment