# Template reference
<a name="v9-alerting-template-reference"></a>

****  
This documentation topic is designed for Grafana workspaces that support **Grafana version 9.x**.  
For Grafana workspaces that support Grafana version 12.x, see [Working in Grafana version 12](using-grafana-v12.md).  
For Grafana workspaces that support Grafana version 10.x, see [Working in Grafana version 10](using-grafana-v10.md).  
For Grafana workspaces that support Grafana version 8.x, see [Working in Grafana version 8](using-grafana-v8.md).

This section provides reference information for creating your templates.

## Template data
<a name="v9-alerting-template-data"></a>

The following data is passed to message templates.


| Name | Type | Notes | 
| --- | --- | --- | 
| `Receiver` | string | Name of the contact point that the notification is being sent to. | 
| `Status` | string | firing if at least one alert is firing, otherwise resolved. | 
| `Alerts` | Alert | List of alert objects that are included in this notification (see below). | 
| `GroupLabels` | KeyValue | Labels these alerts were grouped by. | 
| `CommonLabels` | KeyValue | Labels common to all the alerts included in this notification. | 
| `CommonAnnotations` | KeyValue | Annotations common to all the alerts included in this notification. | 
| `ExternalURL` | string | Back link to the Grafana that sent the notification. If using external Alertmanager, back link to this Alertmanager. | 

The `Alerts` type exposes two functions for filtering the alerts returned.
+ `Alerts.Firing` – Returns a list of firing alerts.
+ `Alerts.Resolved` – Returns a list of resolved alerts.

**Alert (type)**

The alert type contains the following data.


| Name | Type | Notes | 
| --- | --- | --- | 
| Status | string | `firing` or `resolved`. | 
| Labels | KeyValue | A set of labels attached to the alert. | 
| Annotations | KeyValue | A set of annotations attached to the alert. | 
| Values | KeyValue | The values of all expressions, including Classic Conditions | 
| StartsAt | time.Time | Time the alert started firing. | 
| EndsAt | time.Time | Only set if the end time of an alert is known. Otherwise set to a configurable timeout period from the time since the last alert was received. | 
| GeneratorURL | string | A back link to Grafana or external Alertmanager. | 
| SilenceURL | string | A link to silence the alert (with labels for this alert pre-filled). Only for Grafana managed alerts. | 
| DashboardURL | string | Link to grafana dashboard, if alert rule belongs to one. Only for Grafana managed alerts. | 
| PanelURL | string | Link to grafana dashboard panel, if alert rule belongs to one. Only for Grafana managed alerts. | 
| Fingerprint | string | Fingerprint that can be used to identify the alert. | 
| ValueString | string | A string that contains the labels and value of each reduced expression in the alert. | 

 **ExtendedData**

The ExtendedData object contains the following properties.


| Name | Kind | Description | Example | 
| --- | --- | --- | --- | 
| Receiver | `string` | The name of the contact point sending the notification. | `{{ .Receiver }}` | 
| Status | `string` | The status is `firing if at least one alert is firing, otherwise resolved.` | `{{ .Status }}` | 
| Alerts | `[]Alert` | List of all firing and resolved alerts in this notification. | `There are {{ len .Alerts }} alerts` | 
| Firing alerts | `[]Alert` | List of all firing alerts in this notification. | `There are {{ len .Alerts.Firing }} firing alerts` | 
| Resolved alerts | `[]Alert` | List of all resolved alerts in this notification. | `There are {{ len .Alerts.Resolved }} resolved alerts` | 
| GroupLabels | `KeyValue` | The labels that group these alerts int his notification. | `{{ .GroupLabels }}` | 
| CommonLabels | `KeyValue` | The labels common to all alerts in this notification. | `{{ .CommonLabels }}` | 
| CommonAnnotations | `KeyValue` | The annotations common to all alerts in this notification. | `{{ .CommonAnnotations }}` | 
| ExternalURL | `string` | A link to the Grafana workspace or Alertmanager that sent this notification. | `{{ .ExternalURL }}` | 

**KeyValue type**

The `KeyValue` type is a set of key/value string pairs that represent labels and annotations.

In addition to direct access of the data stored as a `KeyValue`, there are also methods for sorting, removing, and transforming the data.


| Name | Arguments | Returns | Notes | Example | 
| --- | --- | --- | --- | --- | 
| SortedPairs |  | Sorted list of key and value string pairs |  | `{{ .Annotations.SortedPairs }}` | 
| Remove | []string | KeyValue | Returns a copy of the Key/Value map without the given keys. | `{{ .Annotations.Remove "summary" }}` | 
| Names |  | []string | List of label names | `{{ .Names }}` | 
| Values |  | []string | List of label values | `{{ .Values }}` | 

**Time**

Time is from the Go [https://pkg.go.dev/time#Time](https://pkg.go.dev/time#Time) package. You can print a time in a number of different formats. For example, to print the time that an alert fired in the format `Monday, 1st January 2022 at 10:00AM`, you write the following template:

```
{{ .StartsAt.Format "Monday, 2 January 2006 at 3:04PM" }}
```

You can find a reference for Go’s time format [here](https://pkg.go.dev/time#pkg-constants).

## Template functions
<a name="v9-alerting-template-functions"></a>

Using template functions you can process labels and annotations to generate dynamic notifications. The following functions are available.


| Name | Argument type | Return type | Description | 
| --- | --- | --- | --- | 
| `humanize` | number or string | string | Converts a number to a more readable format, using metric prefixes. | 
| `humanize1024` | number or string | string | Like humanize, but uses 1024 as the base rather than 1000. | 
| `humanizeDuration` | number or string | string | Converts a duration in seconds to a more readable format. | 
| `humanizePercentage` | number or string | string | Converts a ratio value to a fraction of 100. | 
| `humanizeTimestamp` | number or string | string | Converts a Unix timestamp in seconds to a more readable format. | 
| `title` | string | string | strings.Title, capitalizes first character of each word. | 
| `toUpper` | string | string | strings.ToUpper, converts all characters to upper case. | 
| `toLower` | string | string | strings.ToLower, converts all characters to lower case. | 
| `match` | pattern, text | Boolean | regexp.MatchString Tests for an unanchored regexp match. | 
| `reReplaceAll` | pattern, replacement, text | string | Regexp.ReplaceAllString Regexp substitution, unanchored. | 
| `graphLink` | string - JSON Object with `expr` and `datasource` fields | string | Returns the path to graphical view in Explore for the given expression and data source. | 
| `tableLink` | string - JSON Object with `expr` and `datasource` fields | string | Returns the path to tabular view in Explore for the given expression and data source. | 
| `args` | []interface{} | map[string]interface{} | Converts a list of objects to a map with keys, for example, arg0, arg1. Use this function to pass multiple arguments to templates. | 
| `externalURL` | nothing | string | Returns a string representing the external URL. | 
| `pathPrefix` | nothing | string | Returns the path of the external URL. | 

The following table shows examples of using each function.


| Function | TemplateString | Input | Expected | 
| --- | --- | --- | --- | 
| humanize | { humanize $value } | 1234567.0 | 1.235M | 
| humanize1024 | { humanize1024 $value } | 1048576.0 | 1Mi | 
| humanizeDuration | { humanizeDuration $value } | 899.99 | 14m 59s | 
| humanizePercentage | { humanizePercentage $value } | 0.1234567 | 12.35% | 
| humanizeTimestamp | { humanizeTimestamp $value } | 1435065584.128 | 2015-06-23 13:19:44.128 \+0000 UTC | 
| title | { $value \| title } | aa bB CC | Aa Bb Cc | 
| toUpper | { $value \| toUpper } | aa bB CC | AA BB CC | 
| toLower | { $value \| toLower } | aa bB CC | aa bb cc | 
| match | { match "a\+" $labels.instance } | aa | true | 
| reReplaceAll | {{ reReplaceAll "localhost:(.\*)" "my.domain:$1" $labels.instance }} | localhost:3000 | my.domain:3000 | 
| graphLink | {{ graphLink "{\\"expr\\": \\"up\\", \\"datasource\\": \\"gdev-prometheus\\"}" }} |  | /explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}] | 
| tableLink | {{ tableLink "{\\"expr\\":\\"up\\", \\"datasource\\":\\"gdev-prometheus\\"}" }} |  | /explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}] | 
| args | {{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}} |  | 1 2 | 
| externalURL | { externalURL } |  | http://localhost/path/prefix | 
| pathPrefix | { pathPrefix } |  | /path/prefix |