diff --git a/docs/management/connectors/action-types/cases-webhook.asciidoc b/docs/management/connectors/action-types/cases-webhook.asciidoc index e68b820101b8f..6451998c421e2 100644 --- a/docs/management/connectors/action-types/cases-webhook.asciidoc +++ b/docs/management/connectors/action-types/cases-webhook.asciidoc @@ -8,7 +8,7 @@ :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. +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. added:[8.15.0] [float] [[define-cases-webhook-ui]] @@ -195,244 +195,35 @@ The username for HTTP basic authentication. You can test connectors as you're creating or editing the connector in {kib}. For example: [role="screenshot"] -image::management/connectors/images/cases-webhook-test.gif[{webhook-cm} params test] +image::management/connectors/images/cases-webhook-test.png[{webhook-cm} params test] {webhook-cm} actions have the following configuration properties: Additional comments:: Additional information for the client, such as how to troubleshoot the issue. -// Case ID:: TBD +Case ID:: +A unique case identifier. Description:: The details about the incident. Labels:: The labels for the incident. -// Severity:: TBD +Severity:: +The severity of the case can be `critical`, `high`, `low`, or `medium`. -// Status:: TBD +Status:: +The status of the case can be `closed`, `in-progress` or `open`. -//Summary:: TBD +Summary:: +A brief case summary. -//Tags:: TBD - -Title:: A title for the issue, which is used for searching the contents of the knowledge base. +Tags:: +A list of tags that can be used to filter cases. [float] [[cases-webhook-connector-networking-configuration]] === Connector networking configuration Use the <> to customize connector networking configurations, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use `xpack.actions.customHostSettings` to set per-host configurations. - -//// -[float] -[[cases-webhook-connector-full-example]] -== Full example with third-party system - -In the following example, we connect the {webhook-cm} Connector with a demo instance of {jira} (a third-party case management system). Refer to the https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/[{Jira} API documentation] to learn how to create an issue. - -NOTE: If you want to connect with {jira} quickly, we recommend using the <>. - -[float] -==== Step 1 - Set up connector - -In the {webhook-cm} connector create flyout, begin by entering a connector *Name*, for example, `Jira Test Connector`. Basic authentication will be used in this example, so keep the *Require authentication* option selected and enter the *Username* and *Password* for the test instance, for example, `test-user@elastic.co` and `notarealpassword`. We will not be setting any *Headers* for the requests. - -[role="screenshot"] -image::management/connectors/images/cases-webhook-step1.png[{webhook-cm} connector Step 1, {jira} example] - -[float] -==== Step 2 - Create case - -To find the required values for this step, refer to the https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post[{jira} create issue method documentation]. - -{jira} create issue request method: `POST` - -{jira} create issue request URL: `/rest/api/2/issue` - -{jira} create issue request body: -[source,json] --- -{ - "fields": { - "summary": "Main order flow broken", - "description": "Order entry fails when selecting supplier.", - "labels": ["bugfix", "blitz_test"], - "project":{"key":"PROJ-123"}, - "issuetype":{"id":"10000"} - } -} --- - -{jira} create issue response body: -[source,json] --- -{ - "id": "10000", - "key": "ED-24", - "self": "https://your-domain.atlassian.net/rest/api/2/issue/10000", - "transition": { - "status": 200, - "errorCollection": { - "errorMessages": [], - "errors": {} - } - } -} --- -In the following screen capture, we enter `POST` as the *Create Case Method* and `https://testing-jira.atlassian.net/rest/api/2/issue` as the **Create Case Url**. In our example {jira} instance, the project key is "ROC" and the issuetype ID is "10024". We have entered the {jira} request JSON as the *Create Case Object*, updating the project key to "ROC" and the issuetype ID to "10024". We then use the Case variable selector to enter where we will map the Kibana case title, Kibana case description, and Kibana case tags. The {jira} response body contains an ID with the JSON key of "id", so we enter `id` as the *Create Case Response - Case ID Key*. -[role="screenshot"] -image::management/connectors/images/cases-webhook-step2.gif[{webhook-cm} connector Step 2, {jira} example] - -[float] -==== Step 3 - Get case information - -Next we'll need to look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-[Get issue method documentation] to find the values for this step. In the GET response JSON below, we thinned out some null and unrelated data so that we can focus on the fields we need. - -{jira} get issue request URL: `/rest/api/2/issue/{issueIdOrKey}` - -{jira} get issue response body: -[source,json] --- -{ - "id": "71964", - "self": "https://testing-jira.atlassian.net/rest/api/2/issue/71964", - "key": "ROC-584", - "fields": { - "issuetype": { - "self": "https://testing-jira.atlassian.net/rest/api/2/issuetype/10024", - "id": "10024", - "description": "An improvement or enhancement to an existing feature or task.", - "name": "Improvement", - "subtask": false, - "avatarId": 10310, - "hierarchyLevel": 0 - }, - "project": { - "self": "https://testing-jira.atlassian.net/rest/api/2/project/10021", - "id": "10021", - "key": "ROC", - "name": "ResponseOps Cases", - "projectTypeKey": "software", - "simplified": false - }, - "created": "2022-08-02T16:52:20.554+0300", - "priority": { - "name": "Medium", - "id": "3" - }, - "labels": ["kibanaTag"], - "updated": "2022-08-02T16:52:20.554+0300", - "status": { - "self": "https://testing-jira.atlassian.net/rest/api/2/status/10003", - "description": "", - "name": "To Do", - "id": "10003", - "statusCategory": { - "self": "https://testing-jira.atlassian.net/rest/api/2/statuscategory/2", - "id": 2, - "key": "new", - "colorName": "blue-gray", - "name": "To Do" - } - }, - "description": "Kibana Description", - "summary": "Kibana Title", - "creator": { - "self": "https://testing-jira.atlassian.net/rest/api/2/user?accountId=12345", - "accountId": "12345", - "emailAddress": "test-user@elastic.co", - "displayName": "MLR-QA", - "active": true, - "timeZone": "Europe/Athens", - "accountType": "atlassian" - }, - "reporter": { - "self": "https://testing-jira.atlassian.net/rest/api/2/user?accountId=12345", - "accountId": "12345", - "emailAddress": "test-user@elastic.co", - "displayName": "MLR-QA", - "active": true, - "timeZone": "Europe/Athens", - "accountType": "atlassian" - }, - "comment": { - "comments": [], - "self": "https://testing-jira.atlassian.net/rest/api/2/issue/71964/comment", - "maxResults": 0, - "total": 0, - "startAt": 0 - } - } -} --- - -To make the Get Case URL, we need `/rest/api/2/issue/{issueIdOrKey}`. We will fill in the value with the issue ID, which we stored in the last step as *Create Case Response - Case ID Key*. Using the variable selector on the Get Case URL input, we can see the issue ID is stored as a Mustache value `{{{external.system.id}}}`. So our value for *Get Case URL* will be `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}`. - -In the response JSON we can see the title of the case is "ROC-538". The key for this value is `key` so we enter `key` as the *Get Case Response External Title Key* value. - -We also need the *External Case View URL*. https://support.atlassian.com/jira-software-cloud/docs/link-an-issue/[{jira}'s documentation] instructs you to get the link from the issue itself. The format for this link looks like `https://.atlassian.net/browse/`. We mapped `key` to the *Get Case Response External Title Key* and using the variable selector on the *External Case View URL* input, we can see the issue key is stored as a Mustache value `{{{external.system.title}}}`. Using this, the value for *External Case View URL* is `https://testing-jira.atlassian.net/browse/{{{external.system.title}}}`. -[role="screenshot"] -image::management/connectors/images/cases-webhook-step3.gif[{webhook-cm} connector Step 3, {jira} example] - -[float] -==== Step 4 - Comments and updates - -During this step, we need to set the REST API data for updates and comments. Let's look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-put[Edit issue documentation]. - -{jira} update issue request method: `PUT` - -{jira} update issue request URL: `/rest/api/2/issue/{issueIdOrKey}` - -{jira} update issue request body: -[source,json] --- -{ - "fields": { - "summary": "Main order flow broken", - "description": "Order entry fails when selecting supplier.", - "labels": ["bugfix", "blitz_test"], - "project":{"key":"PROJ-123"}, - "issuetype":{"id":"10000"} - } -} --- - -In the screen capture below, on Step 4 we enter `PUT` as the *Update Case Method* and `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}` as the **Update Case Url** using the variable selector to insert the `{{{external.system.id}}}`. Just like the create case JSON, have entered the {jira} request JSON as the *Update Case Object*, updating the project key to "ROC" and the issuetype ID to "10024". We then use the Case variable selector to enter where we will map the Kibana case title, Kibana case description, and Kibana case tags. -[role="screenshot"] -image::management/connectors/images/cases-webhook-step4a.gif[{webhook-cm} connector Step 4 Update, {jira} example] - -Lastly we will look at {jira}'s https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-comments/#api-rest-api-2-issue-issueidorkey-comment-post[Add comment documentation] to fill out the optional comment REST fields. - -{jira} create comment request method: `POST` - -{jira} create comment request URL: `/rest/api/2/issue/{issueIdOrKey}/comment` - -{jira} create comment request body: -[source,json] --- -{ - "body": "Lorem ipsum dolor sit amet." -} --- - -In the following screen capture, we enter `POST` as the *Create Comment Method* and `https://testing-jira.atlassian.net/rest/api/2/issue/{{{external.system.id}}}/comment` as the **Create Comment Url** using the variable selector to insert the `{{{external.system.id}}}`. We enter the {jira} request JSON as the *Create Comment Object*, using the case variable selector to enter where we will map the case comment. -[role="screenshot"] -image::management/connectors/images/cases-webhook-step4b.gif[{webhook-cm} connector Step 4 Comments, {jira} example] - -[float] -[[cases-webhook-example-implementation]] -=== Implement connector in Kibana Cases -Let's take a look at how our new {webhook-cm} connector works within the case workflow. - -[float] -==== Create a case -[role="screenshot"] -image::management/connectors/images/cases-webhook-create.gif[{webhook-cm} connector Create, {jira} example] - -[float] -==== Update and comment on a case -[role="screenshot"] -image::management/connectors/images/cases-webhook-update.gif[{webhook-cm} connector Update, {jira} example] -//// \ No newline at end of file diff --git a/docs/management/connectors/images/cases-webhook-connector-comments.png b/docs/management/connectors/images/cases-webhook-connector-comments.png index fd94d59f51158..e033c067102d6 100644 Binary files a/docs/management/connectors/images/cases-webhook-connector-comments.png and b/docs/management/connectors/images/cases-webhook-connector-comments.png differ diff --git a/docs/management/connectors/images/cases-webhook-connector-create-case.png b/docs/management/connectors/images/cases-webhook-connector-create-case.png index 0401264e55a72..74ca30dc5df3b 100644 Binary files a/docs/management/connectors/images/cases-webhook-connector-create-case.png and b/docs/management/connectors/images/cases-webhook-connector-create-case.png differ diff --git a/docs/management/connectors/images/cases-webhook-connector-get-case.png b/docs/management/connectors/images/cases-webhook-connector-get-case.png index b280974434661..b072b84b59708 100644 Binary files a/docs/management/connectors/images/cases-webhook-connector-get-case.png and b/docs/management/connectors/images/cases-webhook-connector-get-case.png differ diff --git a/docs/management/connectors/images/cases-webhook-connector.png b/docs/management/connectors/images/cases-webhook-connector.png index f68c1ba0c295f..beab0bb6a513c 100644 Binary files a/docs/management/connectors/images/cases-webhook-connector.png and b/docs/management/connectors/images/cases-webhook-connector.png differ diff --git a/docs/management/connectors/images/cases-webhook-create.gif b/docs/management/connectors/images/cases-webhook-create.gif deleted file mode 100644 index 22343c08073b1..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-create.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-step1.png b/docs/management/connectors/images/cases-webhook-step1.png deleted file mode 100644 index 64827cb011c1c..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-step1.png and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-step2.gif b/docs/management/connectors/images/cases-webhook-step2.gif deleted file mode 100644 index 01b322007f91e..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-step2.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-step3.gif b/docs/management/connectors/images/cases-webhook-step3.gif deleted file mode 100644 index 4e386dd3b871a..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-step3.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-step4a.gif b/docs/management/connectors/images/cases-webhook-step4a.gif deleted file mode 100644 index b33c21db41bbb..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-step4a.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-step4b.gif b/docs/management/connectors/images/cases-webhook-step4b.gif deleted file mode 100644 index e5c6a2b651839..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-step4b.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-test.gif b/docs/management/connectors/images/cases-webhook-test.gif deleted file mode 100644 index 5f42aedfa4888..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-test.gif and /dev/null differ diff --git a/docs/management/connectors/images/cases-webhook-test.png b/docs/management/connectors/images/cases-webhook-test.png new file mode 100644 index 0000000000000..6960a496df624 Binary files /dev/null and b/docs/management/connectors/images/cases-webhook-test.png differ diff --git a/docs/management/connectors/images/cases-webhook-update.gif b/docs/management/connectors/images/cases-webhook-update.gif deleted file mode 100644 index 7f09d1f122e52..0000000000000 Binary files a/docs/management/connectors/images/cases-webhook-update.gif and /dev/null differ diff --git a/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/cases_webhook_connector.ts b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/cases_webhook_connector.ts index eda3c67967285..2b64985d90a76 100644 --- a/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/cases_webhook_connector.ts +++ b/x-pack/test/screenshot_creation/apps/response_ops_docs/stack_connectors/cases_webhook_connector.ts @@ -82,6 +82,11 @@ export default function ({ getService, getPageObjects }: FtrProviderContext) { 1920, 1400 ); + const saveTestButton = await testSubjects.find('create-connector-flyout-save-test-btn'); + await saveTestButton.click(); + await pageObjects.header.waitUntilLoadingHasFinished(); + await testSubjects.setValue('titleInput', 'Example case'); + await commonScreenshots.takeScreenshot('cases-webhook-test', screenshotDirectories); await testSubjects.click('euiFlyoutCloseButton'); }); });