Splunk Cloud Platform

Splunk Dashboard Studio

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

What is a dashboard definition?

If you use Simple XML dashboards in Splunk Enterprise and Splunk Cloud Platform, you might be familiar with the option to edit the XML source code directly, in addition to using the visual editor. This same capability is available to you in the Splunk Dashboard Studio source editor using the JSON-formatted dashboard definition rather than Simple XML.

The dashboard definition is made up of the following five sections:

  • dataSources, where your data sources, searches, and options for each search you create in the visual editor are placed.
  • visualizations, where your visualization stanzas and their options are placed.
  • inputs, where you create your inputs stanzas.
  • defaults, were you set global defaults.
  • layout, where you list your inputs, change the size of your canvas, and modify your dashboards.

The source editor provides limited validation. However, you will not be able to click Back to save your changes if you have formatting errors. You might want to use a JSON validator to ensure that your formatting is correct.

How to format JSON stanzas

Every object on your canvas is defined in the format of a JSON-formatted stanza. Data sources, visualizations, inputs, defaults, and the layout all have similar hierarchies, but also some differences.

For example, you can give your data source stanza a name, separate from the unique ID, using the name property or give a visualization a title using the title property.

Using stanza punctuation

There are a few common rules when formatting JSON.

  • When setting options in the options property, boolean values and numbers do not require quotes.
  • Strings, such as plain text and hex color codes, must be wrapped in quotes.
  • Arrays must be enclosed in brackets.
  • Commas must come at the end of the line after each option entry except the last.
  • The list of options you use must be enclosed in curly braces followed by a comma.
  • Commas must separate each stanza in a section except for the last. For example, if there are three visualization stanzas in the visualization section of a dashboard definition, each stanza is separated by a comma after the last closing curly bracket, with the exception of the last visualization.
  • Commas must separate each property setting except the last.

If you get formatting error messages, you can use one of the many JSON formatting websites to check your code to identify the error.

In the following example of a data source section, the stanza has the unique ID of ds_search_1. Two queryParametersoptions are used, set to earliest and latest, as well as two properties, refresh set to 10 seconds, and refreshType set to delay. The trailing comma assumes there is another data source stanza following the one in the example.

To learn more about data source options and settings, see Data source options and properties.

To learn more about visualization-specific options and properties, see the section for the specific visualization you want to access.


	"dataSources": {
		"ds_search_1": {
			"type": "ds.search",
                        "name": "my search",
			"options": {
				"queryParameters": {
					"earliest": "$TimeRange.earliest$",
					"latest": "$TimeRange.latest$"
				},
				"query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)",
                                "refreshType": "delay",
			        "refresh": "10s"
			},
		},
	},

Example of a dashboard definition

The source editor is where you create your dashboard definition. The dashboard definition is the JSON source code that renders the dashboard in the visual editor. The following dashboard definition is a complete example. There is an overview of each section in this topic.

Source code

Expand the box to view the complete definition. You can copy/paste the code into your own instance to see the data at work.


{
	"visualizations": {
		"viz_chart_1": {
			"type": "viz.pie",
			"options": {			
                               "hasDonutHole": true,
                               "chart.showPercent": true
                       },
			"dataSources": {
				"primary": "search_1"
			},
			"description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$"
		}
	},
	"dataSources": {
		"ds_search_1": {
			"type": "ds.search",
			"options": {
				"queryParameters": {
					"earliest": "$TimeRange.earliest$",
					"latest": "$TimeRange.latest$"
				},
				"query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)"
			},
			"refreshType": "delay",
			"refresh": "10s"
		}
	},
	"inputs": {
		"input_1": {
			"type": "input.timerange",
			"title": "Select a time:",
			"options": {
				"token": "TimeRange",
				"defaultValue": "-24h,now"
			}
		}
	},
	"layout": {
		"options": {
			"submitButton": false,
			"height": 250,
			"display": "auto-scale",
			"width": 1200
		},
		"globalInputs": [
			"input_1"
		],
		"structure": [
			{
				"item": "chart_1",
				"type": "block",
				"position": {
					"x": 440,
					"y": 10,
					"w": 320,
					"h": 210
				}
			}
		],
		"type": "absolute"
	},
	"title": "Time Picker Input Example",
	"description": "Add a timerange picker to modify a search time span."
}

The dataSources section

The dataSources section of the dashboard definition is where you can modify the data source stanzas created in the source editor when you add searches to your visualizations. When you create a new data source in the form of an an ad hoc search through the visual editor Configuration panel, a unique ID is created for each data source automatically. Each data source must have a unique ID that is seperate from the title you might give it. You can change this unique ID as long as it remains unique in your dashboard definition. At the root of the section is "dataSources": {. This is where each data source stanza is placed.

Each data source has a field type. For more information on data sources and their types, see Data source options and properties.


There are four data source types:

  • ds.search
  • ds.chain
  • ds.savedSearch
  • ds.test


For example you use "type": "ds.search" if the data source is using a search to gather data.

For example:

"dataSources": {
		"ds_search_1": {
			"type": "ds.search",
			"options": {
				"queryParameters": {
					"earliest": "$TimeRange.earliest$",
					"latest": "$TimeRange.latest$"
				},
				"query": "index=_internal | top limit=100 sourcetype | eval percent = round(percent,2)"
			},
			"refreshType": "delay",
			"refresh": "10s"
		}
	},

The visualizations section

At the root of the JSON visualization section is "visualizations": {after which, all of your visualization stanzas are listed. Each visualization has a type. For example, a pie chart is of type viz.pie. Like the data source stanzas, each visualization has an options field. All of the options available for that particular visualization are listed with each visualization topic and in the Object options reference. For more information on options available for each visualization, see the Object options reference.

When setting options, boolean values and numbers do not require quotes, unlike strings, such as the hex color codes, which do. Commas must come after each entry except the last. The list of options you use must be enclosed in curly braces followed by a comma.

The dataSources field is where the connected data source ID is called. In this example, it is "search_1". You can also use a name field to name your visualization. This name, however, is different than the unique ID. Add a description field if you'd like to add description text to your visualization.

{
	"visualizations": {
		"chart_1": {
			"type": "viz.pie",
                        "name": "Pie-Chart",
			"options": {
                               "hasDonutHole": true,
                               "chart.showPercent": true
                       },
			"dataSources": {
				"primary": "search_1"
			},
			"description": "Chart of Top Sourcetypes between $TimeRange.earliest$ and $TimeRange.latest$"
		}
	},

The source code stanza of a visualization

When you add a visualization to your dashboard, a corresponding JSON stanza is created in the dashboard definition and given a unique ID.

There are two types of visualizations, those that begin with viz.<visualization>, such as the pie chart, viz.pie, and those that begin with splunk.<visualization>, such as splunk.table. Those visualizations that are of type splunk.<visualization> have options and settings that look different than many of the static and dynamic settings of those of the viz.<visualization> type. Additionally, while viz.<visualization> types that support dynamic elements, or thresholding, have a section called encoding where ranges and colors are set, splunk.<visualization> stanzas have an different section called context, where option variables are set before they are called in the options section of the visualization.

Most viz.<visualization> visualizations follow the same general format. For example, the following stanza represents a basic pie chart:

"viz_8bucihWZ": {
	"type": "viz.pie",
	"options": {
		"chart.showPercent": true
	},
	"dataSources": {
		"primary": "ds_IULrzuI8"
	}
}


A pie chart with dynamically updating colors and percentages.


Most splunk.<visualization> visualizations have the same initial format as the viz.<visualization> type, but become more complex when you apply dynamic formatting. For example, the following stanza represents a table with one column, the field splunk_web_access, formatted by gradient coloring. The colors are represented by the gradientConfig property set in the context section of the stanza and called in the top-level options section of the visualization stanza. Note that there are other options set as well.

{
   "type": "splunk.table",
   "options": {
       "columnFormat": {
           "_time": {
               "data": "> table | seriesByName(\"_time\") | formatByType(timeConfig)"
           },
           "splunk_web_access": {
               "rowBackgroundColors": "> table | seriesByName(\"splunk_web_access\") | gradient(gradientConfig)",
               "width": 160,
               "textOverflow": "break-word"
           }
       }
   },
   "dataSources": {
       "primary": "ds_IzyyreSf"
   },
   "context": {
       "timeConfig": {
           "time": {
               "format": "dddd, MMMM Do YYYY, h:mm:ss a"
           }
       },
       "gradientConfig": {
           "colors": [
               "#B6ECD4",
               "#35B9A0"
           ]
       }
   }

The following is an example of a table visualization with dynamic elements.

A table with one column dynamically colored green.

Visualization fields and settings

Each visualization can have the following fields:

Field Description Required
The unique ID The unique ID is automatically generated, but can be changed. If you change it, however, you must also change the visualization's ID in the layout. Yes
type The type is the kind of visualization you are using. For example, the table visualization type is splunk.table. You can change the type in the source code, much like using the Visualization Picker in the visual editor. It might or might not render depending on the way your data is structured. Yes
title This is the title name you can give your visualization. It is not the same as the unique ID and will not change the unique ID. No
description You can use this field to describe your visualization within the visualization panel. No
options List your options in this field. The formatting depends on the type of option and its setting format. For example, boolean values and integer values don't have quotes, strings require quotes, and arrays and objects have their own formatting requirements. Each value that you can only add to a visualization through the source editor has an example and its correct formatting in the visualization's topic section. No
context This is the field where dynamic variable elements are defined. For example, if you've formatted a table to have a specific column colored according to value ranges, the associated variable is defined with the colors and their ranges. This variable is then called in the options section, possibly as a setting that is a top-level option or an option that is nested within a top level option. If dynamic elements are used, and only with visualizations of type, splunk.<visualization>.
dataSources.primary This is where the unique ID of your primary data source is listed. A visualization can have only one primary data source. No
dataSources.secondary This is where the unique IDs of all secondary data sources are listed. No
dataSources.annotation This is where the unique ID of your annotation data source is listed. Currently, "annotation" is the only secondary data source that has its own designated name. No

The layout section

The layout stanza has four main settings fields. The options field, where you set your dashboard settings, globalInputs where you must list any inputs in your dashboard by their ID, structure which defines the width and height of your visualizations as well as where your visualizations are placed on the x-axis and y-axis of the dashboard canvas, and type which is either absolute or grid. When setting options, boolean values and numbers do not require quotes, unlike strings, such as the hex color codes, which do. Commas must come after each entry except the last. The list of options you use must be enclosed in curly braces followed by a comma.

If you create a visualization in the source editor, but forget to add it and its properties in the layout, it will not render. This is why you should always add visualizations in the visual editor first, and then edit them in the source editor if you need to. This way, the visualization is automatically added to the layout and given a unique ID.

The following is an example of a layout stanza:

	"layout": {
		"options": {
			"submitButton": false,
			"height": 250,
			"display": "auto-scale",
			"width": 1200
		},
		"globalInputs": [
			"input_1"
		],
		"structure": [
			{
				"item": "chart_1",
				"type": "block",
				"position": {
					"x": 440,
					"y": 10,
					"w": 320,
					"h": 210
				}
			}
		],
		"type": "absolute"
	},

The layout is also where you modify the canvas of your dashboard. For more information, see Compare absolute and grid layouts.

Use layout options to modify your dashboard canvas with the source editor

When you click on the canvas of your dashboard, you can change many of the dashboard layout settings in the visual editor Configuration panel. There are some options, however, that you can only set in the source editor, for example, adding a submit button for inputs.

The layoutsection of the dashboard definition is the section where the positions and sizes of visualizations, in pixels, are listed as they exist on the dashboard. You must also list any inputs in the globalInputs area of this section. For more information on inputs, see Specify inputs in the layout.

In the source editor, the layout section is where you can change the canvas size, background color, and background image settings to modify your dashboards.

In addition to the options field, there is a type field where you can specify whether to use the grid or absolute layout. You should not change this setting for populated dashboards, especially from absolute to grid, because it will likely result in the loss of your visualizations and an error message.

Some of the following options are available through the visual editor, others are only available using the options level of the layout section of the dashboard definition.

When some defaults are not changed in the visual editor, the corresponding source options and properties might not appear in the source editor. For example, if you don't change the default width and height of the dashboard, the width and height options and their settings will not appear in the editor. Similarly, if you don't change the display default, this option and setting will also not appear in the source code. To have them appear, you can either change the defaults or add and edit them manually in the source editor. The following is a layout example of these settings after the defaults have been changed in the visual editor.

"layout": {
        "globalInputs": [],
        "type": "absolute",
        "options": {
            "backgroundColor": "#C093F9",
            "backgroundImage":
                          {     "x": 0,                        
                                "y": 0,                       
                               "src": "splunk-enterprise-kvstore://5f6cc9810b19516995423ad1",                        
                                "sizeType": "contain"            
 }
            "submitButton": true,
            "width": 1198,
            "height": 898,
            "display": "auto-scale"
        },
        "structure": []
    },


Option Type Default Description
backgroundColor string lightmode: #FFFFFF darkmode: #FF0000 Splunk Cloud: #171D21 This option is not available if you are using the grid layout. Specify the color of the layout background color using a hex code, such as #FF0000.
display actual-size or auto-scale actual-size This option is not available if you are using the grid layout. Grid layout is always auto-sized.

Specify the display behavior. If this property is set to "actual-size", changing the size of your browser will not change the size of your dashboard or visualizations. If this property is set to "auto-scale", your dashboard and visualizations will automatically also change size.

submitButton boolean N/A You can specify the layout option submitButton. When set to true, a user must click a Submit button in order for the an input selection to take effect. If set to false, or if not specified at all, the dashboard will immediately refresh when a user makes a selection.
backgroundImage object N/A This option is not available if you are using the grid layout. A background image must be one of the following types: jpg, jpeg, png, svg, or gif. You can also use a web-based image using the backgroundImage.src option.
backgroundImage.w number N/A This option is not available if you are using the grid layout. Specify the image w (width) in pixels. You should not specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.h number N/A This option is not available if you are using the grid layout. Specify the image h (height) in pixels. You should not specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.x number (0,y) This option is not available if you are using the grid layout. Specify the position in pixels of the background image on the x-axis. You should not specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.y number (x,0) This option is not available if you are using the grid layout. Specify the position in pixels of the background image on the y-axis. You should not specify this option if you set the sizeType option. If you do, it will overrule that setting.
backgroundImage.src SRC N/A This option is not available if you are using the grid layout. Specify the location of a background image using the option src. For example: "src": "https://www.myImageLocation.com/galleryX/image1.png".
backgroundImage.sizeType auto or contain or cover contain This option is not available if you are using the grid layout. auto scales the image while maintaining the image proportion. contain increases the size of the of the image as much as possible without cropping or stretching it. cover increases the size of the image without stretching it. The image may be cropped vertically and horizontally so that no empty space is shown.
width number 1200 Specify the canvas width in pixels.
height number 900 Specify the canvas height in pixels.

The inputs section

Much like the other sections, inputs have fields for their unique ID, type, title, and options, and follow the same formatting rules as the other sections. Stanza fields and their values must be enclosed in quotes, unless the values are of the boolean or number type, and a comma must follow each of the field settings except for the last. Options are encased in curly braces.

Like visualizations, inputs must be called in the layout section.

The following example is an input of the time range type:

{
	"inputs": {
		"input_1": {
			"type": "input.timerange",
			"title": "Select a time:",
			"options": {
				"token": "TimeRange",
				"defaultValue": "-24h,now"
			}
		}
	}
}

To view the available input types, their associated options, and many more examples, see Use inputs to make dashboards dynamic.

The defaults section

Use the defaults section to set total global settings and global settings for a specific data source type or visualization type. All settings applied at the component, or stanza, level will override those in the defaults section. To read more about the defaults section, see more examples, and view the options available, see Create data source and visualization defaults.

The following is an example of what a defaults section looks like:


	"defaults": {
		"visualizations": {
			"global": {
				"showProgressBar": true
			},
			"viz.singlevalueradial": {
				"showProgressBar": true
			}
		},
                "ds.search": {
			"global": {
				"refresh": "interval"
				}
			}
		}
Last modified on 01 April, 2022
PREVIOUS
Source code editor
  NEXT
Advanced dynamic options syntax

This documentation applies to the following versions of Splunk Cloud Platform: 8.2.2201 (latest FedRAMP release), 8.2.2202, 8.2.2203


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters