Skip to content

Commit 98e236c

Browse files
cnasikascnasikas
authored
[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
1 parent 1c660f8 commit 98e236c

8 files changed

+294
-28
lines changed

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

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,8 @@ A JSON object with these fields:
1919
|==============================================
2020
|Name |Type |Description |Required
2121

22-
|`connector_id` |String |The ID of the connector you want to use for sending
23-
cases to external systems. |Yes
24-
|`connector_name` |String |The connector name. |No
22+
|`connector` |<<update-connector-connector-schema, connector>> |Object containing the connector's
23+
configuration. |Yes
2524
|`closure_type` |String a|Determines whether a case is automatically closed in
2625
{es-sec} when it is pushed to external systems. Valid values are:
2726

@@ -34,9 +33,51 @@ are pushed.
3433
|`version` |String |The connector version. |Yes
3534
|==============================================
3635

36+
[[update-connector-connector-schema]]
37+
*`connector` schema*
38+
39+
[width="100%",options="header"]
40+
|==============================================
41+
|Name |Type |Description |Required
42+
43+
|`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes
44+
|`name` |String a|The connector name. |Yes
45+
|`type` |String a|The type of the connector.
46+
47+
Must be one of these:
48+
49+
* `.servicenow`
50+
* `.jira`
51+
* `.resilient`
52+
* `.none`
53+
|Yes
54+
|`fields` |Object a| Object containing connector's fields.
55+
56+
For {sn} connectors:
57+
58+
* `urgency` (string \| null): The urgency of the incident.
59+
* `severity` (string \| null): The severity of the incident.
60+
* `impact` (string \| null): The impact of the incident.
61+
62+
For Jira connectors:
63+
64+
* `issueType` (string): The issue type of the issue.
65+
* `priority` (string \| null): The priority of the issue.
66+
* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
67+
68+
For {ibm-r} connectors:
69+
70+
* `issueTypes` (number[]): The issue types of the issue.
71+
* `severityCode` (number): The severity code of the issue.
72+
73+
|Yes
74+
|==============================================
75+
3776
NOTE: Call <<cases-get-connector>> to retrieve the version value, and
3877
<<cases-api-find-connectors>> to retrieve connector IDs.
3978

79+
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>>.
80+
4081
===== Example request
4182

4283
Changes the connector's case closure option:
@@ -45,7 +86,12 @@ Changes the connector's case closure option:
4586
--------------------------------------------------
4687
PATCH api/cases/configure
4788
{
48-
"connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
89+
"connector": {
90+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
91+
"name": "My connector",
92+
"type": ".jira",
93+
"fields": null,
94+
}
4995
"closure_type": "close-by-pushing",
5096
"version": "WzIwMiwxXQ=="
5197
}
@@ -62,9 +108,13 @@ PATCH api/cases/configure
62108
[source,json]
63109
--------------------------------------------------
64110
{
65-
"connector_id": "131d4448-abe0-4789-939d-8ef60680b498",
111+
"connector": {
112+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
113+
"name": "My connector",
114+
"type": ".jira",
115+
"fields": null,
116+
},
66117
"closure_type": "close-by-pushing",
67-
"connector_name": "ServiceNow",
68118
"created_at": "2020-03-30T13:31:38.083Z",
69119
"created_by": {
70120
"email": "admin@hms.gov.uk",

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

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ A JSON object with these fields:
2323
|==============================================
2424
|Name |Type |Description |Required
2525

26-
|`connector_id` |String |The connector ID. |Yes
27-
|`connector_name` |String |The connector name. |Yes
26+
|`connector` |<<assign-connector-connector-schema, connector>> |Object containing the connector's
27+
configuration. |Yes
2828
|`closure_type` |String a|Determines whether a case is automatically closed in
2929
{es-sec} when it is pushed to external systems. Valid values are:
3030

@@ -35,17 +35,63 @@ are pushed.
3535
|Yes
3636
|==============================================
3737

38+
[[assign-connector-connector-schema]]
39+
*`connector` schema*
40+
41+
[width="100%",options="header"]
42+
|==============================================
43+
|Name |Type |Description |Required
44+
45+
|`id` |String |The ID of the connector you want to use for sending cases to external systems. |Yes
46+
|`name` |String a|The connector name. |Yes
47+
|`type` |String a|The type of the connector.
48+
49+
Must be one of these:
50+
51+
* `.servicenow`
52+
* `.jira`
53+
* `.resilient`
54+
* `.none`
55+
|Yes
56+
|`fields` |Object a| Object containing the connector's fields.
57+
58+
For {sn} connectors:
59+
60+
* `urgency` (string \| null): The urgency of the incident.
61+
* `severity` (string \| null): The severity of the incident.
62+
* `impact` (string \| null): The impact of the incident.
63+
64+
For Jira connectors:
65+
66+
* `issueType` (string): The issue type of the issue.
67+
* `priority` (string \| null): The priority of the issue.
68+
* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
69+
70+
For {ibm-r} connectors:
71+
72+
* `issueTypes` (number[]): The issue types of the issue.
73+
* `severityCode` (number): The severity code of the issue.
74+
75+
|Yes
76+
|==============================================
77+
3878
NOTE: Call <<cases-api-find-connectors>> to retrieve connector IDs and names.
3979

80+
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>>.
81+
4082
==== Example request
4183

4284
[source,sh]
4385
--------------------------------------------------
4486
POST api/cases/configure
4587
{
46-
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
88+
"connector": {
89+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
90+
"name": "Jira",
91+
"type": ".jira",
92+
"fields": null,
93+
},
4794
"closure_type": "close-by-user",
48-
"connector_name": "ServiceNow"
4995
}
5096
--------------------------------------------------
5197

@@ -59,9 +105,13 @@ POST api/cases/configure
59105
[source,json]
60106
--------------------------------------------------
61107
{
62-
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
108+
"connector": {
109+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
110+
"name": "Jira",
111+
"type": ".jira",
112+
"fields": null,
113+
},
63114
"closure_type": "close-by-user",
64-
"connector_name": "ServiceNow",
65115
"created_at": "2020-03-30T13:31:38.083Z",
66116
"created_by": {
67117
"email": "moneypenny@hms.gov.uk",

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

Lines changed: 68 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,50 @@ A JSON object with these fields:
1919
|`description` |String |The case's description. |Yes
2020
|`tags` |String[] |String array containing words and phrases that help
2121
categorize cases. |Yes, can be an empty array.
22+
|`connector` |<<create-case-connector-schema, connector>> |Object containing the connector's
23+
configuration. |Yes
24+
|==============================================
25+
26+
[[create-case-connector-schema]]
27+
*`connector` schema*
28+
29+
[width="100%",options="header"]
30+
|==============================================
31+
|Name |Type |Description |Required
32+
33+
|`id` |String |ID of the <<actions-api-overview, connector>>
34+
used for pushing case updates to external systems (returned when calling
35+
<<cases-api-find-connectors>>). |Yes
36+
|`name` |String a|The connector name. |Yes
37+
|`type` |String a|The type of the connector.
38+
39+
Must be one of these:
40+
41+
* `.servicenow`
42+
* `.jira`
43+
* `.resilient`
44+
* `.none`
45+
|Yes
46+
|`fields` |Object a| Object containing the connector's fields.
47+
48+
For {sn} connectors:
49+
50+
* `urgency` (string \| null): The urgency of the incident.
51+
* `severity` (string \| null): The severity of the incident.
52+
* `impact` (string \| null): The impact of the incident.
53+
54+
For Jira connectors:
55+
56+
* `issueType` (string): The issue type of the issue.
57+
* `priority` (string \| null): The priority of the issue.
58+
* `parent` (string \| null): The key of the parent issue (Valid when the issue type is `Sub-task`).
59+
60+
For {ibm-r} connectors:
61+
62+
* `issueTypes` (number[]): The issue types of the issue.
63+
* `severityCode` (number): The severity code of the issue.
64+
65+
|Yes
2266
|==============================================
2367

2468
===== Example request
@@ -33,7 +77,16 @@ POST api/cases
3377
"tags": [
3478
"phishing",
3579
"social engineering"
36-
]
80+
],
81+
"connector": {
82+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
83+
"name": "My connector",
84+
"type": ".jira",
85+
"fields": {
86+
"issueType": "10006",
87+
"priority": "High",
88+
}
89+
}
3790
}
3891
--------------------------------------------------
3992
// KIBANA
@@ -59,7 +112,6 @@ version, and creation time. The case's ID is also its saved object ID
59112
"version": "WzUzMiwxXQ==",
60113
"comments": [],
61114
"totalComment": 0,
62-
"connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8", <1>
63115
"title": "This case will self-destruct in 5 seconds",
64116
"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",
65117
"tags": [
@@ -75,14 +127,23 @@ version, and creation time. The case's ID is also its saved object ID
75127
"full_name": "Alan Hunley",
76128
"username": "ahunley"
77129
},
78-
"external_service": null, <2>
130+
"external_service": null, <1>
79131
"status": "open",
80132
"updated_at": null,
81-
"updated_by": null
133+
"updated_by": null,
134+
"connector": {
135+
"id": "131d4448-abe0-4789-939d-8ef60680b498", <2>
136+
"name": "My connector",
137+
"type": ".jira",
138+
"fields": {
139+
"issueType": "10006",
140+
"priority": "High",
141+
}
142+
}
82143
}
83144
--------------------------------------------------
84145

85-
<1> The default connector ID used to push cases to external services (see
86-
<<assign-connector>>).
87-
<2> The `external_service` object stores information when the case is pushed to
146+
<1> The `external_service` object stores information when the case is pushed to
88147
external systems. For more information, see <<actions-api-overview>>.
148+
<2> The default connector ID used to push cases to external services (see
149+
<<assign-connector>>).

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,16 @@ A JSON object listing the retrieved cases.
9393
"phishing"
9494
],
9595
"description": "Windows 95",
96-
"status": "open"
96+
"status": "open",
97+
"connector": {
98+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
99+
"name": "My connector",
100+
"type": ".jira",
101+
"fields": {
102+
"issueType": "10006",
103+
"priority": null,
104+
}
105+
},
97106
},
98107
{
99108
"id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
@@ -118,6 +127,15 @@ A JSON object listing the retrieved cases.
118127
"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!",
119128
"title": "This case will self-destruct in 5 seconds",
120129
"status": "open",
130+
"connector": {
131+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
132+
"name": "My connector",
133+
"type": ".resilient",
134+
"fields": {
135+
"issueTypes": [13],
136+
"severityCode": 6,
137+
}
138+
},
121139
"tags": [
122140
"phishing",
123141
"social engineering",

‎docs/cases/api/cases-api/cases-api-get-case-activity.asciidoc‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,23 @@ A JSON array containing all user activity for the specified case.
106106
"action_id": "223f7bd0-750a-11ea-b83a-553aecdb28b6",
107107
"case_id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
108108
"comment_id": "21a844e0-750a-11ea-b83a-553aecdb28b6"
109-
}
109+
},
110+
{
111+
"action_field":[
112+
"connector"
113+
],
114+
"action":"update",
115+
"action_at":"2020-10-12T16:03:34.940Z",
116+
"action_by":{
117+
"email":"christos.nasikas@elastic.co",
118+
"full_name":"Christos Nasikas",
119+
"username":"cnasikas"
120+
},
121+
"new_value":"{\"id\":\"18bc18cf-bd5d-4c88-bcdd-c7bb52a692cd\",\"name\":\"Resilient\",\"type\":\".resilient\",\"fields\":{\"incidentTypes\":[\"1001\"],\"severityCode\":\"5\"}}",
122+
"old_value":"{\"id\":\"72b9fa3a-b081-487d-9358-61d5da2968c1\",\"name\":\"Jira\",\"type\":\".jira\",\"fields\":{\"issueType\":\"10006\",\"parent\":null,\"priority\":\"Medium\"}}",
123+
"action_id":"7c326760-0ca4-11eb-8a58-a3c589db8483",
124+
"case_id":"7498ae50-0c8c-11eb-aefc-797bf7d42db4",
125+
"comment_id":null
126+
}
110127
]
111128
--------------------------------------------------

‎docs/cases/api/cases-api/cases-api-get-case.asciidoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,15 @@ The requested case JSON object.
6868
"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!",
6969
"title": "This case will self-destruct in 5 seconds",
7070
"status": "open",
71+
"connector": {
72+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
73+
"name": "My connector",
74+
"type": ".jira",
75+
"fields": {
76+
"issueType": "10006",
77+
"priority": "High",
78+
}
79+
},
7180
"tags": [
7281
"phishing",
7382
"social engineering",

‎docs/cases/api/cases-api/cases-api-get-connector.asciidoc‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,13 @@ GET api/cases/configure
2727
[source,json]
2828
--------------------------------------------------
2929
{
30-
"connector_id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
30+
"connector": {
31+
"id": "131d4448-abe0-4789-939d-8ef60680b498",
32+
"name": "Jira",
33+
"type": ".jira",
34+
"fields": null,
35+
},
3136
"closure_type": "close-by-user",
32-
"connector_name": "ServiceNow",
3337
"created_at": "2020-03-30T13:31:38.083Z",
3438
"created_by": {
3539
"email": "admin@hms.gov.uk",

0 commit comments

Comments
 (0)