The pipeline steps are actually documented at https://jenkins.io/doc/pipeline/steps/email-ext/, does this fit the requirement of what you are looking for?

Yes, this is useful. I think a link to that page should be provided on the wiki. Perhaps the wiki can automatically link to the Pipeline step description. However, that is not much in terms of documentation. Prospective users need to know more than "function signatures". Some fields are obvious of course, but others deserve more than just a name-type entry. Perhaps the help text from the plugin could also be rendered the doc/pipeline/steps page. This way prospective users can quickly find the features offered in the Pipeline flavor of the plugin (vs. the traditional flavor).

I think this is valid for all plugins, so feel free to modify this Jira and make it more general.

Thank you.

Putting a section on the plugin wiki page would solve only half of the problem. Now the current "documentation" is far from being usable. How about including at least one real-life example in it? The current text opens more questions than it solves.

How do I build the list of emails which I am supposed to put inside the "to" field? I assume that I want to include the person that triggered the build (if it has an email) and all the emails of the changeset authors.

Examples are the best way to document, not function signatures. If you could provide some help around here it would be great. I am sure that once we learn how to use it we will also start to contribute back (or at least me).

Agreed, it seems like much of the email-ext functionality is not available with the pipeline. Templates, triggers, and many of the tokens seem to not work when called from a Pipeline script. Email-ext seems to have pretty good documentation overall, but none of it seems to apply to the limited subset of features available to pipeline.

Better documentation and examples, and even some templates (if they are available in pipeline) would help us understand what is available, where the gaps exist in functionality available to pipeline, and let us know if there are things we can help contribute to bring the email-ext pipeline features up to the same level that freestyle projects have.

Yes, it's very true, much of the functionality is not available, but some of it also doesn't make sense. For instance, triggers don't make sense in pipeline, which is a large part of the normal freestylejob capability. I think the main functionality that needs attention is the token replacement. What other features from freestylejob are you missing?

Tokens are the biggest thing, but they feed into templates. I'm trying to build an Enterprise version of Jenkins, and bringing jobs over from lots of teams had on their own Jenkins servers running under someone's desk somewhere. One of the big goals has been to use Pipeline, and build a DSL to standardize everything. Almost all of the jobs from the other teams are freestyle and most use email-ext and have built elaborate templates in the Email-ext Template plugin. There's nothing in https://jenkins.io/doc/pipeline/steps/email-ext/ which describes how to call a template. Since templates could have different messages, and many other components based on the trigger, this is what was causing me to ask how to "throw" a trigger to the Email-ext plugin in order to select a different portion of a template.

Additionally, (and this may be something that is there I'm just not seeing how to do it with the documentation) how do we include the possible culprits in the emails? This is one of the best features of Email-ext, to include an ever larger and larger group of people in the notifications until the build gets fixed. I didn't know if it is something as simple as including $CULPRITS in the to field, or if there is something that needs to be in the groovy

I'm less concerned about templates, than some of the useful email lists, like Culprits.

I reached this issue by trying to find out about the missing templates support on a pipeline job...

You could get this without email-ext by using getChangeSets on the workflow run (not sure how you get to that part) and looping through the changesets and their entries to retrieve the committer information. Not as nice as a tidy package, but it can be done.

I'm fairly sure there's code for this on Stack Overflow somewhere, but, here's what I'm doing, if it'll help you. Obvious caveats for my primary use case at present is Perforce, I've cribbed this from a helper class I wrote for my own usage, and modified the opening line so you can see where I'm getting the data from. I've removed most comments - most of them say that I'm guessing the behaviour of specific classes or methods. Otherwise I just read the API docs and source code and iterate live in pipeline until I find the data I want.

Edit: To caveat, I am neither an experienced Java or Groovy programmer.

def changeLogSets = currentBuild.rawBuild.changeSets
if (changeLogSets.size() > 0) {
    for (changeLogSet in changeLogSets) {
        // Not everyone implements ChangeLogSet the same way, so check for those we support
        if (changeLogSet.class == org.jenkinsci.plugins.p4.changes.P4ChangeSet) {
            for (changeLog in changeLogSet) {
                def change = [:]
                
                // Common fields
                change.msg = changeLog.msg
                change.msgAnnotated = changeLog.msgAnnotated
                change.msgEscaped = changeLog.msgEscaped
                change.timestamp = changeLog.timestamp
                change.author = changeLog.author
                change.affectedPaths = changeLog.affectedPaths
                
                // Common fields not implemented the same by Perforce
                change.affectedFiles = []
                for (file in changeLog.files) {
                    // This is horrible, but Perforce returns files as FileSpec, while
                    // Jenkins standard for affectedFiles is ChangeLogSet.AffectedFile, 
                    // and neither are compatible, so just return a fully annotated path instead
                    change.affectedFiles.add("${file.toString()} ${file.getAction().toString()}")
                }
                change.commitId = changeLog.id
                change.timestamp = changeLog.date
                
                // Perforce-specific fields (not a complete list)
                change.clientId = changeLog.clientId
                
                m_Changes.add(change)
            }
        }
    }
}

Hello, this works fine for committers, do you have any idea about accessing the culprits list within a pipeline ?

You can look at the source for AbstractBuild on github and it's getCulprits method.

https://issues.jenkins-ci.org/browse/JENKINS-33980?focusedCommentId=255305&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-255305

Alex Earl added a comment - 2016/Apr/21 8:32 PM
Yes, it's very true, much of the functionality is not available, but some of it also doesn't make sense. For instance, triggers don't make sense in pipeline, which is a large part of the normal freestylejob capability. I think the main functionality that needs attention is the token replacement. What other features from freestylejob are you missing?

I found this thread searching for a way to send emails from a pipeline like they can be configured in freestyle projects (I want emails on StateChange and a list of culprits for my pipeline).

I don't want do sound naive, but why don't triggers make any sense in a pipeline project?

In my pipeline (FPGA Hardware-Design) referencing single freestyle projects for every build-configuration is not managable. This is why I really need a pipeline that can be managed via one script.

The reason triggers don't really make sense in a pipeline is because a plugin runs at a particular point in the pipeline not "at the end" so the correct way to implement the triggers in a pipeline is to call the plugin at the various points where you need to do it. for example to send an email on a failed build you could:

try {
   // something that might fail
} catch(e) {
    currentBuild.result = 'FAILURE'
    emailext body: e.toString(), subject: 'it failed :(', to: 'someone@noware.com'
}

Updated the wiki last night

Actual examples are still sparse. I found this excellent blog on feeding email-ext variables: https://jenkins.io/blog/2016/07/18/pipline-notifications/

If build triggers don't make sense then what would be the appropriate way to determine if a job is "aborted", "fixed", etc? I'm following the blog post jwarburton mentions above and can get the basic pass/fail but would like to know more about categorizing my build as one of the triggers that are listed in the default trigger list.

• Aborted
• Always
• Before Build
• Failure - 1st
• Failure - 2nd
• Failure - Any
• Failure - Still
• Failure - X
• Failure -> Unstable (Test Failures)
• Fixed
• Not Built
• Script - After Build
• Script - Before Build
• Status Changed
• Success
• Test Improvement
• Test Regression
• Unstable (Test Failures)
• Unstable (Test Failures) - 1st
• Unstable (Test Failures) - Still
• Unstable (Test Failures)/Failure -> Success

Thanks.