Update timeline docs (elastic#678) (elastic#691)

Co-authored-by: jmikell821 <[email protected]> Co-authored-by: Janeen Mikell-Straughn <[email protected]> Co-authored-by: Angela Chuang <[email protected]>
nastasha-solomon · May 20, 2021 · 90fe910 · 90fe910
1 parent d2e94f5
commit 90fe910
Show file tree

Hide file tree

Showing 7 changed files with 270 additions and 25 deletions.
diff --git a/docs/events/api/timeline-api-create.asciidoc b/docs/events/api/timeline-api-create.asciidoc
@@ -1,13 +1,13 @@
 [[timeline-api-create]]
-=== Create timeline or timeline template
+=== Create Timeline or Timeline template
 
-Creates a new timeline or timeline template.
+Creates a new Timeline or Timeline template.
 
 Use the `timeline` object's <<timeline-object-typeField, `timelineType`>> field
 to determine whether a timeline or a timeline template is created, where:
 
-* `default` creates a new timeline (`"timelineType": "default"`)
-* `template` creates a new timeline template (`"timelineType": "template"`)
+* `default` creates a new Timeline (`"timelineType": "default"`)
+* `template` creates a new Timeline template (`"timelineType": "template"`)
 
 NOTE: If you do not specify the `timelineType` field, a new timeline is created.
 
@@ -17,7 +17,7 @@ NOTE: If you do not specify the `timelineType` field, a new timeline is created.
 
 ==== Request body
 
-A JSON object defining the timeline or timeline template query and time filter.
+A JSON object defining the Timeline or Timeline template query and time filter.
 
 NOTE: For detailed information about the Timeline object schema and its
 corresponding UI components, see <<timeline-object-schema>>.
@@ -29,26 +29,26 @@ corresponding UI components, see <<timeline-object-schema>>.
 |`timeline` |<<timeline-object-schema, timeline>> a|The timeline object, which
 defines the search criteria and time range. The only required field is `title`.
 
-When you are creating a timeline template, provide these fields to so you can
+When you are creating a Timeline template, provide these fields to so you can
 easily <<timeline-api-import, import template>> updates:
 
-* `templateTimelineId`: Unique identifier (UUID, for timeline templates only)
-* `templateTimelineVersion`: Template version number (for timeline templates
+* `templateTimelineId`: Unique identifier (UUID, for Timeline templates only)
+* `templateTimelineVersion`: Template version number (for Timeline templates
 only)
 
 |Yes
-|`timelineId` |String |If provided, must be `null` for a new timeline or
+|`timelineId` |String |If provided, must be `null` for a new Timeline or
 template.
 |No
-|`version` |String |If provided, must be `null` for a new timeline or template.
+|`version` |String |If provided, must be `null` for a new Timeline or template.
 |No
 |==============================================
 
 ===== Example requests
 
 *Example 1*
 
-Creates a new timeline:
+Creates a new Timeline. 
 
 [source,console]
 --------------------------------------------------
@@ -79,6 +79,7 @@ POST api/timeline
             "name": "event.category",
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d11",
             "queryMatch": {
               "field": "event.category",
               "value": "process",
@@ -89,6 +90,7 @@ POST api/timeline
             "name": "user.name",
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d12",
             "queryMatch": {
               "field": "user.name",
               "value": "SYSTEM",
@@ -98,6 +100,7 @@ POST api/timeline
         ],
         "enabled": true,
         "excluded": false,
+        "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d13",
         "name": "host.os.platform",
         "queryMatch": {
           "field": "host.os.platform",
@@ -117,21 +120,22 @@ POST api/timeline
 --------------------------------------------------
 // KIBANA
 
-<1> To ensure the timeline is displayed correctly in the UI, specify these
+<1> To ensure the Timeline is displayed correctly in the UI, specify these
 fields in all `dataProviders` objects:
 
 * `and` (can be empty)
 * `name`
 * `enabled`
 * `excluded`
+* `id`
 * `queryMatch`
 ** `field`
 ** `value`
 ** `operator`
 
 *Example 2*
 
-Creates a new timeline template:
+Creates a new Timeline template:
 
 [source,console]
 --------------------------------------------------
@@ -162,6 +166,7 @@ POST api/timeline
             "name": "event.category",
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d21",
             "queryMatch": {
               "field": "event.category",
               "operator": ":",
@@ -172,6 +177,7 @@ POST api/timeline
             "name": "user.name",
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d22",
             "queryMatch": {
               "field": "user.name",
               "operator": ":",
@@ -181,6 +187,7 @@ POST api/timeline
         ],
         "enabled": true,
         "excluded": false,
+        "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d23",
         "name": "host.os.platform",
         "queryMatch": {
           "field": "host.os.platform",
@@ -203,7 +210,7 @@ POST api/timeline
 --------------------------------------------------
 // KIBANA
 
-<1> To ensure the timeline template is displayed correctly in the UI, specify
+<1> To ensure the Timeline template is displayed correctly in the UI, specify
 the `value` field even though it is replaced when alerts are investigated in
 Timeline.
 <2> Template UUID.
@@ -212,7 +219,7 @@ Timeline.
 
 *Example 3*
 
-Creates the a timeline template that uses the `kqlQuery` object (KQL bar in the
+Creates the Timeline template that uses the `kqlQuery` object (KQL bar in the
 UI) to ensure only Windows alerts are displayed when alerts are investigated in
 Timeline:
 
@@ -244,6 +251,7 @@ POST api/timeline
           {
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d31",
             "name": "user.name",
             "queryMatch": {
               "field": "user.name",
@@ -254,6 +262,7 @@ POST api/timeline
         ],
         "enabled": true,
         "excluded": false,
+        "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d32",
         "name": "event.category",
         "queryMatch": {
           "field": "event.category",
@@ -287,12 +296,12 @@ POST api/timeline
 
 ==== Response code
 
-`200`:: 
+`200`::
     Indicates a successful call.
-    
+
 ==== Response payload
 
-A JSON timeline object with a unique `savedObjectId` and its `version`.
+A JSON Timeline object with a unique `savedObjectId` and its `version`.
 
 *Example 1*
 
@@ -332,6 +341,7 @@ Timeline response payload:
                 "name": "event.category",
                 "enabled": true,
                 "excluded": false,
+                "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d41",
                 "queryMatch": {
                   "field": "event.category",
                   "value": "process",
@@ -342,6 +352,7 @@ Timeline response payload:
                 "name": "user.name",
                 "enabled": true,
                 "excluded": false,
+                "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d42",
                 "queryMatch": {
                   "field": "user.name",
                   "value": "SYSTEM",
@@ -351,6 +362,7 @@ Timeline response payload:
             ],
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-914beb92-86ab-471c-a00b-25b7e20c2d43",
             "name": "host.os.platform",
             "queryMatch": {
               "field": "host.os.platform",
@@ -414,6 +426,7 @@ Timeline template response payload:
               {
                 "enabled": true,
                 "excluded": false,
+                "id": "timeline-1-43112bd4-3081-491c-b973-605cce4c5f14",
                 "name": "user.name",
                 "queryMatch": {
                   "field": "user.name",
@@ -424,6 +437,7 @@ Timeline template response payload:
             ],
             "enabled": true,
             "excluded": false,
+            "id": "timeline-1-43112bd4-3081-491c-b973-605cce4c5f15",
             "name": "event.category",
             "queryMatch": {
               "field": "event.category",

diff --git a/docs/events/api/timeline-api-delete.asciidoc b/docs/events/api/timeline-api-delete.asciidoc
@@ -0,0 +1,30 @@
+[[timeline-api-delete]]
+=== Delete Timelines or Timeline templates
+
+Delete multiple Timelines or Timeline templates.
+
+==== Request URL
+
+`DELETE <kibana host>:<port>/api/timeline`
+
+==== Request body
+
+A JSON object defining the savedObjectIds of Timelines or Timeline templates to be deleted.
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+|`savedObjectIds` | Array | `savedObjectIds` of Timelines or Timeline templates
+|Yes
+
+|==============================================
+
+===== Example requests
+
+[source,console]
+--------------------------------------------------
+DELETE api/timeline
+{
+	"savedObjectIds": ["56efaaf0-b274-11eb-8078-5b983613cc0f"]
+}
+--------------------------------------------------
diff --git a/docs/events/api/timeline-api-export.asciidoc b/docs/events/api/timeline-api-export.asciidoc
@@ -1,7 +1,7 @@
 [[timeline-api-export]]
-=== Export timelines
+=== Export Timelines
 
-Exports timelines to an ndjson file.
+Exports Timelines to an ndjson file.
 
 ==== Request URL
 
@@ -18,8 +18,8 @@ Exports timelines to an ndjson file.
 |`file_name` |String |File name for saving the exported rules. |Yes
 |==============================================
 
-TIP: When using cURL to export timelines to a file, use the `-O` and `-J`
-options to save the timelines to the file name specified in the URL.
+TIP: When using cURL to export Timelines to a file, use the `-O` and `-J`
+options to save the Timelines to the file name specified in the URL.
 
 ==== Request body
 
@@ -35,7 +35,7 @@ A JSON `ids` array containing the `savedObjectId` fields of the rules you want t
 
 ===== Example request
 
-Exports two timeline and saves them to the `timelines_export.ndjson` file:
+Exports two Timelines and saves them to the `timelines_export.ndjson` file:
 
 [source,console]
 --------------------------------------------------

diff --git a/docs/events/api/timeline-api-get.asciidoc b/docs/events/api/timeline-api-get.asciidoc
@@ -0,0 +1,86 @@
+[[timeline-api-get]]
+=== Get Timelines or Timeline templates
+
+Get Timelines or Timeline templates.
+
+==== Request URL
+
+`GET <kibana host>:<port>/api/timelines`
+
+==== Request params
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`only_user_favorite` |Boolean a|Returns only favorite Timelines / Timeline templates if set to `true`. Default to `false`
+|No
+|`page_index` |Number |Page number of the result
+|No
+|`page_size` |Number |Items per page in result
+|No
+|`search` |String |The key word of the Timelines / Timeline templates you are searching for
+|No
+|`sort_field` |String |The order you want the result to be arranged. Can be `title`, `description`, `updated`, `created`
+|No
+|`sort_order` |String |`asc` or `desc`
+|No
+|`status` |String |Can be `active` or `immutable`. `active` returns all the custom Timelines / Timeline templates, whereas `immutable` returns Elastic prebuilt templates
+|No
+|`timeline_type` |String |Use the `timeline` object's <<timeline-object-typeField, `timelineType`>> field
+to determine whether a timeline or a Timeline template is created, where:
+
+`default` returns Timelines, `template` returns Timeline templates
+|No
+
+|==============================================
+
+===== Example requests
+
+Get Timelines:
+
+[source,console]
+--------------------------------------------------
+GET api/timelines?page_size=10&page_index=1&sort_field=updated&sort_order=desc&timeline_type=default
+
+--------------------------------------------------
+
+
+=== Get Timeline / Timeline template by savedObjectId
+
+Get single Timeline or Timeline template by savedObjectId.
+
+==== Request URL
+
+`GET <kibana host>:<port>/api/timeline?id=<savedObjectId>`
+
+===== Example requests
+
+Get Timeline by savedObjectId:
+
+[source,console]
+--------------------------------------------------
+GET /api/timeline?id=<savedObjectId>
+
+--------------------------------------------------
+
+
+=== Get Timeline template by templateTimelineId
+
+Get a single Timeline template by templateTimelineId.
+
+==== Request URL
+
+`GET <kibana host>:<port>/api/timeline?template_timeline_id=<templateTimelineId>`
+
+===== Example requests
+
+Get Timeline by templateTimelineId:
+
+[source,console]
+--------------------------------------------------
+GET /api/timeline?template_timeline_id=<templateTimelineId>
+
+--------------------------------------------------
+
+
diff --git a/docs/events/api/timeline-api-index.asciidoc b/docs/events/api/timeline-api-index.asciidoc
@@ -1,7 +1,13 @@
 include::timeline-api-overview.asciidoc[]
 
+include::timeline-api-get.asciidoc[]
+
 include::timeline-api-create.asciidoc[]
 
+include::timeline-api-update.asciidoc[]
+
+include::timeline-api-delete.asciidoc[]
+
 // include::timeline-api-export.asciidoc[]
 
 include::timeline-api-import.asciidoc[]
diff --git a/docs/events/api/timeline-api-overview.asciidoc b/docs/events/api/timeline-api-overview.asciidoc
@@ -2,5 +2,6 @@
 [role="xpack"]
 == Timeline API
 
-You can create timelines and timeline templates via the API, as well import new
-timelines from an `ndjson` file.
+You can create Timelines and Timeline templates via the API, as well as import new Timelines from an `ndjson` file.
+
+NOTE: The {kib} Console supports only Elasticsearch APIs. You cannot interact with the {kib} APIs with the Console and must use `curl` or another HTTP tool instead. For more information, refer to https://www.elastic.co/guide/en/kibana/current/console-kibana.html[Console].