[DOCS] Adds documentation for drilldowns

docs/drilldowns/drilldowns.asciidoc

@@ -0,0 +1,103 @@
+[[drilldowns]]
+== Use drilldowns for dashboard actions
+
+Drilldowns, also known as custom actions, allow you to configure a
+workflow for analyzing and troubleshooting your data.
+Using a drilldown, you can navigate from one dashboard to another,
+taking the current time range, filters, and other parameters with you.
+Although the destination dashboard shows the data in a different structure,
+the context is the same. You can continue your investigation from a new perspective.
+
+For example, you might have a dashboard that shows the overall status of multiple data centers.
+You can create a drilldown that navigates from this dashboard to a dashboard
+that shows a specific data center or server.
+
+[float]
+[[how-drilldowns-work]]
+=== How drilldowns work
+
+Drilldowns are Kibana actions configured by the user and stored
+in the dashboard saved object. Drilldowns are specific to the dashboard panel
+for which they are created—they are not shared across panels.
+A panel can have multiple drilldowns.
+
+This example shows a dashboard panel that contains a pie chart.
+Typically, clicking a pie slice applies the current filter.
+When a panel has a drilldown, clicking a pie slice opens a menu with
+the default action and your drilldowns. See the <<drilldowns-example, Try it section>> of this doc
+for instructions on how to create this drilldown.
+
+[role="screenshot"]
+image::images/drilldown_on_piechart.png[Drilldown on pie chart that navigates to another dashboard]
+
+Third-party developers can create drilldowns.
+See https://github.com/elastic/kibana/tree/master/x-pack/examples/ui_actions_enhanced_examples[this example plugin]
+to learn how to code drilldowns.
+
+[float]
+[[create-manage-drilldowns]]
+=== Create and manage drilldowns
+
+To create and manage drilldowns, your dashboard must be in *Edit* mode.
+The panel menu will then include a *Create drilldown* action.
+Once a panel has at least one drilldown, the menu also includes a *Manage drilldowns* action
+for editing and deleting drilldowns.
+
+[role="screenshot"]
+image::images/drilldown_menu.png[Panel menu with Create drilldown and Manage drilldown actions]
+
+[float]
+[[drilldowns-example]]
+=== Try it: Create a drilldown
+
+This example shows how to create the drilldown shown previously in this doc.
+
+[float]
+==== Set up the dashboards
+
+. Add the <<get-data-in, sample web logs>> data set.
+
+. Create a new dashboard, called *Host Overview*, and include these visualizations
+from the sample data set:
++
+[%hardbreaks]
+*[Logs] Heatmap*
+*[Logs] Visitors by OS*
+*[Logs] Host, Visits, and Bytes Table*
+*[Logs] Total Requests and Bytes*
++
+TIP: If you don’t see data for a panel, try changing the time range.
+
+. Open the prebuilt *[Logs] Web traffic* dashboard.
+
+. Set a search and filter.
++
+[%hardbreaks]
+Search: `extension.keyword:( “gz” or “css” or “deb”)`
+Filter: `geo.src : CN`
+
+[float]
+==== Create the drilldown
+
+
+. In the dashboard menu bar, click *Edit*.
+
+. In *[Logs] Visitors by OS*, open the panel menu, and then select *Create drilldown*.
+
+. Give the drilldown a name.
+
+. Select *Host Overview* as the destination dashboard.
+
+. Keep both filters enabled so that the drilldown carries over the global filters and date range.
++
+[role="screenshot"]
+image::images/drilldown_create.png[Create drilldown with entries for drilldown name and destination]
+
+. Save the dashboard.
++
+If you don’t save the drilldown, and then navigate away, the drilldown is lost.
+
+. In *[Logs] Visitors by OS*, click the “win 8” slice of the pie, and then click the name of your drilldown.
++
+You are navigated to your destination dashboard. Verify that the search query, filters,
+and time range are carried over.

docs/user/dashboard.asciidoc

@@ -186,3 +186,5 @@ tools. To create a short URL, you must have write access to {kib}.
 
 To export the dashboard, go to *Management > Saved Objects*. For more information,
 see <<managing-saved-objects, Managing saved objects>>.
+
+include::{kib-repo-dir}/drilldowns/drilldowns.asciidoc[]