Build a dashboard using advanced XML

Important notice: The Advanced XML dashboard framework is officially deprecated. For more information, see Advanced XML Deprecation.

Use advanced XML to add features to dashboards that are not available using simple XML. This topic provides an example of building a dashboard using advancedXML.

It is easiest to start building a dashboard with simple XML, and then convert to advanced XML to add advanced features. However, this example shows how to create a dashboard using advanced XML only within the file system.

Here's a general overview of how to build a dashboard:

1. Decide how to visualize and display your data. For example, you may want to showcase your search results in a graph or you may want to present a list of links to search results.
2. Construct searches and optionally save them.
3. Build panels for each search.
4. Construct a dashboard from the panels.
5. Finally, lay out the dashboard panels.

Begin your dashboard

In an XML editor, create a minimal dashboard file, listed below in the following directory:

$SPLUNK_HOME/etc/apps/<your_app>/default/data/ui/views/

Minimal XML file:

<view template="dashboard.html">
. . .
</view>

Dashboard views always specify dashboard.html for the dashboard template. Dashboard views use a different Mako template than the default template used by search views, so you must specify this template at the beginning of your dashboard's XML file.

You can set the refresh rate for a dashboard using the refresh=<seconds> attribute, as indicated below. This attribute specifies how often to rerun HiddenSearches or get any new HiddenSavedSearch results.

This example sets the dashboard to refresh every 30 minutes:

<view refresh="1800" template="dashboard.html">
. . .

Name a dashboard

Use the <label> tag to provide a name to a dashboard:

<view template="dashboard.html">
  <label>My Dashboard</label>
  . . .

Add chrome

Add chrome to define the appearance of the dashboard.

For each module, specify a layoutPanel to specify the chrome. The top-level module requires a layout panel. A nested module can optionally specify a layout panel. If you don't specify a layout panel for a nested module, it inherits the layout module from its parent. For the most control, it is a good idea to specify a layout panel for each module.

<view template="dashboard.html">
  <label>My Dashboard</label>
  <module name="AccountBar" layoutPanel="appHeader"/>
  <module name="AppBar" layoutPanel="navigationHeader"/>
  <module name="Message" layoutPanel="messaging">
    <param name="filter">*</param>
    <param name="clearOnJobDispatch">False</param>
    <param name="maxSize">1</param>
  </module>
</view>

Note: To see how the default Search dashboard specifies layout panels for its modules, go to:

http://localhost:8000/en-US/app/search/dashboard_live?showsource=true

Scroll to the XML source to view the implementation.

Chrome layout panels

Here are the available layout panels.

Module	Description
messaging	Use this layoutPanel for messaging modules.
appHeader	Contains all the overall links for the AccountBar.
navigationHeader	Use this layoutPanel for the AppBar module, which contains navigation for the app.
viewHeader	viewHeader is a header panel for a view. You can put a view TitleBar in this panel.

Add panels

A panel typically displays results of a search as a table, event listing, or other visualization such as a chart or graph. When building a dashboard, decide how you want to showcase your data with the available modules. Use results modules to display search results.

Here's an example panel:

And here's the XML behind this panel:

  <module name="HiddenSearch" layoutPanel="panel_row1_col1"
       group="Messages per minute last hour" autoRun="True">
    <param name="search">
       search index=_internal eps group=per_source_thruput NOT filetracker Metrics 
       | eval events=eps*kb/kbps | timechart sum(events)
    </param>
    <param name="earliest">-1h</param>

    <module name="ResultsHeader">
      <param name="entityName">scanned</param>
      <param name="entityLabel">Events</param>

      <module name="FlashChart">
        <param name="height">180px</param>
        <param name="width">100%</param>
      </module>

    </module>
  </module>

Each panel typically has only one search associated with it, usually with the HiddenSearch or HiddenSavedSearch module. Display results from the search in a results module, such as a chart or a link list. The panel from the previous example has three modules: HiddenSearch, ResultsHeader and FlashChart. HiddenSearch generates the search results while FlashChart displays them. ResultsHeader displays a header showing the amount of events searched by HiddenSearch.

HiddenSearch is the parent module and therefore specifies the layoutPanel, group, and autoRun settings. LayoutPanel denotes where to place the panel on the dashboard. Group is a header for the panel. AutoRun indicates that the search in the panel should be run upon loading the page. Typically, you set autoRun = true.

Searches and dashboard panels

A search for a panel can be either a report or an inline search.

Report: Create the search, save it as a report, and run the report on a schedule. Then reference the report results from your dashboard with the HiddenSavedSearch module. Reports are best for dashboards that are accessed by many users or where the underlying search is slow to complete.

Inline search: Specify the search query directly in the dashboard panel with the HiddenSearch module. This module runs the search every time the dashboard loads. Inline searches are best for dashboards that have only a few users and the search results return quickly.

Lay out your panels

Panels in a dashboards use a coordinate system to specify their position on the dashboard. The parent module in a panel specifies what coordinate to use. Coordinates specify the row and column position using the layoutPanel attribute to a <module> tag. For example:

<module layoutPanel="panel_rowX_colY">
   . . .

You can specify any number of rows, but you can only specify three columns. For example, here are two parent modules of panels in a dashboard:

<view>
. . .
  <module name="HiddenSearch" 
      layoutPanel="panel_row1_col1" 
      group="Messages per minute last hour"
      autoRun="True">
   . . .
   <module name="HiddenSearch" 
       layoutPanel="panel_row1_col2" 
       group="KBps indexed per hour last 2 hours"
       autoRun="True">
   . . .

You can also set up a group of panels within a larger panel using a single parent module. The following example uses StaticContentSample to set a header for the entire group of panels. Each panel has one parent module to specify the layoutPanel with the addition of the grp attribute for placement within a group.

<module name="StaticContentSample" 
    layoutPanel="panel_row2_col1" 
    group="All Indexed Data" 
    autoRun="True">
    <param name="text">
      This will show you all of the data you have loaded 
       into index=main over all time.
      </param>
  <module name="GenericHeader" 
      layoutPanel="panel_row2_col1_grp1">
     <param name="label">Sources</param>
  . . .
  <module name="GenericHeader" 
       layoutPanel="panel_row2_col1_grp2">
       <param name="label">Sourcetypes</param>
  . . .
  <module name="GenericHeader" 
       layoutPanel="panel_row2_col1_grp3">
       <param name="label">Hosts</param>
. . .

Add a search bar

You can add a search bar to a dashboard using the same panels you use for the search bar in a search view:

Module	Description
splSearchControls-inline	Aligns search modules next to each other in columns. The first module expands to occupy space not occupied by the other modules.
mainSearchControls	Aligns search controls one after another, typically using a vertical alignment.

The following example shows a search bar with a ViewRedirector module to launch searches in a different view.

 <module name="SearchBar" layoutPanel="mainSearchControls">
    <param name="useAssistant">true</param>
    <param name="useTypeahead">true</param>
    <module name="TimeRangePicker">
      <param name="selected">This month</param>
      <module name="ViewRedirector">
        <param name="viewTarget">simple_search_view</param>
      </module> <!-- End ViewRedirector-->
    </module> <!-- End TimeRangePicker-->
 </module> <!-- End SearchBar-->