Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Office 365 Connector on the plugin site for more information.

This plugin from Microsoft Corp. allows sending running Jobs status notifications.

Description

Plugin is used to send actionable messages in Outlook, Office 365 Groups, and Microsoft Teams.

Read more about it

Once the Office 365 Connector plugin is installed, webhooks for notifications are defined in Job Notification section of the configuration of job. Here is the screenshot for that section
Here are the steps to configure a webhook

  • Click on the "Add Webhook" button.
  • Enter the webhook URL which is displayed when you create JenkinsCI connector in Office365.
  • Check the boxes for which you want to receive notifications.
  • Configure the timeout after which jenkins plugin would give on unavailable server.

Once you configure this plugin, build related messages will appear in the workplace messaging system.

To send messages from inside pipeline script:

  • Configure the webhook you want to send message following the steps mentioned above.
  • In the Pipeline script use the following command:
    office365ConnectorSend message: "<Your message>", status:"<Build status>"

To send message from inside Jenkinsfile:

  • In the script use the following command:
    office365ConnectorSend message: "<Your message>", status:"<Build status>", webhookUrl:'<The connector webhook url>'

Requirements

This plugin is created to work with Office 365 Groups.

Release 4.5

  1. Added more logging and modified title of card to display branch name as well.

Release 4.4

  1. Added support for macros that allow to define when the connection is triggered. User can define additional conditions that must be met to trigger the notification. For example having generic build that builds many envs it is possible to get notification only for one (eg based on build params).
  2. Allow additional parameter of "color" to be passed to office365ConnectorSend. This will allow specifying the HEX color code of the card used to display when the 'message' attribute is set.

    Example: office365ConnectorSend message: "My Message", status: "FAILURE", webhookUrl: "https://....", color: "d00000"

Release 3.0

  1. Allow webhook parameter to be expanded, so for a build you can define your webhook as $webhook and have the the ability to expand the $webhook value to an actual URL either by environment variables, build variables, build parameters and etc.
  2. Fix job name with slashes. Main cause branch names ie. feature/abc
  3. Add support for started card and completed card for pipeline.

    office365ConnectorSend status: "Started", webhookUrl: "${env.HOOK}"
    For messages
    office365ConnectorSend message: "Hello world", webhookUrl: "${env.HOOK}"

  4. Made webhookUrl as new default.

  5. Add the colors to the cards.
    See the effect in these screenshots:

    image
    image
    image

Release 2.5

  1. When selected notification type as "Failure", then notification is sent only when previous build is success and current build failed. No notification would be sent for repeated failure. If user wants to receive notification for repeated failure, then he/she should select "Repeated Failure" notification type.
  2. Details about test cases and developers would be displayed in the card only if those details are availble, else they would not be displayed.

Release 2.4.1

  1. Removed unwanted logging on the console.

Release 2.4

  1. Removed Build Start Time from the office365ConnectorSend message card.

Release 2.3

  1. Added support to set "Status" of the card from office365ConnectorSend command.
  2. Added facts culprits and developers when the build is triggered due to SCM commit.

Release 2.2

  1. Added support to send notification from inside Jenkinsfile. 
  2. Added option webhookUrl for the office365ConnectorSend command.

Release 2.1

  1. Fixed Back To Normal Time showing some invalid time issue.

Release 2.0

  1. Added support to send notification from inside the pipeline script. The user can use office365ConnectorSend command to send any notification.

Release 1.4

  1. Included author name and number of files changed if the build is due to SCM change.

Release 1.3.3

  1. Tracks UNSTABLE to SUCCESS build status changes with Notify Back To Normal event.

Release 1.3

  1. Supports notification for pipeline jobs.

Release 1.2.1

  1. Initial version.

19 Comments

  1. Unknown User (jessejacob)

    I'm going to open an issue to see if you'd consider aligning this more closely with Jenkins status changes in other plugins, e.g. email-ext (https://wiki.jenkins-ci.org/display/JENKINS/Email-ext+plugin), which treats the status changes

    • unstable -> success
    • failure -> success

    The same way with the "fixed" trigger. I'm not arguing to add another trigger condition to your plugin, but to including unstable -> success status changes to the "Notify Back To Normal" event. Currently only failure -> success causes "Notify Back To Normal", which doesn't align well with our use case. When developers generate unstable builds from checking in failing tests or adding code analysis errors, we'd like to know when they've fixed it. If this was done we could rely more on this plugin to post messages to our collaboration systems instead of using email, which we'd love to do.

    1. Unknown User (jessejacob)

      Addressed in 1.3.3. Thanks!

  2. Unknown User (jessejacob)

    I'm going to open an issue to see if you'd consider posting more detail for builds triggered by SCM change. Other plugins like email-ext allow you to list committers/culprits individually in email messages. I don't know if the connector doesn't provide this level of detail in the webhook message or if my target MS Teams connector is deciding not to render it, so please close the issue if I need to talk to the MS Teams group on uservoice. Currently the only data I see is "Remarks: Started by an SCM Change". If the build is started by a user action, their name is listed there, but never when it's an SCM change.

  3. Unknown User (sham126)

    In case anyone is wondering how to write this up in DSL you'll need to use configure blocks to manipulate XMLs and then just run through the DSL playground to verify XML structure: http://job-dsl.herokuapp.com/:

    configure { root ->
           root / 'properties' / 'jenkins.plugins.office365connector.WebhookJobProperty' (plugin:'Office-365-Connector@2.4.2') / 'webhooks' / 'jenkins.plugins.office365connector.Webhook' {
                 url ''
                 startNotification true
                 notifySuccess true
                 notifyAborted false
                 notifyNotBuilt false
                 notifyUnstable false
                 notifyFailure true
                 notifyBackToNormal false
                 notifyRepeatedFailure false
                 timeout '30000'
                 }
    }

    1. Unknown User (xlstefan)

      Thank you for this!

  4. Unknown User (jmccormick)

    What is an appropriate way to debug issues? I have configured a free style job according to the provided instructions. Exactly one message was posted to my Team channel. Nothing else will go through, and there is nothing in the logs indicating failure.

  5. Unknown User (a_zen)

    You can use the properties step inside your Jenkins pipeline.

     

  6. Unknown User (a_zen)

    The screenshot is from the Jenkins pipeline step generator.

  7. Unknown User (dhirendrarahtod)

    Having 2 underscroll in the job name converts the post title to italics and removes the underscrolls from the job name.

    I have tried this with jenkins config in the .jenkinsfile and i have also tried with the config on the job itself.

  8. Unknown User (thecrumb)

    Could the name that is defined in the webhook config be passed into the message?  

    It appears the text used in Teams is pulled from the test name/displayname.

    What happens is my jenkins display name is defined and I cannot change it - so that's gets sent into Teams - but I'd like to add some additional info into the message to better identify where the message was coming from...

    So...
    Update from  DISPLAY NAME IN JENKINS

    latest status of build #123

    Some additional info passed in via Jenkinsfile for default webhook 

    office365ConnectorWebhooks([[
            name: 'Some additional info on my test that I'd like to see in the message in teams,
            url: 'https://foobar'
        ]]),


  9. Unknown User (joerattz)

    Can someone tell me how to call the office365ConnectorSend command from a Windows batch command added to a Jenkins Freestyle project?

    Ultimately I would like for the message sent to MS Teams to include the git commit messages since the last build so if there is an easier way to do it, that would be appreciated.

    I'm assuming though that I will need to manually send a message myself with the text of the commits.

    So I have this entered in a Windows batch command build step.  I understand that I haven't done anything to actually capture the git commit messages yet.  I'll do that once I have the communication to MS Teams working.

    office365ConnectorSend message: "started ${env.JOB_NAME} ${env.BUILD_NUMBER} commited by @${user} [View on Jenkins](${env.BUILD_URL})", webhookUrl: url


    That causes this error:

    C:\Program Files (x86)\Jenkins\workspace\DCGuru\Build DCGuru>office365ConnectorSend message: "started ${env.JOB_NAME} ${env.BUILD_NUMBER} commited by @${user} [View on Jenkins](${env.BUILD_URL})", webhookUrl: url 
    'office365ConnectorSend' is not recognized as an internal or external command,
    operable program or batch file.
    
    C:\Program Files (x86)\Jenkins\workspace\DCGuru\Build DCGuru>exit 9009 
    Build step 'Execute Windows batch command' marked build as failure
    [Office365connector] Matched status 'FAILURE' for webhook 'DCGuru - Build'.
    Finished: FAILURE


    Any help would be appreciated.

  10. Unknown User (jmccormick)

    Unknown User (joerattz) You are over complicating it, the plugin will handle the change log messages. Just configure the web hook and then select when you want the notices sent in the Freestyle project configuration (first image on this page). The plugin should handle the change log. The command-line syntax is only for Pipeline builds where you are entering commands into a Script file.

    1. Unknown User (joerattz)

      Unknown User (jmccormick) I'm not getting git commit messages in my MS Teams messages; neither the Started message nor the Build Success message:


      I see four screenshots of MS Teams messages in the documentation above and none of them include git commit messages either.  What am I missing?

      Also, just FYI, I have all the checkboxes checked in that first image on the page in case that matters.


      Thanks.

      1. Unknown User (jmccormick)

        Unknown User (joerattz) Sorry I must have been mistaken. I just looked at our pipeline script and we had to build the change log message manually. Looking at Office365ConnectorWebhookNotifier.addScmDetails, it is only looking through the change set for authors and numbers of files modified. If you are willing, you could always patch that support in yourself. Otherwise it may be a good time to investigate moving to a pipeline build. 

        1. Unknown User (joerattz)

          Thanks for the ideas!

  11. Unknown User (iwiwiwi)

    Can anybody give an example of Macro: Template and Value?


    I wish to add a condition like:

    Template: thisBuildStatus.equals(previousBuildStatus)

    Value: False


    So it could send notification on change of the status. It is not clear to me, how should that look. I will be grateful for your help.

  12. Unknown User (samica)

    Hi, I've installed this plugin on the Jenkins side and I'm already sending notifications to teams successfully.

    This is very useful to the team, however, the text format in the "message" field is showing differently than what I was expecting. 

    For example if a string "Bla_bla_Bla" appears in the message, teams will show "BlablaBla" instead.

    I was investigating and the plugin seems to be enabling "textformat = markdown" by default.


    We would like to get the plain message. Our messages are dynamically constructed based on variables and macros in groovy, so its not convenient to be escaping all the special characters. Can someone let me know how to force the message to be sent in "plain" format?

  13. Unknown User (citylife4)

    Hi Frederico,

    You can wrap your "message:" with a html <pre> tag to remove the makdowns text format on teams!

    Refer to this link for more info: https://github.com/jenkinsci/office-365-connector-plugin/pull/122

  14. Unknown User (hpatel)

    This plugin is neat. However, I wish that the plugin let users insert JSON that microsoft webhooks allow.