Build a form search

Build a form search

Form searches are pages in Splunk Web that let you present a simplified search interface. Instead of requiring your users to type in a full search string every time they want to search on something, form searches let you alias out the part of the search that will remain the same for all users. For example, a tier 1 help desk support team may always search on serial number and user name. You can create a form search that only shows an input for a serial number and a user name so that whenever a tier 1 representative gets a call, he or she can input just the relevant search terms.

Form searches let you alias out pieces of your search as tokens, so users only need to type in a search term for each token. For example, here's a form search from the Sample App:

Before you build a form search, you should understand the basics of how to build a custom UI in Splunk. Also, you may want to know more about how Splunk's simplified XML works here. Then, decide what your form search will look like, which fields you want to alias out and which you want to accept input from your users.

Form searches are built on fields or other identifiable parts of your data. First, build a search that fits your data and use case. Then, identify which parts of this search can be aliased out and hidden from your user. Finally, build a form search view.

App builder contains three example form searches. One of these is a basic search built on the "from" field in sendmail events. The other two examples contain dynamically populated radio buttons and drop downs. These two 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 search views, all building on the same basic concept described above:

Simple form search

The most basic form search is one or more text input boxes as described above. These simple form searches are built on the same simplified XML structure as simple dashboards. All the form search examples in app builder use this simplified XML format.

Dynamic form search

Form searches can contain more than search boxes for text input. Build form searches with drop-downs or radio buttons that display choices from a search. These form searches are called dynamic form searches because the choices are dynamically populated from a search. If you want to build a form search with dynamically populated radio buttons or drop downs, read about dynamic form search.

Advanced form search

If you're comfortable with Splunk's advanced XML syntax, you can build a more sophisticated form search with the ExtendedFieldSearch module within a search view.

Build a simple form search

First, use the searchTemplate attribute to create the search that runs behind the form. Then put dollar signs around the term (or terms) that will get user input:

<searchTemplate>put your search here $term$</searchTemplate>

You can put any kind of search here, as long as you surround the term that you want to replace via the form with $.

Then, to add a form to your page, wrap an input type attribute with a fieldset element:

<fieldset>
        <input type="text" token="username" />
</fieldset>

This will create a form in your page to take user input.

For example, this snippet creates a form that takes in a value of username:

<form>
    <label>My form search</label>
    <searchTemplate>$username$</searchTemplate>

    <fieldset>
        <input type="text" token="username" />
    </fieldset>
    
...

</form>

More form options

There are more options for configuring forms. Set any of these options as additional elements within the input type element.

add a label

Add a label to your form. Use this to add hints or explanation so your users know what kinds of search terms to input. To add a label, use the label attribute.

This example adds Enter a user name before the form:

<input type="text" token="username">
    <label>Enter a user name</label>
</input>

set a default search term

By default, if the user does not fill in the text box when submitting values, the token will be replaced with an empty string. You can change this behavior by setting a default value to fill in the field, or fields, of your form search. To set a default value, use the default attribute.

This example sets Juliet as the default username:

<input type="text" token="username">
    <default>Juliet</default>
</input>

add a prefix or suffix

Your search terms may require additional suffixes or prefixes. Use the prefix and suffix attributes to add additional terms to your search. These will only be added on if a user enters a search into the form.

Set a prefix on your default value:

<input type="text" token="username">
    <prefix>username=</prefix>
</input>

Or quote your default value:

<input type="text" token="username">
    <prefix>username="</prefix>
    <suffix>"</suffix>
</input>

pre-populate form

You may want to pre-populate a form with To pre-populate the form upon loading the page, use the seed attribute.

This example will load a form with the username Jack already in the form:

<input type="text" token="username">
    <seed>Jack</seed>
</input>

Display results

Form searches output results using any of the panels available for simple dashboards.

events

If you just want to display a list of events, add an events node to your form search. The event panel displays the search results as individual events. This panel supports the general options listed above and the following options.

• count = integer
  • The maximum number of rows to display.
• displayRowNumbers = true | false
  • Toggle whether row numbers are shown to the left of results.
• entityName = events | results
  • Toggle whether to show events or results. Events are individual events, while results are created by statistical operators.
  • Defaults to results.
• segmentation = none | inner | outer | full
  • Set the segmentation of events displayed. This affects what you can and can't click on within the event.
• maxLines = integer
  • The maximum number of lines to display for each result/event.
• showPager = true | false
  • Toggle pagination on or off.

<form>
    <label>Username</label>
    
    <searchTemplate>sourcetype=logins $username$</searchTemplate>
    
    <fieldset>
        <input type="text" token="username" />
    </fieldset>
    
    <row>
        <event>
            <option name="count">100</option>
        </event>
    </row>
</form>

Examples

Here are some more advanced examples using the simplified form search XML.

Multi-search form layout

Form searches can be much more interesting when pairing multiple output panels with a common set of inputs. By relocating the searchTemplate nodes out of the top level hierarchy and into each output panel, a composite form search can be made:

<form>
  <label>Form search example 3 - inverted flow, panel-defined search</label>

  <fieldset>

      <!-- define a common form search input that will be used by all panels
          below that implement a searchTemplate node -->
      <input type="text" token="username">
          <label>Global username</label>
          <default>NON_EXISTENT</default>
          <seed>johnvey*</seed>
      </input>

      <input type="time" />

  </fieldset>

  <row>
      <chart>
          <title>Commits over time</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | timechart count</searchTemplate>
          <option name="charting.chart">area</option>
      </chart>
      <table>
          <title>Top files touched by the user</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | top filePath</searchTemplate>
      </table>
  </row>

  <row>
      <table>
          <title>Users vs changetype</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | ctable user changetype maxcols=4</searchTemplate>
          <option name="count">20</option>
      </table>
      <chart>
          <title>Average lines added by the user</title>
          <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | timechart avg(added)</searchTemplate>
          <option name="charting.chart">line</option>
          <option name="charting.legend.placement">none</option>
      </chart>
  </row>

</form>

The above form search will dispatch 4 separate searches, though each search will use the user-entered value provided in the fieldset section. Obviously, the token attribute of each distinct search must match with at least one of the input nodes defined within the fieldset.

Single-search, multi-post process

Finally, a special permutation of form searches can take a single search and display different facets of that search through post-processing. For example, the previous example of 4 searches can be combined into 1 search by:

<form>
  <label>Form search example 4 - inverted flow, panel-defined post-process</label>

  <!-- define a search that returns, in one result set,  all of the data that is 
    needed by the subsequent panels -->
  <searchTemplate>sourcetype=p4change OR sourcetype=jira user="$username$" | head 10000</searchTemplate>

  <fieldset>

      <input type="text" token="username">
          <label>Global username</label>
          <default>NON_EXISTENT</default>
          <seed>johnvey*</seed>
      </input>

      <input type="time" />

  </fieldset>

  <row>
      <chart>
          <title>Commits over time</title>
          <searchPostProcess>timechart count</searchPostProcess>
          <option name="charting.chart">area</option>
      </chart>
      <table>
          <title>Top files touched by the user</title>
          <searchPostProcess>top filePath</searchPostProcess>
      </table>
  </row>

  <row>
      <table>
          <title>Users vs changetype</title>
          <searchPostProcess>ctable user changetype maxcols=4</searchPostProcess>
          <option name="count">20</option>
      </table>
      <chart>
          <title>Average lines added by the user</title>
          <searchPostProcess>timechart avg(added)</searchPostProcess>
          <option name="charting.chart">line</option>
          <option name="charting.legend.placement">none</option>
      </chart>
  </row>

</form>

The searchPostProcess node inside each panel instructs the form search to take the final search results and rerun them through a separate search pipeline. The basic model is to have a non-transforming search seeded in the searchTemplate node, and then apply transforming searches in the searchPostProcess nodes.

• Was this topic useful?
• Post a comment