Inputs
Inputs are dashboard components that let dashboard users interact with dashboard data and visualizations, selecting options to filter data, show and hide visualizations, and more. For example, a user can select a value from a dropdown to filter data in the dashboard by the selected value. Dashboard Studio supports the following input types:
Dropdown and multiselect: allows user to select a value from a preconfigured list of values. You can configure dropdowns and multiselects with static values. You can also configure dropdowns and multiselects with a data source to dynamically populate the list of values based on search results.
Text and number input: allows user to enter a custom text or number. Use a number input when you want to restrict the entered value to be a number. Use a text input otherwise.
Time range: allows user to select a time interval to filter data by. By default, each new dashboard has a global time range picker, which can be used to control the time range for all ds.search data sources.
Button: upon click, triggers a linking interaction such as switching to another tab or a token action, such as resetting all tokens to their default values.
This topic provides general information applicable to all input types. For information about a specific input type, see one of the linked topics.
The following is an example of a dashboard that uses many inputs.
Expand this window to copy/paste the dashboard definition for this example into your own dashboard.
{
"visualizations": {
"viz_1BAm6ljX": {
"type": "splunk.line",
"dataSources": {
"primary": "ds_6v2nFTBZ"
},
"showProgressBar": false,
"showLastUpdated": false,
"title": "Activity by Status",
"description": "Select Method and Status Codes"
}
},
"dataSources": {
"ds_ljNWYr7J": {
"type": "ds.search",
"options": {
"query": "index=_internal \n| stats count by method"
},
"name": "Method"
},
"ds_neN4LNL4": {
"type": "ds.search",
"options": {
"query": "index=_internal \n| stats count by status"
},
"name": "Status"
},
"ds_6v2nFTBZ": {
"type": "ds.search",
"options": {
"query": "index=_internal method=\"$method$\" \n| search status IN ($status$)\n| timechart count by status"
},
"name": "Status codes per method"
}
},
"defaults": {
"dataSources": {
"ds.search": {
"options": {
"queryParameters": {
"latest": "$global_time.latest$",
"earliest": "$global_time.earliest$"
}
}
}
}
},
"inputs": {
"input_global_trp": {
"type": "input.timerange",
"options": {
"token": "global_time",
"defaultValue": "-24h@h,now"
},
"title": "Global Time Range"
},
"input_08lrAW9u": {
"options": {
"items": ">frame(label, value) | prepend(formattedStatics) | objects()",
"defaultValue": "*",
"token": "method"
},
"title": "Select Method",
"type": "input.dropdown",
"dataSources": {
"primary": "ds_ljNWYr7J"
},
"context": {
"formattedConfig": {
"number": {
"prefix": ""
}
},
"formattedStatics": ">statics | formatByType(formattedConfig)",
"statics": [
[
"All"
],
[
"*"
]
],
"label": ">primary | seriesByName(\"method\") | renameSeries(\"label\") | formatByType(formattedConfig)",
"value": ">primary | seriesByName(\"method\") | renameSeries(\"value\") | formatByType(formattedConfig)"
}
},
"input_RhQr1bEx": {
"options": {
"items": ">frame(label, value) | prepend(formattedStatics) | objects()",
"defaultValue": "*",
"token": "status"
},
"title": "Select Status Code",
"type": "input.multiselect",
"dataSources": {
"primary": "ds_neN4LNL4"
},
"context": {
"formattedConfig": {
"number": {
"prefix": ""
}
},
"formattedStatics": ">statics | formatByType(formattedConfig)",
"statics": [
[
"All"
],
[
"*"
]
],
"label": ">primary | seriesByName(\"status\") | renameSeries(\"label\") | formatByType(formattedConfig)",
"value": ">primary | seriesByName(\"status\") | renameSeries(\"value\") | formatByType(formattedConfig)"
}
}
},
"layout": {
"tabs": {
"items": [
{
"layoutId": "layout_1",
"label": "New tab"
}
]
},
"layoutDefinitions": {
"layout_1": {
"type": "grid",
"structure": [
{
"item": "viz_1BAm6ljX",
"type": "block",
"position": {
"x": 0,
"y": 0,
"w": 1200,
"h": 400
}
}
]
}
},
"globalInputs": [
"input_global_trp",
"input_08lrAW9u",
"input_RhQr1bEx"
]
},
"description": "",
"title": "Inputs Examples"
}
Adding and configuring inputs
Click the Add Input icon and select the desired input type.
In the Configuration panel, configure the following options for your input:
For Display, select one of the following:
Above canvas: place inputs that impact the entire dashboard, global inputs, or inputs that the user will only set once above the canvas. The dashboard definition lists inputs placed above the canvas in the
globalInputssub-stanza in thelayouttop-level stanza.In canvas: place inputs that only impact a small number of dashboard components in the canvas so that you can place them near those components. Inputs placed inside the dashboard's canvas are not global. The dashboard definition lists inputs placed in the canvas in the
structuresub-stanza in thelayout > layoutDefinitions > <layoutName>sub-stanza. For an input placed in the canvas, you can also do the following:- Drag the input to any location within the canvas.
- Change the width and height.
- Adjust the input's alignment within its bounding box to top, middle or bottom.
- Select a background color.
Under Visibility, you can configure visibility settings for the input. For example, if the input depends on a token being set, you can hide it until the user sets that token. Consider that you have a dropdown that lists cities after a user selects a country from a separate dropdown. You would want to configure the city dropdown to only be visible once the token from the country dropdown is set. You can also configure advanced conditional visibility. See Conditionally show or hide panels.
Under Source code, you can configure the source code for this input. See Input configuration options.
Configure other options as needed. This topic provides general information applicable for configuring all input types. For information about configuring a specific input type, see the topic for that input type.
Manually refresh dashboards with a submit button
You can add a submit button so the dashboard only refreshes once the user has selected all input choices and clicks the submit button. If a dashboard includes a submit button, searches will not run until a user interacts with the submit button, even if the inputs have default values.
The submit button is a special input that is distinct from the generic button and you must configure it by editing the dashboard definition in the source code editor. The following table summarizes the options related to the submit button:
| Option | Description |
|---|---|
submitButton | When true, a user must click the submit button for input selections to take effect on the dashboard. Otherwise, the dashboard immediately refreshes when a user makes a selection from an input. |
submitOnDashboardLoad | Requires submitButton to be set to true on the dashboard. When true, searches automatically run when the dashboard loads initially without requiring the user to click the submit button. After the initial load, the user must click the submit button to refresh the dashboard's searches and visualizations.When false, searches do not run when the dashboard loads initially. The user must click the submit button for searches to run. |
The following layout example shows where to add submitOnDashboardLoad and submitButton settings:
{
"layout": {
"globalInputs": [],
"type": "absolute",
"options": {
"submitButton": true,
"submitOnDashboardLoad": true,
"display": "auto-scale"
},
"structure": []
}
}
Dashboard definition example with multiple and cascading inputs
The following example shows a dashboard with 2 visualizations: a map and a table, and 4 inputs: a Select Country dropdown, a Select Region multiselect, a Submit button, and a Number of rows in table number input.
In this dashboard, submitOnDashboardLoad is set to true, meaning that searches run when the dashboard runs initially without the user having to click the Submit button. However, since the visualizations rely on the tok_region token set by the Select Region dropdown, the visualizations display the Set token value to render visualization message when the dashboard loads. The following shows the dashboard when it initially loads:
The user can interact with these inputs in the following order:
From the Select Country dropdown, select the desired country to view data for. The options available for selection in this dropdown are dynamically populated by the Base geo search data source associated with the dropdown.
Click the Submit button for the country selection to take effect on the dashboard. This causes the Select Region multiselect to display, as it is configured to only display once the tok_country token from the Select Country dropdown is set.
From the Select Region multiselect, select the desired region to view data for. The options available for selection in this multiselect are dynamically populated by the Region Input data source associated with the multiselect. The Region Input data source uses the token set by the Select Country dropdown, tok_country, in its query. As the Select Region multiselect requires a selection from the Select Country dropdown, it is an example of a cascading input.
Click the Submit button again for the region selection to take effect on the dashboard. The visualizations populate with data for the selected region.
In the Number of rows in table number input, enter the number of rows for the Region Results table to display. The data source for the Region Results table uses the token from the number input, $maximum_row$, to set the number of rows displayed. Note that the number input is placed in the canvas and therefore can be configured with a background color, unlike the inputs above the canvas. The number input is placed directly above the only visualization that it affects.
Copy and paste the dashboard definition into your own dashboard. Note that in the layout stanza, the globalInputs sub-stanza includes the Select Country dropdown (input_3Fh6Evau) and the Select Region (input_2k4rfudu) multiselect, which are above the canvas. You can find the Number of rows in table number input (input_V18pAYFh) under layout > layoutDefinitions > layout1 > structure and the Submit button under layout > layoutDefinitions > options.
{
"title": "Inputs Example Dashboard",
"description": "",
"inputs": {
"input_2k4rfudu": {
"context": {
"formattedConfig": {
"number": {
"prefix": ""
}
},
"formattedStatics": ">statics | formatByType(formattedConfig)",
"label": ">primary | seriesByName(\"Region\") | renameSeries(\"label\") | formatByType(formattedConfig)",
"statics": [],
"value": ">primary | seriesByName(\"Region\") | renameSeries(\"value\") | formatByType(formattedConfig)"
},
"dataSources": {
"primary": "ds_KvSXG9FI"
},
"hideWhenNoData": true,
"options": {
"items": ">frame(label, value) | prepend(formattedStatics) | objects()",
"token": "tok_region"
},
"title": "Select Region",
"type": "input.multiselect"
},
"input_3Fh6Evau": {
"context": {
"formattedConfig": {
"number": {
"prefix": ""
}
},
"formattedStatics": ">statics | formatByType(formattedConfig)",
"label": ">primary | seriesByName(\"Country\") | renameSeries(\"label\") | formatByType(formattedConfig)",
"statics": [],
"value": ">primary | seriesByName(\"Country\") | renameSeries(\"value\") | formatByType(formattedConfig)"
},
"dataSources": {
"primary": "ds_LUzvuQpA"
},
"options": {
"items": ">frame(label, value) | prepend(formattedStatics) | objects()",
"token": "tok_country"
},
"title": "Select Country",
"type": "input.dropdown"
},
"input_V18pAYFh": {
"options": {
"backgroundColor": "#fbf6ef",
"defaultValue": 10,
"token": "maximum_rows"
},
"title": "Number of rows in table",
"type": "input.number"
}
},
"defaults": {
"dataSources": {
"ds.search": {
"options": {
"queryParameters": {
"earliest": "$global_time.earliest$",
"latest": "$global_time.latest$"
}
}
}
}
},
"visualizations": {
"viz_USCUMdZx": {
"dataSources": {
"primary": "ds_hf4OdRZr"
},
"description": "Country: $tok_country|s$ | Region: $tok_region|s$",
"options": {
"center": [
2.842170943040401e-14,
0
],
"layers": [
{
"latitude": "> primary | seriesByName('lat')",
"longitude": "> primary | seriesByName('lon')",
"type": "marker"
}
],
"zoom": 0
},
"title": "Filtered Map",
"type": "splunk.map"
},
"viz_hqaDICFD": {
"dataSources": {
"primary": "ds_hf4OdRZr"
},
"options": {
"backgroundColor": "#fbf6ef",
"tableFormat": {
"headerBackgroundColor": "> backgroundColor | setColorChannel(tableHeaderBackgroundColorConfig)",
"headerColor": "> headerBackgroundColor | maxContrast(tableRowColorMaxContrast)",
"rowBackgroundColors": "> table | seriesByIndex(0) | pick(tableAltRowBackgroundColorsByBackgroundColor)",
"rowColors": "> rowBackgroundColors | maxContrast(tableRowColorMaxContrast)"
}
},
"title": "Region Results",
"type": "splunk.table"
}
},
"dataSources": {
"ds_KvSXG9FI": {
"name": "Region Input",
"options": {
"extend": "ds_LUzvuQpA",
"query": "| where Country=\"$tok_country$\""
},
"type": "ds.chain"
},
"ds_LUzvuQpA": {
"name": "Base Geo Search",
"options": {
"query": "| inputlookup geomaps_data.csv\n| iplocation device_ip",
"queryParameters": {
"earliest": "-24h@h",
"latest": "now"
}
},
"type": "ds.search"
},
"ds_hf4OdRZr": {
"name": "Geo Table",
"options": {
"extend": "ds_LUzvuQpA",
"query": "| search Region IN ($tok_region|s$) \n| head $maximum_rows$"
},
"type": "ds.chain"
}
},
"layout": {
"globalInputs": [
"input_3Fh6Evau",
"input_2k4rfudu"
],
"layoutDefinitions": {
"layout_1": {
"structure": [
{
"item": "viz_USCUMdZx",
"position": {
"h": 400,
"w": 1200,
"x": 0,
"y": 0
},
"type": "block"
},
{
"item": "input_V18pAYFh",
"position": {
"h": 95,
"w": 1200,
"x": 0,
"y": 400
},
"type": "input"
},
{
"item": "viz_hqaDICFD",
"position": {
"h": 200,
"w": 1200,
"x": 0,
"y": 495
},
"type": "block"
}
],
"type": "grid"
}
},
"options": {
"submitButton": true,
"submitOnDashboardLoad": true
},
"tabs": {
"items": [
{
"label": "New tab",
"layoutId": "layout_1"
}
]
}
},
"expressions": {
"conditions": {
"condition_HILqiY2B": {
"name": "hide if no region",
"value": "isSet(\"tok_region\")"
}
}
}
}