elastic · benskelker · Jun 11, 2020 · Jun 11, 2020
diff --git a/docs/siem/cases/api/actions-api/cases-actions-api-intro.asciidoc b/docs/siem/cases/api/actions-api/cases-actions-api-intro.asciidoc
diff --git a/docs/siem/cases/api/cases-api/case-api-update-connector.asciidoc b/docs/siem/cases/api/cases-api/case-api-update-connector.asciidoc
@@ -20,7 +20,7 @@ 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. |No
+cases to external systems. |Yes
 |`connector_name` |String |The connector name. |No
 |`closure_type` |String a|Determines whether a case is automatically closed in
 the {siem-app} when it is pushed to {sn}. Valid values are:

diff --git a/docs/siem/cases/api/cases-api/cases-api-assign-connector.asciidoc b/docs/siem/cases/api/cases-api/cases-api-assign-connector.asciidoc
@@ -1,5 +1,5 @@
 [[assign-connector]]
-=== Set connector
+=== Set default {siem-ui} connector
 
 Sets the default connector in the {siem-ui}.
 
@@ -8,6 +8,9 @@ method after you have created a connector (see <<register-connector>>). After a
 connector has been created and assigned, call <<cases-actions-api-execute>> to
 send cases to the external system.
 
+NOTE: You can also set the default connector in the {siem-ui} for each case
+individually (see <<cases-api-update>>).
+
 ==== Request URL
 
 `POST <kibana host>:<port>/api/cases/configure`

diff --git a/docs/siem/cases/api/cases-api/cases-api-associate-sn.asciidoc b/docs/siem/cases/api/cases-api/cases-api-associate-sn.asciidoc
@@ -1,11 +1,11 @@
 [[cases-api-associate-sn-incident]]
 === Add external details to case
 
-Adds the data returned from {sn} to the specified case.
+Adds the data returned from an external system to the specified case.
 
-After sending a new or updated case to {sn} using the
-<<cases-actions-api-execute, Actions API>>, you must associate the returned
-{sn} incident fields with the case in the {siem-app}.
+After sending a new or updated case to an external system using the
+<<cases-actions-api-execute, Actions API>>, you must associate
+the external system's returned object with the case in the {siem-app}.
 
 ==== Request URL
 
@@ -18,19 +18,19 @@ The URL must include the `case ID` of the case you are updating. Call
 
 ==== Request body
 
-A JSON object with the data returned from {sn}:
+A JSON object with the data returned from the external system:
 
 [width="100%",options="header"]
 |==============================================
 |Name |Type |Description |Required
 
-|`connector_id` |String |The ID of the connector used to send the case to {sn}.
-|Yes
-|`connector_name` |String |The ID of the connector used to send the case to
-{sn}. |Yes
-|`external_id` |String |The `incidentId` returned when calling
+|`connector_id` |String |The ID of the connector used to send the case to the
+external system. |Yes
+|`connector_name` |String |The name of the connector used to send the case to
+the external system.. |Yes
+|`external_id` |String |The `id` returned when calling
 <<cases-actions-api-execute>>. |Yes
-|`external_title` |String |The `number` returned when calling
+|`external_title` |String |The `title` returned when calling
 <<cases-actions-api-execute>>. |Yes
 |`external_url` |String |The `url` returned when calling
 <<cases-actions-api-execute>>. |Yes

diff --git a/docs/siem/cases/api/cases-api/cases-api-create.asciidoc b/docs/siem/cases/api/cases-api/cases-api-create.asciidoc
@@ -53,30 +53,34 @@ version, and creation time.
 [source,json]
 --------------------------------------------------
 {
-  "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
-  "version": "Wzc0LDFd",
+  "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
+  "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": [
+    "phishing",
+    "social engineering",
+    "bubblegum"
+  ],
   "closed_at": null,
   "closed_by": null,
-  "created_at": "2020-03-29T11:30:02.658Z",
+  "created_at": "2020-05-13T09:16:17.416Z",
   "created_by": {
     "email": "ahunley@imf.usa.gov",
     "full_name": "Alan Hunley",
     "username": "ahunley"
   },
-  "external_service": null, <1>
-  "updated_at": null,
-  "updated_by": null,
-  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants.",
-  "title": "This case will self-destruct in 5 seconds",
+  "external_service": null, <2>
   "status": "open",
-  "tags": [
-    "phishing",
-    "social engineering"
-  ]
+  "updated_at": null,
+  "updated_by": null
 }
 --------------------------------------------------
 
-<1> The `external_service` object stores information when the case is pushed to
+<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
 external systems. For more information, see <<actions-api-overview>>.
diff --git a/docs/siem/cases/api/cases-api/cases-api-find-connectors.asciidoc b/docs/siem/cases/api/cases-api/cases-api-find-connectors.asciidoc
@@ -3,8 +3,8 @@
 
 Retrieves a paginated subset of all {sn} connectors.
 
-NOTE: Only {sn} connectors are returned. For more information on connectors,
-see <<actions-api-overview>>.
+NOTE: Only {sn} and Jira connectors are returned. For more information on
+connectors, see <<actions-api-overview>>.
 
 ==== Request URL
 

diff --git a/docs/siem/cases/api/cases-api/cases-api-update.asciidoc b/docs/siem/cases/api/cases-api/cases-api-update.asciidoc
@@ -25,6 +25,9 @@ A JSON array containing one or more case objects with updated field values:
 
 |`id` |String |The ID of the case being updated. |Yes
 |`title` |String |The updated case title. |No
+| `connector_id` |String |ID of the <<actions-api-overview, connector>>
+used for pushing case updates to external systems (returned when calling
+<<cases-api-find-connectors>>). |No
 |`description` |String |The updated case description. |No
 |`status` |String a|The updated case status, which can be:
 
@@ -39,7 +42,7 @@ A JSON array containing one or more case objects with updated field values:
 
 ===== Example request
 
-Updates the `description` and `tags` fields of case ID
+Updates the description, tags, and connector of case ID
 `a18b38a0-71b0-11ea-a0b2-c51ea50a58e2`:
 
 [source,sh]
@@ -48,6 +51,7 @@ PATCH api/cases
 {
   "cases": [
     {
+      "connector_id": "5b347c7b-6925-4452-a4dd-215550294ba2",
       "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
       "description": "James Bond clicked on a highly suspicious email
       banner advertising cheap holidays for underpaid civil servants.
@@ -80,33 +84,46 @@ The updated case with a new `version` value.
 --------------------------------------------------
 [
   {
-    "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
-    "version": "Wzk4LDFd",
+    "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
+    "version": "WzU0OCwxXQ==",
     "comments": [],
     "totalComment": 0,
+    "connector_id": "5b347c7b-6925-4452-a4dd-215550294ba2",
+    "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": [
+      "phishing",
+      "social engineering",
+      "bubblegum"
+    ],
     "closed_at": null,
     "closed_by": null,
-    "created_at": "2020-03-29T11:30:02.658Z",
+    "created_at": "2020-05-13T09:16:17.416Z",
     "created_by": {
       "email": "ahunley@imf.usa.gov",
       "full_name": "Alan Hunley",
       "username": "ahunley"
     },
-    "external_service": null,
-    "updated_at": "2020-03-29T12:01:50.244Z",
+    "external_service": {
+      "external_title": "IS-4",
+      "pushed_by": {
+        "full_name": "Classified",
+        "email": "classified@hms.oo.gov.uk",
+        "username": "M"
+      },
+      "external_url": "https://hms.atlassian.net/browse/IS-4",
+      "pushed_at": "2020-05-13T09:20:40.672Z",
+      "connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8",
+      "external_id": "10003",
+      "connector_name": "Jira"
+    },
+    "status": "open",
+    "updated_at": "2020-05-13T09:48:33.043Z",
     "updated_by": {
       "email": "classified@hms.oo.gov.uk",
       "full_name": "Classified",
       "username": "M"
-    },
-    "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",
-    "tags": [
-      "phishing",
-      "social engineering",
-      "bubblegum"
-    ]
+    }
   }
 ]
 --------------------------------------------------
diff --git a/docs/siem/cases/api/cases-api/cases-api.asciidoc b/docs/siem/cases/api/cases-api/cases-api.asciidoc
@@ -11,5 +11,4 @@ these APIs:
 
 * Actions API: Used to send cases to external systems. <<register-connector>>
 stores the data required to interface with third-party systems, and
-<<cases-actions-api-execute>> sends {siem-soln} cases to external systems
-(currently, {sn}).
+<<cases-actions-api-execute>> sends {siem-soln} cases to external systems.
diff --git a/docs/siem/cases/cases-overview.asciidoc b/docs/siem/cases/cases-overview.asciidoc
@@ -9,12 +9,12 @@ Cases are used to open and track security issues directly in the {siem-app}.
 All cases list the original reporter and all users who contribute to a case
 (`participants`). Comments support Markdown syntax, and allow linking to saved
 <<timelines-overview, Timelines>>. Additionally, you can send cases to external
-systems from within the {siem-app} (currently {sn}). <<cases-ui-integrations>>
-describes how to set this up.
+systems from within the {siem-app} (currently {sn} and Jira).
+<<cases-ui-integrations>> describes how to set this up.
 
 You can create and manage cases via the UI or the <<cases-api-overview>>.
 
-NOTE: To send cases to {sn}, you need the
+NOTE: To send cases to external systems, you need the
 https://www.elastic.co/subscriptions[appropriate license].
 
 IMPORTANT: To make sure you can view and open cases, see <<case-permisions>>.
@@ -36,7 +36,11 @@ https://www.markdownguide.org/cheat-sheet[Markdown] syntax and insert a
 timeline link (click the icon in the top right corner of the area).
 
 . When ready, create the case.
-. If external connections are configured, you can send the case to {sn}.
+. If external connections are configured, you can:
+* Select which connector is used to send the case to an external system
+(`External incident management system`).
+* Send the case to an external system. You can send the case to more than one
+external system.
 
 [role="screenshot"]
 image::images/cases-ui-open.png[]
@@ -52,12 +56,14 @@ To view a case, click on its name. You can then:
 
 * Add a new comment.
 * Edit existing comments and the case's description.
-* Send updates to {sn} (if external connections are configured).
+* Send updates to external systems (if external connections are configured).
 * Close the case.
 * Reopen a closed case.
 * Edit tags.
 * Refresh the case to retrieve the latest updates.
 
+NOTE: Comments can also contain Markdown syntax and timeline links.
+
 [float]
 [[case-permisions]]
 == Cases prerequisites

diff --git a/docs/siem/cases/cases-ui-integrations.asciidoc b/docs/siem/cases/cases-ui-integrations.asciidoc
@@ -2,13 +2,17 @@
 [role="xpack"]
 == Configuring external connections
 
-You can push new cases and case updates to {sn}. To do this, you need to create
-a connector, which stores the information required to push cases to {sn} via
-{sn}'s https://developer.servicenow.com/dev.do#!/reference/api/madrid/rest/c_TableAPI[Table API].
+You can push new cases and case updates to {sn} and Jira. To do this, you need
+to create a connector, which stores the information required to push cases to
+external systems. For {sn}, cases are send via {sn}'s
+https://developer.servicenow.com/dev.do#!/reference/api/madrid/rest/c_TableAPI[Table API]. For Jira, the
+https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2] is
+used.
+
 After you have created a connector, you can set {siem-soln} cases to
-automatically close when they are sent to {sn}.
+automatically close when they are sent to external systems.
 
-NOTE: To create a {sn} connector and send cases to {sn}, you need the
+NOTE: To create connectors and send cases to external systems, you need the
 https://www.elastic.co/subscriptions[appropriate license].
 
 [float]
@@ -18,18 +22,29 @@ https://www.elastic.co/subscriptions[appropriate license].
 +
 [role="screenshot"]
 image::images/cases-ui-connector.png[]
-. Click `Add new connector option`, and then click {sn}.
-+
-[role="screenshot"]
-image::images/cases-ui-sn-connector.png[]
+. From the `Incident management system` list, select `Add new connector`.
+. Select one of these:
+* {sn}: To send cases to {sn}.
+* Jira: To send cases to Jira.
+
 . Fill in the following:
 * _Connector name_: A name for the connector.
-* _URL_: The URL of the {sn} instance to which you want to send cases.
-* _Username_: The username of the {sn} account used to access the {sn}
-instance.
-* _Password_: The password of the {sn} account used to access the {sn} instance.
-. To represent a SIEM case as a {sn} incident, these SIEM case fields are
-mapped to {sn} incidents fields as follows:
+* _URL_: The URL of the external system to which you want to send cases.
+* _Username_ ({sn} connectors only): The username of the {sn} account used to
+access the {sn} instance.
+* _Password_ ({sn} connectors only): The password of the {sn} account used to access the {sn} instance.
+* _Project key_ (Jira connectors only): The key of the Jira project to which
+you are sending cases.
+* _Email_ (Jira connectors only): The Jira account's email address.
+* _API token_ (Jira connectors only): The API token used to authenticate Jira
+updates.
+
+. Save the connector.
+
+To represent a SIEM case in an external system, SIEM case fields are mapped as
+follows:
+
+* For {sn} incidents:
 ** `Title`: Mapped to the {sn} `Short description` field. When an update to a
 SIEM case title is sent to {sn}, the existing {sn} `Short description` field is
 overwritten.
@@ -38,24 +53,35 @@ SIEM case description is sent to {sn}, the existing {sn} `Description` field is
 overwritten.
 ** `Comments`: Mapped to the {sn} `Comments` field. When a comment is updated
 in a SIEM case, a new comment is added to the {sn} incident.
-. Save the connector.
+* For Jira issues:
+** `Title`: Mapped to the Jira `Summary` field. When an update to a
+SIEM case title is sent to Jira, the existing Jira `Summary` field is
+overwritten.
+** `Description`: Mapped to the Jira `Description` field. When an update to a
+SIEM case description is sent to Jira, the existing Jira `Description` field is
+overwritten.
+** `Comments`: Mapped to the Jira `Comments` field. When a comment is updated
+in a SIEM case, a new comment is added to the Jira incident.
+
 
 [float]
 === Close sent cases automatically
 
-To close cases when they are sent to {sn}, select the
-_Automatically close SIEM cases when pushing new incident to third-party_
-option.
+To close cases when they are sent to an external system, select
+_Automatically close SIEM cases when pushing new incident to external system_.
 
 [float]
 === Change and update connectors
 
 You can create additional connectors, update existing connectors, and change
 the connector used to send cases to {sn}.
 
-. To change the connector used to send cases to {sn}: 
+TIP: You can also configure which connector is used for each case individually
+(see <<cases-ui-open>>). 
+
+. To change the default connector used to send cases to external systems: 
 .. Go to *SIEM* -> *Cases* -> *Edit external connection*.
 .. Select the required connector from the `Incident management system` list.
 . To update an existing connector:
-.. Click `Update connector`.
+.. Click `Update <connector name>`.
 .. Update the connector fields as required.
diff --git a/docs/siem/cases/images/cases-ui-connector.png b/docs/siem/cases/images/cases-ui-connector.png
diff --git a/docs/siem/cases/images/cases-ui-home.png b/docs/siem/cases/images/cases-ui-home.png
diff --git a/docs/siem/cases/images/cases-ui-open.png b/docs/siem/cases/images/cases-ui-open.png
diff --git a/docs/siem/detections/images/all-rules.png b/docs/siem/detections/images/all-rules.png
diff --git a/docs/siem/detections/images/detections-ui.png b/docs/siem/detections/images/detections-ui.png
diff --git a/docs/siem/detections/machine-learning/images/cloned-job-details.png b/docs/siem/detections/machine-learning/images/cloned-job-details.png
diff --git a/docs/siem/detections/machine-learning/images/ml-ui.png b/docs/siem/detections/machine-learning/images/ml-ui.png