Merge pull request #237200 from AbbyMSFT/custom-props

Changes to common schema custom properties

Author: v-ccolin

articles/azure-monitor/alerts/alerts-common-schema.md

@@ -22,7 +22,8 @@ The common alert schema provides a consistent structure for:
     - Azure Automation runbook
 
 > [!NOTE]
-> Alerts generated by [VM insights](../vm/vminsights-overview.md) do not support the common schema.
+> - Alerts generated by [VM insights](../vm/vminsights-overview.md) do not support the common schema.
+>-  Smart detection alerts use the common schema by default. You don't have to enable the common schema for smart detection alerts.
 
 ## Structure of the common schema 
 
@@ -31,10 +32,8 @@ The common schema includes information about the affected resource and the cause
 
     If you want to route alert instances to specific teams based on criteria such as a resource group, you can use the fields in the **Essentials** section to provide routing logic for all alert types. The teams that receive the alert notification can then use the context fields for their investigation.
 - **Alert context**: Fields that vary depending on the type of the alert. The alert context fields describe the cause of the alert. For example, a metric alert would have fields like the metric name and metric value in the alert context. An activity log alert would have information about the event that generated the alert.
-- **Custom properties**: You can add more information to the alert payload by adding custom properties if you've configured action groups for a metric alert rule. 
+- **Custom properties**: Additional information that is not included in the alert payload by default can be included in the alert payload using custom properties. Custom properties are a **Key:Value** pair that can include any information configured in the alert rule.  
 
-    > [!NOTE]
-    > Custom properties are currently only supported by metric alerts. For all other alert types, the **custom properties** field is null.
 ## Sample alert payload
 
 ```json
@@ -139,8 +138,6 @@ For sample alerts that use the common schema, see [Sample alert payloads](alerts
 |webTestName          |If the condition type is `webtest`, the name of the webtest.         |
 |windowStartTime      |The start time of the evaluation window in which the alert fired.       |
 |windowEndTime        |The end time of the evaluation window in which the alert fired.         |
-|customProperties     ||
-
 ### Sample metric alert with a static threshold when the monitoringService = `Platform`
 
 ```json
@@ -675,21 +672,13 @@ See [Azure Monitor managed service for Prometheus rule groups (preview)](../esse
 ```
 ## Custom properties fields
 
-If you've configured action groups for a metric alert rule, you can add more information to the alert payload by adding custom properties.
-
-The custom properties section contains “key: value” objects that are added to webhook notifications. 
+If the alert rule that generated your alert contains action groups, custom properties can contain additional information about the alert. The custom properties section contains “key: value” objects that are added to webhook notifications. 
 
 If custom properties aren't set in the alert rule, the field is null.
-
-> [!NOTE]
-> Custom properties are currently only supported by metric alerts. For all other alert types, the **custom properties** field is null.
 ## Enable the common alert schema
 
 Use action groups in the Azure portal or use the REST API to enable the common alert schema. Schemas are defined at the action level. For example, you must separately enable the schema for an email action and a webhook action.
 
-> [!NOTE]
-> Smart detection alerts support the common schema by default. You don't have to enable the common schema for smart detection alerts.
-
 ### Enable the common schema in the Azure portal
 
 ![Screenshot that shows the common alert schema opt in.](media/alerts-common-schema/portal-opt-in.png)

articles/azure-monitor/alerts/alerts-create-new-alert-rule.md

@@ -243,6 +243,19 @@ Alerts triggered by these alert rules contain a payload that uses the [common al
 
     :::image type="content" source="media/alerts-create-new-alert-rule/alerts-rule-actions-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new alert rule.":::
 
+1. (Optional)  In the **Custom properties** section, if you've configured action groups for this alert rule, you can add custom properties in key:value pairs to the alert payload to add more information to the payload. Add the property **Name** and **Value** for the custom property you want included in the payload.
+
+    You can also use custom properties to extract and manipulate data from alert payloads that use the common schema. You can use those values in the action group webhook or logic app.
+
+    The format for extracting values from the common schema, use a "$", and then the path of the common schema field inside curly brackets. For example: `${data.essentials.monitorCondition}`.
+
+    For example, you could use these values in the **custom properties** to utilize data from the payload.
+
+    |Custom properties name  |Custom properties value  |Result  |
+    |---------|---------|---------|
+    |AdditionalDetails|Evaluation windowStartTime: ${data.alertContext.condition.windowStartTime}. windowEndTime: ${data.alertContext.condition.windowEndTime}|AdditionalDetails": "Evaluation windowStartTime: 2023-04-04T14:39:24.492Z. windowEndTime: 2023-04-04T14:44:24.492Z"         |
+    |Alert ${data.essentials.monitorCondition} reason     |“${data.alertContext.condition.allOf[0].metricName} ${data.alertContext.condition.allOf[0].operator}${data.alertContext.condition.allOf[0].threshold} ${data.essentials.monitorCondition}. The value is ${data.alertContext.condition.allOf[0].metricValue}"         |Examples of the results could be: <br> - Alert Resolved reason": "Percentage CPU GreaterThan5 Resolved. The value is 3.585 <br>Percentage CPU GreaterThan5 Fired. The value is 10.585  |
+
 1. On the **Details** tab, define the **Project details**.
     - Select the **Subscription**.
     - Select the **Resource group**.
@@ -267,9 +280,8 @@ Alerts triggered by these alert rules contain a payload that uses the [common al
         |---------|---------|
         |Enable upon creation| Select for the alert rule to start running as soon as you're done creating it.|
         |Automatically resolve alerts (preview) |Select to make the alert stateful. When an alert is stateful, the alert is resolved when the condition is no longer met.<br> If you don't select this checkbox, metric alerts are stateless. Stateless alerts fire each time the condition is met, even if alert already fired.<br> The frequency of notifications for stateless metric alerts differs based on the alert rule's configured frequency:<br>**Alert frequency of less than 5 minutes**: While the condition continues to be met, a notification is sent somewhere between one and six minutes.<br>**Alert frequency of more than 5 minutes**: While the condition continues to be met, a notification is sent between the configured frequency and double the frequency. For example, for an alert rule with a frequency of 15 minutes, a notification is sent somewhere between 15 to 30 minutes.|
-    1. (Optional) If you've configured action groups for this alert rule, you can add custom properties to the alert payload to add more information to the payload. In the **Custom properties** section, add the property **Name** and **Value** for the custom property you want included in the payload.
 
-        :::image type="content" source="media/alerts-create-new-alert-rule/alerts-metric-rule-details-tab.png" alt-text="Screenshot that shows the Details tab when creating a new alert rule.":::
+    :::image type="content" source="media/alerts-create-new-alert-rule/alerts-metric-rule-details-tab.png" alt-text="Screenshot that shows the Details tab when creating a new alert rule.":::
 
     ### [Log alert](#tab/log)
 
@@ -285,48 +297,31 @@ Alerts triggered by these alert rules contain a payload that uses the [common al
         |Mute actions |Select to set a period of time to wait before alert actions are triggered again. If you select this checkbox, the **Mute actions for** field appears to select the amount of time to wait after an alert is fired before triggering actions again.|
         |Check workspace linked storage|Select if logs workspace linked storage for alerts is configured. If no linked storage is configured, the rule isn't created.|
 
-    1. (Optional) If you've configured action groups for this alert rule, you can add custom properties to the alert payload to add more information to the payload. In the **Custom properties** section, add the property **Name** and **Value** for the custom property you want included in the payload.
-
-        > [!NOTE]
-        > The [common schema](alerts-common-schema.md) overwrites custom configurations. Therefore, you can't use both custom properties and the common schema for log alerts.
-
-        :::image type="content" source="media/alerts-create-new-alert-rule/alerts-log-rule-details-tab.png" alt-text="Screenshot that shows the Details tab when creating a new log alert rule.":::
+    :::image type="content" source="media/alerts-create-new-alert-rule/alerts-log-rule-details-tab.png" alt-text="Screenshot that shows the Details tab when creating a new log alert rule.":::
 
     ### [Activity log alert](#tab/activity-log)
 
     1. Enter values for the **Alert rule name** and the **Alert rule description**.
     1. Select the **Region**.
-    1. (Optional) In the **Advanced options** section, select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
-    1. (Optional) If you've configured action groups for this alert rule, you can add custom properties to the alert payload to add more information to the payload. In the **Custom properties** section, add the property **Name** and **Value** for the custom property you want included in the payload.
-
-        > [!NOTE]
-        > The [common schema](alerts-common-schema.md) overwrites custom configurations. Therefore, you can't use both custom properties and the common schema for activity log alerts.
+    1. Select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
 
-        :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
+    :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
 
     ### [Resource Health alert](#tab/resource-health)
 
     1. Enter values for the **Alert rule name** and the **Alert rule description**.
     1. Select the **Region**.
-    1. (Optional) In the **Advanced options** section, select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
-    1. (Optional) If you've configured action groups for this alert rule, you can add custom properties to the alert payload to add more information to the payload. In the **Custom properties** section, add the property **Name** and **Value** for the custom property you want included in the payload.
+    1. Select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
 
-        > [!NOTE]
-        > The [common schema](alerts-common-schema.md) overwrites custom configurations. Therefore, you can't use both custom properties and the common schema for resource health alerts.
-
-        :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
+    :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
 
     ### [Service Health alert](#tab/service-health)
 
     1. Enter values for the **Alert rule name** and the **Alert rule description**.
     1. Select the **Region**.
-    1. (Optional) In the **Advanced options** section, select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
-    1. (Optional) If you've configured action groups for this alert rule, you can add custom properties to the alert payload to add more information to the payload. In the **Custom properties** section, add the property **Name** and **Value** for the custom property you want included in the payload.
-
-        > [!NOTE]
-        > The [common schema](alerts-common-schema.md) overwrites custom configurations. Therefore, you can't use both custom properties and the common schema for service health alerts.
+    1. Select **Enable upon creation** for the alert rule to start running as soon as you're done creating it.
 
-        :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
+    :::image type="content" source="media/alerts-create-new-alert-rule/alerts-activity-log-rule-details-tab.png" alt-text="Screenshot that shows the Actions tab when creating a new activity log alert rule.":::
 
     ---