Add Docs for Bulk Update Schedule and Rule Actions #2506

jpdjere · 2022-09-27T16:01:06Z

Relates to:

Changes

Updated Bulk Update API request to include new possible payloads for:
- Bulk Update Schedule
- Bulk Update Rule Actions

Images

mergify · 2022-09-27T16:01:12Z

This pull request does not have a backport label. Could you fix it @jpdjere? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

v7.x is the label to automatically backport to the 7.x branch.
v7./d./d is the label to automatically backport to the 7./d branch. /d is the digit

NOTE: backport-skip has been added to this pull request.

github-actions · 2022-09-27T16:01:22Z

Documentation previews:

✨ HTML diff
📙 Elastic Security Guide

jpdjere · 2022-09-27T18:35:48Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+[[actions-object-schema-update]]
+===== `actions` schema
+
+These fields are required when calling `PUT` to modify the `actions` object:
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description
+
+|action_type_id |String a|The action type used for sending notifications, can
+be:
+
+* `.slack`
+* `.email`
+* `.pagerduty`
+* `.webhook`
+
+|group |String |Optionally groups actions by use cases. Use `default` for alert
+notifications.
+
+|id |String |The connector ID.
+
+|params |Object a|Object containing the allowed connector fields, which varies according to the connector type:
+
+* For Slack:
+** `message` (string, required): The notification message.
+* For email:
+** `to`, `cc`, `bcc` (string): Email addresses to which the notifications are
+sent. At least one field must have a value.
+** `subject` (string, optional): Email subject line.
+** `message` (string, required): Email body text.
+* For Webhook:
+** `body` (string, required): JSON payload.
+* For PagerDuty:
+** `severity` (string, required): Severity of on the alert notification, can
+be: `Critical`, `Error`, `Warning` or `Info`.
+** `eventAction` (string, required):  Event https://v2.developer.pagerduty.com/docs/events-api-v2#event-action[action type], which can be `trigger`,
+`resolve`, or `acknowledge`.
+** `dedupKey` (string, optional): Groups alert notifications with the same
+PagerDuty alert.
+** `timestamp` (DateTime, optional): https://v2.developer.pagerduty.com/v2/docs/types#datetime[ISO-8601 format timestamp].
+** `component` (string, optional): Source machine component responsible for the
+event, for example `security-solution`.
+** `group` (string, optional): Enables logical grouping of service components.
+** `source` (string, optional): The affected system. Defaults to the {kib}
+saved object ID of the action.
+** `summary` (string, options): Summary of the event. Defaults to
+`No summary provided`. Maximum length is 1024 characters.
+** `class` (string, optional): Value indicating the class/type of the event.
+
+|==============================================


Copy pasted this actions schema from https://github.com/jpdjere/security-docs/blob/main/docs/detections/api/rules/rules-api-bulk-actions.asciidoc#L334

Does it make sense to extract this definition to its own page and link from both pages to that?

Does it make sense to extract this definition to its own page and link from both pages to that?

I think we'd like to do something like that eventually, but we'll be migrating to a new docs system soon and are trying to limit restructuring ahead of that migration.

jpdjere · 2022-09-27T18:43:34Z

@joepeeples Is the build failing because of the wrong format in the asciidoc file?

joepeeples · 2022-09-27T19:09:02Z

@joepeeples Is the build failing because of the wrong format in the asciidoc file?

I think so, it looks like there are two errors in the console output:

12:09:55 INFO:build_docs:asciidoctor: WARNING: detections/api/rules/rules-api-bulk-actions.asciidoc: line 724: section title out of sequence: expected level 3, got level 4
12:09:55 INFO:build_docs:asciidoctor: WARNING: detections/api/rules/rules-api-bulk-actions.asciidoc: line 724: id assigned to section already in use: actions-object-schema-update

Let me try to push a fix, it'll take just a few minutes

- Add discrete tag to include section on same page of HTML output - Rename section anchor so it's a unique value

joepeeples · 2022-09-27T19:43:36Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+        `actions`: <<actions-object-schema, actions[]>> ,
+        `throttle`: String
+      } | Add actions to rules
+| `set_rule_actions` | {
+        `actions`: <<actions-object-schema, actions[]>> ,


If these links are supposed to point to the new "actions schema" section on this page, the link anchors need to be revised (below); currently they're pointing to the section on the Create rule page.

Suggested change

`actions`: <<actions-object-schema, actions[]>> ,

`throttle`: String

} | Add actions to rules

| `set_rule_actions` | {

`actions`: <<actions-object-schema, actions[]>> ,

`actions`: <<actions-object-schema-bulk, actions[]>> ,

`throttle`: String

} | Add actions to rules

| `set_rule_actions` | {

`actions`: <<actions-object-schema-bulk, actions[]>> ,

Thanks 👍 fixed following your suggestion

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

banderror · 2022-09-27T21:58:48Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+
+| `add_rule_actions` | {
+        `actions`: <<actions-object-schema, actions[]>> ,
+        `throttle`: String


Throttle is not documented for add_rule_actions while it is for set_rule_actions. How do we usually document the same request parameters or response objects used in multiple contexts?

I extracted out the throttle schema to the bottom of the page and linked to it from both add_rule_actions and set_rule_actions. What do you think? Also not exactly sure if to call a single property "schema" (I mean "throttle schema")

I'd call it just throttle 🤷‍♂️

banderror · 2022-09-27T22:04:05Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+[discrete]
+[[actions-object-schema-bulk]]
+===== `actions` schema


Is this section going to be deleted?

I think it shouldn't. See Joe's comment above: I would have liked to extract the actions schema to its own page and link to it from both this page and from this page, but he mentioned that he'd rather not do these refactoring before the docs are migrated, soon.

And I think the actions schema should be in this page, otherwise it's confusing to understand what it means in the context of this API request.

I see. The reason I asked is that when I was reviewing this PR links to the actions schema were pointing to the rule creation endpoint. Now when they send the user to this section it LGTM 👍

What I'd probably do is I'd lift "actions schema" and "throttle schema" up, because right now the page structure is:

"BulkEditAction object" - its schema

Examples

"actions schema"

"throttle schema"

I'd keep examples after all schemas

Makes sense, reorganized page

jpdjere · 2022-09-28T15:22:38Z

@joepeeples

This is ready for review. Thanks for your comments!

The preview link: https://security-docs_2506.docs-preview.app.elstc.co/guide/en/security/master/bulk-actions-rules-api.html

banderror

Looks great, thank you! 🚀

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

banderror · 2022-09-29T11:40:22Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+[discrete]
+[[actions-object-schema-bulk]]
+===== `actions` schema


I see. The reason I asked is that when I was reviewing this PR links to the actions schema were pointing to the rule creation endpoint. Now when they send the user to this section it LGTM 👍

banderror · 2022-09-29T11:42:59Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+[discrete]
+[[actions-object-schema-bulk]]
+===== `actions` schema


What I'd probably do is I'd lift "actions schema" and "throttle schema" up, because right now the page structure is:

"BulkEditAction object" - its schema

Examples

"actions schema"

"throttle schema"

I'd keep examples after all schemas

End of block line probably got deleted accidentally

joepeeples

Added a few line edits for consideration, and got the build preview working again. Thanks for including me in the review!

joepeeples · 2022-09-30T15:14:41Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+
+`lookback`: Additional look-back time that the rule analyzes. For example, `"10m"` means the rule analyzes the last 10 minutes of data in addition to the frequency interval.
+
+If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.


Modified this example to be consistent with the previous two examples for interval and lookback:

Suggested change

If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.

If `interval` is set to `"10m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 11 minutes.

joepeeples · 2022-09-30T15:17:27Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+Both `interval` and `lookback` have a format of {integer}{time_unit}, with the accepted time units being `"s"` for
+seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and larger than 0.
+
+Examples: `"45s"`, `"30m"`, `"6h"` 


Suggested change

Both `interval` and `lookback` have a format of {integer}{time_unit}, with the accepted time units being `"s"` for

seconds, `"m"` for minutes and `"h"` for hours. The integer must be positive and larger than 0.

Examples: `"45s"`, `"30m"`, `"6h"`

Both `interval` and `lookback` have a format of `"{integer}{time_unit}"`, where accepted time units are `s` for seconds, `m` for minutes, and `h` for hours. The integer must be positive and larger than 0. Examples: `"45s"`, `"30m"`, `"6h"`

joepeeples · 2022-09-30T16:06:47Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+
+---
+


I'd omit the horiz rule line. We don't use them much in general, and here in particular it makes the throttle section look like it might be part of the preceding table.

Suggested change

---

joepeeples · 2022-09-30T16:07:46Z

docs/detections/api/rules/rules-api-bulk-actions.asciidoc

+===== `throttle` schema
+
+
+`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values:


Suggested change

`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values:

`throttle` defines the maximum interval in which a rule's actions are executed. It accepts the following values:

…/github.com/jpdjere/security-docs into add-docs-for-bulk-edit-schedule-and-actions

jpdjere · 2022-09-30T16:21:28Z

@joepeeples Thanks Joe! Addressed all your comments 👍

Please et me know if I should go ahead and merge this once the tests pass.

joepeeples · 2022-09-30T16:54:28Z

Please et me know if I should go ahead and merge this once the tests pass.

Yes, LGTM! 👍 Thanks again for this update

## Relates to: #2441 #2453 ## Changes - Updated Bulk Update API request to include new possible payloads for: - Bulk Update Schedule - Bulk Update Rule Actions ## Images ![image](https://user-images.githubusercontent.com/5354282/192609873-9dc20d53-0beb-4489-9987-df611a735801.png) (cherry picked from commit c76fac6)

## Relates to: #2441 #2453 ## Changes - Updated Bulk Update API request to include new possible payloads for: - Bulk Update Schedule - Bulk Update Rule Actions ## Images ![image](https://user-images.githubusercontent.com/5354282/192609873-9dc20d53-0beb-4489-9987-df611a735801.png) (cherry picked from commit c76fac6) Co-authored-by: Juan Pablo Djeredjian <jpdjeredjian@gmail.com>

Add Docs for Bulk Update Schedule and Rule Actions

fa83ddb

mergify bot added the backport-skip label Sep 27, 2022

jpdjere added the v8.5.0 label Sep 27, 2022

mergify bot removed the backport-skip label Sep 27, 2022

jpdjere self-assigned this Sep 27, 2022

jpdjere commented Sep 27, 2022

View reviewed changes

Fix CI build checks

faee8fe

- Add discrete tag to include section on same page of HTML output - Rename section anchor so it's a unique value

joepeeples reviewed Sep 27, 2022

View reviewed changes

banderror reviewed Sep 27, 2022

View reviewed changes

Refactor throttle schema

f3bc0ad

jpdjere requested review from joepeeples and banderror September 29, 2022 10:24

banderror approved these changes Sep 29, 2022

View reviewed changes

jpdjere and others added 3 commits September 29, 2022 15:20

Reorganized structure of page

35e5ed4

Merge branch 'main' into add-docs-for-bulk-edit-schedule-and-actions

f1e79fb

Fix build

6a99fdf

End of block line probably got deleted accidentally

joepeeples reviewed Sep 30, 2022

View reviewed changes

jpdjere added 2 commits September 30, 2022 18:18

Address comments by security-docs team

8c28038

Merge branch 'add-docs-for-bulk-edit-schedule-and-actions' of https:/…

335deed

…/github.com/jpdjere/security-docs into add-docs-for-bulk-edit-schedule-and-actions

joepeeples added Team: Docs Team: Detections/Response Detections and Response API Feature: Rules labels Sep 30, 2022

jpdjere merged commit c76fac6 into elastic:main Sep 30, 2022

jpdjere deleted the add-docs-for-bulk-edit-schedule-and-actions branch September 30, 2022 18:02

mergify bot mentioned this pull request Sep 30, 2022

[8.5] Add Docs for Bulk Update Schedule and Rule Actions (backport #2506) #2523

Merged

joepeeples mentioned this pull request Oct 12, 2022

[DOCS] Bulk edit rule actions #2441

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Docs for Bulk Update Schedule and Rule Actions #2506

Add Docs for Bulk Update Schedule and Rule Actions #2506

jpdjere commented Sep 27, 2022 •

edited

Loading

mergify bot commented Sep 27, 2022

github-actions bot commented Sep 27, 2022

jpdjere Sep 27, 2022

joepeeples Sep 27, 2022

jpdjere commented Sep 27, 2022

joepeeples commented Sep 27, 2022

joepeeples Sep 27, 2022

jpdjere Sep 28, 2022

banderror Sep 27, 2022

jpdjere Sep 28, 2022

banderror Sep 29, 2022

banderror Sep 27, 2022

jpdjere Sep 28, 2022 •

edited

Loading

banderror Sep 29, 2022 •

edited

Loading

banderror Sep 29, 2022

jpdjere Sep 29, 2022

jpdjere commented Sep 28, 2022

banderror left a comment

banderror Sep 29, 2022 •

edited

Loading

banderror Sep 29, 2022

joepeeples left a comment

joepeeples Sep 30, 2022

joepeeples Sep 30, 2022

joepeeples Sep 30, 2022

joepeeples Sep 30, 2022

jpdjere commented Sep 30, 2022

joepeeples commented Sep 30, 2022


		`lookback`: Additional look-back time that the rule analyzes. For example, `"10m"` means the rule analyzes the last 10 minutes of data in addition to the frequency interval.

		If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.

	If `interval` is set to `"5m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 6 minutes.
	If `interval` is set to `"10m"` and `lookback` to `"1m"`, then the rule runs every 5 minutes but analyzes the documents added to indices during the last 11 minutes.

		===== `throttle` schema


		`throttle` defines the maximum interval in which a rules `actions` are executed. It accepts the following values:

Add Docs for Bulk Update Schedule and Rule Actions #2506

Add Docs for Bulk Update Schedule and Rule Actions #2506

Conversation

jpdjere commented Sep 27, 2022 • edited Loading

Relates to:

Changes

Images

mergify bot commented Sep 27, 2022

github-actions bot commented Sep 27, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpdjere commented Sep 27, 2022

joepeeples commented Sep 27, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpdjere Sep 28, 2022 • edited Loading

Choose a reason for hiding this comment

banderror Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpdjere commented Sep 28, 2022

banderror left a comment

Choose a reason for hiding this comment

banderror Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joepeeples left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jpdjere commented Sep 30, 2022

joepeeples commented Sep 30, 2022

jpdjere commented Sep 27, 2022 •

edited

Loading

jpdjere Sep 28, 2022 •

edited

Loading

banderror Sep 29, 2022 •

edited

Loading

banderror Sep 29, 2022 •

edited

Loading