[8.6] [DOCS] Clarify alertId and index in add comment API (#145189) (#…

…145760)
elastic · Nov 18, 2022 · 16f1d02 · 16f1d02
1 parent 673a136
commit 16f1d02
Show file tree

Hide file tree

Showing 8 changed files with 43 additions and 33 deletions.
diff --git a/docs/api-generated/cases/case-apis-passthru.asciidoc b/docs/api-generated/cases/case-apis-passthru.asciidoc
@@ -2077,13 +2077,13 @@ Any modifications made to this file will be overwritten.
   </div>
   <div class="model">
     <h3><a name="alert_identifiers"><code>alert_identifiers</code> - Alert identifiers</a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'>The alert identifier. It is required only when <code>type</code> is <code>alert</code>. If it is an array, <code>index</code> must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
+    <div class='model-description'>The alert identifiers. It is required only when <code>type</code> is <code>alert</code>. You can use an array of strings to add multiple alerts to a case, provided that they all relate to the same rule; <code>index</code> must also be an array with the same length or number of elements. Adding multiple alerts in this manner is recommended rather than calling the API multiple times. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
     <div class="field-items">
           </div>  <!-- field-items -->
   </div>
   <div class="model">
     <h3><a name="alert_indices"><code>alert_indices</code> - Alert indices</a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'>The alert index. It is required only when <code>type</code> is <code>alert</code>. If it is an array, <code>alertId</code> must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
+    <div class='model-description'>The alert indices. It is required only when <code>type</code> is <code>alert</code>.  If you are adding multiple alerts to a case, use an array of strings; the position of each index name in the array must match the position of the corresponding alert identifier in the <code>alertId</code> array. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
     <div class="field-items">
           </div>  <!-- field-items -->
   </div>
@@ -2663,7 +2663,7 @@ Any modifications made to this file will be overwritten.
   </div>
   <div class="model">
     <h3><a name="rule"><code>rule</code> - Alerting rule</a> <a class="up" href="#__Models">Up</a></h3>
-    <div class='model-description'>The rule that is associated with the alert. It is required only when <code>type</code> is <code>alert</code>. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
+    <div class='model-description'>The rule that is associated with the alerts. It is required only when <code>type</code> is <code>alert</code>. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.</div>
     <div class="field-items">
       <div class="param">id (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The rule identifier. </div>
 <div class="param">name (optional)</div><div class="param-desc"><span class="param-type"><a href="#string">String</a></span> The rule name. </div>

diff --git a/docs/api/cases/cases-api-add-comment.asciidoc b/docs/api/cases/cases-api-add-comment.asciidoc
@@ -39,22 +39,28 @@ default space is used.
 === {api-request-body-title}
 
 `alertId`::
-(Required*, string or array of strings) The alert identifier. It is required
-only when `type` is `alert`. If it is an array, `index` must also be an array. preview:[]
+(Required*, string or array of strings) The alert identifiers. It is required
+only when `type` is `alert`. You can use an array of strings to add multiple
+alerts to a case, provided that they all relate to the same rule; `index` must
+also be an array with the same length or number of elements. Adding multiple
+alerts in this manner is recommended rather than calling the API multiple times.
+preview:[]
 
 `comment`::
 (Required*, string) The new comment. It is required only when `type` is `user`.
 
 `index`::
-(Required*, string or array of strings) The alert index. It is required only
-when `type` is `alert`. If it is an array, `alertId` must also be an array. preview:[]
+(Required*, string or array of strings) The alert indices. It is required only
+when `type` is `alert`. If you are adding multiple alerts to a case, use an array
+of strings; the position of each index name in the array must match the position
+of the corresponding alert identifier in the `alertId` array. preview:[]
 
 `owner`::
 (Required, string) The application that owns the case. Valid values are:
 `cases`, `observability`, or `securitySolution`.
 
 `rule`::
-(Required*, object) The rule that is associated with the alert. It is required
+(Required*, object) The rule that is associated with the alerts. It is required
 only when `type` is `alert`. preview:[]
 +
 .Properties of `rule`

diff --git a/docs/api/cases/cases-api-update-comment.asciidoc b/docs/api/cases/cases-api-update-comment.asciidoc
@@ -39,9 +39,11 @@ default space is used.
 === {api-request-body-title}
 
 `alertId`::
-(Required*, string or array of strings) The identifier for the alert. It is
-required only when `type` is `alert`. If it is an array, `index` must also be an
-array.preview:[]
+(Required*, string or array of strings) The alert identifiers. It is
+required only when `type` is `alert`. If you are adding multiple alerts to a
+case, use an array of strings; `index` must also be an array with the same
+length or number of elements in that case. Addings multiple alerts in this manner
+is recommended rather than calling the API multiple times.
 
 `comment`::
 (Required*, string) The updated comment. It is required only when `type` is
@@ -52,9 +54,10 @@ array.preview:[]
 <<cases-api-get-comments>>.
 
 `index`::
-(Required*, string or array of strings) The alert index. It is required only
-when `type` is `alert`. If it is an array, `alertId` must also be an array.
-preview:[]
+(Required*, string or array of strings) The alert indices. It is required only
+when `type` is `alert`. If you are adding multiple alerts to a case, use an
+array of strings; `alertId` must also be an array with the same length or number
+of elements. preview:[]
 
 `owner`::
 (Required, string) The application that owns the case. It can be `cases`,

diff --git a/x-pack/plugins/cases/docs/openapi/bundled.json b/x-pack/plugins/cases/docs/openapi/bundled.json
@@ -3115,7 +3115,7 @@
       },
       "alert_identifiers": {
         "title": "Alert identifiers",
-        "description": "The alert identifier. It is required only when `type` is `alert`. If it is an array, `index` must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
+        "description": "The alert identifiers. It is required only when `type` is `alert`. You can use an array of strings to add multiple alerts to a case, provided that they all relate to the same rule; `index` must also be an array with the same length or number of elements. Adding multiple alerts in this manner is recommended rather than calling the API multiple times. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
         "oneOf": [
           {
             "type": "string"
@@ -3132,7 +3132,7 @@
       },
       "alert_indices": {
         "title": "Alert indices",
-        "description": "The alert index. It is required only when `type` is `alert`. If it is an array, `alertId` must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
+        "description": "The alert indices. It is required only when `type` is `alert`.  If you are adding multiple alerts to a case, use an array of strings; the position of each index name in the array must match the position of the corresponding alert identifier in the `alertId` array. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
         "oneOf": [
           {
             "type": "string"
@@ -3148,7 +3148,7 @@
       },
       "rule": {
         "title": "Alerting rule",
-        "description": "The rule that is associated with the alert. It is required only when `type` is `alert`. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
+        "description": "The rule that is associated with the alerts. It is required only when `type` is `alert`. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.\n",
         "type": "object",
         "x-technical-preview": true,
         "properties": {

diff --git a/x-pack/plugins/cases/docs/openapi/bundled.yaml b/x-pack/plugins/cases/docs/openapi/bundled.yaml
@@ -2079,7 +2079,7 @@ components:
     alert_identifiers:
       title: Alert identifiers
       description: |
-        The alert identifier. It is required only when `type` is `alert`. If it is an array, `index` must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+        The alert identifiers. It is required only when `type` is `alert`. You can use an array of strings to add multiple alerts to a case, provided that they all relate to the same rule; `index` must also be an array with the same length or number of elements. Adding multiple alerts in this manner is recommended rather than calling the API multiple times. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
       oneOf:
         - type: string
         - type: array
@@ -2090,7 +2090,7 @@ components:
     alert_indices:
       title: Alert indices
       description: |
-        The alert index. It is required only when `type` is `alert`. If it is an array, `alertId` must also be an array with the same length or number of elements. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+        The alert indices. It is required only when `type` is `alert`.  If you are adding multiple alerts to a case, use an array of strings; the position of each index name in the array must match the position of the corresponding alert identifier in the `alertId` array. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
       oneOf:
         - type: string
         - type: array
@@ -2100,7 +2100,7 @@ components:
     rule:
       title: Alerting rule
       description: |
-        The rule that is associated with the alert. It is required only when `type` is `alert`. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
+        The rule that is associated with the alerts. It is required only when `type` is `alert`. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply best effort to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.
       type: object
       x-technical-preview: true
       properties:

diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/alert_identifiers.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/alert_identifiers.yaml
@@ -1,11 +1,11 @@
 title: Alert identifiers
 description: >
-  The alert identifier. It is required only when `type` is `alert`. If it is
-  an array, `index` must also be an array with the same length or number of
-  elements. This functionality is in technical preview and may be changed or
-  removed in a future release. Elastic will apply best effort to fix any issues,
-  but features in technical preview are not subject to the support SLA of
-  official GA features.
+  The alert identifiers. It is required only when `type` is `alert`. You can use
+  an array of strings to add multiple alerts to a case, provided that they all
+  relate to the same rule; `index` must also be an array with the same length or number of elements. Adding multiple alerts in this manner is recommended
+  rather than calling the API multiple times. This functionality is in technical preview and may be changed or removed in a future release. Elastic will apply
+  best effort to fix any issues, but features in technical preview are not
+  subject to the support SLA of official GA features.
 oneOf:
   - type: string
   - type: array

diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/alert_indices.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/alert_indices.yaml
@@ -1,11 +1,12 @@
 title: Alert indices
 description: >
-  The alert index. It is required only when `type` is `alert`. If it is an
-  array, `alertId` must also be an array with the same length or number of
-  elements. This functionality is in technical preview and may be changed or
-  removed in a future release. Elastic will apply best effort to fix any issues,
-  but features in technical preview are not subject to the support SLA of
-  official GA features.
+  The alert indices. It is required only when `type` is `alert`.  If you are
+  adding multiple alerts to a case, use an array of strings; the position of
+  each index name in the array must match the position of the corresponding
+  alert identifier in the `alertId` array. This functionality is in technical
+  preview and may be changed or removed in a future release. Elastic will apply
+  best effort to fix any issues, but features in technical preview are not
+  subject to the support SLA of official GA features.
 oneOf:
   - type: string
   - type: array

diff --git a/x-pack/plugins/cases/docs/openapi/components/schemas/rule.yaml b/x-pack/plugins/cases/docs/openapi/components/schemas/rule.yaml
@@ -1,6 +1,6 @@
 title: Alerting rule
 description: >
-  The rule that is associated with the alert. It is required only when
+  The rule that is associated with the alerts. It is required only when
   `type` is `alert`. This functionality is in technical preview and may be
   changed or removed in a future release. Elastic will apply best effort to
   fix any issues, but features in technical preview are not subject to the