Splunk® Enterprise

Developing Views and Apps for Splunk Web

Download manual as PDF

Download topic as PDF

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.

Custom alert selection element.png

splunk-radio-input

Use the <splunk-radio-input> element to declare a radio group control.
Custom alert radio button.png

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.

Custom alert example color picker.png

  • 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.

Example custom alert textbox input.png

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.

Example text area custom alert UI.png


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 "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]"
/>

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"
                    label-field="title" value-field="title" 
          </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]"
/>

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)"
                label-field="iso2" value-field="iso2"
                allow-custom-value 
            </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=" -24 " latest= "now"
    value-field="[results field for values]" label-field="[results field for labels]"
/>


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"
                label-field="count" value-field="count"
          </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.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 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.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 8.0.0, 8.0.1

Comments

Hi MisteRious,
Thank you for leaving a comment and submitting feedback. We're currently looking into the lost functionality. I urge you to lodge a support ticket. Please respond to my email if you have any problems doing so, and I'll further assist you.

Best,
Eve

Emeelan splunk, Splunker
December 13, 2018

allow-custom-value dla splunk-search-dropdown stopped working for versions 7.*, please fix it as it cripples our custom alert actions.

MisteRious
December 10, 2018

Is it possible to d a multiselect based on the values returned by a splunk query? In our custom alert action, we need the user to be able to select multiple values from the dropdown (or potentially select all). However, from the above documentation it seems that only single select dropdowns are supported for dynamic input controls?

Ewagh splunk
July 2, 2018

Hi SK8,
Thanks for taking the time to leave your comment. You cannot use JavaScript in the custom alert UI. You can only use it to create the custom alert action itself.

Cheers,
Eve

Emeelan splunk, Splunker
June 6, 2018

It is possible to use javascript in the cutsom alert ui?

SK8
June 1, 2018

In regard to the previous two posts, when you create a custom alert that depends on building an app, you must set the permissions for the alert, which is a knowledge object. In order to do this, you must add a default.meta definition to your alert. Dbabanov's solution is very close to correct, the only change I would make would be to not specify the app in the alert_actions brackets ( [alert_actions]), in order to ensure that all alerts are globally accessible. There is a very handy blog post that describes this particular use case, and it can be found here: https://www.splunk.com/blog/2016/08/22/how-to-create-a-modular-alert.html
Thanks to both of you!

Emeelan splunk, Splunker
November 14, 2017 [ delete ]

Emeelan splunk, Splunker
November 14, 2017

I have same problem. When i add custom alert action with input field, i have message: "this alert action does not require any user configuration". You should change default.meta file. Example for custom alert action "hipchat":
[]
access = read : [ * ], write : [ admin ]

[alert_actions/hipchat]
export = system

[alerts]
export = system

Dbabanov
November 14, 2017

There seems to be something missing from this documentation. Even if I copy the webhook alert app and change the name across all files, the custom alert shows up BUT the input fields defined in the HTML do not show up. Is there somewhere other than the app itself that the configurations need to be put in for the custom HTML to work?

Ryandg
August 25, 2017

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters