How the dashboard definition is structured in the source editor

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.

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 Use data sources.

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. For more information on on visualizations, see The elements of a visualization.

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 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 Use layout options to modify your dashboard canvas with the source editor.

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.

For more information on inputs see Use inputs and tokens.

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 and tokens 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"
				}
			}
		}