Docs for "Alert User Assignment" feature (#4476)

* First draft * Fixed anchor * Updated expand-details-button.png * Minor fixes * Adding icons * Removing line break * Removed extra lines * Update alerts-view-details.asciidoc * Remove extra paren * Adding missing colons * Fixing inline images * Removing borders * Update docs/reference/alert-schema.asciidoc * Update docs/detections/alerts-ui-manage.asciidoc * Moving note.
elastic · Jan 4, 2024 · aa17f9d · aa17f9d
1 parent 474ac29
commit aa17f9d
Show file tree

Hide file tree

Showing 15 changed files with 70 additions and 5 deletions.
diff --git a/docs/detections/alerts-ui-manage.asciidoc b/docs/detections/alerts-ui-manage.asciidoc
@@ -139,6 +139,8 @@ From the Alerts table or the alert details flyout, you can:
 * <<detection-alert-status>>
 * <<add-exception-from-alerts>>
 * <<apply-alert-tags>>
+* <<assign-users-to-alerts>>
+* <<filter-assigned-alerts>>
 * <<endpoint-rule-exceptions,Add an endpoint exception from an alert>>
 * <<host-isolation-ov,Isolate an alert's host>>
 * <<response-actions,Perform response actions on an alert's host>> (Alert details flyout only)
@@ -184,10 +186,65 @@ To apply or remove alert tags on individual alerts, do one of the following:
 
 To apply or remove alert tags on multiple alerts, select the alerts you want to change, then click *Selected _x_ alerts* at the upper-left above the table. Click *Apply alert tags*, select or unselect tags, then click *Apply tags*. 
 
-
 [role="screenshot"]
 image::images/bulk-apply-alert-tag.png[Bulk action menu with multiple alerts selected, 450]
 
+[float]
+[[assign-users-to-alerts]]
+==== Assign users to alerts
+
+Assign users to alerts that you want them to investigate, and manage alert assignees throughout an alert's lifecycle.  
+
+IMPORTANT: Users are not notified when they've been assigned to, or unassigned from, alerts.  
+
+|==============================================
+| Action | Instructions 
+
+| Assign users to an alert 
+
+a| Choose one of the following:
+
+* **Alerts table** - Click **More actions** (**...**) in an alert's row, then click **Assign alert**. Select users, then click **Apply**. 
+* **Alert details flyout** - Click **Take action -> Assign alert**. Alternatively, click the **Assign alert** icon at the top of the alert details flyout, select users, then click **Apply**. 
+
+|Unassign all users from an alert
+
+a| Choose one of the following:
+
+* **Alerts table** - Click **More actions** (**...**) in an alert's row, then click **Unassign alert**.  
+* **Alert details flyout** - Click **Take action -> Unassign alert**. 
+
+| Assign users to multiple alerts
+
+a| From the Alerts table, select the alerts you want to change. Click **Selected _x_ alerts** at the upper-left above the table, then click **Assign alert**. Select users, then click **Apply**. 
+
+NOTE: Users assigned to some of the selected alerts will be displayed as unassigned in the selection list. Selecting said users will assign them to all alerts they haven't been assigned to yet.
+
+| Unassign users from multiple alerts
+
+| From the Alerts table, select the alerts you want to change and click **Selected _x_ alerts** at the upper-left above the table. Click **Unassign alert** to remove users from the alert. 
+
+|==============================================
+
+Show users that have been assigned to alerts by adding the **Assignees** column to the Alerts table (**Fields** → `kibana.alert.workflow_assignee_ids`). Up to four assigned users can appear in the **Assignees** column. If an alert is assigned to five or more users, a number appears instead. 
+
+[role="screenshot"]
+image::images/alert-assigned-alerts.png[Alert assignees in the Alerts table, 650]
+
+Assigned users are automatically displayed in the alert details flyout. Up to two assigned users can be shown in the flyout. If an alert is assigned to three or more users, a numbered badge displays instead.
+
+[role="screenshot"]
+image::images/alert-flyout-assignees.png[Alert assignees in the alert details flyout, 450]
+
+[float]
+[[filter-assigned-alerts]]
+==== Filter assigned alerts
+
+Click the **Assignees** filter above the Alerts table, then select the users you want to filter by. 
+
+[role="screenshot"]
+image::images/alert-filter-assigned-alerts.png[Filtering assigned alerts, 650]
+
 [float]
 [[add-exception-from-alerts]]
 ==== Add a rule exception from an alert
@@ -213,8 +270,7 @@ image::images/timeline-button.png[Investigate in timeline button, 300]
 
 * To view multiple alerts in Timeline (up to 2,000), select the checkboxes next to the alerts, then click *Selected _x_ alerts* -> *Investigate in timeline*.
 +
-image::images/bulk-add-alerts-to-timeline.png[Bulk add alerts to timeline button,30%,30%]
-
+image::images/bulk-add-alerts-to-timeline.png[Bulk add alerts to timeline button,50%,50%]
 
 TIP: When you send an alert generated by a
 <<rules-ui-create, threshold rule>> to Timeline, all matching events are

diff --git a/docs/detections/alerts-view-details.asciidoc b/docs/detections/alerts-view-details.asciidoc
@@ -33,8 +33,8 @@ image::images/alert-details-flyout-right-panel.png[Right panel of the alert deta
 From the right panel, you can also:
 
 * Click **Expand details** to open the <<left-panel,left panel>>, which shows more information about sections in the right panel.
-* Click **Chat** to access the <<security-assistant>>.
-* Click **Share alert** to get a shareable alert URL. We _do not_ recommend copying the URL from your browser's address bar, which can lead to inconsistent results if you've set up filters or relative time ranges for the Alerts page. 
+* Click the **Chat** icon (image:images/ai-assistant-chat.png[AI assistant chat icon,15,15]) to access the <<security-assistant>>.
+* Click the **Share alert** icon (image:images/share-alert.png[Share alert icon,15,15]) to get a shareable alert URL. We _do not_ recommend copying the URL from your browser's address bar, which can lead to inconsistent results if you've set up filters or relative time ranges for the Alerts page. 
 +
 NOTE: If you've configured the {kibana-ref}/settings.html#server-publicBaseUrl[`server.publicBaseUrl`] setting in the `kibana.yml` file, the shareable URL is also in the `kibana.alert.url` field. You can find the field by searching for `kibana.alert.url` on the *Table* tab.
 +
@@ -46,6 +46,7 @@ IMPORTANT: If you've enabled grouping on the Alerts page, the alert details flyo
 ** Alert status
 ** Date and time the alert was created
 ** Alert severity and risk score (these are inherited from rule that generated the alert)
+** Users assigned to the alert (click the **Assign alert** image:images/assign-alert.png[Assign alert,15,15] icon to assign more users)
 
 * Click the **Table** or **JSON** tabs to display the alert details in table or JSON format. In table format, alert details are displayed as field-value pairs. 
 

diff --git a/docs/detections/images/ai-assistant-chat.png b/docs/detections/images/ai-assistant-chat.png
diff --git a/docs/detections/images/alert-assigned-alerts.png b/docs/detections/images/alert-assigned-alerts.png
diff --git a/docs/detections/images/alert-change-status.png b/docs/detections/images/alert-change-status.png
diff --git a/docs/detections/images/alert-details-flyout-preview-panel.gif b/docs/detections/images/alert-details-flyout-preview-panel.gif
diff --git a/docs/detections/images/alert-details-flyout-right-panel.png b/docs/detections/images/alert-details-flyout-right-panel.png
diff --git a/docs/detections/images/alert-filter-assigned-alerts.png b/docs/detections/images/alert-filter-assigned-alerts.png
diff --git a/docs/detections/images/alert-flyout-assignees.png b/docs/detections/images/alert-flyout-assignees.png
diff --git a/docs/detections/images/assign-alert.png b/docs/detections/images/assign-alert.png
diff --git a/docs/detections/images/bulk-add-alerts-to-timeline.png b/docs/detections/images/bulk-add-alerts-to-timeline.png
diff --git a/docs/detections/images/expand-details-button.png b/docs/detections/images/expand-details-button.png
diff --git a/docs/detections/images/open-alert-details-flyout.gif b/docs/detections/images/open-alert-details-flyout.gif
diff --git a/docs/detections/images/share-alert.png b/docs/detections/images/share-alert.png
diff --git a/docs/reference/alert-schema.asciidoc b/docs/reference/alert-schema.asciidoc
@@ -183,4 +183,12 @@ This field can contain an array of values, for example: `["False Positive", "pro
 
 Type: keyword
 
+|N/A | `kibana.alert.workflow_assignee_ids` a| List of users assigned to an alert. 
+
+An array of unique identifiers (UIDs) for user profiles, for example: `["u_1-0CcWliOCQ9T2MrK5YDjhpxZ_AcxPKt3pwaICcnAUY_0, u_2-0CcWliOCQ9T2MrK5YDjhpxZ_AcxPKt3pwaICcnAUY_1"]`
+
+UIDs are linked to user profiles that are automatically created when users first log into a deployment. These profiles contain names, emails, profile avatars, and other user settings.
+
+Type: string[] 
+
 |==============================================