
Convert a script alert action to a custom alert action
The run a script alert action is officially deprecated. Learn how to migrate existing alert action scripts to the custom alert action framework.
Migration planning
- Start the migration process by comparing the scripted and custom alert action frameworks.
- To replicate scripted action functionality, you can use configuration files in combination with a custom alert action script. Review Accessing script argument values in a custom alert action.
- Design a user interface to let users configure the alert action.
See the Custom alert actions overview for a compete guide to the custom alert action developer documentation.
Framework comparison
Feature | Script alert action | Custom alert action | Notes |
---|---|---|---|
Numbered arguments for accessing alert values For example, use $0 or SPLUNK_ARG_0 for the script name.
|
Yes | No | For custom alert actions, use configuration file parameters to access and pass values to the configuration payload that the alert action receives. |
User interface API | No | Yes | The custom alert action API lets you build a configuration user interface that users can access when creating or editing an alert. |
Configuration files | No | Yes | Custom alert actions use alert_actions.conf and savedsearches.conf for registration and configuration. They also use app.conf for app package and UI configuration.
|
Additional components | No | Yes | Custom alert action app components can include a default.meta file to specify permissions and access for the alert action. You can also include an icon for the alert action.
|
Accessing script argument values in a custom alert action
One of the primary differences between the scripted alert action and custom alert actions is the API for accessing contextual values. These values are used in alert action configuration, dispatch, and communication.
The scripted alert action framework offers predefined positional arguments to access specific values.
In custom alert actions, a script can read in parameters and values from configuration files.Some of these values are available by default in the configuration payload. You can create configuration parameters in alert_actions.conf
to pass additional values in to the payload. Developers typically set up configuration files before writing a custom alert action script.
For more information on working with configuration files and the configuration payload, see Set up custom alert configuration files.
SPLUNK_ARG environment variable | Value | How to access the value in a custom alert action |
---|---|---|
0 | Script name | The custom alert action script name must match the custom alert action stanza name in alert_actions.conf . It must also match the stanza name in alert_actions.conf.spec .
|
1 | Number of events returned | Not available by default in the configuration payload. You can create a param to capture this search property using the $job.resultCount$ token in alert_actions.conf .
|
2 | Search terms | Not available by default in the configuration payload. You can create a param to capture this search property using the $job.request.search$ token in alert_actions.conf .
|
3 | Fully qualified search string | Not available by default in the configuration payload. You can create a param to capture this search property using the $job.request.qualifedSearch$ token in alert_actions.conf .
|
4 | Name of saved search | Available as search_name key value pair in the custom alert action payload.
|
5 | Trigger reason | Not available by default in the configuration payload. To replicate the scripted alert trigger reason, create a param for a trigger reason string in alert_actions.conf . Use the $relation$ and $quantity$ job properties to concatenate the trigger reason string.
|
6 | Results link | Available as results_link key value pair in the custom alert action configuration payload.
|
7 | Not used in scripted alert actions | N/A |
8 | File in which the results for the search are stored.
Contains raw results in gzip file format. |
Available as results_file key value pair in the custom alert action configuration payload.
|
Building a user interface
Custom alert action apps include a user interface, while scripted actions do not. You can create a simple user interface as part of migrating an alert action script to a custom alert action. See Define a custom alert action interface for more information.
Example
This example shows you how to migrate a scripted alert action that posts a notification to a Slack chat room.
The files referenced are examples similar to files that you might have in your Splunk platform /scripts
and etc/apps
directories.
Scripted alert action
This sendSlackAlertPythonOnly
script is in the /bin/scripts
directory on the Splunk platform instance. This script has been made cross-compatible with Python 2 and Python 3 using python-future.
from __future__ import print_function from builtins import str import os import sys import requests def send_slack(args_tuple, label=""): message = create_slack_msg(args_tuple, label) payload = str({"text": message}) slackUrl = "https://hooks.slack.com/services/T41234fF2L/B4Z46756FW/Cowjj4NATJV7zqczOV23qWog" r = requests.post(slackUrl, data = payload) def create_slack_msg(args_tuple, label=""): message = """ *This is a Splunk %s :horse:. Below are the 8 command line* *arguments used when invoking this scripted alert action.* 1) Number of Events Returned: %s 2) Search Terms: %s 3) Fully Qualified Search String: %s 4) Name of Saved Search: %s 5) Trigger Reason: %s 6) Linked To Saved Search: %s 7) Tags or File Name for Results: %s 8) File Name for Results (or none if no tags): %s """ % ((label,) + args_tuple) return message if __name__ == "__main__": print("you_are_here", file=sys.stderr) send_slack(tuple(sys.argv[1:]), "Scripted Alert Action (simple python scripted alert action)")
Comparable bash script example
The following bash script is an example of similar scripted alert action functionality in a shell script.
#!/bin/bash slackUrl = "https://hooks.slack.com/services/T41234fF2L/B4Z46756FW/Cowjj4NATJV7zqczOV23qWog" read -d "" message <<- EOF *This is a Splunk Scripted Alert (simple bash script) :horse:. Below are the 8 commandline arguments* *that Splunk invokes this scripted alert with:* 1) Number of Events Returned: $1 2) Search Terms: $2 3) Fully Qualified Search String: $3 4) Name of Saved Search: $4 5) Trigger Reason: $5 6) Linked To Saved Search: $6 7) Tags or File Name for Results: $7 8) File Name for Results (or none if no tags): $8 EOF curl -X POST -H 'Content-type: application/json' --data "{'text': '$message'}" "$slackUrl"
Migrated custom alert action files
The following files are part of a custom alert action app package in the /etc/apps/alert_slack
directory. This custom alert action migrates the sendSlackAlertPythonOnly
scripted alert action.
The example files here are only those required for migrating the scripted alert action. They do not represent all of the files in a custom alert action app. See the Custom alert action component reference for complete details.
Script
This script uses symlinking to import functionality from the sendSlackAlertPythonOnly
scripted alert action. Symlinking is optional when migrating a scripted alert action. This script has been made cross-compatible with Python 2 and Python 3 using python-future.
from __future__ import print_function from future import standard_library standard_library.install_aliases() import sys import os import json from urllib.parse import urlencode import urllib.request, urllib.error, urllib.parse import requests # symlink this from sendSlackAlertPythonOnly import create_slack_msg def send_slack(settings): try: config = settings['configuration'] args_tuple = ( config['result_count'], config['search_query'], config['search_query'], settings['search_name'], config['trigger_reason'], settings['results_link'], 'NA', settings['results_file'] ) message = create_slack_msg(args_tuple, "Custom Alert Action (that invokes a legacy, python, scripted alert)") payload = "{'text': '%s'}" % message slack_url = config['slack_url'] res = requests.post(slack_url, data = payload) if 200 <= res.status_code < 300: print("DEBUG receiver endpoint responded with HTTP status=%d" % res.status_code, file=sys.stderr) return True else: print("ERROR receiver endpoint responded with HTTP status=%d" % res.status_code, file=sys.stderr) return False except Exception as e: print("ERROR Error %s" % e, file=sys.stderr) return False if __name__ == "__main__": if len(sys.argv) < 2 or sys.argv[1] != "--execute": print("FATAL Unsupported execution mode (expected --execute flag)", file=sys.stderr) sys.exit(1) else: settings = json.loads(sys.stdin.read()) if not send_slack(settings): print("ERROR Unable to contact slack endpoint", file=sys.stderr) sys.exit(2) else: print("DEBUG slack endpoint responded with OK status", file=sys.stderr)
app.conf
[ui] is_visible = 0 label = Log Slack Event Alert Action [launcher] author = Splunk description = Log Slack Event Alert Action version=6.6.0 [install] state = enabled is_configured = 1
alert_actions.conf
[slackcustomalert] is_custom = 1 label = Slack Custom Alert Action description = Send splunk event data to a Slack team room icon_path = slacklogo.png payload_format = json param.trigger_reason = Saved Search [slackcustomalert] number of events($job.resultCount$) param.result_count = $job.resultCount$ param.search_query = $job.search$ param.slack_url =
alert_actions.conf.spec
[slackcustomalert] param.trigger_reason = <string> * Provided for backwards compatibility with scripted alerts param.result_count = <string> * Number of results returned param.search_query = <string> * Search string
savedsearches.conf.spec
# Slack event action settings action.slackcustomalert.param.slack_url = <string> * Slack chat room endpoint action.slackcustomalert.param.trigger_reason = <string> * Provided for backwards compatibility with scripted alerts action.slackcustomalert.param.result_count = <string> * Number of results returned action.slackcustomalert.param.search_query = <string> * Search string
User interface HTML file
form class="form-horizontal form-complex"> <div class="control-group"> <label class="control-label" for="slackcustomalert_slack_url">WebHook URL</label> <div class="controls"> <textarea name="action.slackcustomalert.param.slack_url" id="slackcustomalert_slack_url" style="width: 270px; max-width: 270px; height: 60px;"></textarea> </div> </div> <div class="control-group"> <div class="controls"> <span class="help-block" style="display: block; position: static; width: auto; margin-left: 0;"> URL needed to POST data to your Slack team room <br /> <a href="https://api.slack.com/incoming-webhooks" target="_blank" title="Slack Webhook Documentation">Slack Webhook Documentation<i class="icon-external"></i></a> </span> </div> </div> </form>
PREVIOUS Optional custom alert action components |
NEXT Logger example for custom alert actions |
This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 9.0.0, 9.0.1, 9.0.2, 9.0.3
Feedback submitted, thanks!