
Define a custom alert action user interface
Add a custom alert action user interface to let users configure alert action properties. The following user interface API provides a user experience that is consistent with the Splunk platform.
File location
Define the custom alert action interface in an HTML fragment file.
Place the HTML file in the following app directory location.
$SPLUNK_HOME/etc/apps/[custom_alert_action_app_name]/default/data/ui/alerts/
Custom HTML elements
The Splunk platform supports a set of custom HTML elements that manage the behavior and rendering of user interface controls. Here is an overview of the available elements.
Custom HTML element | Description |
---|---|
<splunk-control-group>
|
Wrapper element for a set of interface controls. |
<splunk-search-dropdown>
|
Input control populated dynamically by a search. See Dynamic input controls for more details. |
<splunk-select>
|
Selection control that takes options in HTML. |
<splunk-radio-input>
|
Radio group that takes options in HTML. |
<option>
|
Declares an option for select and radio group elements. Child element of these input elements. |
<splunk-text-area>
|
Resizable text area. |
<splunk-text-input>
|
Text input. |
<splunk-color-picker>
|
Color picker element with three preconfigured palette types. Also allows a custom palette. |
<splunk-color>
|
Declares a color value for a custom color picker palette. Child element of the <splunk-color-picker> element.
|
These elements have styling consistent with standard Splunk Web elements, although they do not have the standard Splunk Web layout by default.
Wrapper for input elements and labels
Wrap all format menu input elements with this component.
<splunk-control-group>
You can specify the following <splunk-control-group>
attributes.
Attribute | Description |
---|---|
label
|
Label for the input element. Appears in the UI. |
help
|
String appearing underneath the control. |
Selection elements
The following elements present options and a selection interface to users.
splunk-select
Use the <splunk-select>
element to create a selection control. Options appear in a list.
Specify one or more <option>
child elements defining available options. In this example, there are six email priority level options.
splunk-radio-input
Use the <splunk-radio-input>
element to declare a radio group control.
Requirements
Specify one or more <option>
child elements to indicate the options that appear as radio buttons.
option
Use an <option>
child element with a <splunk-select>
or <splunk-radio-input>
to specify available options. The <option>
enclosed text appears as the option label. When a user selects an option, the <option>
value is set as the control value.
splunk-color-picker
Use this element to provide a color configuration user interface.
- Specify one of the following color palette types for the color picker.
splunkCategorical
. Default type if none is specified.splunkSemantic
splunkSequential
custom
- Specify colors in the custom palette or extend one of the available palette types using
<splunk-color>
tags.
- For custom color palettes, the
<splunk-color>
tag accepts valid CSS color strings. Invalid strings are ignored.
- You can use the
value
tag to set a default value for the picker.
Predefined color palettes are available as part of the custom alert action and custom visualization APIs. To learn more about the predefined color palette types, see Color in the Design guidelines for custom visualizations.
Text entry elements
The following elements let users add custom text.
splunk-text-input
Use a <splunk-text-input>
element to create a text input control. Users can enter up to a single line of text in a splunk-text-input
control.
splunk-text-area
Use a <splunk-text-area>
element to create a text area control. Users can enter multiple lines of text in a <splunk-text-area>
control.
Input naming
Input controls let users configure the namespaced parameters defined in the savedsearches.conf
configuration file for the custom alert action.
Make sure that the input name matches the parameter name specified in savedsearches.conf
. Matching the name ensures that user configurations propagate correctly to savedsearches.conf
.
Example
This example interface lets users specify the name of a chat room.
In savedsearches.conf
, the action.chat.param.room
setting specifies a chat room name.
# chat alert settings action.chat.param.room = <string> * Name of the room where notifications should go * (required)
The user interface includes a text input for users to specify the chat room name. The input name matches the setting from savedsearches.conf
.
<form> <splunk-control-group label="Chat room"> <splunk-text-input name="action.chat.param.room" id="chat_room"> </splunk-text-input> </splunk-control-group> </form>
Dynamic input controls
Add dynamically populated dropdown controls to a custom alert action interface. Use REST API, lookup table, or indexed data set search results to drive the dynamic input content.
Search to populate the input
Consider the following details when writing a search to generate custom input options.
- In addition to provided platform commands and resources, you can use a custom search command and/or query a custom endpoint.
- For better performance, use a search that generates only the results that you need to populate the input. You can also consider commands to minimize processing.
- The search runs in the context of the current user and the deployment where the custom alert action is installed. When constructing the search, consider how dynamically populated options might vary depending on the resources available to the user and in the deployment.
Dynamic input control attributes
Use the following attributes to build a dynamically populated input dropdown.
Name | Description | Default | Required? |
---|---|---|---|
name | Input name. This name should match the setting name in savedsearches.conf to ensure that user configurations propagate from the input to the configuration file.
|
N/A | Yes |
search | The query string to execute. Query the REST API, a lookup table, or indexed data. | N/A | Yes |
label-field | Field name to use for dropdown option labels. Labels generated from this field are visible in the dropdown interface. | N/A | Yes |
value-field | Field name to use for dropdown option values that correspond to the option labels. In some cases, you can use the same results field for the label-field and value-field . In other cases, you might need to display human-readable labels from one field and use the corresponding values from another field. For example, an input might include a user_name field for the label-field and a user_id field for the value-field .
|
N/A | Yes |
earliest | earliest_time in the search time range
|
" " | No |
latest | latest_time in the search time range
|
"now"
|
No |
app | App context in which the query runs. This specification can be useful when the search requires knowledge objects that are only available in a specific app context. | Defaults to the current app context. | No |
allow-custom-value | Indicate whether to provide a field for the user to enter a custom value. Disabled by default. Developers can implement validation for user entered values. | false | No |
max-results | Specify the maximum number of search results returned. Use any positive integer greater than 0. | 1000 | No |
Note: Static or predefined options cannot be included in a dynamic dropdown input.
Syntax and examples
The following examples use queries against different resources to generate dropdown field labels and values.
REST API
Use the rest
search command to populate the input. You can query available splunkd
endpoints or
a custom endpoint.
<splunk-search-dropdown name="action.[alert_action_app_name].param.[alert_action_parameter]" search="| rest [endpoint path and optional parameters] " value-field="[results field for values]" label-field="[results field for labels]"> </splunk-search-dropdown>
Example
This example queries the services/data/indexes
endpoint and uses the title
results field for option labels and values.
<splunk-control-group label="REST input"> <splunk-search-dropdown name="action.controls_demo.param.search_dropdown" search="| rest /services/data/indexes" value-field="title" label-field="title"> </splunk-search-dropdown> </splunk-control-group>
Lookup
Use a lookup table to populate the input.
<splunk-search-dropdown name="action.[alert_action_app_name].param.[alert_action_parameter]" search=" | inputlookup [alert_action_lookup].csv" value-field="[results field for values]" label-field="[results field for labels]"> </splunk-search-dropdown>
Example
This example searches a lookup table with geographical information. The input also includes a field for users to enter a custom value.
<splunk-control-group label="Allow custom values 1"> <splunk-search-dropdown name="action.controls_demo.param.search_dropdown" search="| inputlookup geo_attr_countries.csv | search iso2=* | eval country=coalesce(country, iso2)" value-field="iso2" label-field="iso2" allow-custom-value> </splunk-search-dropdown> </splunk-control-group>
Indexed data
Search indexed data to populate the input.
<splunk-search-dropdown name="action.[alert_action_app_name].param.[alert_action_parameter]" search="index=[index_name] [...additional query content...]" earliest="[value]" latest= "[value]" value-field="[results field for values]" label-field="[results field for labels]"> </splunk-search-dropdown>
Example
This example searches for internal data. It also sets a time range for the input.
<splunk-control-group label="Search driven dropdown 2"> <splunk-search-dropdown name="action.controls_demo.param.search_dropdown" search="index=_internal | streamstats count | table count | sort - count" earliest="-24h" latest="now" value-field="count" label-field="count"> </splunk-search-dropdown> </splunk-control-group>
Security considerations
Except for a dynamic dropdown control, only static HTML markup should be used in the interface. Do not include scripts or other constructs that could put your system at risk.
Linking to static resources
To include URLs or links to static resources, use the replacement tag {{ SPLUNKWEB_URL_PREFIX }}
.
PREVIOUS Create a custom alert action script |
NEXT Optional custom alert action components |
This documentation applies to the following versions of Splunk® Enterprise: 6.5.7, 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.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.8, 7.1.7, 7.0.0, 7.3.7, 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, 7.3.9, 8.0.0, 8.0.1
Feedback submitted, thanks!