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
Feb 13, 2014
1.509.3
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Kohsuke Kawaguchi (id: kohsuke)
Alex Earl (id: slide_o_mix)
Usage Installations 2013-Apr 12051
2013-May 14889
2013-Jun 16869
2013-Jul 19165
2013-Aug 20627
2013-Sep 22079
2013-Oct 24137
2013-Nov 25356
2013-Dec 25856
2014-Jan 28206
2014-Feb 29723
2014-Mar 31818

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 arbitrary number of parameters (with multiple values allowed for a single parameter name:

${FOO}                             # 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 evaluates 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: 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: Favorite Plugin — This plugin allows you to mark a job a favorite.
Page: PMD Plugin — This plugin generates the trend report for PMD, an open source static code analysis program. 
Page: Task Scanner Plugin — This plugin scans the workspace files for open tasks and generates a trend report.
Page: CCM Plugin — This plug-in generates reports on cyclomatic complexity for .NET code.
Page: Checkstyle Plugin — This plugin generates the trend report for Checkstyle, an open source static code analysis program. 
Page: Ownership Plugin — Plugin provides explicit ownership for jobs and slave nodes.
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: Warnings Plugin — This plugin generates the trend report for compiler warnings in the console log or in log files.
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: Robot Framework Plugin — This plugin collects and publishes Robot Framework test results
Page: DRY Plugin — This plugin generates the trend report for duplicate code checkers like CPD or Simian.
Page: Groovy plugin — This plugin adds the ability to directly execute Groovy code.
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: Project Description Setter Plugin — Set the project description from a file in the workspace (à la GitHub README.md)
Page: Repository Connector Plugin — Repository Connector adds a build step which allows to resolve artifacts from a maven repository like nexus (without having maven installed).
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: Xcode Plugin — This plugin adds the ability to call Xcode command line tools to automate build and packaging iOS applications (iPhone, iPad, ...).
Page: Build Name Setter Plugin — This plugin sets the display name of a build to something other than #1, #2, #3, ...
Page: Conditional BuildStep Plugin — A buildstep wrapping any number of other buildsteps, controlling their execution based on a defined condition.
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: 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: 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: Delivery Pipeline Plugin — Visualisation of Delivery/Build Pipelines, renders pipelines based on upstream/downstream jobs. Full screen view for information radiators.

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