[DOCS] Move preconfigured webhook case management connector details (#…

…166106)
elastic · Sep 8, 2023 · aa6ad19 · aa6ad19
1 parent e5a7261
commit aa6ad19
Show file tree

Hide file tree

Showing 3 changed files with 131 additions and 59 deletions.
diff --git a/docs/management/connectors/action-types/cases-webhook.asciidoc b/docs/management/connectors/action-types/cases-webhook.asciidoc
@@ -1,9 +1,12 @@
-[role="xpack"]
 [[cases-webhook-action-type]]
 == {webhook-cm} connector and action
 ++++
 <titleabbrev>{webhook-cm}</titleabbrev>
 ++++
+:frontmatter-description: Add a connector that can send requests to case management web services.
+:frontmatter-tags-products: [kibana] 
+:frontmatter-tags-content-type: [how-to] 
+:frontmatter-tags-user-goals: [configure]
 
 The {webhook-cm} connector uses https://github.com/axios/axios[axios] to send POST, PUT, and GET requests to a case management RESTful API web service.
 
@@ -105,62 +108,6 @@ Create comment object:: (Optional) A JSON payload sent to the create comment URL
 +
 NOTE: Due to Mustache template variables (the text enclosed in triple braces, for example, `{{{case.title}}}`), the JSON is not validated in this step. The JSON is validated once the mustache variables have been placed and when REST method runs. We recommend manually ensuring that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
 
-[float]
-[[preconfigured-cases-webhook-configuration]]
-=== Create preconfigured connectors
-
-If you are running {kib} on-prem, you can define connectors by
-adding `xpack.actions.preconfigured` settings to your `kibana.yml` file.
-For example:
-
-[source,text]
---
-xpack.actions.preconfigured:
-  my-case-management-webhook:
-    name: Case Management Webhook Connector
-    actionTypeId: .cases-webhook
-    config:
-      hasAuth: true
-      headers:
-        'content-type': 'application/json'
-      createIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue'
-      createIncidentMethod: 'post'
-      createIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}'
-      getIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}'
-      getIncidentResponseExternalTitleKey: 'key'
-      viewIncidentUrl: 'https://testing-jira.atlassian.net/browse/{{{external.system.title}}}'
-      updateIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}'
-      updateIncidentMethod: 'put'
-      updateIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}'
-      createCommentMethod: 'post',
-      createCommentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment',
-      createCommentJson: '{"body": {{{case.comment}}}}',
-    secrets:
-      user: testuser
-      password: passwordvalue
---
-
-`config`:: Defines information for the connector type.
-`hasAuth`::: A boolean that corresponds to *Requires authentication*. If `true`, this connector will require values for `user` and `password` inside the secrets configuration. Defaults to `true`.
-`headers`::: A `record<string, string>` that corresponds to *Headers*.
-`createIncidentUrl`::: A URL string that corresponds to *Create Case URL*.
-`createIncidentMethod`::: A string that corresponds to *Create Case Method*.
-`createIncidentJson`::: A stringified JSON with Mustache variables that corresponds to *Create Case JSON*.
-`createIncidentResponseKey`::: A string from the response body of the create case method that corresponds to the *External Service Id*.
-`getIncidentUrl`::: A URL string with an *External Service Id* Mustache variable that corresponds to *Get Case URL*.
-`getIncidentResponseExternalTitleKey`::: A string from the response body of the get case method that corresponds to the *External Service Title*.
-`viewIncidentUrl`::: A URL string with either the *External Service Id* or *External Service Title* Mustache variable that corresponds to *View Case URL*.
-`updateIncidentUrl`::: A URL string that corresponds to *Update Case URL*.
-`updateIncidentMethod`::: A string that corresponds to *Update Case Method*.
-`updateIncidentJson`::: A stringified JSON with Mustache variables that corresponds to *Update Case JSON*.
-`createCommentUrl`::: A URL string that corresponds to *Create Comment URL*.
-`createCommentMethod`::: A string that corresponds to *Create Comment Method*.
-`createCommentJson`::: A stringified JSON with Mustache variables that corresponds to *Create Comment JSON*.
-
-`secrets`:: Defines sensitive information for the connector type.
-`user`::: A string that corresponds to *User*. Required if `hasAuth` is set to `true`.
-`password`::: A string that corresponds to *Password*. Required if `hasAuth` is set to `true`.
-
 [float]
 [[cases-webhook-action-configuration]]
 === Test connectors

diff --git a/docs/management/connectors/pre-configured-connectors.asciidoc b/docs/management/connectors/pre-configured-connectors.asciidoc
@@ -112,7 +112,7 @@ Index names must start with `kibana-alert-history-` to take advantage of the pre
 * <<preconfigured-pagerduty-configuration>>
 * <<preconfigured-server-log-configuration>>
 * <<preconfigured-webhook-configuration>>
-
+* <<preconfigured-cases-webhook-configuration>>
 
 [float]
 [[preconfigured-index-configuration]]
@@ -241,4 +241,54 @@ xpack.actions.preconfigured:
 <5> A valid user name. Required if `hasAuth` is set to `true`.
 <6> A valid password. Required if `hasAuth` is set to `true`. NOTE: This value should be stored in the <<creating-keystore,{kib} keystore>>.
 
-NOTE: SSL authentication is not supported in preconfigured webhook connectors.
+NOTE: SSL authentication is not supported in preconfigured webhook connectors.
+
+
+[float]
+[[preconfigured-cases-webhook-configuration]]
+==== {webhook-cm} connectors
+
+The following example creates a <<cases-webhook-action-type,{webhook-cm} connector>>:
+
+[source,text]
+--
+xpack.actions.preconfigured:
+  my-case-management-webhook:
+    name: Case Management Webhook Connector
+    actionTypeId: .cases-webhook
+    config:
+      hasAuth: true <1>
+      headers: <2>
+        'content-type': 'application/json'
+      createIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue' <3>
+      createIncidentMethod: 'post' <4>
+      createIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' <5>
+      getIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}' <6>
+      getIncidentResponseExternalTitleKey: 'key' <7>
+      viewIncidentUrl: 'https://testing-jira.atlassian.net/browse/{{{external.system.title}}}' <8>
+      updateIncidentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}' <9>
+      updateIncidentMethod: 'put' <10>
+      updateIncidentJson: '{"fields":{"summary":{{{case.title}}},"description":{{{case.description}}},"labels":{{{case.tags}}}' <11>
+      createCommentMethod: 'post', <12>
+      createCommentUrl: 'https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment', <13>
+      createCommentJson: '{"body": {{{case.comment}}}}', <14>
+    secrets:
+      user: testuser <15>
+      password: passwordvalue <16>
+--
+<1> If `true`, this connector will require values for `user` and `password` inside the secrets configuration.
+<2> A set of key-value pairs sent as headers with the request.
+<3> A REST API URL string to create a case in the third-party system.
+<4> The REST API HTTP request method to create a case in the third-party system.
+<5> A stringified JSON payload with Mustache variables that is sent to the create case URL to create a case.
+<6> A REST API URL string with an external service ID Mustache variable to get the case from the third-party system.
+<7> A string from the response body of the get case method that corresponds to the external service title.
+<8> A URL string with either the external service ID or external service title Mustache variable to view a case in the external system.
+<9> The REST API URL to update the case by ID in the third-party system.
+<10> The REST API HTTP request method to update the case in the third-party system.
+<11> A stringified JSON payload with Mustache variables that is sent to the update case URL to update a case.
+<12> The REST API HTTP request method to create a case comment in the third-party system.
+<13> A REST API URL string to create a case comment by ID in the third-party system.
+<14> A stringified JSON payload with Mustache variables that is sent to the create comment URL to create a case comment.
+<15> A user name, which is required when `hasAuth` is `true`.
+<16> A password, which is required when `hasAuth` is `true`.
diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc
@@ -269,15 +269,76 @@ A configuration URL that varies by connector:
 NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts.
 --
 
+`xpack.actions.preconfigured.<connector-id>.config.createCommentJson`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a stringified JSON payload with Mustache variables that is sent to the create comment URL to create a case comment. The required variable is `case.description`.
++
+NOTE: The JSON is validated after the Mustache variables have been placed when the REST method runs. You should manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+`xpack.actions.preconfigured.<connector-id>.config.createCommentMethod`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies the REST API HTTP request method to create a case comment in the third-party system.
+For example: `post`, `put`(default), or `patch`.
+
+`xpack.actions.preconfigured.<connector-id>.config.createCommentUrl`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a REST API URL string to create a case comment by ID in the third-party system.
++
+NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts.
+
+`xpack.actions.preconfigured.<connector-id>.config.createIncidentJson`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a stringified JSON payload with Mustache variables that is sent to the create case URL to create a case. Required variables are `case.title` and `case.description`.
++
+NOTE: The JSON is validated after the Mustache variables have been placed when the REST method runs. You should manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+`xpack.actions.preconfigured.<connector-id>.config.createIncidentMethod`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies the REST API HTTP request method to create a case in the third-party system, either `post`(default), `put`, or `patch`.
+
+`xpack.actions.preconfigured.<connector-id>.config.createIncidentUrl`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a REST API URL string to create a case in the third-party system.
++
+NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts.
+
+`xpack.actions.preconfigured.<connector-id>.config.createIncidentResponseKey`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a string from the response body of the create case method that corresponds to the external service identifier.
+
 `xpack.actions.preconfigured.<connector-id>.config.executionTimeField`::
 For an <<index-action-type,index connector>>, a field that indicates when the document was indexed.
 
+`xpack.actions.preconfigured.<connector-id>.config.getIncidentResponseExternalTitleKey`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a string from the response body of the get case method that corresponds to the external service title.
+
+`xpack.actions.preconfigured.<connector-id>.config.getIncidentUrl`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a REST API URL string with an external service ID Mustache variable to get the case from the third-party system.
++
+NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts. 
+
+`xpack.actions.preconfigured.<connector-id>.config.hasAuth`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies whether a user and password are required inside the secrets configuration. Defaults to `true`.
+
+`xpack.actions.preconfigured.<connector-id>.config.headers`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a set of key-value pairs sent as headers with the request.
+
 `xpack.actions.preconfigured.<connector-id>.config.index`::
 For an <<index-action-type,index connector>>, specifies the {es} index.
 
 `xpack.actions.preconfigured.<connector-id>.config.projectKey`::
 For a <<jira-action-type,Jira connector>>, specifies the Jira project key.
 
+`xpack.actions.preconfigured.<connector-id>.config.updateIncidentJson`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a stringified JSON payload with Mustache variables that is sent to the update case URL to update a case. Required variables are `case.title` and `case.description`.
++
+NOTE: The JSON is validated after the Mustache variables have been placed when the REST method runs. You should manually ensure that the JSON is valid, disregarding the Mustache variables, so the later validation will pass.
+
+`xpack.actions.preconfigured.<connector-id>.config.updateIncidentMethod`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies the REST API HTTP request method to update the case in the third-party system.
+For example: `post`, `put`(default), or `patch`.
+
+`xpack.actions.preconfigured.<connector-id>.config.updateIncidentUrl`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies the REST API URL to update the case by ID in the third-party system.
++
+NOTE: If you are using the `xpack.actions.allowedHosts` setting, make sure the hostname in the URL is added to the allowed hosts.
+
+`xpack.actions.preconfigured.<connector-id>.config.viewIncidentUrl`::
+For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a URL string with either the external service ID or external service title Mustache variable to view a case in the external system.
+
 `xpack.actions.preconfigured.<connector-id>.name`::
 The name of the preconfigured connector.
 
@@ -299,9 +360,23 @@ For a <<jira-action-type,Jira connector>>, specifies the API authentication toke
 `xpack.actions.preconfigured.<connector-id>.secrets.email`::
 For a <<jira-action-type,Jira connector>>, specifies the account email for HTTP basic authentication.
 
+`xpack.actions.preconfigured.<connector-id>.secrets.password`::
+A password secret that varies by connector:
++
+--
+* For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a password that is required when `xpack.actions.preconfigured.<connector-id>.config.hasAuth` is `true`.
+--
+
 `xpack.actions.preconfigured.<connector-id>.secrets.routingKey`::
 For a <<pagerduty-action-type,PagerDuty connector>>, specifies the 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.
 
+`xpack.actions.preconfigured.<connector-id>.secrets.user`::
+A user name secret that varies by connector:
++
+--
+* For a <<cases-webhook-action-type,{webhook-cm} connector>>, specifies a user name that is required when `xpack.actions.preconfigured.<connector-id>.config.hasAuth` is `true`.
+--
+
 [float]
 [[alert-settings]]
 === Alerting settings