(DOCSP-29040): Backport DOCSP-28882 to v6.0. (#4979)

corryroot · corryroot · commit 9d26dc3b2a18 · 2023-04-10T12:05:12.000-04:00
* (DOCSP-28882): Added an Alerts Workflow. * (DOCSP-28882): Incorporated Dave's feedback. * (DOCSP-28882): Incorporated Dave's feedback.
diff --git a/source/includes/extracts-alerts.yaml b/source/includes/extracts-alerts.yaml
@@ -6,7 +6,8 @@ content: |
   :doc:`global </tutorial/manage-global-alerts>` alert you create, you must
   set a target and a condition or metric. The *target* points to what changed:
   the |mms| component. If your *condition* becomes true or a *metric* meets
-  your set threshold, |mms| triggers an alert.
+  your set threshold, |mms| triggers an alert. To learn more, see 
+  :ref:`alerts-workflow`.
 
 ---
 ref: alert-overview
@@ -16,7 +17,8 @@ content: |
   For each :doc:`alert </tutorial/manage-alert-configurations>` you create,
   you must set a target and a condition or metric. The *target* points to what
   changed: the |mms| component. If your *condition* becomes true or a *metric*
-  falls below or rises above your set threshold, |mms| triggers an alert.
+  falls below or rises above your set threshold, |mms| triggers an 
+  alert. To learn more, see :ref:`alerts-workflow`.
 
 ---
 ref: alert-conf-call-failure
diff --git a/source/includes/steps-alerts-workflow.yaml b/source/includes/steps-alerts-workflow.yaml
@@ -0,0 +1,71 @@
+title: The alert condition is met.
+level: 4
+ref: alert-triggers-aw
+content: |
+
+  - For informational alerts like the 
+    :alert-type:`User joined the organization <JOINED_ORG>`. 
+    alert, |mms| sends notifications as soon as the condition is 
+    met. These alerts don't appear in the |mms| UI. The 
+    informational alerts workflow ends here.
+
+  - Otherwise, |mms| retrieves metrics at regular intervals 
+    based on granularity. When the retrieved metrics indicate that 
+    an alert condition is met, |mms| tracks the alert condition 
+    until it ends, or until it remains past the amount of time 
+    specified in the :guilabel:`send if condition lasts at least` 
+    field.
+
+    .. note::
+
+       If the alert condition ends between sampling periods, 
+       |mms| doesn't track the alert condition or send any 
+       notifications.
+
+---
+title: The alert condition remains past the amount of time specified in the :guilabel:`send if condition lasts at least` field.
+level: 4
+ref: notification-threshold-aw
+content: |
+
+  |mms| sends notifications. The alerts appear on the 
+  :guilabel:`All Alerts` tab (organization alerts) or the 
+  :guilabel:`Open Alerts` tab (project alerts).
+
+---
+title: The alert remains active until it resolves, or you disable or delete it.
+level: 4
+ref: alert-active-aw
+content: |
+
+  The following stages might occur:
+
+  - You :ref:`acknowledge the alert <acknowledge-alert>`. |mms| 
+    sends no further notifications until either the acknowledgement 
+    period ends, you resolve the alert condition, or you 
+    unacknowledge the alert. If an alert condition ends during an 
+    acknowledgment period, |mms| sends a notification.
+
+  - You :ref:`unacknowledge an alert <unacknowledge-alert>` that 
+    you previously acknowledged. After you unacknowledge an active 
+    alert, |mms| resumes sending notifications at regular 
+    intervals until the condition resolves or you delete, disable, 
+    or re-acknowledge the alert.
+
+  - You :ref:`disable the alert <disable-enable-alert-setting>`. 
+    |mms| cancels active alerts related to the setting. A disabled 
+    alert setting remains visible but grayed-out and you can later 
+    re-enable it.
+
+  - You :ref:`enable an alert <disable-enable-alert-setting>` that 
+    you previously disabled.
+
+  - You :ref:`delete the alert <delete-alert-setting>`. |mms| 
+    cancels active alerts related to the setting. A deleted alert 
+    setting does not remain visible.
+
+  - The alert condition resolves. The alert appears on the 
+    :guilabel:`All Alerts` tab (organization alerts) or the 
+    :guilabel:`Closed Alerts` tab (project alerts).
+
+...
diff --git a/source/includes/steps-view-org-alerts.yaml b/source/includes/steps-view-org-alerts.yaml
@@ -7,4 +7,5 @@ stepnum: 2
 level: 4
 ref: alerts-org
 title: "If it is not already displayed, click the :guilabel:`All Alerts` tab."
+
 ...
diff --git a/source/tutorial/manage-alert-configurations.txt b/source/tutorial/manage-alert-configurations.txt
@@ -202,6 +202,8 @@ When you create a new alert, you can clone an existing alert.
 
       .. include:: /includes/steps/configure-project-alert.rst
 
+.. _delete-alert-setting:
+
 Delete an Alert Configuration
 -----------------------------
 
@@ -221,6 +223,8 @@ Delete an Alert Configuration
 If you delete an alert setting, |mms| cancels active alerts related to
 the setting. A deleted alert setting does not remain visible.
 
+.. _disable-enable-alert-setting:
+
 Disable or Enable an Alert Configuration
 ----------------------------------------
 
@@ -253,11 +257,21 @@ View the History of Changes to an Alert Configuration
    .. tab:: Organization Alerts
       :tabid: org
 
+      You can view all alerts, alert settings, and deleted alerts on 
+      the :guilabel:`Organization Alerts` page. To learn more, see 
+      :ref:`alerts-workflow`.
+
       .. include:: /includes/steps/alert-configuration-history-org.rst
 
    .. tab:: Project Alerts
       :tabid: project
 
+      You can view open alerts, closed alerts, and alert 
+      settings on the :guilabel:`Project Alerts` page. 
+      |mms| sends notifications for all alerts 
+      that appear on the :guilabel:`Open` tab. To learn more, 
+      see :ref:`alerts-workflow`.
+
       .. include:: /includes/steps/alert-configuration-history.rst
 
 
diff --git a/source/tutorial/manage-alerts-and-events.txt b/source/tutorial/manage-alerts-and-events.txt
@@ -42,13 +42,23 @@ View Alerts
      - id: org
        name: Organization Alerts
        content: |
+
+         You can view all alerts, alert settings, and deleted alerts on 
+         the :guilabel:`Organization Alerts` page. To learn more, see 
+         :ref:`alerts-workflow`.
          
          .. include:: /includes/steps/view-org-alerts.rst
 
      - id: project
        name: Project Alerts
        content: |
 
+         You can view open alerts, closed alerts, and alert 
+         settings on the :guilabel:`Project Alerts` page. 
+         |service| sends notifications for all alerts 
+         that appear on the :guilabel:`Open` tab. To learn more, 
+         see :ref:`alerts-workflow`.
+
          .. include:: /includes/steps/view-proj-alerts.rst
 
 .. _mms_view_all_activity:
@@ -77,6 +87,8 @@ Retrieve the Activity Feed
 You can retrieve events for a specified organization or project using
 the :doc:`/reference/api/events/` |api| resource.
 
+.. _acknowledge-alert:
+
 Acknowledge an Alert
 --------------------
 
@@ -109,6 +121,8 @@ PagerDuty dashboard.
 
          .. include:: /includes/steps/alerts-acknowledge-proj.rst
 
+.. _unacknowledge-alert:
+
 Unacknowledge an Alert
 ----------------------
 
diff --git a/source/tutorial/nav/alert-resolutions.txt b/source/tutorial/nav/alert-resolutions.txt
@@ -25,7 +25,7 @@ that suspends host alerts while you shut down hosts for maintenance.
 
 .. include:: /includes/extracts/manage-alerts-and-events-overview.rst
 
-To learn more, see :ref:`manage-alerts`.
+To learn more, see :ref:`alerts-workflow` and :ref:`manage-alerts`.
 
 .. _resolved-alert:
 
diff --git a/source/tutorial/nav/alerts.txt b/source/tutorial/nav/alerts.txt
@@ -43,6 +43,16 @@ future. To learn how to fix the immediate problem, implement a
 long-term solution, and monitor your progress, see 
 :ref:`alerts-resolutions`.
 
+.. _alerts-workflow:
+
+Alerts Workflow
+---------------
+
+When an :ref:`alert condition <alert-conditions>` is met, the following 
+alert lifecycle begins:
+
+.. include:: /includes/steps/alerts-workflow.rst
+
 .. toctree::
    :titlesonly:
    :hidden:
