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