Adds missing Update Timeline & Timeline template API docs (#3692) (#3770

) * Adds missing Update Timeline & Timeline template API docs * Fixes incorrect info * Renames asciidoc file * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Nastasha Solomon <[email protected]> * TW feedback * Update docs/events/api/timeline-template-api-update.asciidoc Co-authored-by: Joe Peeples <[email protected]> * TW review updates --------- Co-authored-by: Nastasha Solomon <[email protected]> Co-authored-by: Joe Peeples <[email protected]> (cherry picked from commit a913268) Co-authored-by: natasha-moore-elastic <[email protected]>
elastic · Aug 21, 2023 · 177379f · 177379f
1 parent 451fc81
commit 177379f
Show file tree

Hide file tree

Showing 2 changed files with 386 additions and 0 deletions.
diff --git a/docs/events/api/timeline-api-index.asciidoc b/docs/events/api/timeline-api-index.asciidoc
@@ -4,6 +4,8 @@ include::timeline-api-get.asciidoc[]
 
 include::timeline-api-create.asciidoc[]
 
+include::timeline-template-api-update.asciidoc[]
+
 include::timeline-api-update.asciidoc[]
 
 include::timeline-api-delete.asciidoc[]

diff --git a/docs/events/api/timeline-template-api-update.asciidoc b/docs/events/api/timeline-template-api-update.asciidoc
@@ -0,0 +1,384 @@
+[[timeline-template-api-update]]
+=== Update Timeline or Timeline template
+
+Updates an existing Timeline or Timeline template.
+
+Use the `timeline` object's <<timeline-object-typeField, `timelineType`>> field
+to specify whether you're updating a Timeline or a Timeline template:
+
+* `"timelineType": "default"` updates an existing Timeline.
+* `"timelineType": "template"` updates an existing Timeline template.
+
+==== Request URL
+
+`PATCH <kibana host>:<port>/api/timeline`
+
+==== Request body
+
+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, refer to <<timeline-object-schema>>.
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`timeline` |<<timeline-object-schema, timeline>> a|The `timeline` object of the Timeline or Timeline template that you're updating.
+
+If you're updating a Timeline template, provide these fields so you can
+easily <<timeline-api-import, import template>> updates:
+
+* `templateTimelineId`: Use the unique identifier (UUID) of the Timeline template that you're updating. 
+* `templateTimelineVersion`: Specify a new version number for the template. It must be greater than the existing version number.
+
+|Yes
+|`timelineId` |String |The `savedObjectId` of the Timeline or Timeline template that you're updating.
+|Yes
+|`version` |String |The version of the Timeline or Timeline template that you're updating.
+|Yes
+|==============================================
+
+===== Example requests
+
+*Example 1*
+
+Updates an existing Timeline.
+
+[source,console]
+--------------------------------------------------
+PATCH api/timeline
+{
+  "timeline": {
+    "columns": [
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "@timestamp"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "message"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "event.category"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "event.action"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "host.name"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "source.ip"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "destination.ip"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "user.name"
+      }
+    ],
+    "dataProviders": [],
+    "description": "",
+    "eventType": "all",
+    "filters": [],
+    "kqlMode": "filter",
+    "kqlQuery": {
+      "filterQuery": null
+    },
+    "title": "abd",
+    "dateRange": {
+      "start": 1587370079200,
+      "end": 1587456479201
+    },
+    "savedQueryId": null,
+    "sort": {
+      "columnId": "@timestamp",
+      "sortDirection": "desc"
+    },
+    "created": 1587468588922,
+    "createdBy": "casetester",
+    "updated": 1587468588922,
+    "updatedBy": "casetester",
+    "timelineType": "default"
+  },
+  "timelineId": "4bc294e0-3516-11ee-9f62-49614d8a84fd", <1>
+  "version": "WzE5MTUsMV0=" <2>
+}
+--------------------------------------------------
+
+<1> `timelineId` must match the `savedObjectId` of the Timeline that you're updating.
+<2> `version` must match the `version` of the Timeline that you're updating.
+
+*Example 2*
+
+Updates an existing Timeline template.
+
+[source,console]
+--------------------------------------------------
+PATCH api/timeline
+{
+  "timeline": {
+    "columns": [
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "@timestamp"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "message"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "event.category"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "event.action"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "host.name"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "source.ip"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "destination.ip"
+      },
+      {
+        "columnHeaderType": "not-filtered",
+        "id": "user.name"
+      }
+    ],
+    "dataProviders": [],
+    "description": "",
+    "eventType": "all",
+    "filters": [],
+    "kqlMode": "filter",
+    "kqlQuery": {
+      "filterQuery": null
+    },
+    "title": "abd",
+    "dateRange": {
+      "start": 1587370079200,
+      "end": 1587456479201
+    },
+    "savedQueryId": null,
+    "sort": {
+      "columnId": "@timestamp",
+      "sortDirection": "desc"
+    },
+    "timelineType": "template",
+    "created": 1587473119992,
+    "createdBy": "casetester",
+    "updated": 1587473119992,
+    "updatedBy": "casetester",
+    "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1", <1>
+    "templateTimelineVersion": 2 <2>
+  },
+  "timelineId": "7d7d4b60-3516-11ee-9f62-49614d8a84fd", <3>
+  "version": "WzE5MTcsMV0=" <4>
+}
+--------------------------------------------------
+<1> `templateTimelineId` must match the `templateTimelineId` of the Timeline template that you're updating. 
+<2> `templateTimelineVersion` must be a Timeline template version greater than the existing one.
+<3> `timelineId` must match the `savedObjectId` of the Timeline template that you're updating.
+<4> `version` must match the `version` of the Timeline template that you're updating.
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+==== Response payload
+
+A JSON Timeline object with a unique `savedObjectId` and its `version`.
+
+*Example 1*
+
+Response payload of an updated Timeline:
+
+[source,json]
+--------------------------------------------------
+{
+  "data": {
+    "persistTimeline": {
+      "code": 200,
+      "message": "success",
+      "timeline": {
+        "savedObjectId": "4bc294e0-3516-11ee-9f62-49614d8a84fd",
+        "version": "WzE5MTgsMV0=",
+        "columns": [
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "@timestamp"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "message"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "event.category"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "event.action"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "host.name"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "source.ip"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "destination.ip"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "user.name"
+          }
+        ],
+        "dataProviders": [],
+        "dataViewId": null,
+        "description": "",
+        "eventType": "all",
+        "excludedRowRendererIds": [],
+        "favorite": [],
+        "filters": [],
+        "kqlMode": "filter",
+        "kqlQuery": {
+          "filterQuery": null
+        },
+        "title": "abd",
+        "templateTimelineId": null,
+        "templateTimelineVersion": null,
+        "dateRange": {
+          "start": 1587370079200,
+          "end": 1587456479201
+        },
+        "savedQueryId": null,
+        "created": 1587468588922,
+        "createdBy": "casetester",
+        "updated": 1691408201273,
+        "updatedBy": "elastic",
+        "timelineType": "default",
+        "status": "active",
+        "sort": [
+          {
+            "sortDirection": "desc",
+            "columnId": "@timestamp"
+          }
+        ],
+        "eventIdToNoteIds": [],
+        "noteIds": [],
+        "notes": [],
+        "pinnedEventIds": [],
+        "pinnedEventsSaveObject": []
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+*Example 2*
+
+Response payload of an updated Timeline template:
+
+[source,json]
+--------------------------------------------------
+{
+  "data": {
+    "persistTimeline": {
+      "code": 200,
+      "message": "success",
+      "timeline": {
+        "savedObjectId": "7d7d4b60-3516-11ee-9f62-49614d8a84fd",
+        "version": "WzE5MTksMV0=",
+        "columns": [
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "@timestamp"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "message"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "event.category"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "event.action"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "host.name"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "source.ip"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "destination.ip"
+          },
+          {
+            "columnHeaderType": "not-filtered",
+            "id": "user.name"
+          }
+        ],
+        "dataProviders": [],
+        "dataViewId": null,
+        "description": "",
+        "eventType": "all",
+        "excludedRowRendererIds": [],
+        "favorite": [],
+        "filters": [],
+        "kqlMode": "filter",
+        "kqlQuery": {
+          "filterQuery": null
+        },
+        "title": "abd",
+        "templateTimelineId": "6f9a3480-bf4f-11ea-9fcd-ed4e5fd0dcd1",
+        "templateTimelineVersion": 2,
+        "dateRange": {
+          "start": 1587370079200,
+          "end": 1587456479201
+        },
+        "savedQueryId": null,
+        "created": 1587473119992,
+        "createdBy": "casetester",
+        "updated": 1691408702104,
+        "updatedBy": "elastic",
+        "timelineType": "template",
+        "status": "active",
+        "sort": [
+          {
+            "sortDirection": "desc",
+            "columnId": "@timestamp"
+          }
+        ],
+        "eventIdToNoteIds": [],
+        "noteIds": [],
+        "notes": [],
+        "pinnedEventIds": [],
+        "pinnedEventsSaveObject": []
+      }
+    }
+  }
+}
+--------------------------------------------------