anchor.diff:  [[email-ext-plugin]]
  -= email-ext-plugin
  += Email Extension Plugin
   :toc: macro
   :toc-title:
   ifdef::env-github[]
  
positive.code: GroovyObject jiveFormatter = (GroovyObject) groovyClass.newInstance();
  ----
  
  === Plugins
  
  * https://plugins.jenkins.io/email-ext-recipients-column/[Email Ext Recipients Column Plugin]
  * https://plugins.jenkins.io/job-direct-mail/[Job Direct Mail Plugin]
  * https://plugins.jenkins.io/pom2config/[Pom2Config Plugin]
  * https://plugins.jenkins.io/github-pullrequest/[GitHub Integration Plugin]
  * https://plugins.jenkins.io/emailext-template/[Email-ext Template Plugin]
  * https://plugins.jenkins.io/configurationslicing/[Configuration Slicing Plugin]
  * https://plugins.jenkins.io/view-job-filters/[View Job Filters]
  * https://plugins.jenkins.io/run-condition-extras/[Run Condition Extras Plugin]
  
  == Contributing
  
  Refer to our https://github.com/jenkinsci/.github/blob/master/CONTRIBUTING.md[contribution guidelines].
  
  Make sure you have installed http://maven.apache.org/[Maven 3] 
  and JDK 8.0 or later. Make also sure you have properly configured your
  `~/.m2/settings.xml` as explained in the https://jenkins.io/doc/developer/tutorial/[Plugin Tutorial].
  Those are needed to build properly any Jenkins plugin.
  
  === Check out and build
  
  How to check out the source and build:
  
  [source,sh]
  ----
  git clone git@github.com:jenkinsci/email-ext-plugin.git
  cd email-ext-plugin
  mvn clean install
  ----
  
  == Version History
  
  Please refer to xref:CHANGELOG.adoc[the changelog].
  
negative.code: build.logFile.text.readLines().any { it =~ /.*ERROR.*/ }
  ----
  
  === Tokens
  
  This plugin uses *tokens* to allow dynamic data to be inserted into
  recipient list, subject line, or body. A *token* is a string that starts
  with a `$` (dollar sign) and is terminated by whitespace. When an email
  is triggered, a token in the subject or content fields will be replaced
  dynamically by the actual value that it represents. Also, the value of a
  token can contain other tokens that will themselves be replaced by
  actual content. For instance, the `$DEFAULT_SUBJECT` token is replaced
  by the text (and other tokens) that is in the *Default Subject* field
  from the *Extended E-mail Notification* section of the *Configure
  System* page. Similarly, the `$PROJECT_DEFAULT_SUBJECT` token will be
  replaced by the value of the *Default Subject* field from the project
  configuration page.
  
  This plugin sets the email content fields with default values when you
  enable it for your project. The *Default Subject* and *Default Content*
  fields on the project configuration page default to `$DEFAULT_SUBJECT`
  and `$DEFAULT_CONTENT` (respectively), delegating to the the system-wide
  configuration from the *Extended E-mail Notification* section of the
  *Configure System* page. Similarly, the per-trigger content fields
  default to `$PROJECT_DEFAULT_SUBJECT` and `$PROJECT_DEFAULT_CONTENT`,
  delegating to the project's configuration. Since the value of a token
  can contain other tokens, this provides different points of
  configuration that can allow you to quickly make changes at the broadest
  level (all projects), the narrowest level (individual emails), and
  in-between (individual projects).
  
  To see a list of all available email tokens and what they display, click
  on the "?" (question mark) associated with the *Content Token Reference*
  in the *Editable Email Notification* section of the project
  configuration page.
  
  As of version 2.22, this plugin also supports tokens provided by the
  https://plugins.jenkins.io/token-macro/[Token Macro plugin]. You can see
  the available *Token Macro Plugin Tokens* below the *Extended Email
  Publisher Specific Tokens* when you click on the "?" (question mark)
  associated with the *Content Token Reference* in the *Editable Email
  Notification* section of the project configuration page.
  
  === Jelly script content templates
  
  image::docs/images/html.jpg[]
  
  image::docs/images/txt.jpg[]
  
  New to version 2.9 is the ability to use Jelly scripts. Jelly scripts
  are powerful in that you can hook into the Jenkins API to get any
  information you want or need. There are two Jelly scripts packaged with
  this plugin, and it is also possible to write your own.
  
  There are two default Jelly scripts available out of the box; one is
  designed for HTML emails and the other is designed for text emails. See
  the screenshots below for what these templates look like. You can
  specify which script you want by using the `template` argument. The
  usage for each type of script is as follows:
  
  * Text only Jelly script: `${JELLY_SCRIPT,template="text"}`
  * HTML Jelly script: `${JELLY_SCRIPT,template="html"}`
  
  You can also write your own Jelly scripts. The Jelly scripts are
  particularly powerful since they provide a hook into the Jenkins API,
  including
  https://javadoc.jenkins-ci.org/hudson/model/AbstractBuild.html[`hudson.model.AbstractBuild`]
  and
  https://javadoc.jenkins-ci.org/hudson/model/AbstractProject.html[`hudson.model.AbstractProject`].
  For example on how to do this, take a look at the existing
  https://github.com/jenkinsci/email-ext-plugin/blob/master/src/main/resources/hudson/plugins/emailext/templates/html.jelly[`html`]
  and
  https://github.com/jenkinsci/email-ext-plugin/blob/master/src/main/resources/hudson/plugins/emailext/templates/text.jelly[`text`]
  scripts.
  
  Using custom Jelly scripts (those not packaged with this plugin)
  requires the cooperation of your Jenkins administrator. The steps are
  relatively simple:
  
  . Create the Jelly script template. The name of the script should be
  `<name>.jelly`. It is important that the name ends in `.jelly`.
  . Have your Jenkins administrator place the script inside
  `${JENKINS_HOME}/email-templates/`.
  . Use the `$JELLY_SCRIPT` token with the `template` parameter equal to
  your script filename without the `.jelly` extension. For example, if the
  script filename is `foobar.jelly`, the email content would be
  `${JELLY_SCRIPT,template="foobar"}`.
  
  Jelly script tips:
  
  * You can get the object of other plugin actions by querying build
  actions like:
  `${it.getAction('hudson.plugins.fitnesse.FitnesseResultsAction')}`
  * Then you need to know what all functions are allowed by this action
  object and traverse through result.
  
  === Groovy script content templates
  
  New to version 2.15 is the ability to use Groovy scripts. Scripts are
  powerful in that you can hook into the Jenkins API to get any
  information you want or need. There are two scripts with corresponding
  templates packaged with this plugin, and it is also possible to write
  your own.
  
  There are two default scripts and templates available out of the box;
  one is designed for HTML emails and the other is design for text emails.
  You can specify which script you want by using the `script` argument;
  you can also leave the default script and specify a different template
  file using the `template` argument. Furthermore, you can also include a
  script that does some initialization using the `init` argument. The
  usage for each type of script is as follows:
  
  * Text only Groovy script: `${SCRIPT, template="groovy-text.template"}`
  * HTML Groovy script: `${SCRIPT, template="groovy-html.template"}`
  
  You can also write your own scripts and templates. The scripts are
  particularly powerful since they provide a hook into the Jenkins API,
  including
  https://javadoc.jenkins-ci.org/hudson/model/AbstractBuild.html[`hudson.model.AbstractBuild`]
  and
  https://javadoc.jenkins-ci.org/hudson/model/AbstractProject.html[`hudson.model.AbstractProject`].
  For example on how to do this, take a look at the existing
  https://github.com/jenkinsci/email-ext-plugin/blob/master/src/main/resources/hudson/plugins/emailext/templates/groovy-html.template[`html`]
  and
  https://github.com/jenkinsci/email-ext-plugin/blob/master/src/main/resources/hudson/plugins/emailext/templates/groovy-text.template[`text`]
  scripts.
  
  Using custom scripts (those not packaged with this plugin) requires the
  cooperation of your Jenkins administrator. The steps are relatively
  simple:
  
  . Create the Groovy script template. The name of the script ends in the
  standard extension for the language (i.e., `.groovy`). The template can
  be named anything.
  . Have your Jenkins administrator place the script inside
  `${JENKINS_HOME}/email-templates/`.
  . Use the `$SCRIPT` token with the template parameter equal to your
  template filename, or in addition the script parameter equal to the
  custom script name. For example, if the template filename is
  `foobar.template`, the email content would be
  `${SCRIPT, template="foobar.template"}`.
  
  Refer to the following examples for doing various things with the
  built-in Groovy templates:
  
  * link:/docs/templates/jenkins-matrix-email-html.template[`jenkins-matrix-email-html.template`]
  * link:/docs/templates/jenkins-generic-matrix-email-html.template[`jenkins-generic-matrix-email-html.template`]
  
  === Attachments
  
  New to version 2.15 is the ability to add attachments using
  https://ant.apache.org/manual/Types/fileset.html[the Ant pattern
  matching syntax] used in many places in Jenkins. You can set a maximum
  total attachment size in the *Extended E-mail Notification* section of
  the *Configure System* page; otherwise, it will be unlimited.
  
  === Jive Formatter
  
  link:/docs/templates/jive-formatter.groovy[`jive-formatter.groovy`]
  contains methods for easy and convenient formatting of emails being sent
  from Jenkins to Jive. It should be called from the *Pre-send Script*
  area. Also, it doesn't seem like Jive supports text with multiple
  formats, so only call one formatting method per block of text.
  
  Either `formatLine` or `formatText` can and should be called on every
  line of text that will be sent to the Jive system prior to calling
  formatting methods like color or size. Please test on your own instances
  of Jive and add functionality as you find it!
  
  The following lines should be added to the *Pre-send Script* area prior
  to attempting to invoke any functions:
  
  [source,groovy]
  ----
  