[Docs] Adds 7.10 Cases API updates (#310)

* Update patch connector * Update create case * Update patch case * Update find cases * Update get case * Update get case activity * Update post configure * Improve configuration * Fix build * Fixes
elastic · Oct 22, 2020 · 98e236c · 98e236c
1 parent 1c660f8
commit 98e236c
Show file tree

Hide file tree

Showing 8 changed files with 294 additions and 28 deletions.
diff --git a/docs/cases/api/cases-api/case-api-update-connector.asciidoc b/docs/cases/api/cases-api/case-api-update-connector.asciidoc
@@ -19,9 +19,8 @@ A JSON object with these fields:
 |==============================================
 |Name |Type |Description |Required
 
-|`connector_id` |String |The ID of the connector you want to use for sending
-cases to external systems. |Yes
-|`connector_name` |String |The connector name. |No
+|`connector` |<<update-connector-connector-schema, connector>> |Object containing the connector's
+configuration. |Yes
 |`closure_type` |String a|Determines whether a case is automatically closed in
 {es-sec} when it is pushed to external systems. Valid values are:
 
@@ -34,9 +33,51 @@ are pushed.
 |`version` |String |The connector version. |Yes
 |==============================================
 
+[[update-connector-connector-schema]]
+*`connector` schema*
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes
+|`name` |String a|The connector name. |Yes
+|`type` |String a|The type of the connector. 
+
+Must be one of these:
+
+* `.servicenow`
+* `.jira`
+* `.resilient`
+* `.none`
+|Yes
+|`fields` |Object a| Object containing connector's fields.
+
+For {sn} connectors:
+
+* `urgency` (string \| null): The urgency of the incident.
+* `severity` (string \| null): The severity of the incident.
+* `impact` (string \| null): The impact of the incident.
+
+For Jira connectors:
+
+* `issueType` (string): The issue type of the issue.
+* `priority` (string \| null): The priority of the issue.
+* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
+
+For {ibm-r} connectors:
+
+* `issueTypes` (number[]): The issue types of the issue.
+* `severityCode` (number): The severity code of the issue.
+
+|Yes
+|==============================================
+
 NOTE: Call <<cases-get-connector>> to retrieve the version value, and
 <<cases-api-find-connectors>> to retrieve connector IDs.
 
+NOTE: Fields can be set but are not being used by case configuration. You can set the fields of the connector at <<cases-api-create>>.
+
 ===== Example request
 
 Changes the connector's case closure option: 
@@ -45,7 +86,12 @@ Changes the connector's case closure option:
 --------------------------------------------------
 PATCH api/cases/configure
 {
-  "connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
+  "connector": { 
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "My connector",
+    "type": ".jira",
+    "fields": null,
+  }
   "closure_type": "close-by-pushing",
   "version": "WzIwMiwxXQ=="
 }
@@ -62,9 +108,13 @@ PATCH api/cases/configure
 [source,json]
 --------------------------------------------------
 {
-  "connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
+  "connector": { 
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "My connector",
+    "type": ".jira",
+    "fields": null,
+  },
   "closure_type": "close-by-pushing",
-  "connector_name": "ServiceNow",
   "created_at": "2020-03-30T13:31:38.083Z",
   "created_by": {
     "email": "[email protected]",

diff --git a/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc b/docs/cases/api/cases-api/cases-api-assign-connector.asciidoc
@@ -23,8 +23,8 @@ A JSON object with these fields:
 |==============================================
 |Name |Type |Description |Required
 
-|`connector_id` |String |The connector ID. |Yes
-|`connector_name` |String |The connector name. |Yes
+|`connector` |<<assign-connector-connector-schema, connector>> |Object containing the connector's
+configuration. |Yes
 |`closure_type` |String a|Determines whether a case is automatically closed in
 {es-sec} when it is pushed to external systems. Valid values are:
 
@@ -35,17 +35,63 @@ are pushed.
 |Yes
 |==============================================
 
+[[assign-connector-connector-schema]]
+*`connector` schema*
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes
+|`name` |String a|The connector name. |Yes
+|`type` |String a|The type of the connector. 
+
+Must be one of these:
+
+* `.servicenow`
+* `.jira`
+* `.resilient`
+* `.none`
+|Yes
+|`fields` |Object a| Object containing the connector's fields.
+
+For {sn} connectors:
+
+* `urgency` (string \| null): The urgency of the incident.
+* `severity` (string \| null): The severity of the incident.
+* `impact` (string \| null): The impact of the incident.
+
+For Jira connectors:
+
+* `issueType` (string): The issue type of the issue.
+* `priority` (string \| null): The priority of the issue.
+* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
+
+For {ibm-r} connectors:
+
+* `issueTypes` (number[]): The issue types of the issue.
+* `severityCode` (number): The severity code of the issue.
+
+|Yes
+|==============================================
+
 NOTE: Call <<cases-api-find-connectors>> to retrieve connector IDs and names.
 
+NOTE: Fields can be set but are not being used by case configuration. You can set the fields of the connector at <<cases-api-create>>.
+
 ==== Example request
 
 [source,sh]
 --------------------------------------------------
 POST api/cases/configure
 {
-  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "connector": { 
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "Jira",
+    "type": ".jira",
+    "fields": null,
+  },
   "closure_type": "close-by-user",
-  "connector_name": "ServiceNow"
 }
 --------------------------------------------------
 
@@ -59,9 +105,13 @@ POST api/cases/configure
 [source,json]
 --------------------------------------------------
 {
-  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "connector": { 
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "Jira",
+    "type": ".jira",
+    "fields": null,
+  },
   "closure_type": "close-by-user",
-  "connector_name": "ServiceNow",
   "created_at": "2020-03-30T13:31:38.083Z",
   "created_by": {
     "email": "[email protected]",

diff --git a/docs/cases/api/cases-api/cases-api-create.asciidoc b/docs/cases/api/cases-api/cases-api-create.asciidoc
@@ -19,6 +19,50 @@ A JSON object with these fields:
 |`description` |String |The case's description. |Yes
 |`tags` |String[] |String array containing words and phrases that help
 categorize cases. |Yes, can be an empty array.
+|`connector` |<<create-case-connector-schema, connector>> |Object containing the connector's
+configuration. |Yes
+|==============================================
+
+[[create-case-connector-schema]]
+*`connector` schema*
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`id` |String |ID of the <<actions-api-overview, connector>>
+used for pushing case updates to external systems (returned when calling
+<<cases-api-find-connectors>>). |Yes
+|`name` |String a|The connector name. |Yes
+|`type` |String a|The type of the connector. 
+
+Must be one of these:
+
+* `.servicenow`
+* `.jira`
+* `.resilient`
+* `.none`
+|Yes
+|`fields` |Object a| Object containing the connector's fields.
+
+For {sn} connectors:
+
+* `urgency` (string \| null): The urgency of the incident.
+* `severity` (string \| null): The severity of the incident.
+* `impact` (string \| null): The impact of the incident.
+
+For Jira connectors:
+
+* `issueType` (string): The issue type of the issue.
+* `priority` (string \| null): The priority of the issue.
+* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
+
+For {ibm-r} connectors:
+
+* `issueTypes` (number[]): The issue types of the issue.
+* `severityCode` (number): The severity code of the issue.
+
+|Yes
 |==============================================
 
 ===== Example request
@@ -33,7 +77,16 @@ POST api/cases
   "tags": [
     "phishing",
     "social engineering"
-  ]
+  ],
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "priority": "High",
+    }
+  }
 }
 --------------------------------------------------
 // KIBANA
@@ -59,7 +112,6 @@ version, and creation time. The case's ID is also its saved object ID
   "version": "WzUzMiwxXQ==",
   "comments": [],
   "totalComment": 0,
-  "connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8", <1>
   "title": "This case will self-destruct in 5 seconds",
   "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active",
   "tags": [
@@ -75,14 +127,23 @@ version, and creation time. The case's ID is also its saved object ID
     "full_name": "Alan Hunley",
     "username": "ahunley"
   },
-  "external_service": null, <2>
+  "external_service": null, <1>
   "status": "open",
   "updated_at": null,
-  "updated_by": null
+  "updated_by": null,
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498", <2>
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "priority": "High",
+    }
+  }
 }
 --------------------------------------------------
 
-<1> The default connector ID used to push cases to external services (see
-<<assign-connector>>).
-<2> The `external_service` object stores information when the case is pushed to
+<1> The `external_service` object stores information when the case is pushed to
 external systems. For more information, see <<actions-api-overview>>.
+<2> The default connector ID used to push cases to external services (see
+<<assign-connector>>).
diff --git a/docs/cases/api/cases-api/cases-api-find-cases.asciidoc b/docs/cases/api/cases-api/cases-api-find-cases.asciidoc
@@ -93,7 +93,16 @@ A JSON object listing the retrieved cases.
         "phishing"
       ],
       "description": "Windows 95",
-      "status": "open"
+      "status": "open",
+      "connector": {
+        "id": "131d4448-abe0-4789-939d-8ef60680b498",
+        "name": "My connector",
+        "type": ".jira",
+        "fields": {
+          "issueType": "10006",
+          "priority": null,
+        }
+      },
     },
     {
       "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
@@ -118,6 +127,15 @@ A JSON object listing the retrieved cases.
       "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active!",
       "title": "This case will self-destruct in 5 seconds",
       "status": "open",
+      "connector": {
+        "id": "131d4448-abe0-4789-939d-8ef60680b498",
+        "name": "My connector",
+        "type": ".resilient",
+        "fields": {
+          "issueTypes": [13],
+          "severityCode": 6,
+        }
+      },
       "tags": [
         "phishing",
         "social engineering",

diff --git a/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc b/docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc
@@ -106,6 +106,23 @@ A JSON array containing all user activity for the specified case.
     "action_id": "223f7bd0-750a-11ea-b83a-553aecdb28b6",
     "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
     "comment_id": "21a844e0-750a-11ea-b83a-553aecdb28b6"
-  }
+  },
+  {
+      "action_field":[
+         "connector"
+      ],
+      "action":"update",
+      "action_at":"2020-10-12T16:03:34.940Z",
+      "action_by":{
+         "email":"[email protected]",
+         "full_name":"Christos Nasikas",
+         "username":"cnasikas"
+      },
+      "new_value":"{\"id\":\"18bc18cf-bd5d-4c88-bcdd-c7bb52a692cd\",\"name\":\"Resilient\",\"type\":\".resilient\",\"fields\":{\"incidentTypes\":[\"1001\"],\"severityCode\":\"5\"}}",
+      "old_value":"{\"id\":\"72b9fa3a-b081-487d-9358-61d5da2968c1\",\"name\":\"Jira\",\"type\":\".jira\",\"fields\":{\"issueType\":\"10006\",\"parent\":null,\"priority\":\"Medium\"}}",
+      "action_id":"7c326760-0ca4-11eb-8a58-a3c589db8483",
+      "case_id":"7498ae50-0c8c-11eb-aefc-797bf7d42db4",
+      "comment_id":null
+   }
 ]
 --------------------------------------------------
diff --git a/docs/cases/api/cases-api/cases-api-get-case.asciidoc b/docs/cases/api/cases-api/cases-api-get-case.asciidoc
@@ -68,6 +68,15 @@ The requested case JSON object.
   "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active!",
   "title": "This case will self-destruct in 5 seconds",
   "status": "open",
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "priority": "High",
+    }
+  },
   "tags": [
     "phishing",
     "social engineering",

diff --git a/docs/cases/api/cases-api/cases-api-get-connector.asciidoc b/docs/cases/api/cases-api/cases-api-get-connector.asciidoc
@@ -27,9 +27,13 @@ GET api/cases/configure
 [source,json]
 --------------------------------------------------
 {
-  "connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+  "connector": { 
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "Jira",
+    "type": ".jira",
+    "fields": null,
+  },
   "closure_type": "close-by-user",
-  "connector_name": "ServiceNow",
   "created_at": "2020-03-30T13:31:38.083Z",
   "created_by": {
     "email": "[email protected]",