Skip to end of metadata
Go to start of metadata

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

Plugin Information

View Token Macro on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:


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.

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

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

    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()));

Token Transforms

There are a few different transforms that can be applied on top of the result of the token itself. These are similar to BASH shell transforms.

${#MACRO_NAME} // returns the number of characters in the result of evaluating MACRO_NAME.
${MACRO_NAME:<START>[:LENGTH]} // returns the substring starting at START, and optionally specifying the length. You may use negative numbers similar to BASH.
${MACRO_NAME#<NEEDLE>} // returns the value with <NEEDLE> removed, IF it is at the START of the result value.
${MACRO_NAME%<NEEDLE>} // returns the value with <NEEDLE> removed, IF it is at the END of the result value.

Plugins that produce tokens

  • Page:
    Warnings Next Generation Plugin — This plugin collects compiler warnings or issues reported by static analysis tools and visualizes the results.
  • 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, including repository browsers for several providers. A recent Git runtime is required (1.7.9 minimum, 1.8.x recommended). Interaction with the Git runtime is performed by the use of the Git Client Plugin, which is only tested on official git client. Use exotic installations at your own risk.
  • Page:
    Robot Framework Plugin — This plugin collects and publishes Robot Framework test results in Jenkins.
  • Page:
    Analysis Collector Plugin — This plug-in is an add-on for the plug-ins Checkstyle, Dry, FindBugs, PMD, Android LintTask 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:
    DRY Plugin — This plugin generates the trend report for duplicate code checkers like CPD or Simian.
  • Page:
    Git Parameter Plugin

    Adds ability to choose branches, tags or revisions from git repository configured in project.

  • Page:
    Task Scanner Plugin — This plugin scans the workspace files for open tasks and generates a trend report.
  • Page:
    PMD Plugin — This plugin generates the trend report for PMD, an open source static code analysis program. 
  • Page:
    Checkstyle Plugin — This plugin generates the trend report for Checkstyle, an open source static code analysis program. 
  • 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:
    OWASP Dependency-Check Plugin — This plugin can analyze dependencies and generate trend reports for Dependency-Check, an open source utility that detects known vulnerabilities in project dependencies.
  • Page:
    CCM Plugin — This plug-in generates reports on cyclomatic complexity for .NET code.
  • Page:
    Warnings Plugin — This plugin generates the trend report for compiler warnings in the console log or in log files.
  • Page:
    Favorite Plugin — This plugin allows you to mark a job a favorite.
  • Page:
    Promoted Builds Plugin — This plugin allows you to distinguish good builds from bad builds by introducing the notion of 'promotion'.
  • 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:
    Delivery Pipeline Plugin — Visualisation of Continuous Delivery pipelines. Renders pipelines based on upstream/downstream jobs or Jenkins pipelines. Provides a full screen view for information radiators.
  • Page:

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:
    Assembla Merge Request Builder Plugin — Allows Jenkins to build merge requests from Assembla.
  • Page:
    OpenShift Deployer Plugin

    This plugin add the ability to create gears and deploy applications to OpenShift.

  • 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:
    PagerDuty Plugin — Allows users to trigger postbuild incidents via PagerDuty
  • Page:
    Nuget Plugin — A Jenkins plugin allowing to:
    • trigger a job when a NuGet dependency is updated.
    • publish packages to NuGet repositories
  • Page:
    Windows Exe Runner Plugin — This plug-in is used to run the Windows Exe.
  • Page:
    Cloud Foundry Plugin — Pushes a project to Cloud Foundry or a CF-based platform (e.g. Stackato) at the end of a build.
  • 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:
    Google Play Android Publisher Plugin — Enables Jenkins to upload Android apps (APK files) and related info to Google Play.
  • Page:
    Repository Connector Plugin — Repository Connector adds features for resolving artifacts from a Maven repository like Nexus or Artifactory.
  • 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:
    GitHub Issues Plugin — This plugin allows you to create a GitHub issue whenever your build fails. Once the build starts passing again, the issue will automatically be closed.
  • 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:
    AWSEB Deployment Plugin — This plugin allows you to deploy into AWS Elastic Beanstalk by Packaging, Creating a new Application Version, and Updating an Environment
  • Page:
    Build Name Setter Plugin — This plugin sets the display name of a build to something other than #1, #2, #3, ...
  • Page:
    Project Description Setter Plugin — Set the project description from a file in the workspace (à la GitHub
  • Page:
    Conditional BuildStep Plugin — A buildstep wrapping any number of other buildsteps, controlling their execution based on a defined condition.
  • Page:
    Delivery Pipeline Plugin — Visualisation of Continuous Delivery pipelines. Renders pipelines based on upstream/downstream jobs or Jenkins pipelines. Provides a 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 2.7 (March 7, 2019)

  • Updates to support Java 11

Version 2.6 (January 28, 2019)

Version 2.3 (September 1, 2017)

  • Fixed incompatibility issue with Docker Plugin by reducing the scope of the pipeline dependencies.

Version 2.2 (August 22, 2017)

  • There is an incompatibility issue with Token Macro 2.2 and the Docker Plugin. Downgrade to 2.1 if you are using the Docker Plugin
  • Add ability to use JsonPath for the JSON macro, use expr="jsonpath expression here" instead of path=""
  • Add tm pipeline step that will take a string with macros and expand and return the resulting string
  • Fix issue with BUILD_STATUS in pipeline jobs (JENKINS-44322)

Version 2.1 (April 4, 2017)

  • Fixed issue where the plugin may report incorrect parameters when it shouldn't (JENKINS-38871)
  • Fixed issue with CHANGES_SINCE_LAST_SUCCESS not showing "No Changes" (JENKINS-38668)
  • Additional tests were added (JENKINS-40683)
  • Fixed issues so that the plugin can be used in the global plugin tests for core (JENKINS-39672)
  • Fixed issue with whitespace following the variable definition (JENKINS-38420)
  • Added JSON token for retrieving data from a JSON file.

Version 2.0 (September 20, 2016)

  • Thanks to the following for contributions in this release dcoraboeufduemir
  • Initial support for using Token Macro in pipeline script context (JENKINS-35368)
  • Fixed issue with synchronization which was causing slowness (JENKINS-32331)
  • Provide new method to get auto-completion possibilities for a given string (JENKINS-9345)
  • Allow for additional transforms on the result of the token (JENKINS-28951)

Version 1.12.1 (December 14, 2015)

  • Fixed bad dependency in pom.xml causing circular dependency issue

Version 1.12 (December 10, 2015)

  • Migrated tokens from email-ext to token-macro
  • Fixed issue with multiline JOB_DESCRIPTION in subject (JENKINS-32012)
  • Fixed issue where extra $'s for escaping $'s were being removed (JENKINS-29816)
  • Added UPSTREAM_RUN_NAME macro (JENKINS-27542)

Version 1.11 (October 16, 2015)

  • (plus) Added FILE macro to display Workspace file contents (JENKINS-27540)
  • (plus) Added XML macro, which retrieves the data from XML file using XPath (JENKINS-12742)
  • (info) Allow configuring charsets in LOG_REGEX macro (PR 18)
  • (error) Cleanup of issues discovered by FindBugs, the plugin is FindBugs-clean (PR 18)

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 (JENKINS-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
  • No labels


  1. It does not appear to be listed in the standard jenkins plugins management screen. where do you download it from these days?

  2. It seems that a bug has been introduced whereby the PROPFILE macro no longer parses nested tokens.  I have 4 build servers running Jenkins at version 1.5.2.  On each of these servers I'm using the email-ext plugin (v2.27.1) in combination with the token-macro plugin (v1.6) to generate post-build emails using values contained in a properties file associated with the project being built.  There are a number of project-specific fields in these emails that are generated using token-macro as follows:

    • ${PROPFILE, file="${ENV, var="PROPERTIES_PATH"}", property=""}

    The variable 'PROPERTIES_PATH' is an environment variable generated by a pre-build groovy script.  This works successfully on my 4 existing build servers.  I've just created a new build server at Jenkins v1.564 and as part of this process I updated all my plugins (email-ext v2.32 and token-macro v1.9 - I tried token-macro v1.10 and got the same bad result).  To my surprise, my post-build emails no longer work.  Instead of the appropriate property value in the resultant email I now see the following literal string:

    • ${PROPFILE, file="../../build_properties/xxxxxxxxxx33ad9b591a2438d4/", property=""}

    In other words, token-macro is correctly resolving the environment variable token PROPERTIES_PATH but is then failing to resolve the PROPFILE token.  If I hard-code the environment variable token in my template to the value passed in the post-build email (using copy and paste, so exactly the same value is being used) then the token representing the desired property is correctly resolved, indicating that both of these tokens are capable of being resolved and will resolve as long as they are not nested.  Unless a decision has been taken to remove the ability of PROPFILE to resolve nested tokens then it would appear that a bug has been introduced somewhere between version 1.6 and 1.9.

    I have fixed the problem by reverting email-ext to v2.27.1 and token-macro to v1.6 but this is not a sustainable solution since these plugins will undoubtedly evolve as Jenkins evolves making them unusable at some point in the future and breaking all my post-build emails.

  3. I have an issue with latest 1.12 version.

    The following plugins are deactivated because of cyclic dependencies, most likely you can resolve the issue by updating these to a newer version.

    • config-file-provider
    • token-macro

    Rolling back token-macro plugin from version 1.12 to version 1.11 resolved the issue.

  4. I see this for many plugins.   Plugin
    Failure - Connection reset
    at hudson.model.UpdateCenter$
    Caused: Failed to load to /var/lib/jenkins/plugins/token-macro.jpi.tmp
    at hudson.model.UpdateCenter$
    Caused: hudson.util.IOException2: Failed to download from (redirected to:
    at hudson.model.UpdateCenter$
    any advice or ideas why?

  5. This is very handy. However I'd note two things:

    First, it might be nice if you note in the documentation that $$ is needed to escape dollar signs.

    Second, you recommend pegdown but it's deprecated.

    1. Where is pegdown recommended? Also, please use the mailing list for questions/comments.

  6. Hi, I could not found $BUILD_DURATION in token list in version 2.3, but found in 2.1.
    Did it been removed or hide in somewhere?  

    1. It must be coming from another plugin because token-macro hasn't included a BUILD_DURATION macro in any version that I can see. Please use the mailing list for future questions.