Parameters.md

Workbook Parameters

Parameters allow workbook authors to collect input from the consumers and reference it in other parts of the workbook – usually to scope the result set or setting the right visual. It is a key capability that allows authors to build interactive reports and experiences.

Workbooks allow you to control how your parameter controls are presented to consumers – text box vs. drop down, single- vs. multi-select, values from text, JSON, KQL or Azure Resource Graph, etc.

Supported parameter types include:

• Time - allows a user to select from prepopulated time ranges or select a custom range
• Drop down - allows a user to select from a value or set of values
• Text - allows a user to enter arbitrary text
• Resource - allows a user to select one or more Azure resources
• Subscription - allows a user to select one or more Azure subscription resources
• Resource Type - allows a user to select one or more Azure resource type values
• Location - allows a user to select one or more Azure location values

These parameter values can be referenced in other parts of workbooks either via bindings or value expansions.

Creating a parameter

1. Start with an empty workbook in edit mode.
2. Choose Add parameters from the links within the workbook.
3. Click on the blue Add Parameter button.
4. In the new parameter pane that pops up enter:
   1. Parameter name: TimeRange (note that parameter names can not include spaces or special characters)
   2. Display name: Time Range (however, display names can include spaces, special characters, emoji, etc)
   3. Parameter type: Time range picker
   4. Required: checked
   5. Available time ranges: Last hour, Last 12 hours, Last 24 hours, Last 48 hours, Last 3 days, Last 7 days and Allow custom time range selection
5. Choose 'Save' from the toolbar to create the parameter.

This is how the workbook will look like in read-mode, in the "Pills" style.

Referencing a parameter

Via Bindings

1. Add a query control to the workbook and select an Application Insights resource.
2. Open the the Time Range drop down and select the Time Range option from the Parameters section at the bottom.
3. This binds the time range parameter to the time range of the chart. The time scope of the sample query is now Last 24 hours.
4. Run query to see the results

In KQL

1. Add a query control to the workbook and select an Application Insights resource.
2. In the KQL, enter a time scope filter using the parameter: | where timestamp {TimeRange}
3. This expands on query evaluation time to | where timestamp > ago(1d) which is the time range value of the parameter.
4. Run query to see the results

In Text

1. Add a text control to the workbook.
2. In the markdown, enter The chosen time range is {TimeRange:label}
3. Choose Done Editing
4. The text control will show text: The chosen time range is Last 24 hours

Parameter formatting

The In Text section used the label of the parameter instead of its value. Parameters expose various such options depending on its type - e.g. time range pickers allow value, label, query, start, end and grain.

Use the Previews section of the Edit Parameter pane to see the expansion options for your parameter:

For more specific examples of formatting times, see Time formatting

Formatting parameters using JSONPath

For string parameters that are json content, you can use a JSONPath format in the parameter format string.

For example, you may have a string parameter named selection that was the result of a query or selection in a visualization that has the following value

{ "series":"Failures", "x": 5, "y": 10 }

Using JSONPath, you could get individual values from that object:

format	result
{selection:$.series}	Failures
{selection:$.x}	5
{selection:$.y}	10

Note: If the parameter value is not valid json, the result of the format will be an empty value.