API updates and migration advice

The custom visualizations API has been updated for the latest Splunk Enterprise software version.

If you used one of the previous versions of the API to build a custom visualization app, review the following versioned changes for details and migration requirements.

Changes to existing functionality require migration to support compatibility with the custom visualizations framework. Other updates add new functionality and migration is optional.

The Splunk Custom Visualization API does not support the base (search id="baseSearch" or post-process (search base="baseSearch") searches. Change these searches to inline searches to make them compatible. For more information see Overview of search types and uses in the Splunk Dashboards and Visualizations Manual.

Backwards compatibility

App code migrated to the newest API version is no longer compatible with the previous Splunk Enterprise software version. For published apps, use versioning to support separate compatibility with different Splunk Enterprise versions.

Migrating to 6.6

Changes to existing functionality

Software version 6.6 introduces a drilldown editor user interface for visualizations saved to dashboards.

The drilldown editor is available in dashboard edit mode. As of software version 6.6, the visualization Format menu no longer includes drilldown enablement and configuration settings for Splunk platform visualizations.

After saving a visualization to a dashboard, users can use the drilldown editor or Simple XML to configure drilldown behavior.

Update	Type of update	Changes	How to migrate
supports_drilldown Support flag for drilldown editor availability in visualizations.conf	A new UI editor is available in Splunk Enterprise 6.6. This flag determines whether the editor is available for a visualization.	Previous drilldown default behavior and configuration options in the Format menu might have changed.	Remove any existing drilldown configuration options in the Format menu. Add the supports_drilldown flag to visualizations.conf and set it to true to provide the drilldown editor option in dashboards.
display.visualizations.custom.drilldown Drilldown enablement setting in the custom visualization. Located in savedsearches.conf.	Indicates whether drilldown is enabled by default. Default value is all (enabled).	Replaces prior drilldown enablement settings in the Format editor.	Remove any existing drilldown configuration options in the Format menu and use the supports_drilldown flag to make the drilldown editor available to users. No other migration change is necessary.

New functionality in 6.6

Software version 6.6 introduces trellis layout. This feature lets users split search results on a field or aggregation to visualize values in separate segments.

Update	Type of update	Changes	Replaces	How to migrate
supports_trellis Support flag for trellis layout in visualizations.conf	Trellis layout lets users split search results over a field or aggregation. Visualizations appear in segments to show each field value.	Adds a new UI option and menu for configuring trellis layout on visualizations.	N/A	Add the flag to visualizations.conf to make the trellis layout configuration menu available for the visualization.

Migrating to 6.5

Changes to existing functionality

The following updates for software version 6.5 require migration in any apps built using the previous API version.

Update	Where	Type of update	Changes	Replaces	How to migrate
<splunk-control-group>	formatter.html	Change to supported API	Provides a component for wrapping input controls with layout, labels, and help text. CSS layout classes are deprecated and should no longer be used.	Replaces CSS layout classes for formatter controls. Replaces separate label and help text <div> elements.	Use this component to wrap formatter.html elements instead of using <div> elements with CSS classes. Labels and help text should no longer be declared explicitly using a separate <div>. See the Formatter API reference for more details.
Visualization namespacing syntax	formatter.html	Change to supported API	Provides an abbreviated syntax for referencing a visualization in the HTML file.	Previous fully qualified namespacing syntax should not be used.	Use the new namespacing for accuracy and stability. See the Formatter API reference for more details.
Base visualization interface and utility class location	SplunkVisualizationBase SplunkVisualizationUtils	File path change	The base interface and utility class files are located in the api/ directory.	These files are no longer located in the vizapi/ directory.	Update any file location references in your visualization code to use the api/ directory.

New functionality in 6.5

The following updates provide new functionality in the custom visualizations framework for software version 6.5. Migration is optional but recommended.

Update	Where	Changes	Replaces	How to migrate
New utility functions	SplunkVisualizationUtils	Provides new utilities for accessing color palettes, formatting dates and time, and boolean normalization.	N/A	Use the new utility functions to access commonly needed resources or functionality. Continue using the required security utilities. See Utility functions in the API reference for more details.
<splunk-color-picker>	formatter.html	Provides a way to set a preconfigured color palette type, extend a preconfigured palette, or create a custom color palette.	N/A	Use one of the preconfigured color palettes or specify custom colors for extending and creating new palettes. See the Formatter API reference for more details.
data.meta.done flag indicating search completion.	visualization.js	Provides a way to check for search completion.	N/A	Use the flag to handle large results sets from long running searches. See Data handling guidelines for more details.