About advanced XML
This section provides an introduction to building views using advanced XML. It describes basic concepts and provides some example views.
Simple XML and the Splunk Dashboard Editor
Before building a view using advanced XML, you may want to start with the Dashboard Editor, which uses simple XML. To add features not available with simple XML, convert views from simple XML to advanced XML using the following URI from Splunk Web:
- Caution: Not all features available in simple XML are available in advanced XML.
You can create and edit views according to your needs. Use simple XML for basic views. Use advanced XML for features not available from simple XML. For example, if you want to build a search view, or you want to use modules that are not available in simple XML.
In Splunk Enterprise, every element in a view, from the search bar to the results, derives from a module. Some invisible elements, such as searches running in the background, derive from modules as well. You build and configure views by selecting the appropriate modules and linking them together.
For example, the search bar is one module. Graphs and charts, text entry boxes, links, drop-down menus, and other components are also modules. The Module Reference in this manual lists all available modules, sorted by category. Splunk Web also displays modules sorted alphabetically at the following URL:
Module implementation is available in the following directory of a Splunk installation:
Modules use parameters to specify module-specific configurations, such as the size of a graph or chart, or the number of events to display per view. Use the <param> tag within a <module> tag to specify parameters. For example:
<module name="Message"> <param name="filter">*</param> </module>
The Module Reference lists the parameters that are available for each module. Some params are required, while others are optional. Some params have default settings.
Modules in a view pass information through a tree structure. For example, in a search view, search information passes from a parent module to child modules. Each child module can modify the search in some way. Finally, the search returns events or is transformed into results. For dashboard views, each panel in the dashboard is likely built from a separate search. In this case, you have more modules with smaller trees than a dashboard built from a single search.
The top-level module in a hierarchy uses the
layoutPanel attribute to specify its location within the view. Child modules in the tree that do not specify the
layoutPanel attribute inherit the attribute from their parent. Multiple panels in a view specify their position on the page using the
layoutPanel attribute. For example:
<module name="SearchBar" layoutPanel="mainSearchControls">
?showsource=true to the URL of any view to see the hierarchy of modules in the page. For example,
You can use intentions to pass search language modifications down the module tree hierarchy. Specifically, modules pass searches down the hierarchy, modifying the searches by adding intentions. Once a series of intentions reaches a special type of module -- a dispatching module -- the intentions are composed into a search that is run in Splunk Enterprise.
Most results modules are dispatching modules. If a results module does not have any results from a search by the time they are invoked in a view, the results module compiles the intentions and runs the resulting search.
There are two types of views: dashboards and search views. A Mako layout template defines each of these types of views. Mako templates are written in Python. Splunk Enterprise layout templates define page layout, or how each element fits into a page. You can find the layout templates in the following location:
Dashboards use a series of rows and columns in their layout. Search views contain a search bar at the top, an events view area, and a few other areas for customization.
Dashboards display results from a variety of different searches, typically using results modules. A search view contains a set of search modules. The search passes through any number of modules, displaying results in one or more results modules. You can add other modules to dashboard views and search views as necessary.
You can use CSS to modify the appearance of a view. For example, you can modify the CSS to float a module next to another module, or move one module below another module. For more information about how to change CSS for a view, see Customize CSS in this manual.
Basic steps to configure a view
The basic steps to configure a view are:
1. Decide which modules to include in your view.
2. Configure each module in
<view_name>.xml in the views directory, inside your app directory. Use either of the following two locations:
- Note: Be careful about using the
- If you are creating your own app, use the
- If you are customizing an app shipped with Splunk (for example, the search app), or an app you installed from another source, use the
localdirectory. If you use the
defaultdirectory in this case, your changes can be overwritten by an update to the app.
4. If you have more than one view for your app, arrange the views in the UI by following the instructions in Build navigation.
5. To change the CSS for a view, Customize CSS.
Useful URIs for view building
Here are some URIs that provide useful information about your system when building a view. These are especially useful when building views through the file system, and not using Splunk Web.
Tools available with info
The most useful toolset for building views is the info endpoint. This page offers a list of all available modules, RelaxNG schemas for building views, and many other utilities.
Use this endpoint to view the implementation of the underlying advanced XML for a view. The advanced XML is available in a tree view and as source code. You use this endpoint to convert simple XML to advanced XML.
This endpoint provides a list of all advanced XML modules, sorted alphabetically. Compare with the Module Reference, available in this manual, sorted by functionality.
Display a new view
Use this endpoint to access a view that is newly added to a Splunk Enterprise instance.
Reload a specific view
Use this endpoint to refresh a specific view in Splunk Web.
Use this endpoint to refresh a specific view in Splunk Web.
Reload all views
Reload all views for the specified app.
Reload the navigation menu in Splunk Web.
About editing XML
Here are a few suggestions about editing XML files for views.
Special characters in XML files
Some characters have special meaning in an XML file and cannot be used literally. You can wrap the text within CDATA tags as illustrated below. The XML parser does not process text within CDATA tags.
<![CDATA[ <code>"Text within a CDATA tag"</code> ]]>
Or you can escape these characters using HTML entities:
Schemas and editors
Splunk recommends that you use an XML editor that understands XML schemas. Schemas are useful for validating XML and also provide guidelines for building an XML file.
Many XML editors let you load a schema -- DTD, XSD, Relax, RelaxNG are just a few different types of schemas. Splunk Enterprise contains RelaxNG formatted schemas for views, from dashboards to form searches to advanced XML views.
Read more about how to use the Splunk Enterprise schemas in the Use XML schemas topic in this manual.
With advanced XML, you often nest child modules several levels deep. It is a good idea to use consistent indentation and commenting to ensure that you properly close parent modules.
Use cases for this manual
Build a search view using advanced XML
This documentation applies to the following versions of Splunk® Enterprise: 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15