@ -99,7 +99,7 @@ The notification template is assigned to the contact point to determine the noti
{{<figuresrc="/media/docs/alerting/how-notification-templates-works.png"max-width="1200px"caption="A flow of the alert notification process, from querying the alert rule to sending the alert notification message.">}}
{{<figuresrc="/media/docs/alerting/how-notification-templates-works.png"max-width="1200px"caption="A flow of the alert notification process, from querying the alert rule to sending the alert notification message.">}}
By default, Grafana provides default templates, such as `default.title` and `default.message`, to format notification messages.
By default, Grafana provides default templates, such as `{{define "default.title"}}` and `{{define "default.message"}}`, to format notification messages.
@ -64,7 +64,7 @@ Notification templates allows you to change the default notification messages.
You can modify the content and format of notification messages. For example, you can customize the content to show only specific information or adjust the format to suit a particular contact point, such as Slack or Email.
You can modify the content and format of notification messages. For example, you can customize the content to show only specific information or adjust the format to suit a particular contact point, such as Slack or Email.
{{% admonition type="note" %}}
{{% admonition type="note" %}}
Avoid adding extra information about alert instances in notification templates, as this information is only be visible in the notification message.
Avoid adding extra information about alert instances in notification templates, as this information is only visible in the notification message.
Instead, you should [use annotations or labels](ref:template-annotations-and-labels) to add information directly to the alert, ensuring it's also visible in the alert state and alert history within Grafana. You can then print the new alert annotation or label in notification templates.
Instead, you should [use annotations or labels](ref:template-annotations-and-labels) to add information directly to the alert, ensuring it's also visible in the alert state and alert history within Grafana. You can then print the new alert annotation or label in notification templates.
In contact points, you can select notification templates to customize the notification messages sent.
In contact points, you can select notification templates to customize the notification messages sent.
By default, Grafana provides a template for the notification title (`default.title`) and a template for the notification message (`default.message`). Both default templates display common alert details.
By default, Grafana provides a template for the notification title (`{{define "default.title"}}`) and a template for the notification message (`{{define "default.message"}}`). Both default templates display common alert details.
You can also create custom templates to customize the content and format of notification messages, which can then be applied to one or more contact points.
You can also create custom templates to customize the content and format of notification messages, which can then be applied to one or more contact points. In Grafana, a custom notification template is created within a notification template group.
This documentation provides step-by-step instructions for selecting templates in contact points, previewing templates, and creating custom templates using the Grafana UI.
This documentation provides step-by-step instructions for selecting templates in contact points, previewing templates, and creating notification template groups using the Grafana UI.
## Select a notification template for a contact point
## Select a notification template for a contact point
@ -50,29 +50,28 @@ To add an existing notification template to your contact point, complete the fol
For example, if you are creating an email contact point integration, click **Message** or **Subject**.
For example, if you are creating an email contact point integration, click **Message** or **Subject**.
1. Click **Edit**.
1. Click **Edit**.
A dialog box opens where you can select templates.
A dialog box opens where you can select notification templates.
1. Click **Select existing template** to select a template and [preview](#preview-a-notification-template) it using the default payload.
1. Click **Select notification template** or **Enter custom message** to customize a template or message
You can also copy the selected template and use it in the custom tab.
- You can select an existing notification template and [preview](#preview-a-notification-template) it using the default payload.
- You can also copy the notification template and use it in the **Enter custom message** tab.
1. Click **Enter custom message** to customize and edit the field directly. Note that the title changes depending on the field you are editing.
1. You can switch between the two tabs to access the list of available templates and copy them across to the customized version.
1. Click **Save contact point**.
1. Click **Save contact point**.
## Create a notification template
## Create a notification template and notification template group
Create notification templates to customize notification messages and reuse them in contact points.
Create notification templates to customize notification messages and reuse them in contact points.
Your notification template name must be unique. You cannot have two templates with the same name in the same notification template or in different notification templates. Avoid defining templates with the same name as default templates, such as: `__subject`, `__text_values_list`, `__text_alert_list`, `default.title` and `default.message`.
In Grafana, custom notification templates (`{{define "<NAME>"}}`) are created within a notification template group, allowing you to test and implement multiple templates together.
Your notification template name (`{{define "<NAME>"}}`) must be unique. You cannot have two templates with the same name in the same notification template group or in different notification template groups. Therefore, avoid using names already defined as default templates, such as: `__subject`, `__text_values_list`, `__text_alert_list`, `default.title` and `default.message`.
To create a notification template in Grafana, complete the following steps.
To create a notification template in Grafana, complete the following steps.
1. Click **Alerts & IRM** -> **Contact points**.
1. Click **Alerts & IRM** -> **Contact points**.
1. Click the **Notification Templates** tab and then **+ Add notification template**.
1. Click the **Notification Templates** tab and then **+ Add notification template group**.
1. Enter a name for the notification template.
1. Enter a name for the notification template group.
1. Write the content of the template in the content field.
1. Write the content of the template in the content field.
@ -80,13 +79,13 @@ To create a notification template in Grafana, complete the following steps.
If `{{ define }}` is not included in the content, `{{ define "<NOTIFICATION_TEMPLATE_NAME>" }}` and `{{ end }}` is automatically added to the start and end.
If `{{ define }}` is not included in the content, `{{ define "<NOTIFICATION_TEMPLATE_NAME>" }}` and `{{ end }}` is automatically added to the start and end.
To create a notification template that contains more than one template, complete the following steps.
To create a notification template group that contains more than one notification template, complete the following steps.
1. Click **+ Add notification template**.
1. Click **+ Add notification template group**.
1. Enter a name for the notification template.
1. Enter a name for the notification template group.
1. Write each template in the Content field, including `{{ define "name-of-template" }}` and `{{ end }}` at the start and end of each template.
1. Write each template in the Content field, including `{{ define "<NOTIFICATION_TEMPLATE_NAME>" }}` and `{{ end }}` at the start and end of each template.
1. Save your changes.
1. Save your changes.
@ -103,7 +102,7 @@ Notification template preview is only for Grafana Alertmanager.
1. Click **+ Add notification template** or edit an existing template.
1. Click **+ Add notification template group** or edit an existing template group.
1. Add or update your template content.
1. Add or update your template content.
Default data is provided and you can add or edit alert data to it as well as alert instances. You can add alert data directly in the Payload data window itself or click **Select alert instances** or **Add custom alerts**.
Default data is provided and you can add or edit alert data to it as well as alert instances. You can add alert data directly in the Payload data window itself or click **Select alert instances** or **Add custom alerts**.
@ -165,15 +165,15 @@ To export contact points from the Grafana UI, complete the following steps.
1. Click **Copy Code** or **Download**.
1. Click **Copy Code** or **Download**.
### Export templates
### Export notification template groups
Grafana currently doesn't offer an Export UI or [Export endpoint](#export-api-endpoints) for notification templates, unlike other Alerting resources presented in this documentation.
Grafana currently doesn't offer an Export UI or [Export endpoint](#export-api-endpoints) for notification template groups, unlike other Alerting resources presented in this documentation.
However, you can export it by manually copying the content template and title directly from the Grafana UI.
However, you can export it by manually copying the content and name of the notification template group from the Grafana UI.
1. Find the notification template group you want to export.
1. Copy the content and title.
1. Copy the content and name.
1. Adjust it for the [file provisioning format](ref:alerting_file_provisioning_template) or [Terraform resource](ref:alerting_tf_provisioning_template).
1. Adjust it for the [file provisioning format](ref:alerting_file_provisioning_template) or [Terraform resource](ref:alerting_tf_provisioning_template).
### Export the notification policy tree
### Export the notification policy tree
@ -217,8 +217,8 @@ You can use the [Alerting HTTP API](ref:alerting_http_provisioning) to return ex
However, note the standard endpoints return a JSON format that is not compatible for provisioning through configuration files or Terraform, except the `/export` endpoints listed below.
However, note the standard endpoints return a JSON format that is not compatible for provisioning through configuration files or Terraform, except the `/export` endpoints listed below.
# Use configuration files to provision alerting resources
# Use configuration files to provision alerting resources
@ -649,19 +649,19 @@ settings:
{{</collapse>}}
{{</collapse>}}
## Import templates
## Import notification template groups
Create or delete templates using provisioning files in your Grafana instance(s).
Create or delete notification template groups using provisioning files in your Grafana instance(s).
1. Find the notification template in Grafana.
1. Find the notification template group in Grafana.
1. [Export](ref:export_templates) a template by copying the template content and title.
1. [Export](ref:export_templates) a template group by copying the template content and name.
1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to.
1. Copy the contents into a YAML or JSON configuration file and add it to the `provisioning/alerting` directory of the Grafana instance you want to import the alerting resources to.
Example configuration files can be found below.
Example configuration files can be found below.
1. Restart your Grafana instance (or reload the provisioned files using the Admin API).
1. Restart your Grafana instance (or reload the provisioned files using the Admin API).
Here is an example of a configuration file for creating templates.
Here is an example of a configuration file for creating notification template groups.
```yaml
```yaml
# config file version
# config file version
@ -671,16 +671,16 @@ apiVersion: 1
templates:
templates:
# <int> organization ID, default = 1
# <int> organization ID, default = 1
- orgId: 1
- orgId: 1
# <string,required> name of the template, must be unique
# <string,required> name of the template group, must be unique
name: my_first_template
name: my_first_template
# <string,required> content of the template
# <string,required> content of the template group
template: |
template: |
{{ define "my_first_template" }}
{{ define "my_first_template" }}
Custom notification message
Custom notification message
{{ end }}
{{ end }}
```
```
Here is an example of a configuration file for deleting templates.
Here is an example of a configuration file for deleting notification template groups.
```yaml
```yaml
# config file version
# config file version
@ -690,7 +690,7 @@ apiVersion: 1
deleteTemplates:
deleteTemplates:
# <int> organization ID, default = 1
# <int> organization ID, default = 1
- orgId: 1
- orgId: 1
# <string,required> name of the template, must be unique
# <string,required> name of the template group, must be unique
name: my_first_template
name: my_first_template
```
```
@ -863,8 +863,8 @@ In alerting resources, most properties support template variable interpolation,
- Notification template group content: `templates[].template`
Note for properties that support interpolation, you may unexpectedly substitute template variables when not intended. To avoid this, you can escape the `$variable` with `$$variable`.
Note for properties that support interpolation, you may unexpectedly substitute template variables when not intended. To avoid this, you can escape the `$variable` with `$$variable`.
@ -272,19 +272,19 @@ In this section, we'll create Terraform configurations for each alerting resourc
1. Continue to add more Grafana resources or [use the Terraform CLI for provisioning](#provision-grafana-resources-with-terraform).
1. Continue to add more Grafana resources or [use the Terraform CLI for provisioning](#provision-grafana-resources-with-terraform).
### Add and enable templates
### Add and enable notification templates
[Notification templates](ref:notification-template) allow customization of alert notifications across multiple contact points.
[Notification templates](ref:notification-template) allow customization of alert notifications across multiple contact points.
1. Create or find the notification template you want to import in Grafana. Alternatively, consider writing the resource in code as demonstrated in the example below.
1. Create or find the notification template group you want to import in Grafana. Alternatively, consider writing the resource in code as demonstrated in the example below.
1. [Export](ref:alerting_export) the template as [`grafana_message_template` Terraform resource](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/message_template).
1. [Export](ref:alerting_export) the notification template group as [`grafana_message_template` Terraform resource](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/message_template).
This example is a simple demo template defined as `custom_email.message`.
This example creates a notification template group named `custom_emails` that defines a `custom_email.message` template.
Template groups enable you to define multiple notification templates (`{{ define "" }}`) within a single group. They can be managed from the Grafana Alerting UI.
| GET | /api/v1/provisioning/mute-timings/:name | [route get mute timing](#route-get-mute-timing) | Get a mute timing. |
| GET | /api/v1/provisioning/mute-timings | [route get mute timings](#route-get-mute-timings) | Get all the mute timings. |
| POST | /api/v1/provisioning/mute-timings | [route post mute timing](#route-post-mute-timing) | Create a new mute timing. |
| PUT | /api/v1/provisioning/mute-timings/:name | [route put mute timing](#route-put-mute-timing) | Replace an existing mute timing. |
| GET | /api/v1/provisioning/mute-timings/export | [route get mute timings export](#route-get-mute-timings-export) | Export all mute timings in provisioning file format. |
| GET | /api/v1/provisioning/mute-timings/:name/export | [route get mute timing export](#route-get-mute-timing-export) | Export a mute timing in provisioning file format. |
| GET | /api/v1/provisioning/templates/:name | [route get template](#route-get-template) | Get a notification template. |
| GET | /api/v1/provisioning/mute-timings/:name | [route get mute timing](#route-get-mute-timing) | Get a mute timing. |
| GET | /api/v1/provisioning/templates | [route get templates](#route-get-templates) | Get all notification templates. |
| GET | /api/v1/provisioning/mute-timings | [route get mute timings](#route-get-mute-timings) | Get all the mute timings. |
| PUT | /api/v1/provisioning/templates/:name | [route put template](#route-put-template) | Create or update a notification template. |
| POST | /api/v1/provisioning/mute-timings | [route post mute timing](#route-post-mute-timing) | Create a new mute timing. |
| PUT | /api/v1/provisioning/mute-timings/:name | [route put mute timing](#route-put-mute-timing) | Replace an existing mute timing. |
| GET | /api/v1/provisioning/mute-timings/export | [route get mute timings export](#route-get-mute-timings-export) | Export all mute timings in provisioning file format. |
| GET | /api/v1/provisioning/mute-timings/:name/export | [route get mute timing export](#route-get-mute-timing-export) | Export a mute timing in provisioning file format. |
**Example Request for all notification templates:**
| name | `path` | string | `string` | | ✓ | | Template Name |
| name | `path` | string | `string` | | ✓ | | Name of the template group |
| version | `query` | string | `string` | | | | Current version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation. |
| version | `query` | string | `string` | | | | Current version of the resource. Used for optimistic concurrency validation. Keep empty to bypass validation. |
#### All responses
#### All responses
@ -1047,7 +1049,7 @@ Status: Not Found
[NotFound](#not-found)
[NotFound](#not-found)
### <spanid="route-get-template"></span> Get a notification template. (_RouteGetTemplate_)
### <spanid="route-get-template"></span> Get a notification template group. (_RouteGetTemplate_)
```
```
GET /api/v1/provisioning/templates/:name
GET /api/v1/provisioning/templates/:name
@ -1055,9 +1057,9 @@ GET /api/v1/provisioning/templates/:name
#### Parameters
#### Parameters
| Name | Source | Type | Go type | Separator | Required | Default | Description |
| Name | Source | Type | Go type | Separator | Required | Default | Description |
description:`Select a single template and preview it, or copy it to paste it in the custom tab. ${templateOption==='Existing'?'Clicking Save will save your changes to the selected template.':''}`,
description:`Select an existing notification template and preview it, or copy it to paste it in the custom tab. ${templateOption==='Existing'?'Clicking Save saves your changes to the selected template.':''}`,
"intro":"Notification templates use Go templating language to create notification messages.\n\nIn Grafana, a template group can define multiple notification templates using {{ define \"<NAME>\" }}.\nThese templates can then be used in contact points and within other notification templates by calling {{ template \"<NAME>\" }}.\nFor detailed information about notification templates, refer to our documentation."
},
"misconfigured-badge-text":"Misconfigured",
"misconfigured-badge-text":"Misconfigured",
"misconfigured-warning":"This template is misconfigured.",
"misconfigured-warning":"This template is misconfigured.",
"misconfigured-warning-details":"Templates must be defined in both the <1></1> and <4></4> sections of your alertmanager configuration."
"misconfigured-warning-details":"Templates must be defined in both the <1></1> and <4></4> sections of your alertmanager configuration."
Pepe Cano
1 year ago
committed by