diff --git a/docs/events/api/timeline-api-index.asciidoc b/docs/events/api/timeline-api-index.asciidoc index ecb6b148ac..9d4fc23d30 100644 --- 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 new file mode 100644 index 0000000000..0b5c12dcd5 --- /dev/null +++ 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 <> 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 :/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 <>. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`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 <> 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": [] + } + } + } +} +--------------------------------------------------