Dashboards and Visualizations

 


Create and edit forms with the Dashboard Editor

Create and edit forms with the Dashboard Editor

You create a form by adding one or more inputs to a dashboard. Here is the basic workflow for creating a form. The actual order of completing the tasks can vary.

  1. Create a dashboard and add one or more inputs to the form.
    See Add an input to create a form.
  2. (Optional) Edit the label and token fields.
    Searches in the form use the token defined in the input to specify which values to retrieve from the search.
    See Tokens in form inputs.
  3. Reference the token in search strings and other locations.
    Modify search strings to reference the value returned by the token. You can also reference the token in headings and dynamic drilldowns throughout the dashboard.
    See Reference a token in a search and Add a time input to a form.
  4. Specify default form behavior, such as when to run the search driving the form.
    See Specify the behavior of a form.
  5. For inputs that provide multiple options, specify user options.
    This applies to dropdown, check box, multiselect, and radio inputs.
    See Specify choices for inputs that accept multiple options.
  6. Specify any additional attributes for inputs.
    See Form input examples for an example of each input type.
  7. (Optional) Rearrange inputs and panels.
    You can drag and drop the placement of panels and form inputs. You can also drag inputs to specific panels.

Add an input to create a form

Adding an input to an existing dashboard converts that dashboard to a form. After you add the input, the top-level element in the underlying simple xml changes from <dashboard> to <form>.

  1. From a dashboard, click Edit > Edit Panels.
  2. Click Add Input.
  3. From the list of inputs, select an input.
    For example, select Text to add a text field for user input.
  4. (Optional) If you have more than one input, you can drag an input to rearrange it on the form.
  5. (Optional) Drag an input into a panel.
    Using tokens, you can make the input apply only to the visualizations within that panel. See Tokens in form inputs.
  6. To edit the input, select the Edit Icon of the input and edit the attributes.
    See the following sections for details.
  7. Click Done when you are finished editing the inputs.

Tokens in form inputs

When you add an input to a form, the Dashboard Editor generates a unique token for use with that input. The token is a placeholder for dynamic values. Typically, you reference the token in a search string to specify the values returned for display in the form. You can also reference tokens in panel headers and drilldown for charts.

Use tokens with time inputs to identify the time inputs in the form. For each panel that you want to drive by that time input, modify the search of the panel to reference the time input by its token.

The following examples show two common ways to reference tokens in a form:

Reference a token in a search
Add a time input to a form

You can also reference tokens when you use the drilldown feature for charts. See Dynamic drilldown.

Reference a token in a search

The panel in the following dashboard contains the following search, which displays a time chart of source types. When you add an input to convert the dashboard to a form, you reference a token in the search to specify which values to return in the form.

index=_internal | timechart count by sourcetype

Viz example dashboard.png

  1. From the dashboard, click Edit > Edit Panels.
  2. Add a Text input to convert the dashboard to a form.
    The Dashboard Editor generates the following unique value for the Token attribute: field[n].
  3. Change the generated value for the token to the more meaningful src_type_tok.
    The values for tokens should be unique within the dashboard.
  4. Edit the search string in the panel to reference the token:
    index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype
  5. Click Save. Click Done.
    Now the form contains a Text input to filter results returned by the search.

    Viz text input.png

Add a time input to a form

The following example shows how to add a time input to a form. When you initially add panels to a form, you specify a time range for the panel. To apply the values from the newly added time input, edit the search for the panel to override the panel's time range.

  1. From the dashboard, click Edit > Edit Panels.
  2. Select Add Input > Time.
  3. Select the Edit Icon for the input and specify the attributes for the time range picker.
    (Optional) Specify a meaningful name for the token. For example, "time_range_7days_tok".
  4. Click Apply.
  5. For each panel in which the time input applies, do the following:

    1. Click the Search Icon
    2. Click Edit Search String.
    3. For Time Range Scope select Shared Time Picker.
      See Multiple time inputs in a form for details on selecting the time range scope.
    4. Click Save.
  6. Click Done.

    Viz text time input.png

Multiple time inputs in a form

A form can have one or more time inputs to specify the time range for visualizations. You can also specify the time range for visualizations directly in simple XML code, without referencing a time picker.

When you add a time picker to a form, the Dashboard Editor generates a unique token for that time picker. You can edit the generated name for the token to provide a more meaningful name. A visualization references the token to apply the time range to its search.

If you do not specify a token for a time picker, the time picker becomes global. Any visualization that does not specify a time range, either through a reference to a time picker token or directly in code, applies the time range from the global time picker.

These are the ways you can specify time inputs.

  • Global time picker
    The time input does not specify a token.
  • Time picker by token reference
    The visualization references the token of a time picker.
  • Time specified directly in the search
    The <earliest> and <latest> elements in simple XML code specify the time range.

Select a time range for a visualization

You select a time range from the Panel Editor:

  1. From a dashboard, select Edit > Edit Panels.
  2. Click the Search Icon on a panel.
  3. Select Edit Search String.
  4. From the Time Range Scope drop down menu, select a time picker.
    Depending on the time range pickers in your form, you select from one of the following:

    • Shared Time Picker (global)
      A time picker without a token reference.
    • Shared Time Picker (token name)
      A time picker referenced by token.
    • Explicit Selection
      Specify a time range directly in the simple XML code
    • Tokens
      Specify specific tokens to represent the Earliest and Latest values of the time range.
  5. Click Save. Click Done.

Specify the behavior of a form

There are various ways to submit the token values in a search to populate the form with results from the search. How you submit token values determines when the page displays results from the search driving the form.

Submit token values when the page loads

To submit token values when the page loads, enable autorun behavior.

  1. From the dashboard, click Edit > Edit Panels.
  2. Enable the Autorun dashboard check box. Click Done.

Submit token values when an input changes

For each input, you can submit the token values whenever an input changes. By default, this behavior is enabled. You do not need a Submit button for the form when you enable Search When Changed. The following procedure shows how to disable or enable search when an input changes.

  1. From the dashboard, click Edit > Edit Panels.
  2. Select an input for editing.
  3. Select or deselect the Search When Changed check box. Click Done.

Add a Submit button to submit input values

You can add a Submit button to a form that submits the input values when the user clicks the button. Typically, you do not specify the Search when changed property of an input if you use a Submit button.

The Dashboard Editor places the Submit button to the right of all form inputs. You cannot change the position of the Submit button.

  1. From the dashboard, click Edit > Edit Panels.
  2. Select Add Input > Submit.
  3. Continue editing the form. Click Done when editing is complete.

About seed and default values

You can specify seed and default values for form inputs.

  • Default
    The value of the input when the user does not specify an input value.
  • Seed
    (Text input only) Use the specified value as the initial value for the input when a page loads. The seed value applies only on initial page load. If subsequently the text input field is empty, the seed value does not apply.
Note: The main difference between seed and default is that the seed value allows the user to submit an empty string. If you specify both a seed value and a default value, only the default value applies.

Specify choices for inputs that accept multiple options

Several form inputs provide multiple choices for selection. The procedure for specifying the choices is the same for each of these form inputs. This makes it easy to convert from one type of input to another.

The following inputs allow multiple options for selection:

check box
dropdown
multiselect
radio
Note: The multiselect and check box inputs option require an additional procedure for specifying multiple values. See Specify multiple values with check box and multiselect.

You can specify static (hard-coded) labels and values for options or you can specify a populating search that dynamically creates the labels and values.

Specify choices with static options

The following procedure shows how to specify static options for inputs that contain multiple options. The following procedure references the dropdown input, but it applies to the following input types:

  • dropdown
  • check box
  • multiselect
  • radio
  1. From a dashboard, select Add Input > Dropdown.
  2. Select the edit icon for the input. Select Static Options.
  3. Specify a name and value for the first option.
  4. For each additional option, Click Add Option and specify the name and value for the option.
  5. (Optional) Scroll to the Default field and specify a default value.
  6. (Optional) Drag and drop the options to rearrange them.
  7. Click Apply.

Specify choices with dynamic options

Use a populating search to specify labels and values for inputs that contain multiple options. The following procedure references the dropdown input, but it applies to the following input types:

  • dropdown
  • check box
  • multiselect
  • radio

This procedure shows how to create a populating search for dropdown menu options. It shows one way to customize the generated labels for the options.

Viz pop search example3.png

  1. Create a dashboard with a panel driven by the following search:
    index=_internal $source_tok$ | timechart count
  2. From a dashboard, select Add Input > Dropdown.
  3. Select the Edit Icon for the input. Edit the following fields in the Input Editor:

    • Label: Select a source type
    • Search on Change: Enable
    • Token: source_tok
    • Token Prefix: sourcetype="
    • Token Suffix: "
    • (Static Options) Name: All; Value: *
  4. Click Dynamic Options to specify a populating search.
  5. Specify the following inline search to populate the menu options:
    index=_internal | stats count by sourcetype | eval label=sourcetype." (".count.")"
    This search uses an eval function to define a label field.
  6. (Optional) Select Run Search to preview the results of the search.
  7. Specify fields returned from the populating search:
    Field for Label: label
    Field for Value: sourcetype
  8. Click Apply.

Specify multiple values with check box and multiselect

The multiselect and check box form inputs differ from other inputs in that they allow users to select multiple options. The following figures show a check box input and a mulitselect input for choosing which source types to model in the panel.

Viz check multi inputs.png

To specify the source type values in the above form, build a search string indicating the values to return. For this example, the following search string allows the selection of multiple values for source types:

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR sourcetype="splunkd_access")

The search driving the panel accesses the token value of check box and multiselect differently than the other form inputs. Use the submitted modifier to the token.

index=_internal $src_type_tok$ | timechart count by sourcetype

The Input Editor provides editing fields to specify multiple values for selection in a check box or multiselect. The table below describes these fields and provides example values that build the following search string:

(sourcetype="<b>selected value</b>" OR sourcetype="<b>selected value</b>" OR ... )


Editor Field Description Example Values
Token Prefix String prefixed to the value of the input element.

For multiple selections, this is typically an open parenthesis to enclose the string selecting the values.
(
Token Suffix String appended to the value of the input element.

For multiple selections, this is typically a close parenthesis to enclose the string selecting the values.
)
Token Value Prefix String prefixed to the value of the input element. Can be a regular expression. Default value is an opening double quote (").

Typically, this is the opening part of a sub-string that selects the multiple values.
sourcetype="
Token Value Suffix String appended to the value of the input element. Can be a regular expression. Default value is an closing double quote (").

Typically, this is the closing part of a sub-string that selects the multiple values.
"
Delimiter A string placed between each selected value. Typically, you specify " OR " or " AND " using upper case. Do not specify the quote marks, but specify a space character before and after the string.

Default value: " "

Default value does not include quote marks. The quote marks show that the default value is a space character.
 OR 

The following procedure shows how to enable multiple selections for a check box or multiselect input.

  1. From the dashboard, click Edit > Edit Panels.
  2. Select Add Input. Select either Checkbox or Multiselect.
  3. Specify Label, Search on Change, and Token.
  4. Specify choices as described in Specify choices with static options and Specify choices with dynamic options.
  5. Build the multiselect search string using the editing fields in the above table.
    (Recommended) Use the preview feature to verify the multiselect search string.
  6. (Optional) Specify a default value.
  7. Click Apply. Click Done.

Form input examples

This section provides an example of each form input, with a list of the key fields for implementing the example.

Check box

This example uses the check box input to indicate which source types to display in a timechart. A populating search specifies the available options to select. Three source types are selected by default:

splunk_web_access
splunk_web_service
splunkd

This example enables Search on Change. The form loads when a selection is made.

The panel displays results in the default column chart, using the following base search. The visualization references the input values using the value specified for Token. In this example, the token name is src_type_tok.

index=_internal $src_type_tok$ | timechart count by sourcetype

Src types checkbox.png         Src types checkbox panel.png

General settings

Specify the Label for the input and the Search on Change behavior. This example enables search on change.

Token options

Use the Token Options to specify the value returned by the check box input.

For the Token field, specify a name for the token that returns the value. The base search for the visualization references this token. In this example, specify src_type_tok.

Use the following fields to build the search for the returned value. The Preview field in the Input Editor updates as you edit these fields.

  • Token Prefix
  • Token Suffix
  • Token Value Prefix
  • Token Value Suffix
  • Delimiter

The example values listed in the table below build the following search string:

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR ...)

After you dynamically create the check boxes, from the Default field, select the check boxes that are enabled by default.

Static options

Use the static options to explicitly define the Name and Value of the check boxes for the input.

This example leaves the static options blank. It uses a populating search to define the check boxes for the input.

Dynamic Options

Reference a report or define an inline populating search to define the check boxes for the input.

This example uses the following inline search:

| metadata type=sourcetypes index=_internal

The example runs the search against all time.

Use field names to pecify a name/value pair for the check boxes. This example species the sourcetype field for both Field for Label and Field for Value.

Example values for check box input

This table lists the example values for the check box input example.


Editor Field Example Values
General
Label
Source Types (Check Box)
Search on Change
Enabled
Token Options
Token
src_type_tok
Default
splunk_web_access
splunk_web_service
splunkd
Token Prefix*
(
Token Suffix*
)
Token Value Prefix*
sourcetype="
Token Value Suffix*
"
Delimiter*
 OR 
Dynamic Options
Content Type
Inline Search
Search String
| metadata type=sourcetypes index=_internal
Time Range
All time
Field for Label
sourcetype
Field for Value
sourcetype
*These fields build the search string that dynamically create the check boxes. For the Delimiter field, be sure to specify an opening and closing space.

Dropdown input

This example uses a dropdown input to indicate which source types to display as a time chart. The panel displays results as a bar chart, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

The token $src_type_tok$ references the values specified by the dropdown.


Src types dropdown.png  Src types dropdown panel.png

The example uses static options to define choices for the dropdown.

The example specifies splunk for Token Prefix. Each selected value prefixes the token prefix to the value.

There is a default value for the dropdown.

The example relies on a Submit button to run the search. Changes to the selection do not apply until you click the Submit button.

Editor Field Example Values
General
Label
Source Types (Dropdown)
Search on Change
Not specified
Token Options
Token
src_type_tok
Default
Daemon
Token Prefix
splunk
Static Options
Name : Value
Daemon : d
Name : Value
Web Service : _web_service
Name : Value
Web Access : _web_access
Name : Value
Daemon Access : d_access

Multiselect

This example uses a multiselect input to indicate which source types to display in a timechart. The panel displays results in the default column chart, using the following base search.

index=_internal $src_type_tok$ | timechart count by sourcetype

Src types multiselect.png         Src types multiselect panel.png

The example uses static options to define choices for the dropdown.

Two source types are selected by default:

Daemon
Web Access

This example enables Search on Change. The form loads when a selection is made.

For a multiselect input, you define multiple values to select by building the following search string.

(sourcetype="splunkd" OR sourcetype="splunk_web_access" OR ...)

The token $src_type_tok$ references this search string in the search that drives the panel contents. The fields that build the search string are indicated in the table below.

Editor Field Example Values
General
Label
Source Types (Multiselect)
Search on Change
Enabled
Token Options
Token
src_type_tok
Default
Daemon
WEb Access
Token Prefix*
(
Token Suffix*
)
Token Value Prefix*
sourcetype="
Token Value Suffix*
"
Delimiter*
 OR 
Static Options
Name : Value
Daemon : splunkd
Name : Value
Web Service : splunk_web_service
Name : Value
Web Access : splunk_web_access
Name : Value
Daemon Access : splunkd_access
Name : Value
Daemon Access : splunkd_access
Name : Value
Version : splunk_version
Name : Value
Error : splunkd_stderr
*These fields build the search string that supplies the token value. For the Delimiter field, be sure to specify an opening and closing space.

Radio input

This example uses a radio input to indicate which source types to display as a time chart. The panel displays results as an area chart, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

Src types radio.png  Src types radio panel.png

The token $src_type_tok$ references the values specified by the dropdown.

The example uses static options to define choices for the dropdown.

There is a default value for the radio input.

This example enables Search on Change. The form loads when a selection is made.

Editor Field Example Values
General
Label
Source Types (Radio)
Search on Change
Enabled
Token Options
Token
src_type_tok
Default
Web Service
Static Options
Name : Value
Daemon : splunkd
Name : Value
Web Service : splunk_web_service
Name : Value
Web Access : splunk_web_access
Name : Value
Daemon Access : splunkd_access

Text input

This example uses a text input to indicate which source types to display as a time chart. The panel displays results as a pie graph, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

The token $src_type_tok$ references the values specified in the text input.

This example specifies a seed value of splunkd* without specifying a default value. Upon initial load, the seed value is applied. The form reloads when you specify a new value.

Because there is no default value, an empty text input does not return any results.

Src types text.png         Src types text panel.png


Editor Field Example Values
General
Label
Source Types (Text input)
Search on Change
Enabled
Token Options
Token
src_type_tok
Default
Not specified
Seed
splunkd*


Time input

This example shows how to use a time input to specify time ranges for a panel in a form. The form contains a radio input to indicate which source types to display as a time chart. The panel displays results as a column chart, using the following base search.

index=_internal sourcetype=$src_type_tok$ | timechart count by sourcetype

Src types time.png  Src types time panel.png

The examples specifies time_input_tok to reference the time input in a panel.

In the Panel Editor, select Edit Search String. From the Time Range Scope dropdown, select Shared Time Picker (time_input_tok).

The default value for the time input is Last 7 days.

The example enables Search on Change for the time input. The form loads when a new time range is selected.

Editor Field Example Values
General
Label
Time Input
Search on Change
Enabled
Token Options
Token
time_input_tok
Default
Last 7 days

This documentation applies to the following versions of Splunk: 6.1 , 6.1.1 , 6.1.2 , 6.1.3 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!