[Docs] 7.11 Cases API updates (#445)

Author: cnasikas

docs/cases/api/actions-api/cases-actions-api-intro.asciidoc

@@ -59,7 +59,7 @@ For {sn} connectors:
 * `severity` (string \| null): The severity of the incident.
 * `impact` (string \| null): The impact of the incident.
 
-For Jira connectors:
+For {jira} connectors:
 
 * `issueType` (string): The issue type of the issue.
 * `priority` (string \| null): The priority of the issue.
@@ -121,6 +121,7 @@ PATCH api/cases/configure
     "full_name": "Ms Admin",
     "username": "admin"
   },
+  "error": null,
   "updated_at": "2020-03-31T06:21:35.759Z",
   "updated_by": {
     "email": "[email protected]",

docs/cases/api/cases-api/case-api-update-connector.asciidoc

@@ -20,9 +20,14 @@ A JSON object with a `comment` field:
 |==============================================
 |Name |Type |Description |Required
 
-|`comment` |String |The case's new comment. |Yes
+|`type` |String |The comment type, which can be `user` or `alert`. |Yes
+|`comment` |String |The case's new comment. |Yes, only when type is `user`.
+|`alertId` |String |The alert id. |Yes, only when type is `alert`.
+|`index` |String |The alert index. |Yes, only when type is `alert`.
 |==============================================
 
+NOTE: Only alerts (signals) of {es-sec} are supported.
+
 ===== Example request
 
 Adds a comment to case ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`:
@@ -31,6 +36,7 @@ Adds a comment to case ID `293f1bc0-74f6-11ea-b83a-553aecdb28b6`:
 --------------------------------------------------
 POST api/cases/293f1bc0-74f6-11ea-b83a-553aecdb28b6/comments
 {
+  "type": "user",
   "comment": "That is nothing - Ethan Hunt answered a targeted social
   media campaign promoting phishy pension schemes to IMF operatives."
 }
@@ -58,6 +64,7 @@ comment, and the comment's ID, version, and creation time.
     {
       "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
       "version": "WzIwNDMxLDFd",
+      "type": "user",
       "comment": "That is nothing - Ethan Hunt answered a targeted social media campaign promoting phishy pension schemes to IMF operatives.",
       "created_at": "2020-04-02T15:28:03.034Z",
       "created_by": {
@@ -71,7 +78,7 @@ comment, and the comment's ID, version, and creation time.
       "updated_by": null
     }
   ],
-  "totalComment": 0,
+  "totalComment": 1,
   "title": "This case will self-destruct in 5 seconds",
   "tags": [
     "phishing",

docs/cases/api/cases-api/cases-api-add-comment.asciidoc

@@ -55,13 +55,13 @@ Must be one of these:
 |Yes
 |`fields` |Object a| Object containing the connector's fields.
 
-For {sn} connectors:
+For {jira} 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:
+For {jira} connectors:
 
 * `issueType` (string): The issue type of the issue.
 * `priority` (string \| null): The priority of the issue.
@@ -118,8 +118,38 @@ POST api/cases/configure
     "full_name": "Ms Moneypenny",
     "username": "moneypenny"
   },
+  "error": null,
+  "mappings":[
+    { 
+      "source":"title", <1>
+      "target":"summary",
+      "action_type": "overwrite"
+    },
+    {
+      "source":"description", <2>
+      "target":"description",
+      "action_type": "overwrite"
+    },
+    {
+      "source":"comments", <3>
+      "target":"comments",
+      "action_type":"append"
+    }
+  ],
   "updated_at": null,
   "updated_by": null,
   "version": "WzE3NywxXQ=="
 }
 --------------------------------------------------
+
+<1> {es-sec} case `title` fields are mapped to {jira} `summary`
+fields. When a {es-sec} `title` field is updated and sent to {jira}, the {jira}
+`summary` field is overwritten.
+
+<2> {es-sec} case `description` fields are mapped to {jira} `description`
+fields. When a {es-sec} `description` field is updated and sent to {jira},
+the {jira} `description` field is overwritten.
+
+<3> {es-sec} case `comments` fields are mapped to {jira} `comments` fields.
+When a {es-sec} `comments` field is updated and sent to {jira}, the updated
+text is appended to the {jira} `comments` field.

docs/cases/api/cases-api/cases-api-assign-connector.asciidoc

@@ -99,6 +99,15 @@ The updated JSON case object.
   "title": "This case will self-destruct in 5 seconds",
   "tags": [],
   "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
-  "status": "open"
+  "status": "open",
+  "connector": {
+    "id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
+    "name": "ServiceNow",
+    "type": ".servicenow",
+    "fields": null
+  },
+  "settings": {
+    "syncAlerts": true
+  },
 }
 --------------------------------------------------

docs/cases/api/cases-api/cases-api-associate-sn.asciidoc

@@ -21,6 +21,8 @@ A JSON object with these fields:
 categorize cases. |Yes, can be an empty array.
 |`connector` |<<create-case-connector-schema, connector>> |Object containing the connector's
 configuration. |Yes
+|`settings` |<<create-case-settings-schema, settings>> |Object containing the case's
+settings. |Yes
 |==============================================
 
 [[create-case-connector-schema]]
@@ -51,7 +53,7 @@ For {sn} connectors:
 * `severity` (string \| null): The severity of the incident.
 * `impact` (string \| null): The impact of the incident.
 
-For Jira connectors:
+For {jira} connectors:
 
 * `issueType` (string): The issue type of the issue.
 * `priority` (string \| null): The priority of the issue.
@@ -65,6 +67,15 @@ For {ibm-r} connectors:
 |Yes
 |==============================================
 
+[[create-case-settings-schema]]
+*`settings` schema*
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+|`syncAlerts` |Boolean| Turn on or off synching with alerts. | Yes
+|==============================================
+
 ===== Example request
 
 [source,sh]
@@ -86,6 +97,9 @@ POST api/cases
       "issueType": "10006",
       "priority": "High",
     }
+  },
+  "settings": {
+    "syncAlerts": true
   }
 }
 --------------------------------------------------
@@ -139,6 +153,9 @@ version, and creation time. The case's ID is also its saved object ID
       "issueType": "10006",
       "priority": "High",
     }
+  },
+  "settings": {
+    "syncAlerts": true
   }
 }
 --------------------------------------------------

docs/cases/api/cases-api/cases-api-create.asciidoc

@@ -29,7 +29,7 @@ All parameters are optional:
 
 |`sortOrder` |String |Determines the sort order, which can be `desc` or `asc`.
 
-|`status` |String |Filters the returned cases by state, which can be `open` or
+|`status` |String |Filters the returned cases by state, which can be `open`, `in-progress`, or
 `closed`.
 
 |`tags` |String |Filters the returned cases by tags.
@@ -103,12 +103,15 @@ A JSON object listing the retrieved cases.
           "priority": null,
         }
       },
+      "settings": {
+        "syncAlerts": true
+      }
     },
     {
       "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
       "version": "Wzk4LDFd",
       "comments": [],
-      "totalComment": 1,
+      "totalComment": 0,
       "closed_at": null,
       "closed_by": null,
       "created_at": "2020-03-29T11:30:02.658Z",
@@ -136,6 +139,9 @@ A JSON object listing the retrieved cases.
           "severityCode": 6,
         }
       },
+      "settings": {
+        "syncAlerts": false 
+      },
       "tags": [
         "phishing",
         "social engineering",

docs/cases/api/cases-api/cases-api-find-cases.asciidoc

@@ -1,9 +1,9 @@
 [[cases-api-find-connectors]]
 === Find connectors
 
-Retrieves a paginated subset of all {sn} connectors.
+Retrieves a paginated subset of all connectors.
 
-NOTE: Only {sn} and Jira connectors are returned. For more information on
+NOTE: Only {sn}, {jira}, and {ibm-r} connectors are returned. For more information on
 connectors, see <<actions-api-overview>>.
 
 ==== Request URL
@@ -41,25 +41,6 @@ A JSON object describing the connectors and their settings.
       "actionTypeId": ".servicenow",
       "name": "ServiceNow",
       "config": {
-        "casesConfiguration": {
-          "mapping": [
-            {
-              "actionType": "overwrite",
-              "source": "title",
-              "target": "short_description"
-            },
-            {
-              "actionType": "append",
-              "source": "description",
-              "target": "description"
-            },
-            {
-              "actionType": "append",
-              "source": "comments",
-              "target": "comments"
-            }
-          ]
-        },
         "apiUrl": "https://dev78437.service-now.com"
       },
       "referencedByCount": 0
@@ -70,25 +51,6 @@ A JSON object describing the connectors and their settings.
       "name": "Defector",
       "config": {
         "apiUrl": "https://dev87359.service-now.com",
-        "casesConfiguration": {
-          "mapping": [
-            {
-              "source": "title",
-              "target": "short_description",
-              "actionType": "append"
-            },
-            {
-              "source": "description",
-              "target": "description",
-              "actionType": "append"
-            },
-            {
-              "source": "comments",
-              "target": "comments",
-              "actionType": "append"
-            }
-          ]
-        }
       },
       "referencedByCount": 0
     }

docs/cases/api/cases-api/cases-api-find-connectors.asciidoc

@@ -41,7 +41,9 @@ A JSON array containing all user activity for the specified case.
       "description",
       "status",
       "tags",
-      "title"
+      "title",
+      "connector",
+      "settings"
     ],
     "action": "create",
     "action_at": "2020-04-02T15:25:19.088Z",
@@ -50,7 +52,7 @@ A JSON array containing all user activity for the specified case.
       "full_name": "Alan Hunley",
       "username": "ahunley"
     },
-    "new_value": "{\"title\":\"This case will self-destruct in 5 seconds\",\"tags\":[\"phishing\",\"social engineering\"],\"description\":\"James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.\"}",
+    "new_value": "{\"title\":\"This case will self-destruct in 5 seconds\",\"tags\":[\"phishing\",\"social engineering\"],\"description\":\"James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.\"},\"connector\":{\"id\":\"none\",\"name\":\"none\",\"type\":\".none\",\"fields\":null},\"settings\":{\"syncAlerts\":true}",
     "old_value": null,
     "action_id": "29ce6370-74f6-11ea-b83a-553aecdb28b6",
     "case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
@@ -108,21 +110,38 @@ A JSON array containing all user activity for the specified case.
     "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
-   }
+    "action_field":[
+        "connector"
+    ],
+    "action":"update",
+    "action_at":"2020-10-12T16:03:34.940Z",
+    "action_by":{
+        "email":"[email protected]",
+        "full_name":"Classified",
+        "username":"M"
+    },
+    "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
+  },
+  {
+    "action_field":[
+        "settings"
+    ],
+    "action":"update",
+    "action_at":"2020-10-12T16:03:34.940Z",
+    "action_by":{
+        "email":"[email protected]",
+        "full_name":"Classified",
+        "username":"M"
+    },
+    "new_value":"{\"syncAlerts\":false}",
+    "old_value":"{\"syncAlerts\":true}",
+    "action_id":"6c326760-0ca4-21eb-8a58-a3c589db8483",
+    "case_id":"4498ae50-0c8c-11eb-eefc-797bf7d42db4",
+    "comment_id":null
+  }
 ]
 --------------------------------------------------