×
Find plugins

Token Macro2.3Minimum Jenkins requirement: 1.642.3ID: token-macro

Installs: 133067
Last released: 18 days ago
Maintainers
Kohsuke Kawaguchi
Alex Earl

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

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

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:
    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:
    Favorite Plugin — This plugin allows you to mark a job a favorite.
  • Page:
    Robot Framework Plugin — This plugin collects and publishes Robot Framework test results
  • Page:
    Promoted Builds Plugin — This plugin allows you to distinguish good builds from bad builds by introducing the notion of 'promotion'.
  • 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:
    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:
    DRY Plugin — This plugin generates the trend report for duplicate code checkers like CPD or Simian.
  • Page:
    OWASP Dependency-Check Plugin — This plugin can analyze dependencies and generate trend reports for OWASP Dependency-Check, an open source utility that detects known vulnerabilities in project dependencies.
  • 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:
    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:
    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:
    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:
    Checkstyle Plugin — This plugin generates the trend report for Checkstyle, 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:
  • Page:
    CCM Plugin — This plug-in generates reports on cyclomatic complexity for .NET code.

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:
    Nuget Plugin

    A Jenkins plugin allowing to:

    • trigger a job when a NuGet dependency is updated.
    • publish packages to NuGet repositories
  • 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:
    Assembla Merge Request Builder Plugin — Allows Jenkins to build merge requests from Assembla.
  • 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:
    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:
    OpenShift Deployer Plugin

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

  • Page:
    Project Description Setter Plugin

    Set the project description from a file in the workspace (à la GitHub README.md)

  • 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:
    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:
    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:
    Conditional BuildStep Plugin — A buildstep wrapping any number of other buildsteps, controlling their execution based on a defined condition.
  • 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:
    Build Name Setter Plugin — This plugin sets the display name of a build to something other than #1, #2, #3, ...
  • Page:
    Repository Connector Plugin

    Repository Connector adds features for 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 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
ArchivesGet past versions
Labels
This plugin has no labels