Added Shortcuts and re-worked Tags

content/en/synthetics/notifications/template_variables.md

@@ -19,10 +19,48 @@
 
 {{< img src="synthetics/notifications/action_tab.png" alt="Actions tab from the Synthetics Result Explorer with Export Result JSON highlighted" style="width:90%;" >}}
 
+The following table provides a reference to the available variable categories and their base paths:
+
+| Section | Path |
+|---------|------|
+| [Test execution variables](#test-execution-variables) | `synthetics` (various shortcuts) |
+| [Result attributes](#result-attributes) | `synthetics.attributes` |
+| [Local and global variables](#local-and-global-variables) | `synthetics.attributes.result.variables` |
+| [Extracted variable values](#extracted-variable-values) | `synthetics.attributes.result.steps.<step-index>.extractedValue` (Browser/Mobile) |
+| [Step execution details](#step-execution-details) | `synthetics.attributes.variables.extracted` |
+| [Step summary](#step-summary) | `synthetics.attributes.result.steps` |
+
 ## Available variables
 
 ### Test execution variables
 
+Path: `synthetics` (various shortcuts)
+
+Use these variables to access common test execution data such as failure messages, step counts, duration, and tags.
+
+`{{synthetics.failed_step.failure.message}}`
+: The error message (for example, `Element's content should match the given regex`).
+
+`{{synthetics.failed_step.url}}`
+: The URL of the failed step (for example, `https://www.datadoghq.com/blog/`).
+
+`{{synthetics.attributes.result.response.statusCode}}`
+: The HTTP status code (for example, `403`).
+
+`{{synthetics.result.step_count}}`
+: Number of steps (for example, `4`).
+
+`{{synthetics.result.duration}}`
+: Duration of the test run (in milliseconds) (for example, `9096`).
+
+`{{tags}}`
+: Lists all the tags added to the synthetics test.
+: To access individual tag values, use `{{tags.<tag-key>}}`. For example, if your test is tagged with `env:prod`, use `{{tags.env}}` to return the tag value `prod`.
+
+### Result attributes
+
+Path: `synthetics.attributes`
+
 Use these variables to include details about the test, execution location, device, counts, and result status in your notification messages.
 
 {{< tabs >}}
@@ -61,7 +99,7 @@
 {{% /tab %}}
 {{% tab "Device" %}}
 
-Applies to browser and mobile tests.
+Applies to Browser and Mobile tests.
 
 `{{synthetics.attributes.device}}`
 : The `device` object contains information about the device on which the test is run on
@@ -131,12 +169,24 @@
 `{{synthetics.attributes.count.hops}}`
 : The number of traceroute hops for TCP and ICMP tests
 
+{{% /tab %}}
+{{% tab "Failed Step" %}}
+
+Applies to Multistep, Browser, and Mobile tests.
+
+`{{synthetics.failed_step}}`
+: The `failed_step` object provides a shortcut to the step that caused the test to fail, eliminating the need to reference `{{synthetics.attributes.result.steps.<step-index>}}` directly. 
+
+For example, `{{synthetics.failed_step.name}}` maps to `{{synthetics.attributes.result.steps.<step-index>.name}}` for Multistep API tests, and to `{{synthetics.attributes.result.steps.<step-index>.description}}` for Browser and Mobile tests.
+
 {{% /tab %}}
 {{< /tabs >}}
 
-### Result variables
+### Local and global variables
 
-These variables provide access to local and global variable values used during test execution. Use them to include variable names, types, and values in your notifications. These variables are accessed with the `{{synthetics.attributes.result}}` prefix.
+Path: `synthetics.attributes.result.variables`
+
+These variables provide access to local and global variable values used during test execution. Use them to include variable names, types, and values in your notifications.
 
 {{< tabs >}}
 {{% tab "Local config variables" %}}
@@ -179,9 +229,19 @@
 : Variable value (note: uses `.val`, not `.value`)
 
 {{% /tab %}}
-{{% tab "Step extracted variables" %}}
+{{< /tabs >}}
+
+### Extracted variable values
 
-For tests with steps, step data is contained in `{{synthetics.attributes.result.steps.<step-index>.extractedValue}}`. For information on how to access the `<step-index>` see the [step summary](#step-summary) section below.
+Path: `synthetics.attributes.result.steps.<step-index>.extractedValue`
+
+**Applies to:** Browser and Mobile tests.
+
+These are the actual variable values that a step captured during test execution. For example, if you have a Browser test step that extracts text from a page element into a variable, this is where you access that extracted value.
+
+For information on how to access the `<step-index>`, see the [step summary](#step-summary) section below.
+
+**Note:** For Multistep API tests, use [API tests][2] instead.
 
 `synthetics.attributes.result.steps.<step-index>.extractedValue.name`
 : Variable name
@@ -192,12 +252,11 @@
 `synthetics.attributes.result.steps.<step-index>.extractedValue.value`
 : Variable value (if step was successful)
 
-{{% /tab %}}
-{{< /tabs >}}
+### Step execution details
 
-### Variables extracted by steps
+Path: `synthetics.attributes.variables.extracted`
 
-For multistep API, browser, and mobile tests, extracted variables are available at the step level within the `synthetics.attributes.variables.extracted` property. These values are only available when the step completes successfully.
+These are step execution metadata and results containing detailed information about how each step ran, including response data, timing metrics, and protocol-specific details. These values are only available when the step completes successfully.
 
 {{< tabs >}}
 {{% tab "General steps" %}}
@@ -533,7 +592,9 @@
 
 ### Step summary
 
-Access step data by index, name, or ID to reference specific steps in your notification messages. This section also includes summary counts for total steps, completed steps, and errors.
+Path: `synthetics.attributes.result.steps`
+
+Access step data by index, name, or ID to reference specific steps in your notification messages.
 
 Each step exposes the following properties: `.id`, `.status`, `.type`, `.duration`, `.description`, `.failure.message`, `.code`, and `.url`.
 
@@ -574,4 +635,5 @@
 
 {{< partial name="whats-next/whats-next.html" >}}
 
-[1]: /synthetics/explore/results_explorer
+[1]: /synthetics/explore/results_explorer
+[2]: /synthetics/notifications/template_variables/?tab=apitests#step-execution-details