From d4ddb81fd85318340d3de472250917984b1da8e9 Mon Sep 17 00:00:00 2001
From: Juan Pablo Djeredjian <jpdjeredjian@gmail.com>
Date: Wed, 4 Jan 2023 15:42:04 +0100
Subject: [PATCH] Document the new skipped response parameter of the
 _bulk_action endpoint (#2731)

Relates to: https://github.com/elastic/security-docs/issues/2684

Feature tickets:  https://github.com/elastic/kibana/issues/145093 https://github.com/elastic/kibana/issues/139802

Implemented in PR: https://github.com/elastic/kibana/pull/144461
---
 .../api/rules/rules-api-bulk-actions.asciidoc | 31 +++++++++++++++----
 1 file changed, 25 insertions(+), 6 deletions(-)

diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
index 82e60c4c4a..c1016d6227 100644
--- a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
+++ b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
@@ -427,7 +427,18 @@ POST api/detection_engine/rules/_bulk_action
 [discrete]
 ===== Response payload
 
-For `enable`, `disable`, `delete`, `edit`, and `duplicate` actions, a JSON object containing the action's outcome: number of failed and successful outcomes, number of rules, and number of rule objects created, deleted or updated (depending on the action).
+For `enable`, `disable`, `delete`, `edit`, and `duplicate` actions, a JSON object containing the action's outcome:
+
+- `attributes.summary.total`: Total number of rules matching the bulk action
+- `attributes.summary.succeeded`: Number of successful outcomes (number of rules that were enabled, deleted, or updated)
+- `attributes.summary.failed`: Number of failed outcomes
+- `attributes.summary.skipped`: Number of rules that were skipped due to various reasons (explained below)
+- `attributes.results.created`: Rule objects that were created during the action's execution
+- `attributes.results.updated`: Rule objects that were updated during the action's execution
+- `attributes.results.deleted`: Rule objects that were deleted during the action's execution
+- `attributes.results.skipped`: Rules that were skipped during the action's execution
+
+A rule can only be `skipped` when the bulk action to be performed on it results in nothing being done. For example, if the `edit` action is used to add a tag to a rule that already has that tag, or to delete an index pattern that is not specified in a rule. Objects returned in `attributes.results.skipped` will only include rules' `id`, `name`, and `skip_reason`.
 
 [source,json]
 --------------------------------------------------
@@ -516,12 +527,16 @@ For `enable`, `disable`, `delete`, `edit`, and `duplicate` actions, a JSON objec
          ],
          "deleted":[
 
+         ],
+         "skipped":[
+            { "id": "51658332-a15e-4c9e-912a-67214e2e2359", "name": "Skipped rule", "skip_reason": "RULE_NOT_MODIFIED" }
          ]
       },
       "summary":{
-         "failed":0,
-         "succeeded":1,
-         "total":1
+         "failed": 0,
+         "skipped": 1,
+         "succeeded": 1,
+         "total": 2
       }
    }
 }
@@ -687,11 +702,13 @@ If processing of any rule fails, a partial error outputs the ID and/or name of t
                 }
             ],
             "created": [],
-            "deleted": []
+            "deleted": [],
+            "skipped": [],
         },
         "summary": {
             "failed": 1,
             "succeeded": 1,
+            "skipped": 0,
             "total": 2
         }
     }
@@ -770,11 +787,13 @@ Notice that there are no arrays in `attributes.results`. In dry run mode, rule u
         "results": {
             "updated": [],
             "created": [],
-            "deleted": []
+            "deleted": [],
+            "skipped": [],
         },
         "summary": {
             "failed": 2,
             "succeeded": 1,
+            "skipped": 0,
             "total": 3
         }
     }