[Docs]Timeline and Template UI updates

docs/siem/index.asciidoc

@@ -12,4 +12,8 @@ include::detections/machine-learning/ml-index.asciidoc[]
 
 include::detections/detections-index.asciidoc[]
 
+include::timeline/timeline-ui-overview.asciidoc[]
+
+include::timeline/timeline-templates.asciidoc[]
+
 include::cases/cases-index.asciidoc[]

docs/siem/siem-ui.asciidoc

@@ -233,7 +233,6 @@ The Cases page is used to open and track security issues directly in the
 image::images/cases-ui-home.png[]
 
 [float]
-[[timelines-ui]]
 == Timelines
 
 Use Timeline as your workspace for alert investigations or threat hunting.
@@ -260,7 +259,6 @@ can also link to timelines from Cases and external ticketing systems.
 
 
 [discrete]
-[[raw]]
 ==== Focus on signals or raw events
 
 Many security events in Timeline are presented in an easy-to-follow rendered
@@ -272,7 +270,6 @@ You can click and expand events from within Timeline to see the underlying
 event data, either in tabular form, as as {es} JSON.
 
 [discrete]
-[[narrow-expand]]
 ==== Narrow or expand your query
 
 You can specify logical `AND` and `OR` operations with an item's placement in
@@ -281,7 +278,6 @@ sets are `OR`-ed together. As you hover the item over the drop area, you can see
 whether your placement is on target to create an `AND` or `OR` filters.
 
 [discrete]
-[[pivot]]
 ==== Pivot on a data point
 
 Click a filter to access additional operations such as exclude, temporarily
@@ -290,7 +286,6 @@ item so that it is excluded.
 
 [discrete]
 [[row-renderer]]
-==== Get more context for each event
 
 As you build and modify your queries, you can see the results of your
 interactions in the details pane below.
@@ -301,7 +296,6 @@ event. If you see a particular item that interests you, you can drag it to the
 drop area for further introspection.
 
 [discrete]
-[[import-export-timelines]]
 ==== Export and import timelines
 
 You can import and export timelines, which enables importing timelines from one
@@ -320,7 +314,6 @@ then select _Export selected_.
 the timeline `ndjson` file.
 
 [discrete]
-[[other]]
 ==== Other actions
 
 The Timeline is flexible and highly interactive.  As you would expect, the

docs/siem/timeline/timeline-templates.asciidoc

@@ -0,0 +1,146 @@
+[[timeline-templates-ui]]
+== About Timeline templates
+
+You can attach Timeline templates to detection rules. When attached, the rule's
+alerts use the template when they are investigated in Timeline. This enables
+immediately viewing the alert's most interesting fields when you start an
+investigation.
+
+Templates can include two type of filters:
+
+* *'Regular' filter*: Like other {kib} KQL filters, defines both the source
+event field and its value. For example: `host.name : "win-server"`.
+* *Template filter*: Only defines the event field, and uses a placeholder
+for the field's value. When you investigate an alert in Timeline, the field's
+value is taken from the alert.
+
+For example, if you define the `host.name: "{host.name}"` template filter, when
+alerts generated by the rule are investigated in Timeline, the alert's
+`host.name` value is used in the filter. If the alert's `host.name` value is
+`Linux_stafordshire-061`, the Timeline filter is:
+`host.name: "Linux_stafordshire-061"`.
+
+NOTE: For information on how to add Timeline templates to rules, see
+<<create-rule-ui>>.
+
+When you load {es-sec} prebuilt rules, some prebuilt Timeline templates are
+also loaded. You can attach these templates to detection rules. The following
+templates are loaded:
+
+* `Generic Endpoint Timeline`: Useful for investigating Elastic Endpoint
+security alerts.
+* `Generic Process Timeline`: Useful for investigating process-related alerts.
+* `Generic Network Timeline`: Useful for investigating network-related alerts.
+
+TIP: You can <<man-templates-ui, duplicate prebuilt templates>> and use them as
+a starting point for your own custom templates.
+
+[discrete]
+[[template-legend-ui]]
+=== Timeline template legend
+
+When you add filters to a Timelime template, the items are color coded to
+indicate which type of filter is added. Additionally, you change Timeline
+filters to template filters as you build your template.
+
+'Regular' Timeline filter::
+Click `Convert to template field` changes the filter to a template filter:
++
+[role="screenshot"]
+image::images/template-filter-value.png[width=30%]
+
+Template filter::
++
+[role="screenshot"]
+image::images/timeline-template-filter.png[width=30%]
+
+When you <<man-templates-ui, convert a template to a Timeline>>, template
+filters with placeholders are disabled:
+
+[role="screenshot"]
+image::images/invalid-filter.png[width=30%]
+
+To enable the filter, either specify a value or change it to a field exists
+filter (see <<pivot>>).
+
+
+[discrete]
+=== Create a Timeline template
+
+. Go to *Security* -> *Timelines*.
+. Click the *Templates* tab, and then *Create new timeline template*.
++
+[role="screenshot"]
+image::images/create-template-ui.png[]
+
+. Give the template a title.
+. Optionally, add a description and notes.
+. To add filters, click *Add field*, and then select the required option:
+
+* _Add field_: Add a `regular` Timeline filter.
+* _Add template field_: Add a template filter with a value placeholder.
+
+TIP: You can also drag and send items to the template from the *Overview*,
+*Hosts*, *Network*, and *Detections* pages.
+
+*Example*
+
+To create a template for process-related alerts on a specific host:
+
+* Add an 'ordinary' filter for the host name:
+`host.name: "Linux_stafordshire-061"`
+* Add template filter for process names: `process.name: "{process.name}"`
+
+[role="screenshot"]
+image::images/template-query-example.png[]
+
+When alerts generated by rules associated with this template are investigated
+in Timeline, the host name is `Linux_stafordshire-061`, whereas the process name
+value is retrieved from the alert's `process.name` field.
+
+[discrete]
+[[man-templates-ui]]
+=== Manage existing Timeline templates
+
+You can view, duplicate, delete, and create templates from existing Timelines:
+
+. Go to *Security* -> *Timelines*.
+. Click the *Templates* tab.
++
+[role="screenshot"]
+image::images/all-actions-timeline-ui.png[]
+
+. Click the *All actions* icon in the relevant row, and then select the action:
+
+* _Create timeline from template_
+* _Duplicate template_
+* _Delete template_
+
+TIP: To perform the same action on multiple templates, select templates and
+then the required action from the _Bulk actions_ menu.
+
+NOTE: You cannot delete prebuilt templates.
+
+[discrete]
+=== Export and import Timeline templates
+
+You can import and export Timeline templates, which enables importing templates
+from one {kib} space or instance to another. Exported templates are saved in an
+http://ndjson.org[`ndjson`] file.
+
+. Go to *Security* -> *Timelines*.
+. Click the *Templates* tab.
+. To export templates, do one of the following:
+
+* To export one template, click the *All actions* icon in the relevant row and
+then select _Export selected_.
+* To export multiple templates, select all the required templates and then click
+*Bulk actions* -> _Export selected_.
+
+. To import templates, click *Import Timeline* and then select or drap-and-drop
+the template `ndjson` file.
++
+NOTE: Each template object in the file must be represented in a single line.
+Multiple template objects are delimited with newlines.
+
+NOTE: You cannot export prebuilt templates.

docs/siem/timeline/timeline-ui-overview.asciidoc

@@ -0,0 +1,165 @@
+[[timelines-ui]]
+[role="xpack"]
+= Investigating events in Timeline
+
+Use Timeline as your workspace for investigations and threat hunting.
+Data from multiple indices can be added to a Timeline, which enables
+investigating complex threats.
+
+You can drag or send items of interest to Timeline to create the query you need
+to investigate an alert or event. You can add items from tables and histograms
+on the *Overview*, *Detections*, *Hosts* and *Network* pages, as well as from
+within a Timeline itself. Additionally, you can add a query directly in Timeline
+(click `+ Add field`).
+
+[role="screenshot"]
+image::images/timeline-ui.png[]
+
+Timelines are responsive, and they persist as you move through the {es-sec-app}
+collecting data. Auto-saving ensures that the results of your investigation are
+available for review by other analysts and incident response teams. To record
+and share your findings with others, attach your Timeline to a
+<<cases-overview, case>>.
+
+TIP: An untitled Timeline is saved as a draft. To attach a Timeline to a
+<<cases-overview, case>>, you must give it a title.
+
+In addition to Timelines, you can create and attach Timeline templates to
+<<detection-engine-overview, detection rules>>. Timeline templates allow you to
+define the source event fields used when you investigate a detections alert in
+Timeline. You can select whether the fields use predefined values or values
+retrieved from the alert. For more information, see <<timeline-templates-ui>>.
+
+
+[discrete]
+[[refine-timeline-results]]
+== View and refine Timeline results
+
+Using the drop-down options
+by the KQL bar, you can select whether <<det-engine-terminology, alerts>>,
+other raw events, or both are displayed in the Timeline.
+
+[discrete]
+[[conf-timeline-display]]
+== Configure Timeline event context and display
+
+Many events in Timeline are presented in easy-to-follow rendered views that
+include relevant contextual information. These views are called
+*Event Renderers*, and they can be configured via the Settings icon in the upper
+left corner of the result's pane:
+
+[role="screenshot"]
+image::images/timeline-ui-renderer.png[]
+
+The example above displays a flow event renderer. If you see a particular item
+that interests you, you can drag it to the dropzone for further investigation.
+
+Other display options include:
+
+* View in full screen mode
+* Add, remove, reorder, and resize columns
+* Add notes to individual events
+* Add investigation notes for the entire Timeline
+* Pin interesting events in the Timeline
+
+[discrete]
+[[narrow-expand]]
+== Narrow or expand your query
+
+You can specify logical `AND` and `OR` operations with an item's placement in
+the drop area. Multiple horizontal filters use `AND` logic, vertical filters use
+`OR`.
+
+[discrete]
+[[pivot]]
+== Edit existing filters
+
+Click a filter to access additional operations such as exclude, temporarily
+disable, or delete items from the query:
+
+[role="screenshot"]
+image::images/timeline-ui-filter-options.png[width=30%]
+
+This is how the filters appear in the UI:
+
+Field with value::
+Filters for events with the specified field value:
++
+[role="screenshot"]
+image::images/timeline-filter-value.png[width=30%]
+
+Field exists::
+Filters for events containing the specified field:
++
+[role="screenshot"]
+image::images/timeline-field-exists.png[width=30%]
+
+Exclude results::
+Filters for events that do not contain the specified field value
+(`field with value` filter) or the specified field (`field exists` filter):
++
+[role="screenshot"]
+image::images/timeline-filter-exclude.png[width=30%]
+
+Temporarily disable::
+The filter is not used in the query until it is enabled again:
++
+[role="screenshot"]
+image::images/timeline-disable-filter.png[width=30%]
+
+Filter for field present::
+Converts a `field with value` filter to a `field exists` filter.
+
+NOTE: When you convert a <<timeline-templates-ui, Timeline template>> to a
+Timeline, some fields may be disabled. For more information, see
+<<template-legend-ui>>.
+
+[discrete]
+[[timeline-to-cases-ui]]
+== Attach Timeline to a case
+
+To attach a Timeline to a new or existing case, click the Settings in the upper
+right corner, and then select one of these:
+
+* _Attach timeline to new case_
+* _Attach timeline to existing case_
+
+For more information about cases, see <<cases-overview, Cases>>.
+
+[discrete]
+[[manage-timelines-ui]]
+== Manage existing Timelines
+
+You can view, duplicate, delete, and create templates from existing Timelines:
+
+. Go to *Security* -> *Timelines*.
+. Click the *All actions* icon in the relevant row, and then select the action:
+
+* _Create template from timeline_ (see <<timeline-templates-ui>>)
+* _Duplicate timeline_
+* _Delete timeline_
+
+TIP: To perform the same action on multiple Timelines, select Timelines and
+then the required action from the _Bulk actions_ menu. 
+
+[discrete]
+[[import-export-timelines]]
+== Export and import Timelines
+
+You can import and export Timelines, which enables importing Timelines from one
+{kib} space or instance to another. Exported Timelines are saved in an
+http://ndjson.org[`ndjson`] file.
+
+. Go to *Security* -> *Timelines*.
+. To export Timelines, do one of the following:
+
+* To export one Timeline, click the *All actions* icon in the relevant row and
+then select _Export selected_.
+* To export multiple Timelines, select all the required Timelines and then click
+*Bulk actions* -> _Export selected_.
+
+. To import Timelines, click *Import Timeline* and then select or drap-and-drop
+the Timeline `ndjson` file.
++
+NOTE: Each Timeline object in the file must be represented in a single line.
+Multiple Timeline objects are delimited with newlines.