Forms: An introduction
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Forms: An introduction
A form is a Splunk view similar to a dashboard, but provides an interface for users to supply values to one or more search terms, typically using text boxes, dropdown menus, or radio buttons. A form shields users from the details of the underlying search – it allows users to focus only on the terms for which they are searching and the results. The results can be displayed in tables, event listings, or any of the visualizations available to dashboards.
For example, consider a help desk support team that searches on a serial number and user name for every support case. You can create a form search that shows a dropdown list for a serial number and a text box for a user name. A support engineer can then easily search for the relevant data for a support case.
Forms live within apps, which means you can set permissions on a form the same way you can with a saved search, event type, or other object. Once you build a form you can navigate directly to it. For example,
This section describes the various types of forms and how to build a form search. It includes basic examples that you can use to get started. You can find additional examples in the Sample app available from your Splunk installation and the UI Examples app available from [Splunkbase].
Form owners and permissions
Forms are either private to a user, available to users of an app, or available to all users. In this respect, they are much like dashboards.
Splunk places private forms in the following location:
Splunk places forms available to users of an app (or available to all users) in the following location:
You can change the read and write permissions to a form for users, based on their Splunk user roles.
About form searches
Form searches are built on fields or other identifiable parts of your data. Typically, you first build a search that fits your data and use case. Then, identify the parts of this search that can be specified by the user. Finally, build a form search view (or embed your form search in a dashboard).
Form searches use tokens for search fields that accept user data. When a user types in a search term of a form, the token is replaced with the user input. For example, the following form search provides a textbox to specify the value for
series in a search. Here is the underlying search for this form:
index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | fields eps, kb, kbps
Here is the Simplified XML implementing the form search. The token
$series$ represents the text entered by the user in the text box. The form also includes the default Splunk TimePicker to allow the user to select a time range for the search.
<form> <label>Sample form</label> <!-- define master search template --> <!-- leave time unbounded so that the time input can be used --> <!-- $series$ is the token replaced by the input in the textbox --> <searchTemplate> index=_internal source=*metrics.log group="per_sourcetype_thruput" series=$series$ | fields eps, kb, kbps </searchTemplate> <fieldset> <!-- Create a text box; token is "series" --> <!-- label: Label for the text box --> <!-- default: A default value is not specified --> <!-- seed: Upon first load, the text box specifies 'splunkd' --> <!-- suffix: All tokens are followed by a * --> <!-- If user does not specify text, then search uses '*' --> <input type="text" token="series"> <label>sourcetype</label> <default></default> <seed>splunkd</seed> <suffix>*</suffix> </input> <!-- Add default TimePicker --> <input type="time" /> </fieldset> <row> <!-- Show results as a table --> <table> <option name="showPager">true</option> <option name="count">20</option> </table> </row> </form>
The Splunk sample app contains several example form searches. An example similar to this example, plus two others that contain dynamically populated radio buttons and drop downs. The dynamic form search views present different options in the radio buttons and drop downs depending on your data. Adapt these examples to fit your use case.
Types of form search views
There are three different types of form views:
- Simple form search The most basic form, a simple form search contains one or more text input boxes. Simple form searches use Splunk's Simplified XML, which is also used to create dashboards described in the previous section.
- Dynamic form search Form searches contain drop-down lists or radio buttons that display choices created by different searches. The available choices are dynamically populated from these searches. Use Simplified XML to create dynamic form searches.
- Advanced form search Use Splunk's Advanced XML to build complex form searches. The ExtendedFieldSearch module documentation describes features available in advanced form searches. Splunk recommends that you start with the Simplified XML and move on to the advanced only if there are options you cannot enable. To learn more about building an advanced form search, see the topic How to build an advanced form search.
Simplified XML and Advanced XML
Most of the documentation in this section describes creating and editing forms using Simplified XML. Simplified XML sits on top of Splunk's Advanced XML implementation. Complex forms might need to leverage functionality only available from Advanced XML.
You can always convert Simplified XML to Advanced XML. However, you cannot later go back to Simplified XML. Splunk recommends that you start advanced projects in Simplified XML, and then convert them later to Advanced XML to add the more complex features. "Introduction to advanced views" in this manual provides details on editing Advanced XML.
To convert Simplified XML to Advanced XML use the showsource URI:
Use HTML entities for special characters
XML does not support the following five characters. Use HTML entities to display these characters:
| || |
| || |
| || |
| || |
| || |