Docs: Add actions to visualizations (#100684)

2025-02-26 18:35:30 -05:00
parent 2b0029267c
commit e0a4a69c2e
20 changed files with 183 additions and 46 deletions
@@ -18,11 +18,16 @@ labels:
    - cloud
    - enterprise
    - oss
-menuTitle: Configure data links
-title: Configure data links
+menuTitle: Configure data links and actions
+title: Configure data links and actions
 description: Configure data links to create links between dashboards and link to external resources
 weight: 80
 refs:
+  api-settings:
+    - pattern: /docs/grafana/
+      destination: /docs/grafana/<GRAFANA_VERSION>/panels-visualizations/visualizations/canvas/#button-api-options
+    - pattern: /docs/grafana-cloud/
+      destination: /docs/grafana/latest/panels-visualizations/visualizations/canvas/#button-api-options
  global-variables:
    - pattern: /docs/grafana/
      destination: /docs/grafana/<GRAFANA_VERSION>/dashboards/variables/add-template-variables/#__from-and-__to
@@ -125,9 +130,14 @@ refs:
      destination: /docs/grafana-cloud/visualizations/panels-visualizations/visualizations/bar-chart/
 ---

-# Configure data links
+# Configure data links and actions

-Data links allow you to link to other panels, dashboards, and external resources while maintaining the context of the source panel. You can create links that include the series name or even the value under the cursor. For example, if your visualization shows four servers, you can add a data link to one or two of them.
+_Data links_ allow you to link to other panels, dashboards, and external resources and _actions_ let you trigger basic, unauthenticated, API calls.
+In both cases, you can carry out these tasks while maintaining the context of the source panel.
+
+## Data links
+
+With data links, you can create links that include the series name or even the value under the cursor. For example, if your visualization shows four servers, you can add a data link to one or two of them.

 The link itself is accessible in different ways depending on the visualization. For the time series visualization you need to click a data point or line:

@@ -139,7 +149,7 @@ For visualizations like stat, gauge, or bar gauge you can click anywhere on the

 If there's only one data link in the visualization, clicking anywhere on the visualization opens the link rather than the context menu.

-## Supported visualizations
+### Supported visualizations

 You can configure data links for the following visualizations:

@@ -164,11 +174,32 @@ You can configure data links for the following visualizations:

 {{< /column-list >}}

-## Data link variables
+## Actions

-Variables in data links let you send people to a detailed dashboard with preserved data filters. For example, you could use variables to specify a label, time range, series, or variable selection.
+Using actions, you can trigger processes like starting or shutting down a server, directly from a dashboard panel. [API settings](ref:api-settings) are configured in the **Add action** dialog box. You can also pass variables in the API editor.

-To see a list of available variables, enter `$` in the data link **URL** field.
+### Supported visualizations
+
+You can configure actions for the following visualizations:
+
+{{< column-list >}}
+
+- [Bar chart](ref:bar-chart)
+- [Candlestick](ref:candlestick)
+- [State timeline](ref:state-timeline)
+- [Status history](ref:status-history)
+- [Table](ref:table)
+- [Time series](ref:time-series)
+- [Trend](ref:trend)
+- [XY chart](ref:xy-chart)
+
+{{< /column-list >}}
+
+## Data link and action variables {#data-link-variables}
+
+Variables in data links and actions let you send people to a detailed dashboard or trigger an API call with preserved data filters. For example, you could use variables to specify a label, time range, series, or variable selection.
+
+To see a list of available variables, enter `$` in the data link or action **URL** field.

 {{% admonition type="note" %}}
 These variables changed in 6.4 so if you have an older version of Grafana, then use the version picker to select docs for an older version of Grafana.
@@ -176,11 +207,11 @@ These variables changed in 6.4 so if you have an older version of Grafana, then

 Azure Monitor, [CloudWatch](ref:cloudwatch), and [Google Cloud Monitoring](ref:google-cloud-monitoring) have pre-configured data links called _deep links_.

-You can also use template variables in your data links URLs. For more information, refer to [Templates and variables](ref:templates-and-variables).
+You can also use template variables in your data links or actions URLs. For more information, refer to [Templates and variables](ref:templates-and-variables).

 ### Time range panel variables

-These variables allow you to include the current time range in the data link URL:
+These variables allow you to include the current time range in the data link or action URL:

 | Variable           | Description                                                              |
 | ------------------ | ------------------------------------------------------------------------ |
@@ -188,7 +219,7 @@ These variables allow you to include the current time range in the data link URL
 | `__from`           | For more information, refer to [Global variables](ref:global-variables). |
 | `__to`             | For more information, refer to [Global variables](ref:global-variables). |

-When you create data links using time range variables like `__url_time_range` in the URL, you have to form the query parameter syntax yourself; that is, you must format the URL by appending query parameters using the question mark (`?`) and ampersand (`&`) syntax. These characters aren't automatically generated.
+When you create data links and actions using time range variables like `__url_time_range` in the URL, you have to form the query parameter syntax yourself; that is, you must format the URL by appending query parameters using the question mark (`?`) and ampersand (`&`) syntax. These characters aren't automatically generated.

 ### Series variables

@@ -219,9 +250,9 @@ Value-specific variables are available under `__value` namespace:
 | `__value.text`    | Text representation of a value                                                    |
 | `__value.calc`    | Calculation name if the value is result of calculation                            |

-Using value-specific variables in data links can show different results depending on the set option of Tooltip mode.
+Using value-specific variables in data links and actions can show different results depending on the set option of Tooltip mode.

-When you create data links using time range variables like `__value.time` in the URL, you have to form the query parameter syntax yourself; that is, you must add the question mark (`?`) and ampersand (`&`). These characters aren't automatically generated.
+When you create data links and actions using time range variables like `__value.time` in the URL, you have to form the query parameter syntax yourself; that is, you must add the question mark (`?`) and ampersand (`&`). These characters aren't automatically generated.

 ### Data variables

@@ -247,20 +278,29 @@ When linking to another dashboard that uses template variables, select variable

 If you want to add all of the current dashboard's variables to the URL, then use `${__all_variables}`.

-## Add a data link
+## Add data links or actions {#add-a-data-link}
+
+The following tasks describe how to configure data links and actions.
+
+{{< tabs >}}
+{{< tab-content name="Add data links" >}}
+To add a data link, follow these steps:

 1. Navigate to the panel to which you want to add the data link.
 1. Hover over any part of the panel to display the menu icon in the upper-right corner.
 1. Click the menu icon and select **Edit** to open the panel editor.
-1. In the panel edit pane, scroll down to the **Data links** section and expand it.
+1. Scroll down to the **Data links and actions** section and expand it.
 1. Click **+ Add link**.
-1. In the dialog box that opens, enter a **Title**. This is a human-readable label for the link displayed in the UI. This is a required field.
-1. Enter the **URL** or variable to which you want to link. This is a required field.
+1. In the dialog box that opens, enter a **Title**.

-   To add a data link variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables.
+   This is a human-readable label for the link displayed in the UI. This is a required field.
+
+1. Enter the **URL** to which you want to link.
+
+   To add a data link variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. This is a required field.

 1. If you want the link to open in a new tab, toggle the **Open in a new tab** switch.
-1. If you want the data link to open with a single click, toggle the **One click** switch.
+1. If you want the data link to open with a single click on the visualization, toggle the **One click** switch.

   Only one data link can have **One click** enabled at a time. **One click** is only supported for some visualizations.

@@ -268,4 +308,37 @@ If you want to add all of the current dashboard's variables to the URL, then use
 1. Click **Save dashboard**.
 1. Click **Back to dashboard** and then **Exit edit**.

-If you add multiple data links, you can control the order in which they appear in the visualization. To do this, click and drag the data link to the desired position.
+   {{< /tab-content >}}
+   {{< tab-content name="Add actions" >}}
+
+   {{< admonition type="note">}}
+   Actions are not supported for all visualizations. For the list of supported visualizations, refer to [Supported visualizations](#supported-visualizations-1).
+   {{< /admonition >}}
+
+   To add an action, by follow these steps:
+
+1. Navigate to the panel to which you want to add the action.
+1. Hover over any part of the panel to display the menu icon in the upper-right corner.
+1. Click the menu icon and select **Edit** to open the panel editor.
+1. Scroll down to the **Data links and actions** section and expand it.
+1. Click **+ Add action**.
+1. In the dialog box that opens, define the API call settings:
+
+   | Option               | Description                                                                                                                                               |
+   | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | Title                | A human-readable label for the action that's displayed in the UI.                                                                                         |
+   | Confirmation message | A descriptive prompt to confirm or cancel the action.                                                                                                     |
+   | Method               | Select from **POST**, **PUT**, or **GET**.                                                                                                                |
+   | URL                  | The request URL.</p><p>To add a variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. |
+   | Query parameters     | **Key** and **Value** pairs. Click the **+** icon to add as many key/value pairs as you need.                                                             |
+   | Headers              | Comprised of **Key** and **Value** pairs and a **Content-Type**.</p><p>Click the **+** icon to add as many key/value pairs as you need.                   |
+   | Content-Type         | Select from the following: **application/json**, **text/plain**, **application/XML**, and **application/x-www-form-urlencoded**.                          |
+   | Body                 | The body of the request.                                                                                                                                  |
+
+1. Click **Save** to save changes and close the dialog box.
+1. Click **Save dashboard**.
+1. Click **Back to dashboard** and then **Exit edit**.
+   {{< /tab-content >}}
+   {{< /tabs >}}
+
+If you add multiple data links or actions, you can control the order in which they appear in the visualization. To do this, click and drag the data link or action to the desired position.
@@ -199,7 +199,7 @@ You can set standard min/max options to define hard limits of the Y-axis. For mo

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -211,7 +211,7 @@ This option only applies when bar size is set to manual.

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -136,7 +136,7 @@ The candlestick visualization is based on the time series visualization. It can

 {{< docs/shared lookup="visualizations/tooltip-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -171,7 +171,7 @@ Adjust the sizes of the gauge text.

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -711,7 +711,7 @@ Displays debug information in the upper right corner. This can be useful for deb

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -208,7 +208,7 @@ Choose whether you want to display the heatmap legend on the visualization by to

 Set the color used to show exemplar data.

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -157,7 +157,7 @@ Choose from the following:

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -174,7 +174,7 @@ Use these settings to define how the legend appears in your visualization. For m

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -172,7 +172,7 @@ Adjust the sizes of the gauge text.

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -157,7 +157,7 @@ The **Page size** option lets you paginate the state timeline visualization to l

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -143,7 +143,7 @@ Controls the opacity of state regions.

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -362,9 +362,9 @@ If you want to apply this setting to only some fields instead of all fields, you

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

-{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
+{{< docs/shared lookup="visualizations/datalink-options-3.md" source="grafana" version="<GRAFANA_VERSION>" >}}

 ### Value mappings

@@ -362,7 +362,7 @@ Set the position of the bar relative to a data point. In the examples below, **S

 {{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-### Data links
+### Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -60,7 +60,7 @@ For example, you could represent engine power and torque versus speed where spee

 {{< docs/shared lookup="visualizations/tooltip-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -308,7 +308,7 @@ You can customize the following standard options:

 To learn more, refer to [Configure standard options](ref:configure-standard-options).

-## Data links
+## Data links and actions

 {{< docs/shared lookup="visualizations/datalink-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}

@@ -1,12 +1,16 @@
 ---
-title: Data link options
+title: Data links and actions options
 comments: |
-  This file is used in the following visualizations: bar gauge, gauge, pie chart, stat, table
+  This file is used in the following visualizations: bar gauge, gauge, pie chart, stat
 ---

 Data links allow you to link to other panels, dashboards, and external resources while maintaining the context of the source panel.
 You can create links that include the series name or even the value under the cursor.
-To learn more, refer to [Configure data links](../../configure-data-links/).
+To learn more, refer to [Configure data links and actions](../../configure-data-links/).
+
+{{< admonition type="note" >}}
+Actions are not supported for this visualization.
+{{< /admonition >}}

 For each data link, set the following options:

@@ -14,4 +18,5 @@ For each data link, set the following options:
 - **URL**
 - **Open in new tab**

-Data links for this visualization don't include the **One click** switch, however, if there's only one data link configured, that data link has single-click functionality. If multiple data links are configured, then clicking the visualization opens a menu that displays all the data links.
+Data links for this visualization don't include the **One click** switch, however, if there's only one data link configured, that data link has single-click functionality.
+If multiple data links are configured, then clicking the visualization opens a menu that displays all the data links.
@@ -1,10 +1,11 @@
 ---
-title: Data link options
+title: Data links and actions options
 comments: |
  This file is used in the following visualizations: bar chart, candlestick, state timeline, status history, time series, trend, xy chart
 ---

-Data links allow you to link to other panels, dashboards, and external resources while maintaining the context of the source panel. You can create links that include the series name or even the value under the cursor.
+_Data links_ allow you to link to other panels, dashboards, and external resources and _actions_ let you trigger basic, unauthenticated, API calls.
+In both cases, you can carry out these tasks while maintaining the context of the source panel.

 For each data link, set the following options:

@@ -13,4 +14,21 @@ For each data link, set the following options:
 - **Open in new tab**
 - **One click** - Opens the data link with a single click. Only one data link can have **One click** enabled at a time.

-To learn more, refer to [Configure data links](../../configure-data-links/).
+For each action, define the following API call settings:
+
+<!-- prettier-ignore-start -->
+
+| Option               | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| Title                | A human-readable label for the action that's displayed in the UI. |
+| Confirmation message | A descriptive prompt to confirm or cancel the action. |
+| Method               | Select from **POST**, **PUT**, or **GET**. |
+| URL                  | The request URL.</p><p>To add a variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. |
+| Query parameters     | **Key** and **Value** pairs. Click the **+** icon to add as many key/value pairs as you need. |
+| Headers              | Comprised of **Key** and **Value** pairs and a **Content-Type**.</p><p>Click the **+** icon to add as many key/value pairs as you need. |
+| Content-Type         | Select from the following: **application/json**, **text/plain**, **application/XML**, and **application/x-www-form-urlencoded**. |
+| Body                 | The body of the request. |
+
+<!-- prettier-ignore-end -->
+
+To learn more, refer to [Configure data links and actions](../../configure-data-links/).
@@ -0,0 +1,36 @@
+---
+title: Data links and actions options
+comments: |
+  This file is used in the following visualizations: table
+---
+
+_Data links_ allow you to link to other panels, dashboards, and external resources and _actions_ let you trigger basic, unauthenticated, API calls.
+In both cases, you can carry out these tasks while maintaining the context of the source panel.
+
+For each data link, set the following options:
+
+- **Title**
+- **URL**
+- **Open in new tab**
+
+Data links for this visualization don't include the **One click** switch, however, if there's only one data link configured, that data link has single-click functionality.
+If multiple data links are configured, then clicking the visualization opens a menu that displays all the data links.
+
+For each action, define the following API call settings:
+
+<!-- prettier-ignore-start -->
+
+| Option               | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| Title                | A human-readable label for the action that's displayed in the UI. |
+| Confirmation message | A descriptive prompt to confirm or cancel the action. |
+| Method               | Select from **POST**, **PUT**, or **GET**. |
+| URL                  | The request URL.</p><p>To add a variable, click in the **URL** field and enter `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. |
+| Query parameters     | **Key** and **Value** pairs. Click the **+** icon to add as many key/value pairs as you need. |
+| Headers              | Comprised of **Key** and **Value** pairs and a **Content-Type**.</p><p>Click the **+** icon to add as many key/value pairs as you need. |
+| Content-Type         | Select from the following: **application/json**, **text/plain**, **application/XML**, and **application/x-www-form-urlencoded**. |
+| Body                 | The body of the request. |
+
+<!-- prettier-ignore-end -->
+
+To learn more, refer to [Configure data links and actions](../../configure-data-links/).
@@ -1,10 +1,15 @@
 ---
-title: Data link options
+title: Data links and actions options
 comments: |
  This file is used in the following visualizations: geomap, heatmap, histogram
 ---

-Data links allow you to link to other panels, dashboards, and external resources while maintaining the context of the source panel. You can create links that include the series name or even the value under the cursor.
+Data links allow you to link to other panels, dashboards, and external resources while maintaining the context of the source panel.
+You can create links that include the series name or even the value under the cursor.
+
+{{< admonition type="note" >}}
+Actions are not supported for this visualization.
+{{< /admonition >}}

 For each data link, set the following options:

@@ -12,4 +17,4 @@ For each data link, set the following options:
 - **URL**
 - **Open in new tab**

-To learn more, refer to [Configure data links](../../configure-data-links/).
+To learn more, refer to [Configure data links and actions](../../configure-data-links/).