Using Email-ext plugin in Jenkins pipeline

Using Email-ext plugin in Jenkins pipeline need not be scary !! And this post will show how. We will create a step in the JenkinsFile incorporating the email functionality. We will use email-ext groovy template to generate the emails. The email content will have the test run summary and the build artifacts download link. We will also attach the test run logs to the email. What more can you want?

WHY

Email-ext plugin is one of the most popular plugin in Jenkins ecosystem. And it is one of the most tricky one to work with too. Documentation is sparse and samples are hard to come by. And for a non-java background person it is frankly a house of pain. Hopefully this post will help you on getting started with this plugin.
So lets see how to train this dragon.

HOW

First install the Email-ext plugin. There is a default section in the Jenkins->Manage Jenkins->Configure System.
Fill in the needed configuration data.

Email-ext plugin

Since I am working in .NET environment, the I will also install MSTest plugin for publishing the test results. Once that is sorted then start creating the JenkinsFile. Check the sample JenkinsFile below. For the uninitiated this JenkinsFile is the big thing in Jenkins 2. It is essentially the recommended way to store the Jenkins pipeline. You create this file and then check it in the source code repository. Jenkins on doing the code checkout will automatically detect this file and then use it to run the build.

In this example we will use the Email-ext plugin to create an email having:
* Subject line having the information about the build, namely the build name and the status if it is failed or success.
* Contain the code changes which triggered the build.
* Test cases passing or failing, if the build involved running some test cases.
* Pass variables to the Email-ext plugin.

Email-ext plugin can use groovy scripts to create custom mails. This is very powerful since you get access to Jenkins internals. This can allow you to pull out hard to get details about the job and put the same in the email. Email-ext plugin creators have provided two sample templates. We will use the HTML version. Go to the Jenkins home. Create a folder email-templates if it is not there. Put this file there. If you do not have access to this then you might have to ask the administrator of the Jenkins instance to do this for you.

Here is the JenkinsFile.

node('master') 
{   
    try 
    { 
        stage ('Checkout') 
        { 
            deleteDir()
            checkout scm   
        }


        stage ('Compile')
        { 
            //All the compilation steps
        }
        
        stage ('TestRun') 
        {
            //Run all the tests
        }
        
        stage('TestResultpublish')
        { 
            step([$class: 'MSTestPublisher', testResultsFile: 'TestResults/*.trx'])
            zip archive: true, dir: '\\apps\\TestApplication\\bin\\Release', glob: '', zipFile: tagName + '.zip'
    
        }
    } 
    catch (err)
    {
        //Do something
        throw err
    }
    finally
    {
        stage('Email')
        {
            env.ForEmailPlugin = env.WORKSPACE      
            emailext attachmentsPattern: 'TestResults\\*.trx',      
            body: '''${SCRIPT, template="groovy_html.template"}''', 
            subject: currentBuild.currentResult + " : " + env.JOB_NAME, 
            to: 'ironman@starkindustries.com'
        }
    }
}

I will skip the explanation of the different stages and concentrate on the stage for Email-ext plugin. See how I have kept it in finally section so that even when there is some error, email is still sent. Many things are happening.

• Line 24 : We publish the test results of the job using the MSTest plugin for Jenkins.
• Line 25 : This is an optional step. It allows you to attach the build artifacts to the email sent out so that the recipients can download the same. Note that for the zip operator you have to install Pipeline Utility Steps plugin. You pass the path of the Release folder relative to the workspace and the name of the zip file to be created. Here we use the build number. And viola !
• Line 38 : Believe it or not, email-ext plugin does not have access to many of the environment variables we take for granted in Jenkins pipeline. This is the way we send the current workspace location to the template. Later we will see how to access this in the template.
• Line 39 : We pass location and pattern of the files to be attached to the email. In my case it is the mstest and hence the report files are .trx files.
• Line 40 : We set the body of the email. Here we simply specify the template location. The template will do the hard work of populating the email.
• Line 41 : We set the subject of the email. Here we will keep the subject as FAILURE or SUCCESS followed by the JOB_NAME.
• Line 42 : I am sending it to the custom email address.

And that is it. It will work. However there is much you can do in this. Remember how we sent the WORKSPACE as environment variable to the template.
Add this in the template file to get the value.

def envVarValue = envOverrides["WORKSPACE"]

Do not ask me to explain this syntax. I am a .NET guy and looking at this groovy template was painful enough.

And here are the emails you can expect. See how the test file is attached. And the plugin read the tests passing and failing. It has rendered them beautifully. I have edited out the actual details but you can see the possibilities.