arjabbar/TokenMacros.md

## TokenMacros.md

      
    Raw
  

              TokenMacros.md
            
          
    Email-Ext Jenkins Plugin Macros

Purpose

Created to make it a little easier to find the macro that you need outside of opening a Freestyle job in Jenkins.
Documentation from Jenkins page

Arguments may be given for each token in the form name="value" for strings and in the form name=value for booleans and numbers. In string arguments, escape ", , and line terminators (\n or \r\n) with a , e.g. arg1=""quoted""; arg2="c:\path"; and arg3="one\ntwo". The brackets may be omitted if there are no arguments.
Examples: $TOKEN, ${TOKEN}, ${TOKEN, count=100}, ${ENV, var="PATH"}
Project Tokens

${DEFAULT_SUBJECT}

This is the default email subject that is configured in Jenkinss system configuration page.
${DEFAULT_CONTENT}

This is the default email content that is configured in Jenkinss system configuration page.
${DEFAULT_PRESEND_SCRIPT}

This is the default pre-send script content that is configured in Jenkinss system configuration. This is the only token supported in the pre-send script entry field.
${DEFAULT_POSTSEND_SCRIPT}

This is the default post-send script content that is configured in Jenkinss system configuration. This is the only token supported in the post-send script entry field.
${PROJECT_DEFAULT_SUBJECT}

This is the default email subject for this project. The result of using this token in the advanced configuration is what is in the Default Subject field above. WARNING: Do not use this token in the Default Subject or Content fields. Doing this has an undefined result.
${PROJECT_DEFAULT_CONTENT}

This is the default email content for this project. The result of using this token in the advanced configuration is what is in the Default Content field above. WARNING: Do not use this token in the Default Subject or Content fields. Doing this has an undefined result.
Extended Email Publisher Specific Tokens
${JELLY_SCRIPT,template="TEMPLATE_NAME"}

Custom message content generated from a Jelly script template. There are two templates provided: "html" and "text". Custom Jelly templates should be placed in $JENKINS_HOME/email-templates.When using custom templates, the template filename without ".jelly" should be used for the "template" argument.You may also use the Config File Provider plugin to manage your templates. Prefix the managed file NAME with "managed:" for the template parameter. Example: ${JELLY_SCRIPT, template="managed:ManagedFileName"}
${SCRIPT}

Custom message content generated from a groovy script.Custom scripts should be placed in "$JENKINS_HOME/email-templates". When using a custom script the plugin will look in the resources forthe email-ext plugin first, and then in the $JENKINS_HOME/email-templatesdirectory. No other directories will be searched.You may also use the Config File Provider plugin to manage your scripts. Prefix the managed file NAME with "managed:" for the template or script parameter. Example: ${SCRIPT, template="managed:ManagedFileName"}

script - When this is used, only the last value in the script will be used in the expansion (script and template can not be used together).
template - The template in Groovy's SimpleTemplateEngine format.

${TEMPLATE}

Custom message content generated from a template file.Custom templates should be placed in "$JENKINS_HOME/email-templates". When using a custom script the plugin will look in the resources forthe email-ext plugin first, and then in the $JENKINS_HOME/email-templatesdirectory. No other directories will be searched.You may also use the Config File Provider plugin to manage your templates. Use the "Custom File" config type for the template.Prefix the managed file NAME with "managed:" for the file parameter. Example: ${TEMPLATE, file="managed:ManagedFileName"}

file - The template in plain text format.

Token Macro Plugin Tokens
${CCM_RESULT}

Expands to the build result of the CCM plug-in.
${CCM_COUNT}

Expands to the total number of CCM warnings in a build.
${CCM_FIXED}

Expands to the total number of fixed CCM warnings in a build.
${CCM_NEW}

Expands to the total number of new CCM warnings in a build.
${FAILED_TESTS}

Displays failing unit test information, if any tests failed.

showStack
Shows stack trace in failing test output. Defaults to true.
showMessage
Shows error message in failing test output. Defaults to true.
maxTests
Display at most this many tests. No limit is set by default.
onlyRegressions
Display only the failing tests that are different from previous builds. Defaults to false.

${TEST_COUNTS,var="TYPE"}

Displays the number of tests based on the type (var) passed in (total, pass, fail, skip). Defaults to total.
${GIT_BRANCH}

Expands to the name of the branch that was built.
Parameters

all
If specified, all the branches that point to the given commit is listed. By default, the token expands to just one of them.
fullName
If specified, this token expands to the full branch name, such as 'origin/master'. Otherwise, it only expands to the short name, such as 'master'.

${GIT_REVISION}

Expands to the Git SHA1 commit ID that points to the commit that was built.
Parameters

length=N (optional, default to 40)
Specify the commit ID length. Full SHA1 commit ID is 40 character long, but it is common to cut it off at 8 or 12 as that often provide enough uniqueness and is a lot more legible.

${GROOVY,script = "code"}

Executes Groovy code
Example:
${GROOVY,script = "return jenkins.model.Jenkins.instance.pluginManager.plugins"}
Note:
By default, the support for token macro pressing is switched off and has to be switch on in global config page.
Warning:
If token macro processing via Token Macro Plugin is allowed, the evaluation of macro is done in System Groovy, therefore any user can run arbitrary system script, regardless he has administer permission!
${WARNINGS_FIXED}

Expands to the total number of fixed compiler warnings in a build.
${WARNINGS_NEW}

Expands to the total number of new compiler warnings in a build.
${WARNINGS_COUNT}

Expands to the total number of compiler warnings in a build.
${WARNINGS_RESULT}

Expands to the build result of the warnings plug-in.
${DEPENDENCYCHECK_RESULT}

Expands to the build result of the Dependency-Check plug-in.
${DEPENDENCYCHECK_COUNT}

Expands to the total number of Dependency-Check warnings in a build.
${DEPENDENCYCHECK_FIXED}

Expands to the total number of fixed Dependency-Check warnings in a build.
${DEPENDENCYCHECK_NEW}

Expands to the total number of new Dependency-Check warnings in a build.
${ADMIN_EMAIL}

Displays the email address for the Jenkins administrator
${BUILD_CAUSE} ${CAUSE}

Displays the cause of the build.
${BUILD_LOG_EXCERPT}

Displays an excerpt from the build log.

start - Regular expression to match the excerpt starting line (matching line is excluded).
end - Regular expression to match the excerpt ending line (matching line is excluded).
See java.util.regex.Pattern

${BUILD_LOG}

Displays the end of the build log.

maxLines - Display at most this many lines of the log. Defaults to 250.
escapeHtml - If true, HTML is escape. Defaults to false.

${BUILD_LOG_MULTILINE_REGEX}

Displays build log segments that match the regular expression.

regex - java.util.regex.Pattern
Segments of the build log that match this regular expression are included. See also null. No default. Required parameter
maxMatches - The maximum number of matches to include. If 0, all matches will be included. Defaults to 0.
showTruncatedLines - If true, include [...truncated ### lines...] lines. Defaults to true.
substText - If non-null, insert this text into the email rather than the entire segment. Defaults to null.
escapeHtml - If true, escape HTML. Defaults to false.
matchedSegmentHtmlStyle - If non-null, output HTML. Matched lines will become <b style="your-style-value">html escaped matched lines</b>. Defaults to null.

${BUILD_LOG_REGEX}

Displays lines from the build log that match the regular expression.

regex - Lines that match this regular expression are included. See also java.util.regex.Pattern.Defaults to "(?i)\b(error|exception|fatal|fail(ed|ure)|un(defined|resolved))\b"
linesBefore - The number of lines to include before the matching line. Lines that overlap with another match or linesAfter are only inlcuded once. Defaults to 0.
linesAfter - The number of lines to include after the matching line. Lines that overlap with another match or linesBefore are only included once. Defaults to 0.
maxMatches - The maximum number of matches to include. If 0, all matches will be included. Defaults to 0.
showTruncatedLines - If true, include [...truncated ### lines...] lines. Defaults to true.
substText - If non-null, insert this text into the email rather than the entire line. Defaults to null.
escapeHtml - If true, escape HTML. Defauts to false.
matchedLineHtmlStyle - If non-null, output HTML. Matched lines will become <b style="your-style-value"> html escaped matched line</b>. Defaults to null.
addNewline - If true, adds a newline after subsText. Defaults to true.
defaultValue - This value will be used if nothing is replaced.

${BUILD_NUMBER}

Expands to the current build number, a sequential auto-incrementing unique number that identifies the build, such as "125"
##${BUILD_STATUS}
Displays the status of the current build. (failing, success, etc...)
${BUILD_URL}

Displays the URL for the current build
${CHANGES_SINCE_LAST_BUILD} ${CHANGES}

Displays the changes since the last build.

showDependencies
If true, changes to projects this build depends on are shown. Defaults to false
showPaths
If true, the paths, modified by a commit are shown. Defaults to false
format
For each commit listed, a string containing %X, where %x is one of:

%a = author
%d = date
%m = message
%p = path
%r = revision


Not all revision systems support %d and %r. If specified showPaths argument is ignored. Defaults to "[%a] %m\n"

pathFormat - A string containing %p to indicate how to print paths. Defaults to "\t%p\n"
regex - A regular expression.
replace - A replacement for all sub-strings of the change message that match the given regular expression.
default - Message to use when no changes are detected. Defaults to "No changes\n"

${CHANGES_SINCE_LAST_SUCCESS}

Displays the changes since the last successful build.


reverse - If true, show most recent builds at the top instead of the bottom. Defaults to false.


format - For each build listed, a string containing %X, where %X is one of

%c = changes
%n = build number
Defaults to Changes for Build #%n\n%c\n


changesFormat - For each change in a build. See ${CHANGES_SINCE_LAST_BUILD} for placeholders.
Following Parameters are also supported: showPaths, pathFormat, showDependencies, dateFormat, regex, replace, default. See ${CHANGES_SINCE_LAST_BUILD} details.


${CHANGES_SINCE_LAST_UNSTABLE}

Expands to the changes since the last unstable or successful build.


reverse - If true, show most recent builds at the top instead of the bottom. Defaults to false.


format - For each build listed, a string containing %X, where %X is one of

%c = changes
%n = build number
Defaults to Changes for Build #%n\n%c\n


changesFormat - For each change in a build. See ${CHANGES_SINCE_LAST_BUILD} for placeholders.
Following Parameters are also supported: showPaths, pathFormat, showDependencies, dateFormat, regex, replace, default. See ${CHANGES_SINCE_LAST_BUILD} details.


${ENV,var="VARIABLENAME"}

Expands to an environment variable (specified here as VARIABLENAME) from the build environment. Note that this does not include any variables set by the build scripts themselves, only those set by Jenkins and other plugins.
${JENKINS_URL}

Displays the URL to the Jenkins server. (You can change this on the system configuration page.)
${JOB_DESCRIPTION}

Displays the description of the job.
${LOG_REGEX}

Uses a regular expression to find a single log entry and generates a new output using the capture groups from it. This is partially based on the description-setter plugin (https://github.com/jenkinsci/description-setter-plugin).
${PROJECT_NAME}

Displays the project's full name. (See AbstractProject.getFullDisplayName)
${PROJECT_DISPLAY_NAME}

Displays the project's display name. (See AbstractProject.getDisplayName)
${PROJECT_URL}

Displays a URL to the project's page.
${PROPFILE,file="FILENAME",property="PROPERTYNAME"}

Expands to the value of a property in a property file. The filename is relative to the build workspace root.
${FILE,path="PATH"}

Expands to the contents of a file. The file path is relative to the build workspace root.
${XML,file="FILE",xpath="XPATH"}

Expands to the result(s) of an XPath expression run against the given XML file.
If the XPath evaluates to more than one value, then a semicolon-separated string is returned.
The file path is relative to the build workspace root.
In addition to the tokens, you can modify the result of the token expansion using parameter expansions. They follow similar rules as bash Parameter Expansions. The supported expansions are: ${#TOKEN} which resolves to the length of the expanded token value, ${TOKEN:offset:length} which takes a substring of the token result (length is optional and offset and length can both be negative), ${TOKEN#pattern} which matches the pattern against the start of the expanded token and removes it if it, ${TOKEN%pattern} which matches the pattern against the end of the expanded token and removes it it if matches.