HipChat example for custom alert actions

The HipChat example implements an alert action that does the following:

• Posts a message to a HipChat room.
• Writes log messages to a Splunk Enterprise log file.

When a user selects the HipChat alert actions, the user can select from various actions that are available.

Python file for the HipChat Example

This script has been made cross-compatible with Python 2 and Python 3 using python-future.

$SPLUNK_HOME$/etc/apps/hipchat_app/bin/hipchat.py

from __future__ import print_function
from future import standard_library
standard_library.install_aliases()
import sys, json, urllib.request, urllib.error, urllib.parse

def send_message(settings):
    print("DEBUG Sending message with settings %s" % settings, file=sys.stderr)
    room = settings.get('room')
    auth_token = settings.get('auth_token')
    base_url = settings.get('base_url').rstrip('/')
    fmt = settings.get('format', 'text')
    print("INFO Sending message to hipchat room=%s with format=%s" % (room, fmt), file=sys.stderr)
    url = "%s/room/%s/notification?auth_token=%s" % (
        base_url, urllib.parse.quote(room), urllib.parse.quote(auth_token)
    )
    body = json.dumps(dict(
        message=settings.get('message'),
        message_format=fmt,
        color=settings.get('color', "green")
    ))
    print('DEBUG Calling url="%s" with body=%s' % (url, body), file=sys.stderr)
    req = urllib.request.Request(url, body, {"Content-Type": "application/json"})
    try:
        res = urllib.request.urlopen(req)
        body = res.read()
        print("INFO HipChat server responded with HTTP status=%d" % res.code, file=sys.stderr)
        print("DEBUG HipChat server response: %s" % json.dumps(body), file=sys.stderr)
        return 200 <= res.code < 300
    except urllib.error.HTTPError as e:
        print("ERROR Error sending message: %s" % e, file=sys.stderr)
        return False

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--execute":
        payload = json.loads(sys.stdin.read())
        if not send_message(payload.get('configuration')):
            print("FATAL Failed trying to send room notification", file=sys.stderr)
            sys.exit(2)
        else:
            print("INFO Room notification successfully sent", file=sys.stderr)
    else:
        print("FATAL Unsupported execution mode (expected --execute flag)", file=sys.stderr)
        sys.exit(1)

Configuration files for the HipChat example

The HipChat example for custom alert actions contains the following configuration files.

File	Description
alert_actions.conf	Define the properties of the custom alert action.
app.conf	Package and UI information about the add-on. Required to display information about logger alert actions on the Alert Actions Manager page.
hipchat_alert_icon.png	Icon file for the alert action in the Splunk Enterprise UI.
alert_actions.conf.spec savedsearches.conf.spec	Configuration spec files describing settings in alert_actions.conf and seavedsearches.conf.

alert_actions.conf

alert_action.conf defines the properties of the custom alert action. It also defines parameters to the hipchat.py script.

$SPLUNK_HOME$/etc/apps/hipchat_app/default/alert_actions.conf

[hipchat]
is_custom = 1
label = HipChat
description = Send HipChat room notifications
icon_path = hipchat_alert_icon.png
payload_format = json

# base URL and Auth token available from your HipChat installation
param.base_url = http://hipchat.splunk.com/v2/
param.auth_token = Hr9marGO3ywwCyZqsE9r91MAMExtFpJKsxCnptbx

• Note: The HipChat example does not override the alert.execute.cmd command. For more details, see Override a script with alert.execute.cmd.

app.conf

Defines properties that appear in the Alert Actions Manager page.

[ui]
is_visible = 1
label = Mod Alert Tests

[launcher]
author = Splunk
description = Quick examples for testing mod alerts
version = 1.0

[install]
state = enabled
is_configured = 1

PNG file for the custom alert action icon

The height and width dimensions of the PNG file should be equal. A PNG files with dimensions of 48x48 pixels works best.

$SPLUNK_HOME$/etc/apps/hipchat_app/appserver/static/hipchat_alert_icon.png

Spec files for the custom alert action

The README directory contains the spec files for custom alert actions.

alert_actions.conf.spec

alert_action.conf.spec describes custom settings for the custom alert action. These settings are used across all instances.

$SPLUNK_HOME$/etc/apps/hipchat_app/README/alert_actions.conf.spec

[hipchat]

param.base_url = <string>
* HipChat API base URL - adjust if you're using you own server on premise

param.auth_token = <string>
* HipChat OAuth2 token 
* see https://www.hipchat.com/docs/apiv2/auth

savedsearches.conf.spec

savedsearches.conf.spec describes additional savedsearches.conf settings introduced by the custom alert actions. These are per-instance settings.

Reference the parameters listed here with controls in the form that implements the UI for custom actions. See Configure the UI for custom actions.

$SPLUNK_HOME$/etc/apps/hipchat_app/README/savedsearches.conf.spec

# HipChat alert settings

action.hipchat = [0|1]
* Enable hipchat notification

action.hipchat.param.room = <string>
* Name of the room to send the notification to
* (required)

action.hipchat.param.message = <string>
* The message to send to the hipchat room. 
* (required)

action.hipchat.param.message_format = [html|text]
* The format of the room notification (optional)
* Default is "html"
* (optional)

action.hipchat.param.color = [red|green|blue|yellow|grey]
* Background color of the room notification (optional)
* (optional)

action.hipchat.param.notify = [1|0]
* Notify users in the room
* Defaults to 0 (not notifying users in the room)
* (optional)

action.hipchat.param.auth_token = <string>
* Override Hipchat API auth token from global alert_actions config
* (optional)

HTML file for the custom alert action form

The HTML file defines the form elements for the custom alert action in the Splunk Enterprise UI.

Highlights of the HTML code:

• Defines a set of controls to display in the form for the custom action.
• Uses pre-defined CSS styles to define the controls in the form.
• Uses {{SPLUNKWEB_URL_PREFIX}} to define paths to local resources. [TBD]

$SPLUNK_HOME$/etc/apps/hipchat_app/default/data/ui/alerts/hipchat.html

<form class="form-horizontal form-complex">
    <div class="control-group">
        <label class="control-label" for="hipchat_room">Room</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.room" id="hipchat_room" />
            <span class="help-block">
              The name of a HipChat room.
            </span>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_message">Message</label>

        <div class="controls">
            <textarea name="action.hipchat.param.message" id="hipchat_message" />
            <span class="help-block">
                The chat message for the HipChat room.
                Include tokens to insert text based on search results.
                <a href="{{SPLUNKWEB_URL_PREFIX}}/help?location=learnmore.alert.action.tokens" target="_blank"
                   title="Splunk help">Learn More <i class="icon-external"></i></a>
            </span>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label">Message Format</label>

        <div class="controls">
            <label class="radio" for="hipchat_message_format_plain">
                <input id="hipchat_message_format_plain" type="radio" name="action.hipchat.param.message_format" value="plain" />
                Plain Text
            </label>
            <label class="radio" for="hipchat_message_format_html">
                <input id="hipchat_message_format_html" type="radio" name="action.hipchat.param.message_format" value="html" />
                HTML
            </label>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_color">Background Color</label>

        <div class="controls">
            <select id="hipchat_color" name="action.hipchat.param.color">
                <option value="">None</option>
                <option value="red">Red</option>
                <option value="green">Green</option>
                <option value="blue">Blue</option>
                <option value="grey">Grey</option>
            </select>
            <span class="help-block">Change the background of the hipchat message.</span>
        </div>
    </div>
    <div class="control-group">
        <div class="controls">
            <label class="checkbox" for="hipchat_notify">
                <input type="checkbox" name="action.hipchat.param.notify" id="hipchat_notify" value="1"/>
                Notify users in the room
            </label>
        </div>
    </div>
    <div class="control-group">
        <label class="control-label" for="hipchat_auth_token">Auth Token</label>

        <div class="controls">
            <input type="text" name="action.hipchat.param.auth_token" id="hipchat_auth_token" placeholder="Optional"/>
            <span class="help-block">Override the globally configured HipChat Auth Token for this alert.</span>
        </div>
    </div>
</form>