Version: 1.0.1
Rundeck DIY Webhook Notification
Trevor Highfill

Rundeck notification plugin for the DIYer, because it allows you to supply your own custom messages to be sent to a webhook.

rundeck-diy-webhook-notification

Build Status

Rundeck notification plugin for the DIYer, because it allows you to supply your own custom messages to be sent to a webhook.

Installation

  1. Download the plugin file
wget "https://github.com/theque5t/rundeck-diy-webhook-notification/releases/download/v1.0.1/rundeck-diy-webhook-notification-1.0.1.jar"
  1. Put the plugin file, rundeck-diy-webhook-notification-1.0.1.jar, into the plugin directory
mv rundeck-diy-webhook-notification-1.0.1.jar /var/lib/rundeck/libext
  1. The plugin is now ready for use

Usage

Provider Name: DIYWebhookNotificationPlugin

Plugin Properties:

  • Webhook URL: The webhook url. Example: https://hostname/services/TXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX
    configure project: project.plugin.Notification.DIYWebhookNotificationPlugin.webhookUrl=value
    configure framework: framework.plugin.Notification.DIYWebhookNotificationPlugin.webhookUrl=value

  • Content Type: The content type header. Example: application/json
    configure project: project.plugin.Notification.DIYWebhookNotificationPlugin.contentType=value
    configure framework: framework.plugin.Notification.DIYWebhookNotificationPlugin.contentType=value

  • Message Body: The message body. Example: {"text":"Hello world!"}
    configure project: project.plugin.Notification.DIYWebhookNotificationPlugin.messageBody=value
    configure framework: framework.plugin.Notification.DIYWebhookNotificationPlugin.messageBody=value

picture

Building the Message

The execution order and summary of what occurs when building the final message body is as follows:

  1. Any embedded property references will be replaced with the runtime value.
  2. Any execution data references will be replaced with the runtime value.
  3. Any template markup will be rendered.

Embedded Property References

You can add embedded property references to your message following this syntax: ${group.key}

Example for "On Start":

{"text":"Job ${job.name}(#${job.execid}): Started"}
${job.name} and ${job.execid} from the above example are embedded property references

Execution Data References

You can add execution data references to your message following this syntax: $map.key$

Examples:

{"text":"Job ${job.name}(#${job.execid}): $execution.status$"}
$execution.status$ from the above example is an execution data reference
{"text":"Job ${job.name}(#$execution.id$): $execution.status$"}
$execution.id$ and $execution.status$ from the above example are execution data references
{"text":"Job ${job.name}(#${job.execid}) from Group $execution.context.job.group$: $execution.status$"}
$execution.context.job.group$ and $execution.status$ from the above example are execution data references

Refer here and here to see what data is available. You can also supply a reference that equals an entire map. For example:

{"text":"Job: ${job.name}
Id: $execution.job.id$
Status: $execution.status$
Job Details: $execution.job$"}
$execution.job$ from the above example points to the job map

Template Markup

You can add template markup following the template language syntax.

Example:

{"text":"Job ${job.name}(#${job.execid}): {{ "$execution.status$" | capitalize }}"}
{{ "$execution.status$" | capitalize }} from the above example is template markup

Refer to the documentation for designers for further assistance with the template language.

Slack Example 1

Notification: On Start, On Success, On Failure

Webhook URL: https://hooks.slack.com/services/TXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX

Content Type: application/json

Message Body:

{
        "username": "Rundeck",
        "icon_url": "https://github.com/rundeck/rundeck/blob/49ae04af6e31d5b1bb1c8bba4bb284ff9739327b/rundeckapp/grails-app/assets/images/logos/rundeck-red-chevron.png?raw=true",
        "channel": "#test",
        "attachments": [
          {
            "fallback":"*$execution.job.name$* (<$execution.href$|#$execution.id$>) {% assign status = "$execution.status$" | capitalize | prepend: "*" | append: "*" %}{% if status == '*Running*' %}{{ status | append: " :warning:" }}{% elsif status == '*Succeeded*' %}{{ status | append: " :heavy_check_mark:" }}{% else %}{{ status | append: " :heavy_multiplication_x:" }}{% endif %}",
            "pretext":"*$execution.job.name$* (<$execution.href$|#$execution.id$>) {% assign status = "$execution.status$" | capitalize | prepend: "*" | append: "*" %}{% if status == '*Running*' %}{{ status | append: " :warning:" }}{% elsif status == '*Succeeded*' %}{{ status | append: " :heavy_check_mark:" }}{% else %}{{ status | append: " :heavy_multiplication_x:" }}{% endif %}",
            "color":"{% if status == '*Running*' %}warning{% elsif status == '*Succeeded*' %}good{% else %}danger{% endif %}",
            "fields":[
          {
            "title":"Job Name",
            "value":"<$execution.job.href$|$execution.job.name$>",
            "short":true
          },
          {
            "title":"Project",
            "value":"$job.project$",
            "short":true
          },
          {
            "title":"Execution ID",
            "value":"<$execution.href$|#$execution.id$>",
            "short":true
          },
          {
            "title":"Started By",
            "value":"{% assign user = "$execution.user$" %}{% if user == 'admin' %}<@XX00XXX0X>{% else %}{{ user }}{% endif %}",
            "short":true
          }{% assign optionMap = "$execution.context.option$" %}{% if optionMap == '{}' %}{% else %},
          {
            "title":"Options",
            "value":"{% assign lengthMinusTwo = optionMap | size | minus: 2 %}{% assign options = optionMap | slice: 1, lengthMinusTwo %}{% assign options = options | split: ", " | reverse %}{% for option in options %} •  {{ option | replace_first: '=', ': `' }}`\n{% endfor %}",
            "short":true
          }
          {% endif %}
        ]
      }
    ]
}

Linking to the Slack user: "value":"{% assign user = "$execution.user$" %}{% if user == 'admin' %}<@XX00XXX0X>{% else %}{{ user }}{% endif %}" from the above example is template markup that replaces the Rundeck user value with the correlating Slack member ID. The Slack member ID can be found on their Slack profile. This shows how you can link the job notifications to the Rundeck user's Slack account.

picture

Slack Example 2

This example makes use of Slack's new Block Kit UI framework

Notification: On Start

Webhook URL: https://hooks.slack.com/services/TXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX

Content Type: application/json

Message Body:

{
  "username": "Rundeck",
  "icon_url": "https://github.com/rundeck/rundeck/blob/49ae04af6e31d5b1bb1c8bba4bb284ff9739327b/rundeckapp/grails-app/assets/images/logos/rundeck-red-chevron.png?raw=true",
  "channel": "#test",
  "text": "{% assign status = "$execution.status$" %}$execution.job.name$ (#$execution.id$) {% if status == 'running' %}{{ status | append: " :arrow_forward:" }}{% elsif status == 'succeeded' %}{{ status | append: " :white_check_mark:" }}{% else %}{{ status | append: " :no_entry:" }}{% endif %}",
  "blocks":
  [
    {
      "type": "divider"
    },
    {
      "type": "context",
      "elements":
      [
        {
          "type": "mrkdwn",
          "text": ":rundeck-project: $job.project$ :rundeck-group: {{ "$job.group$" | split: '/' | join: ' / ' }}"
        }
      ]
    },
    {
      "type": "section",
      "text":
      {
        "type": "mrkdwn",
        "text": "{% if status == 'running' %}{{ ":rundeck-job-running:" }}{% elsif status == 'succeeded' %}{{ ":rundeck-job-succeeded:" }}{% else %}{{ " :rundeck-job-failed:" }}{% endif %} <$execution.job.href$|$execution.job.name$> (<$execution.href$#output|#$execution.id$>)"
      }
    },
    {
      "type": "section",
      "fields":
      [
        {
          "type": "mrkdwn",
          "text": "*Options:*\n{% assign optionMap = '$execution.context.option$' %}{% if optionMap == '{}' %}{% else %}{% assign lengthMinusTwo = optionMap | size | minus: 2 %}{% assign options = optionMap | slice: 1, lengthMinusTwo %}{% assign options = options | split: ", " | reverse %}{% for option in options %} \u2022  {{ option | replace_first: '=', ': `' }}`\n{% endfor %}{% endif %}"
        },
        {
          "type": "mrkdwn",
          "text": "*Nodes:*\n{% assign nodes = "${job.filter}" %}{% assign nodes = nodes | split: "," %}{% for node in nodes %} \u2022  {{ node }}\n{% endfor %}"
        }
      ]
    },
    {
      "type": "context",
      "elements":
      [
        {
          "type": "mrkdwn",
          "text": "Started by: {% assign user = "$execution.user$" %}{% if user == 'admin' %}<@XX00XXX0X>{% else %}{{ user }}{% endif %}"
        }
      ]
    },
    {
      "type": "divider"
    }
  ]
}

Notification: On Success, On Failure

Webhook URL: https://hooks.slack.com/services/TXXXXXXXX/XXXXXXXXX/XXXXXXXXXXXXXXXXXXXXXXXX

Content Type: application/json

Message Body:

{
  "username": "Rundeck",
  "icon_url": "https://github.com/rundeck/rundeck/blob/49ae04af6e31d5b1bb1c8bba4bb284ff9739327b/rundeckapp/grails-app/assets/images/logos/rundeck-red-chevron.png?raw=true",
  "channel": "#test",
  "text": "{% assign status = "$execution.status$" %}$execution.job.name$ (#$execution.id$) {% if status == 'running' %}{{ status | append: " :arrow_forward:" }}{% elsif status == 'succeeded' %}{{ status | append: " :white_check_mark:" }}{% else %}{{ status | append: " :no_entry:" }}{% endif %}",
  "blocks":
  [
    {
      "type": "section",
      "text":
      {
        "type": "mrkdwn",
        "text": "{% if status == 'running' %}{{ ":rundeck-job-running:" }}{% elsif status == 'succeeded' %}{{ ":rundeck-job-succeeded:" }}{% else %}{{ " :rundeck-job-failed:" }}{% endif %} <$execution.job.href$|$execution.job.name$> (<$execution.href$#output|#$execution.id$>)"
      }
    }
  ]
}

Slack Emojis: The example above utilizes custom Slack emojis that were added to the Slack workspace. Because they're emoji's, additional context about the data within the notification can be seen by hovering the mouse over the emoji. In the image below, the mouse is hovering over folder icon, which then tells the user the data to the right is actually the "Rundeck group."

picture

Acknowledgements

rundeck-diy-webhook-notification makes use of the open source projects listed on the index.md in the build/reports/dependency-license directory. Click here to be automatically redirected to the index.md.