Convert Simple XML dashboards to HTML

You can leverage the tools, flexibility, and power of the Splunk Web Framework by converting existing Simple XML dashboards into HTML. By working directly in HTML and JavaScript, you'll be able to customize your dashboards beyond what you can do in Simple XML:

  • Change the layout of visualizations.
  • Add formatting and custom CSS to your dashboards, add images, and anything else you can do in HTML.
  • Add and customize Splunk visualizations.
  • Customize drilldown and other interactive behaviors.
  • Integrate with third-party visualizations.

Many of these customizations can also be done using Simple XML extensions. However, HTML dashboards are especially useful when you want to:

  • Create a layout that is more advanced than the panel- and row-based layout used by the Dashboard Editor.
  • Use advanced input controls, such as a slider input selector.
  • Use custom REST endpoints for server-side logic.

After you convert a dashboard to HTML, it will be listed with your other dashboards and you can continue to manage it using Splunk Web (for example, to change permissions). However, be aware that when you convert a Splunk dashboard to HTML, the dashboard will lose these built-in features:

  • Interactive editing using the built-in Dashboard Editor
  • Integrated PDF generation and scheduled delivery

    Note  HTML dashboards are specific to the version of Splunk on which they are generated. Converted dashboards might not work if you upgrade Splunk later.

Learn more:

 

How Simple XML gets converted to HTML

A Simple XML dashboard consists of different types of visualizations: elements (such as tables, charts, maps, event viewers, and single views) and form inputs (such as radio buttons, text boxes, dropdowns, and time-range pickers).

When you convert Simple XML to HTML, each Simple XML visualization is converted into a SplunkJS Stack-equivalent Splunk view, with a wrapper around each view that includes a panel implementation, and a search manager if that visualization is bound to a search. In the autogenerated HTML, each visualization's layout, definition, and related searches are separated:

  • The layout is converted into Splunk's styles indicating how to place and format items on the page, similar to Bootstrap's grid system.
  • The definition of each visualization is converted into JavaScript. The code for each visualization includes its properties and an auto-generated ID.
  • Any search that is specified in a visualization is extracted and represented in JavaScript. The code for each search includes its properties and an auto-generated ID.

Here's a simple example that demonstrates the conversion of a visualization from XML to HTML. Let's start with a search that displays a result table:

index=_internal | head 5 | table host, source

When you save this search as a dashboard panel, the XML that is created for the table and title looks like this:

...
<row>
    <table>
        <title>Result table</title>
        <searchString>index=_internal | head 5 | table host, source</searchString>
    </table>
</row>
...

When converted to HTML, a layout is created that uses nested <div> tags to define a row containing a panel. The panel refers to the table's ID ("element1"), indicating that the table is displayed in that panel. The table's heading is also included in the panel. The HTML looks like this:

...
<div class="dashboard-row dashboard-row1">
    <div class="dashboard-cell" style="width: 100%;">
        <div class="dashboard-panel clearfix">
            <div class="panel-element-row">
                <!-- Display "element1" in this panel -->
                <div class="dashboard-element table" id="element1" style="width: 100%">
                    <div class="panel-head">
                        <h3>Result table</h3>
                    </div>
                    <div class="panel-body"></div>
                </div>
            </div>
        </div>
    </div>
</div>
...

The definition of the table and the search that powers it are defined separately in JavaScript. Just as the table ID connects the layout to the table, the search ID ("search1") also connects the table to its search via the table's managerid property. Here's the JavaScript:

...

var search1 = new SearchManager({
    "id": "search1",               // This is the search ID
    "status_buckets": 0,
    "earliest_time": "$earliest$",
    "search": "index=_internal | head 5 | table host, source",
    "latest_time": "$latest$",
    "cancelOnUnload": true,
    "app": utils.getCurrentApp(),
    "auto_cancel": 90,
    "preview": true
}, {tokens: true, tokenNamespace: "submitted"});

...

var element1 = new TableElement({
    "id": "element1",              // This is the table ID
    "managerid": "search1",        // This connects the table to the search
    "el": $('#element1')
}, {tokens: true}).render();

...

Without knowing much more than this, you can edit the HTML to make simple customizations. For example, you can add your own CSS, or change the layout (the default styles and how to use them are described in Splunk dashboard styles). But if you want to customize the way these visualizations behave and interact, you'll need to work with JavaScript and learn more about the SplunkJS Stack component of the Web Framework.

 

To convert a Simple XML dashboard to HTML

You need to have permission to be able to convert a dashboard, specifically a role that has the "edit_view_html" capability. For details, see About defining roles with capabilities.

  1. In Splunk Web, open the dashboard you want to convert.
  2. Click Edit and select Convert to HTML.
  3. Set the properties for the converted dashboard:
  4. Converting to HTML Dashboard

    • To create an HTML version of the dashboard, click Create New. Or, to replace and write over the existing dashboard, click Replace Current.
      1. Note  Replacing the current dashboard makes the HTML version of the dashboard visible to users and hides the Simple XML version. You can revert to the Simple XML dashboard by deleting the HTML file. The file locations depend on the permissions (see below).
    • Optionally, change the title, ID (the filename), description, and permissions.
  5. Click Convert Dashboard.
 

To edit an HTML dashboard

You can edit a converted HTML dashboard by by using the built-in Source Editor in Splunk Enterprise, or by opening the source file in a text editor of your choice.

Use the Source Editor

To use the Source Editor in Splunk Enterprise:

  1. In Splunk Web, find the dashboard you want to edit by clicking Settings, then User interface, then Views.
  2. Select the App context and Owner filters as appropriate to list your dashboards.
  3. Find your HTML dashboard in the list and click Edit, and then click Source to display the source code.

You can also click the Dashboards tab within any app to list dashboards.

Use your own text editor

To edit the source files for HTML dashboards in a text editor of your choice, you need access to source files on your Splunk instance. You might need to contact your Splunk administrator for permission and access.

The location of the HTML file depends on the permissions you chose for the dashboard:

  • Private: $SPLUNK_HOME/etc/users/username/appname/local/data/ui/html
  • Shared: $SPLUNK_HOME/etc/apps/appname/local/data/ui/html

The procedures throughout this documentation show the paths for shared permissions.