From 15c72c2739b6d445d5a9891029d66b6b4f1c0298 Mon Sep 17 00:00:00 2001
From: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
Date: Wed, 2 Sep 2020 07:07:31 -0700
Subject: [PATCH] Docs: Updated data links content (#27110)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* updated content

* updated content

* Update data-link-variables.md

* Update global-variables.md

* updated content

* Update best-practices-for-managing-dashboards.md

* Update docs/sources/linking/data-link-variables.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update docs/sources/linking/data-link-variables.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update docs/sources/linking/data-link-variables.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update docs/sources/linking/data-link-variables.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update docs/sources/linking/data-links.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update docs/sources/linking/dashboard-links.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>

* Update dashboard-links.md

Co-authored-by: Torkel Ödegaard <torkel@grafana.org>
---
 .../best-practices-for-managing-dashboards.md |  2 +-
 docs/sources/linking/dashboard-links.md       |  2 +-
 docs/sources/linking/data-link-variables.md   | 55 +++++++++++++++++++
 docs/sources/linking/data-links.md            | 10 +++-
 docs/sources/menu.yaml                        |  4 +-
 .../variables/templates-and-variables.md      |  1 -
 .../variables/variable-types/_index.md        |  3 +-
 .../variable-types/global-variables.md        |  5 +-
 .../variables/variable-types/url-variables.md | 53 ------------------
 9 files changed, 72 insertions(+), 63 deletions(-)
 create mode 100644 docs/sources/linking/data-link-variables.md
 delete mode 100644 docs/sources/variables/variable-types/url-variables.md

diff --git a/docs/sources/best-practices/best-practices-for-managing-dashboards.md b/docs/sources/best-practices/best-practices-for-managing-dashboards.md
index b6cb7e529f1..8e3d5b7ddf6 100644
--- a/docs/sources/best-practices/best-practices-for-managing-dashboards.md
+++ b/docs/sources/best-practices/best-practices-for-managing-dashboards.md
@@ -31,7 +31,7 @@ What is your dashboard maturity level? Analyze your current dashboard setup and
   - If you create a temporary dashboard, perhaps to test something, prefix the name with `TEST: `. Delete the dashboard when you are finished.
 - Copying dashboards with no significant changes is not a good idea.
   - You miss out on updates to the original dashboard, such as documentation changes, bug fixes, or additions to metrics.
-  - In many cases copies are being made to simply customize the view by setting template parameters. This should instead be done by maintaining a link to the master dashboard and customizing the view with [URL parameters]({{< relref "../variables/variable-types/url-variables.md" >}}).
+  - In many cases copies are being made to simply customize the view by setting template parameters. This should instead be done by maintaining a link to the master dashboard and customizing the view with [URL parameters]({{< relref "../linking/data-link-variables.md" >}}).
 - When you must copy a dashboard, clearly rename it and _do not_ copy the dashboard tags. Tags are important metadata for dashboards that are used during search. Copying tags can result in false matches.
 - Maintain a dashboard of dashboards or cross-reference dashboards. This can be done in several ways:
     - Create dashboard links, panel, or data links. Links can go to other dashboards or to external systems. For more information, refer to [Linking]({{< relref "../linking/_index.md" >}}).
diff --git a/docs/sources/linking/dashboard-links.md b/docs/sources/linking/dashboard-links.md
index 402da2399eb..8f4c5a420fe 100644
--- a/docs/sources/linking/dashboard-links.md
+++ b/docs/sources/linking/dashboard-links.md
@@ -10,7 +10,7 @@ weight = 200
 
 # Dashboard links
 
-When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For more information about specifying links, refer to [URL variables]({{< relref "../variables/variable-types/url-variables.md" >}}).
+When you create a dashboard link, you can include the time range and current template variables to directly jump to the same context in another dashboard. This way, you don’t have to worry whether the person you send the link to is looking at the right data. For other types of links, refer to [Data link variables]({{< relref "data-link-variables.md" >}}).
 
 Dashboard links can also be used as shortcuts to external systems, such as submitting [a GitHub issue with the current dashboard name](https://github.com/grafana/grafana/issues/new?title=Dashboard%3A%20HTTP%20Requests).
 
diff --git a/docs/sources/linking/data-link-variables.md b/docs/sources/linking/data-link-variables.md
new file mode 100644
index 00000000000..b658067e25f
--- /dev/null
+++ b/docs/sources/linking/data-link-variables.md
@@ -0,0 +1,55 @@
++++
+title = "URL variables"
+keywords = ["grafana", "url variables", "documentation", "variables", "data link"]
+aliases = ["/docs/grafana/latest/variables/url-variables.md","/docs/grafana/latest/variables/variable-types/url-variables.md"]
+type = "docs"
+weight = 400
++++
+
+# Data link variables
+
+You can use variables in data links to refer to series fields, labels, and values. For more information about data links, refer to [Data links]({{< relref "data-links.md" >}}).
+
+To see a list of available variables, type `$` in the data link **URL** field to see a list of variables that you can use.
+
+> **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.
+
+You can also use template variables in your data links URLs, refer to [Templates and variables]({{< relref "../variables/templates-and-variables.md" >}}) for more information on template variables.
+
+## Time range panel variables
+
+These variables allow you to include the current time range in the data link URL.
+
+* ``__url_time_range`` - current dashboard's time range (i.e. ``?from=now-6h&to=now``)
+* `$__from and $__to` - For more information, refer to [Global variables]({{< relref "../variables/variable-types/global-variables.md#__from-and-__to" >}}).
+
+## Series variables
+
+Series specific variables are available under ``__series`` namespace:
+
+* ``__series.name`` - series name to the URL
+* ``__series.labels.<LABEL>`` - label's value to the URL. If your label contains dots use ``__series.labels["<LABEL>"]`` syntax
+
+## Field variables
+
+Field-specific variables are available under ``__field`` namespace:
+
+* ``__field.name`` - the name of the field
+
+## Value variables
+
+Value-specific variables are available under ``__value`` namespace:
+
+* ``__value.time`` - value's timestamp (Unix ms epoch) to the URL (i.e. ``?time=1560268814105``)
+* ``__value.raw`` - raw value
+* ``__value.numeric`` - numeric representation of a value
+* ``__value.text`` - text representation of a value
+* ``__value.calc`` - calculation name if the value is result of calculation
+
+## Template variables
+
+When linking to another dashboard that uses template variables, select variable values for whoever clicks the link.
+
+``var-myvar=${myvar}`` - where ``myvar`` is a name of the template variable that matches one in the current dashboard that you want to use. 
+
+If you want to add all of the current dashboard's variables to the URL, then use  ``__all_variables``.
diff --git a/docs/sources/linking/data-links.md b/docs/sources/linking/data-links.md
index e5c608fa002..a2a79e43297 100644
--- a/docs/sources/linking/data-links.md
+++ b/docs/sources/linking/data-links.md
@@ -14,6 +14,14 @@ Stat, Gauge, or Bar Gauge you can click anywhere on the visualization to open th
 
 >**Note:** For stat, gauge, bar gauge, and table visualizations, you add and edit data links on the Field tab. For the graph visualization, you add and edit data links on the Panel tab.
 
+You can use variables in data links to send people to a detailed dashboard with preserved data filters. For example, you could use variables to specify a time range, series, and variable selection. For more information, refer to [Data link variables]({{< relref "data-link-variables.md" >}}).
+
+## Typeahead suggestions
+
+When creating or updating a data link, press Cmd+Space or Ctrl+Space on your keyboard to open the typeahead suggestions to more easily add variables to your URL.
+
+{{< docs-imagebox img="/img/docs/data_link_typeahead.png"  max-width= "800px" >}}
+
 ## Add a data link
 
 1. Hover your cursor over the panel that you want to add a link to and then press `e`. Or click the dropdown arrow next to the panel title and then click **Edit**.
@@ -22,7 +30,7 @@ Stat, Gauge, or Bar Gauge you can click anywhere on the visualization to open th
 1. Enter a **Title**. **Title** is a human-readable label for the link that will be displayed in the UI.
 1. Enter the **URL** you want to link to.
    
-   You can even add one of the template variables defined in the dashboard. Press Ctrl+Space or Cmd+Space and click in the **URL** field to see the available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [URL variables]({{< relref "../variables/variable-types/url-variables.md" >}}).
+   You can even add one of the template variables defined in the dashboard. Click in the **URL** field and then type `$` or press Ctrl+Space or Cmd+Space to see a list of available variables. By adding template variables to your panel link, the link sends the user to the right context, with the relevant variables already set. For more information, refer to [Data link variables]({{< relref "data-link-variables.md" >}}).
    
 1. If you want the link to open in a new tab, then select **Open in a new tab**.
 1. Click **Save** to save changes and close the window.
diff --git a/docs/sources/menu.yaml b/docs/sources/menu.yaml
index b1856d40b4a..f440dbdff03 100644
--- a/docs/sources/menu.yaml
+++ b/docs/sources/menu.yaml
@@ -261,6 +261,8 @@
       link: /linking/panel-links/
     - name: Data links
       link: /linking/data-links/
+    - link: /linking/data-link-variables/
+      name: Data link variables
 - name: Templates and variables
   link: /variables/
   children:
@@ -289,8 +291,6 @@
           name: Chained variables
         - link: /variables/variable-types/global-variables/
           name: Global variables
-        - link: /variables/variable-types/url-variables/
-          name: URL variables
     - name: Selection options
       link: /variables/variable-selection-options/
     - name: Value groups/tags
diff --git a/docs/sources/variables/templates-and-variables.md b/docs/sources/variables/templates-and-variables.md
index e565fdb9f4d..c42101aaad6 100644
--- a/docs/sources/variables/templates-and-variables.md
+++ b/docs/sources/variables/templates-and-variables.md
@@ -79,7 +79,6 @@ Grafana uses the following types of variables.
 | Ad hoc filters   | Key/value filters that are automatically added to all metric queries for a data source (InfluxDB, Prometheus, and Elasticsearch only). [Add ad hoc filters]({{< relref "variable-types/add-ad-hoc-filters.md" >}}).   |
 | Global variables   | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "variable-types/global-variables" >}}).   |
 | Chained variables   | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "variable-types/chained-variables.md" >}}).   |
-| URL variables   | You can use variables in data links to link to specific portions of your visualizations. Refer to [Data links]({{< relref "../linking/data-links.md" >}}).   |
 
 ## Variable best practices
 
diff --git a/docs/sources/variables/variable-types/_index.md b/docs/sources/variables/variable-types/_index.md
index 29c6560ec0b..0eaf747d553 100644
--- a/docs/sources/variables/variable-types/_index.md
+++ b/docs/sources/variables/variable-types/_index.md
@@ -19,5 +19,4 @@ Grafana uses several types of variables.
 | Interval   | Interval variables represent time spans. [Add an interval variable]({{< relref "add-interval-variable.md" >}}).   |
 | Ad hoc filters   | Key/value filters that are automatically added to all metric queries for a data source (InfluxDB, Prometheus, and Elasticsearch only). [Add ad hoc filters]({{< relref "add-ad-hoc-filters.md" >}}).   |
 | Global variables   | Built-in variables that can be used in expressions in the query editor. Refer to [Global variables]({{< relref "global-variables" >}}).   |
-| Chained variables   | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "chained-variables.md" >}}).   |
-| URL variables   | You can use variables in data links to link to specific portions of your visualizations. Refer to [Data links]({{< relref "../../linking/data-links.md" >}}).   |
\ No newline at end of file
+| Chained variables   | Variable queries can contain other variables. Refer to [Chained variables]({{< relref "chained-variables.md" >}}).   |
\ No newline at end of file
diff --git a/docs/sources/variables/variable-types/global-variables.md b/docs/sources/variables/variable-types/global-variables.md
index 2252e0a0a85..d9847e06cb6 100644
--- a/docs/sources/variables/variable-types/global-variables.md
+++ b/docs/sources/variables/variable-types/global-variables.md
@@ -33,7 +33,9 @@ Grafana has two built in time range variables: `$__from` and `$__to`. They are c
 | `${__from:date:seconds}` | 1594671549               | Unix seconds epoch |
 | `${__from:date:YYYY-MM}` | 2020-07                  | Any custom [date format](https://momentjs.com/docs/#/displaying/) |
 
-The above syntax works with `${__to}` as well.  
+The above syntax works with `${__to}` as well.
+
+You can use this variable in URLs as well. For example, send a user to a dashboard that shows a time range from six hours ago until now: https://play.grafana.org/d/000000012/grafana-play-home?viewPanel=2&orgId=1?from=now-6h&to=now
 
 ## $__interval
 
@@ -83,4 +85,3 @@ This is used in several places, including:
 - Log Analytics queries in the Azure Monitor data source.
 - SQL queries in MySQL, Postgres, and MSSQL
 - The `$__timeFilter` variable is used in the MySQL data source.
-
diff --git a/docs/sources/variables/variable-types/url-variables.md b/docs/sources/variables/variable-types/url-variables.md
deleted file mode 100644
index 7a12d677565..00000000000
--- a/docs/sources/variables/variable-types/url-variables.md
+++ /dev/null
@@ -1,53 +0,0 @@
-+++
-title = "URL variables"
-keywords = ["grafana", "url variables", "documentation", "variables"]
-aliases = ["/docs/grafana/latest/variables/url-variables.md"]
-type = "docs"
-+++
-
-# URL variables
-
-You can use variables in data links to link to specific portions of your visualizations. For more information about data links, refer to [Data links]({{< relref "../../linking/data-links.md" >}}).
-
-> **Note:** These variables changed in 6.4 so if you have an older version of Grafana please use the version picker to select
-docs for an older version of Grafana.
-
-## Typeahead suggestions
-
-Press Cmd+Space or Ctrl+Space on your keyboard to open the typeahead suggestions to more easily add variables to your URL.
-
-{{< docs-imagebox img="/img/docs/data_link_typeahead.png"  max-width= "800px" >}}
-
-## Time variables
-
-* ``__url_time_range`` - current dashboard's time range (i.e. ``?from=now-6h&to=now``)
-* ``__from`` - current dashboard's time range from value
-* ``__to`` - current dashboard's time range to value
-
-## Series variables
-
-Series specific variables are available under ``__series`` namespace:
-
-* ``__series.name`` - series name to the URL
-* ``__series.labels.<LABEL>`` - label's value to the URL. If your label contains dots use ``__series.labels["<LABEL>"]`` syntax
-
-## Field variables
-
-Field specific variables are available under ``__field`` namespace:
-
-* ``__field.name`` - field name to the URL
-
-## Value variables
-
-Value specific variables are available under ``__value`` namespace:
-
-* ``__value.time`` - value's timestamp (Unix ms epoch) to the URL (i.e. ``?time=1560268814105``)
-* ``__value.raw`` - raw value
-* ``__value.numeric`` - numeric representation of a value
-* ``__value.text`` - text representation of a value
-* ``__value.calc`` - calculation name if the value is result of calculation
-
-## Template variables
-
-When linking to another dashboard that uses template variables, you can use ``var-myvar=${myvar}`` syntax (where ``myvar`` is a name of template variable)
-to use current dashboard's variable value. If you want to add all of the current dashboard's variables to the URL use  ``__all_variables`` variable.