Adds missing Update Timeline & Timeline template API docs

docs/events/api/timeline-api-index.asciidoc

@@ -4,6 +4,8 @@ include::timeline-api-get.asciidoc[]
 
 include::timeline-api-create.asciidoc[]
 
+include::timeline-api-update-2.asciidoc[]
+
 include::timeline-api-update.asciidoc[]
 
 include::timeline-api-delete.asciidoc[]

docs/events/api/timeline-api-update-2.asciidoc

@@ -0,0 +1,385 @@
+[[timeline-api-update-2]]
+=== 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 a Timeline or a Timeline template is updated, where:
+
+* `"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, see <<timeline-object-schema>>.
+
+[width="100%",options="header"]
+|==============================================
+|Name |Type |Description |Required
+
+|`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 updating a Timeline template, provide these fields so you can
+easily <<timeline-api-import, import template>> updates:
+
+* `templateTimelineId`: Unique identifier (UUID, for Timeline templates only). This must match the existing Timeline template version.
+* `templateTimelineVersion`: Template version number (for Timeline templates only). This must be a Timeline template version greater than the existing one.
+
+|Yes
+|`timelineId` |String |The `savedObjectId` of an existing Timeline that you're updating.
+|Yes
+|`version` |String |The version of an existing Timeline 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 existing Timeline's `savedObjectId`.
+<2> `version` must match the existing Timeline version.
+
+*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 existing Timeline template version.
+<2> `templateTimelineVersion` must be a Timeline template version greater than the existing one.
+<3> `timelineId` must match the existing Timeline's `savedObjectId`.
+<4> `version` must match the existing Timeline version.
+
+==== Response code
+
+`200`::
+    Indicates a successful call.
+
+==== Response payload
+
+A JSON Timeline object with a unique `savedObjectId` and its `version`.
+
+*Example 1*
+
+Update Timeline response payload:
+
+[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*
+
+Update Timeline template response payload:
+
+[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": []
+      }
+    }
+  }
+}
+--------------------------------------------------