Updates related_integrations field API docs #5183

maximpn · 2024-05-08T10:57:03Z

Relates to: elastic/kibana#173595
Epic: https://github.com/elastic/security-team/issues/1974

Summary

API updates for elastic/kibana#173595.

Updates related API docs for related_integration field changes made in elastic/kibana#178295.

github-actions · 2024-05-08T10:57:16Z

A documentation preview will be available soon.

🔨 Buildkite builds
📚 HTML diff
📙 Preview page

Request a new doc build by commenting

Rebuild this PR: run docs-build
Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here.}

dplumlee

Left a few comments that apply to all the identical blocks as well but from a rules management definition pov, this looks good to me

dplumlee · 2024-05-08T15:59:02Z

docs/detections/api/rules/rules-api-create.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


We might want to sort these by required and optional, although this is a weird field where in some cases it's optional and in others it's not

@dplumlee Yeah, if this was strictly optional all the time, I'd say re-order the list, but since it's a little of both it's good ordered as it is.

docs/detections/api/rules/rules-api-create.asciidoc

mergify · 2024-05-08T16:19:57Z

This pull request is now in conflicts. Could you fix it @maximpn? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b allow-editing-related-integrations upstream/allow-editing-related-integrations
git merge upstream/main
git push upstream allow-editing-related-integrations

joepeeples

Thanks @maximpn for creating these updates! Added a few suggestions and comments. I'm not sure what's causing the conflicts in the PR but will look at that next.

joepeeples · 2024-05-08T17:54:21Z

docs/detections/api/rules/rules-api-create.asciidoc

@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

 * `field_names`: String[] , required

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:


Suggested change

|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:

|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

@joepeeples,

It seems vscode doesn't properly parse integrations-docs link and shows it as is. Is there a way to verify it locally?

@maximpn you can build the Security docs locally if you also have elastic/docs cloned on your machine. Run the command line build alias docbldsec --open to build the Security docs, and they'll open in a browser.

That can be a bit involved, so the PR preview from CI is another way to verify. I checked and the link resolves correctly.

joepeeples · 2024-05-08T18:13:43Z

docs/detections/api/rules/rules-api-create.asciidoc

@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

 * `field_names`: String[] , required

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses


Some users might not know what EPR stands for, or maybe they're unfamiliar with Elastic Package Registry in general. I'm also wondering how they'd find out what a given package's name is; maybe we can add a link to help them find the integration/packages they're trying to add?

I tried looking for a list in elastic/package-registry but didn't find anything. Maybe elastic/integrations/tree/main/packages?

I don't think we have package name documented somewhere. For example this page shows integrations list. Package's name as well as integration's name are in fact identifies and hidden from users. UI fetches integrations list from EPR (of course not directly but via Fleet) and uses that ids for API requests. To be 100% sure about id correctness users should use EPR. EPR allows to search for a package while the package contains integrations. After that package or integration ids can be saved since these a stable.

@joepeeples what do you think the best approach to describe it?

@maximpn Simpler is probably better; we can link users to the EPR repo, which documents the API requests that can help them search for the right packages and integrations.

Suggested change

* `package` (String, required): Integration package's name EPR uses

* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry].

joepeeples · 2024-05-08T18:16:17Z

docs/detections/api/rules/rules-api-create.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


Suggested change

* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.

* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

joepeeples · 2024-05-08T18:17:27Z

docs/detections/api/rules/rules-api-update.asciidoc

@@ -278,6 +278,12 @@ rule's version number is incremented by 1.
 `PATCH` calls enabling and disabling the rule do not increment its version
 number.

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:


Suggested change

|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:

|related_integrations |Object[] a| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

joepeeples · 2024-05-08T18:17:59Z

docs/detections/api/rules/rules-api-update.asciidoc

+|related_integrations |Object[] a| Fleet integrations the rule depends on. The object has three fields:
+
+* `package` (String, required): Integration package's name EPR uses
+* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.


Suggested change

* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.

* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

mergify · 2024-05-22T11:07:45Z

This pull request is now in conflicts. Could you fix it @maximpn? 🙏
To fixup this pull request, you can check out it locally. See documentation: https://help.github.com/articles/checking-out-pull-requests-locally/

git fetch upstream
git checkout -b allow-editing-related-integrations upstream/allow-editing-related-integrations
git merge upstream/main
git push upstream allow-editing-related-integrations

maximpn · 2024-05-22T11:12:12Z

Hi @joepeeples,

I've updated the PR according to your comments. The last this left is to describe how to get a package name and a link to EPR documentation. Check my comment above.

docs/detections/api/rules/rules-api-update.asciidoc

maximpn · 2024-05-27T12:40:44Z

@joepeeples,

I've addressed your last comments. Could you review the recent changes?

joepeeples

Everything looks good, and now that we have an 8.15 branch we can merge and backport to that.

* allow editing related integrations * improve readability * add an EPR link --------- Co-authored-by: Joe Peeples <[email protected]> (cherry picked from commit c8aa530)

* allow editing related integrations * improve readability * add an EPR link --------- Co-authored-by: Joe Peeples <[email protected]> (cherry picked from commit c8aa530) Co-authored-by: Maxim Palenov <[email protected]>

maximpn added Team: Detections/Response Detections and Response API Feature: Rules Docset: ESS Issues that apply to docs in the Stack release v8.15.0 labels May 8, 2024

maximpn self-assigned this May 8, 2024

maximpn requested a review from a team as a code owner May 8, 2024 10:57

banderror requested review from a team and dplumlee May 8, 2024 11:09

banderror mentioned this pull request May 8, 2024

Edit related_integrations field for custom rules in UI and API #5099

Closed

dplumlee previously approved these changes May 8, 2024

View reviewed changes

joepeeples reviewed May 8, 2024

View reviewed changes

joepeeples dismissed dplumlee’s stale review via acff659 May 8, 2024 18:59

allow editing related integrations

a1a5336

improve readability

e8dbbbb

maximpn force-pushed the allow-editing-related-integrations branch from acff659 to e8dbbbb Compare May 22, 2024 11:09

joepeeples reviewed May 22, 2024

View reviewed changes

docs/detections/api/rules/rules-api-update.asciidoc Outdated Show resolved Hide resolved

add an EPR link

a191acc

maximpn requested a review from joepeeples May 27, 2024 12:40

Merge branch 'main' into allow-editing-related-integrations

e774d35

joepeeples approved these changes Jul 5, 2024

View reviewed changes

joepeeples merged commit c8aa530 into elastic:main Jul 5, 2024
3 checks passed

mergify bot mentioned this pull request Jul 5, 2024

[8.15] Updates related_integrations field API docs (backport #5183) #5509

Merged

maximpn deleted the allow-editing-related-integrations branch July 9, 2024 06:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates related_integrations field API docs #5183

Updates related_integrations field API docs #5183

maximpn commented May 8, 2024 •

edited

Loading

github-actions bot commented May 8, 2024

dplumlee left a comment

dplumlee May 8, 2024

joepeeples May 8, 2024

mergify bot commented May 8, 2024

joepeeples left a comment

joepeeples May 8, 2024

maximpn May 22, 2024

joepeeples May 22, 2024

joepeeples May 8, 2024

maximpn May 22, 2024

joepeeples May 22, 2024

joepeeples May 8, 2024

joepeeples May 8, 2024

joepeeples May 8, 2024

mergify bot commented May 22, 2024

maximpn commented May 22, 2024

maximpn commented May 27, 2024

joepeeples left a comment

		@@ -380,6 +380,12 @@ Required when `actions` are used to send notifications.

		* `field_names`: String[] , required

		\|related_integrations \|Object[] a\| Fleet integrations the rule depends on. The object has three fields:

	\|related_integrations \|Object[] a\| Fleet integrations the rule depends on. The object has three fields:
	\|related_integrations \|Object[] a\| {integrations-docs}[Elastic integrations] the rule depends on. The object has these fields:

	* `package` (String, required): Integration package's name EPR uses
	* `package` (String, required): The integration package's name, as used by the https://github.com/elastic/package-registry[Elastic Package Registry].

	* `integration` (String, optional): Integration's name. It's optional for packages with the only one integration whose name matches package name but required for packages with multiple integrations.
	* `integration` (String, optional): The integration's name. This field is optional for packages with only one integration whose name matches the package name, but it's required for packages with multiple integrations.

Updates related_integrations field API docs #5183

Updates related_integrations field API docs #5183

Conversation

maximpn commented May 8, 2024 • edited Loading

Summary

github-actions bot commented May 8, 2024

dplumlee left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mergify bot commented May 8, 2024

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

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

mergify bot commented May 22, 2024

maximpn commented May 22, 2024

maximpn commented May 27, 2024

joepeeples left a comment

Choose a reason for hiding this comment

maximpn commented May 8, 2024 •

edited

Loading