Child pages
  • Notification Plugin
Skip to end of metadata
Go to start of metadata

Plugin Information

View Notification on the plugin site for more information.

This plugin from Tikal Knowledge allows sending Job Status notifications in JSON and XML formats.

Job Notifications are defined in job's configuration, in their own separate section "Job Notifications":

Several notification endpoints can be defined. Each endpoint can be configured with:

  • "Format" : notification payload format, JSON or XML.
  • "Protocol": protocol to use for sending notification messages, HTTP, TCP or UDP.
  • "Event": job events that trigger notifications: Job Started, Job Completed, Job Finalized or All Events (the default option). The difference between job being "completed" and "finalized" is as follows: when job is finalized all post-build activities, such as archiving artifacts, were executed as well. This is not the case with job being merely "completed" which usually involves only creation of job's artifacts without post-processing them. If you're unsure of which event to use, you can start with "Job Finalized".
  • "URL": URL to send notifications to. It takes the form of "http://host" for HTTP protocol, and "host:port" for TCP and UDP protocols.
  • "Timeout": Timeout in milliseconds for sending notification request, 30 seconds by default.

Example of notification message (you can use requestb.in and jsonlint.com services to aggregate HTTP requests and validate JSON payload):

{
    "name": "asgard",
    "url": "job/asgard/",
    "build": {
        "full_url": "http://localhost:8080/job/asgard/18/",
        "number": 18,
        "phase": "COMPLETED",
        "status": "SUCCESS",
        "url": "job/asgard/18/",
        "scm": {
            "url": "https://github.com/evgeny-goldin/asgard.git",
            "branch": "origin/master",
            "commit": "c6d86dc654b12425e706bcf951adfe5a8627a517"
        },
        "artifacts": {
            "asgard.war": {
                "archive": "http://localhost:8080/job/asgard/18/artifact/asgard.war"
            },
            "asgard-standalone.jar": {
                "archive": "http://localhost:8080/job/asgard/18/artifact/asgard-standalone.jar",
                "s3": "https://s3-eu-west-1.amazonaws.com/evgenyg-bakery/asgard/asgard-standalone.jar"
            }
        }
    }
}

The payload submitted includes the following information:

  • Job's name and URL.
  • Build's number, full URL, phase, and status.
  • SCM URL, branch and commit (only for Git repositories).
  • Artifacts generated. They need to be archived by "Archive the artifacts" or published to S3 by "Publish artifacts to S3 Bucket" post-build actions. In addition, Jenkins needs to have its URL configured in "Manage Jenkins" => "Configure System" => "Jenkins Location" => "Jenkins URL".

AWS S3 Support

If Jenkins S3 Plugin is installed and artifacts are uploaded to AWS S3 by "Publish artifacts to S3 Bucket" post-build action - the plugin will send their downloadable locations as well.

Note that you need to edit S3 bucket's policy (see example) to make its artifacts directly "downloadable" by anonymous users. Here's one possible policy:

{
    "Version": "2008-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::notification-plugin/*"
        }
    ]
}

15 Comments

  1. It would be extremely useful if the plugin you read the hostname:port or http:// URL from a build parameter (i.e. environment variable), as this would allow a remote job initiator to specify the postback URL/host:port dynamically. Would this be a difficult modification?

  2. I would really love to be able to append some custom data to the notification data. Maybe this could achieved with an optional text field in which I could type some custom data in json-format, the result could be:

    {"name":"JobName",
     ...
     "custom_data":{"foo":1,
                    "bar":"1234"
                   }
    }
    

    What do you think?

    1. Lars, please have a look at "jenkins-notify-plugin" - it allows to provide a configurable Groovy template as a JSON payload. This plugin wasn't officially released as most of its functionality was merged with Notification Plugin. Still, it can be useful in some cases.

  3. For HTTP, could you possible make it send as POST? I tried a php script at the other end of the notification, and i cant seem to work out how to recieve the data.

    1. This is already sending the data via POST.
      To read this information in a PHP-Script, you need to read it from 'php://input'

      $body = file_get_contents('php://input');
      $object = json_decode($body);
      // ...
      
  4. Note that the above sample JSON is not valid. It is missing a comma after the fullurl "full_url":"http://ci.jenkins.org/job/project/5",

    1. Thanks! I just updated a JSON sample.

  5. I just installed the latest version and I don't see Event or Timeout dropdown. Also, it is not sending artifacts in the payload even though I have "Archive the artifacts" and Jenkins URL configured. Any ideas?

  6. I just wanted to test this plugin and do end up with no success. I have temporarily running a webserver on machine and give this URL. The URL should be reachable as I can call it via Web (Server address). The plugin Ends up in timeout.

    My app does take any input per post or get and any structural format like scalar, array or hash. I choosed to get the info as XML.

    Please help.

    Thanks in advance and regards

  7. How can I use this plugin with pipeline type projects? 

    1. Did you manage to figure out how to do this? Thanks!

      1. If you look at https://<jenkins-instance>/job/<pipeline-job>/pipeline-syntax/ you generate a snippet for the Notifications settings. Look for it under the "properties" step to find the settings.

  8. It would be very useful if we could customize the body of the request, we could for example use this plugin with AWS SQS (which requires a number of parameters) to publish build status updates to any number of endpoints. RIght now I am forced to create a Lambda that takes in a simple http request and build a request from the lambda to SNS 

  9. It would be more useful if the following features add:

    • Elapsed-time (on Finalized-events)
    • User who run the job (if exists)

    Many thanks in advance.

Write a comment…