Advanced XML structure

Before we dig into the modules provided, let's look at the structure of XML itself and cover a couple of concepts.

The tag structure of an advanced XML document is essentially as follows:

view 
module 
param 
... 
module 
... 

The main concept of Splunk's XML structure is that the effects of the upper modules flow downstream to the child modules.

This is a vital concept to understand. The XML structure has almost nothing to do with layout and everything to do with the flow of data.

Let's look at the following simple example:

<view 
template="dashboard.html"> 
<label>Chapter 9, Example 1</label> 
<module 
name="HiddenSearch" 
layoutPanel="panel_row1_col1" 
autoRun="True"> 
<param name="earliest">-99d</param> 
<param name="search">error | top user</param> 
<module name="SimpleResultsTable"></module> 
</module> 
</view> 

This document produces the following sparse dashboard with one panel:

Let's step through this example line by line:

• <view: This opens the outer tag. This tag begins all advanced XML dashboards.
• template="dashboard.html">: This sets the base HTML template. Dashboard layout templates are stored in the following path:

$SPLUNK_HOME/share/splunk/search_mrsparkle/templates/view/

• Among other things, the templates define the panels available for use in layoutPanel.

• <label>Chapter 9, Example 1</label>: This sets the label used for navigation.
• <module: This begins our first module declaration.
• name="HiddenSearch": This is the name of the module to use. HiddenSearch runs a search but displays nothing, relying instead on child modules to render the output.
• layoutPanel="panel_row1_col1": This states where in the dashboard to display our panel. It seems strange to give this attribute to a module that displays nothing, but layoutPanel must be specified on every immediate child of view. See the Understanding layoutPanel section for more details.
• autoRun="True">: Without this attribute, the search does not run when the dashboard loads, and instead waits for user interaction from form elements. Since we have no form elements, we need this attribute in order to see the results.
• <param name="earliest">-99d</param>: It is very important to specify a value at the earliest as the query will, by default, run over all time. param values affect only the module tag they are nested directly inside.
• <param name="search">error | top user</param>: This is the actual query to run.
• <module name="SimpleResultsTable"></module>: This module simply displays a table of the events produced by a parent module. Since there are no param tags specified, the defaults for this module are used.
• </module>: Close the HiddenSearch module. This is required for valid XML, but it also implies that the scope of influence of this module is closed. To reiterate, only the downstream modules of the HiddenSearch module receive the events it produces.
• </view>: This closes the document.

This is a very simple dashboard. It lacks navigation, form elements, job status, and drilldowns. Adding all of these things is initially somewhat complicated to understand. Luckily, you can build a dashboard in simple XML, convert it to advanced XML, and then modify the provided XML as needed.