Summary

By default jenkins sends email notifications when a job is failing, unstable or back to normal. The purpose of this document is to describe how to configure the email-ext plugin and jenkins to replace the standard email notification system and send notifications only on status change (i.e when a job starts failing or is back to normal)

Configure Jenkins

The standard plugin is too limited to configure the conditions that should cause an email notification to be send.

The plugin email-ext (available from https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin) allows the job admin to configure every aspect of email notifications. He can customize when an email is sent, who should receive it, and what the email says.

I won't describe the general configuration of the plugin as it is already well described in the plugin documentatition and will focus on jenkins.

Configuration Steps

• Start by installing the plugin email-ext following instructions at https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin

• Go to the job's configuration page your want to setup.
• Scroll down to the section "Post-build Actions"
• Disable "E-mail Notification" if it is already checked
• Enable "Editable Email Notification"
• Add triggers for 'Fixed' and 'First Failure' and configure the other fields as you like.

The screenshot below shows an example of configuration

Full example

This configuration setup a job that fails randomly 66% of the time with email notification setup to send email only on status change.

<?xml version='1.0' encoding='UTF-8'?>
<project>
  <actions/>
  <description>&lt;h3&gt;Example of usage of the email notification plugin.&lt;/h3&gt;&#xd;
&lt;p&gt;&#xd;
&lt;ul&gt;&#xd;
&lt;li&gt;Blueprint: https://blueprints.launchpad.net/ubuntu/+spec/desktop-q-desktop-quality&lt;/li&gt;&#xd;
&lt;li&gt;WorkItem: [jibel] send a notification on &quot;job status change&quot; (i.e when a test starts failing) &lt;/li&gt;&#xd;
&lt;/ul&gt;&#xd;
&lt;/p&gt;&#xd;
&#xd;
&lt;p&gt;&#xd;
This job fails randomly and sends a notification only on state change and won&apos;t send a notification on every failure.&#xd;
&lt;/p&gt;&#xd;
</description>
  <logRotator>
    <daysToKeep>-1</daysToKeep>
    <numToKeep>50</numToKeep>
    <artifactDaysToKeep>-1</artifactDaysToKeep>
    <artifactNumToKeep>-1</artifactNumToKeep>
  </logRotator>
  <keepDependencies>false</keepDependencies>
  <properties>
    <hudson.queueSorter.PrioritySorterJobProperty>
      <priority>100</priority>
    </hudson.queueSorter.PrioritySorterJobProperty>
    <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
      <maxConcurrentPerNode>0</maxConcurrentPerNode>
      <maxConcurrentTotal>0</maxConcurrentTotal>
      <throttleEnabled>false</throttleEnabled>
      <throttleOption>project</throttleOption>
    </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
  </properties>
  <scm class="hudson.scm.NullSCM"/>
  <canRoam>true</canRoam>
  <disabled>false</disabled>
  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>
  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>
  <triggers class="vector">
    <hudson.triggers.TimerTrigger>
      <spec>*/15 * * * *</spec>
    </hudson.triggers.TimerTrigger>
  </triggers>
  <concurrentBuild>false</concurrentBuild>
  <builders>
    <hudson.tasks.Shell>
      <command>#!/bin/bash
#
# $RANDOM generate a random value between 0 and 32768
# The average pass rate of this script is 33%
#

value=$RANDOM
limit=$(( 32767 * 2 / 3 ))

echo &quot;random=$value&quot;

if [ $value -gt $limit ]; then
    echo &quot;Test passed: $value &gt; $limit&quot;
    exit 0
else
    echo &quot;Test failed: $value &lt; $limit&quot;
    exit 1
fi
</command>
    </hudson.tasks.Shell>
  </builders>
  <publishers>
    <hudson.plugins.emailext.ExtendedEmailPublisher>
      <recipientList>jean-baptiste@canonical.com</recipientList>
      <configuredTriggers>
        <hudson.plugins.emailext.plugins.trigger.FirstFailureTrigger>
          <email>
            <recipientList></recipientList>
            <subject>$PROJECT_DEFAULT_SUBJECT</subject>
            <body>$PROJECT_DEFAULT_CONTENT</body>
            <sendToDevelopers>false</sendToDevelopers>
            <sendToRequester>false</sendToRequester>
            <includeCulprits>false</includeCulprits>
            <sendToRecipientList>true</sendToRecipientList>
          </email>
        </hudson.plugins.emailext.plugins.trigger.FirstFailureTrigger>
        <hudson.plugins.emailext.plugins.trigger.FixedTrigger>
          <email>
            <recipientList></recipientList>
            <subject>$PROJECT_DEFAULT_SUBJECT</subject>
            <body>$PROJECT_DEFAULT_CONTENT</body>
            <sendToDevelopers>false</sendToDevelopers>
            <sendToRequester>false</sendToRequester>
            <includeCulprits>false</includeCulprits>
            <sendToRecipientList>true</sendToRecipientList>
          </email>
        </hudson.plugins.emailext.plugins.trigger.FixedTrigger>
      </configuredTriggers>
      <contentType>default</contentType>
      <defaultSubject>Test Status change notification</defaultSubject>
      <defaultContent>Example of usage of the email notification plugin.

Jenkins Job: http://jenkins.local:8080/job/example-statuschange/
Blueprint: https://blueprints.launchpad.net/ubuntu/+spec/desktop-q-desktop-quality
WorkItem: [jibel] send a notification on &quot;job status change&quot; (i.e when a test starts failing)

This job fails randomly and sends a notification only on state change and won&apos;t send a notification on every failure.
</defaultContent>
      <attachmentsPattern></attachmentsPattern>
    </hudson.plugins.emailext.ExtendedEmailPublisher>
  </publishers>
  <buildWrappers/>
</project>