[Docs/Reporting] Improve docs on automating Reporting (elastic#40931)

* [Docs/Reporting] Improve docs on automating Reporting * Update docs/reporting/automating-report-generation.asciidoc Co-Authored-By: gchaps <[email protected]> * Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <[email protected]> * Update docs/reporting/script-example.asciidoc Co-Authored-By: gchaps <[email protected]> * --wip-- [skip ci] * word change
tsullivan · Jul 15, 2019 · 05b715c · 05b715c
1 parent 4dcf222
commit 05b715c
Show file tree

Hide file tree

Showing 3 changed files with 101 additions and 31 deletions.
diff --git a/docs/reporting/automating-report-generation.asciidoc b/docs/reporting/automating-report-generation.asciidoc
@@ -4,40 +4,46 @@
 You can automatically generate reports with {watcher}, or by submitting
 HTTP POST requests from a script.
 
-To automatically generate reports with a watch, you need to configure
-{watcher} to trust the {kib} server’s certificate. For more information,
-see <<securing-reporting, Securing Reporting>>.
-
 include::report-intervals.asciidoc[]
 
-To get the URL for triggering a report generation during a given time period:
+[float]
+=== Getting the POST URL
+
+Generating a report either through Watcher or a script requires capturing the **POST
+URL**, which is the URL to queue a report for generation.
+
+To get the URL for triggering PDF report generation during a given time period:
 
-. Load the saved object.
+. Load the saved object in the Visualize editor, or load a Dashboard.
 . Use the timepicker to specify a relative or absolute time period.
 . Click *Share* in the Kibana toolbar.
 . Select *PDF Reports*.
 . Click **Copy POST URL**.
 
-NOTE: The response from this request with be JSON, and will contain a `path` property
-with a URL to use to download the generated report. When requesting that path,
-you will get a 503 response if it's not completed yet. In this case, retry after the
-number of seconds in the `Retry-After` header in the response until the PDF is returned.
+To get the URL for triggering CSV report generation during a given time period:
 
-To configure a watch to email reports, you use the `reporting` attachment type
-in an `email` action. For more information, see
-{stack-ov}/actions-email.html#configuring-email[Configuring Email Accounts].
+. Load a saved search in Discover.
+. Use the timepicker to specify a relative or absolute time period.
+. Click *Share* in the Kibana toolbar.
+. Select *CSV Reports*.
+. Click **Copy POST URL**.
+
+[float]
+=== Using Watcher
 
 include::watch-example.asciidoc[]
 
-For more information about configuring watches, see
-{stack-ov}/how-watcher-works.html[How Watcher Works].
+[float]
+=== Using a Script
 
-== Deprecated Report URLs
+include::script-example.asciidoc[]
 
-The following is deprecated in 6.0, and you should now use {kib} to get the URL for a
-particular report.
+[float]
+== Deprecated Report URLs
 
-You may request PDF reports optimized for printing through three {reporting} endpoints:
+The following POST URL paths were once supported but are now deprecated. If there are
+any problems with using these paths after upgrading Kibana's version, you should use
+{kib} to re-generate the POST URL for a particular report.
 
 * Dashboard Reports:  `/api/reporting/generate/dashboard/<dashboard-id>`
 * Visualization Reports:  `/api/reporting/generate/visualization/<visualization-id>`
@@ -49,11 +55,3 @@ Previously there was a `&sync` parameter appended to generation URLs which would
 the request open until the document was fully generated. This feature has been removed.
 Existing use of the `&sync` parameter, in Watcher for example, will need to be updated.
 ===================
-
-To specify the time period you want to include in the report, you use the `_g`
-parameter in the request. For example:
-
-[source,shell]
----------------------------------------------------------
-http://0.0.0.0:5601/api/reporting/generate/dashboard/error-monitoring?_g=(time:(from:now-1d%2Fd,mode:quick,to:now-1d%2Fd))
----------------------------------------------------------
diff --git a/docs/reporting/script-example.asciidoc b/docs/reporting/script-example.asciidoc
@@ -0,0 +1,60 @@
+To automatically generate reports from a script, you'll make a request to the POST URL.
+The response from this request will be JSON, and will contain a `path` property with a
+URL to use to download the generated report when it is complete.
+
+The request method must be POST and it must include a `kbn-version` header for Kibana
+to allow the request.
+
+The following example queues CSV report generation using the POST URL with cURL:
+
+[source,shell]
+---------------------------------------------------------
+curl \
+-XPOST \ <1>
+-u elastic \ <2>
+-H 'kbn-version: 8.0.0' \ <3>
+'http://0.0.0.0:5601/api/reporting/generate/csv?jobParams=...' <4>
+---------------------------------------------------------
+// CONSOLE
+
+<1> POST method is required.
+<2> Provide user credentials for a user with permission to access Kibana and X-Pack reporting.
+<3> The `kbn-version` header is required for all POST requests to Kibana.
+<4> The POST URL. You can copy and paste the URL for any report from the Kibana UI.
+
+Here is an example response:
+
+[source,json]
+---------------------------------------------------------
+{
+  "path": "/api/reporting/jobs/download/jxzaofkc0ykpf4062305t068", <1>
+  "job": {
+    "id": "jxzaofkc0ykpf4062305t068",
+    "index": ".reporting-2018.11.11",
+    "jobtype": "csv",
+    "created_by": "elastic",
+    "payload": ..., <2>
+    "timeout": 120000,
+    "max_attempts": 3,
+    "priority": 10
+  }
+}
+---------------------------------------------------------
+// CONSOLE
+
+<1> The relative path on the Kibana host for downloading the report.
+<2> (Not included in the example) Internal representation of the reporting job, as
+found in the `.reporting-*` index.
+
+[IMPORTANT]
+===================
+When using the `path` to request the download, you will get a 503 (Service Unavailable)
+response if report generation hasn't completed yet. In that case, retry after the
+number of seconds in the `Retry-After` header in the download API response until the
+report is complete.
+
+If there was an error in generating the report, the download URL will return a 500
+(Internal Server Error) response. More information is available in the
+Reporting management page in Kibana: *Management > Kibana > Reporting*
+===================
+
diff --git a/docs/reporting/watch-example.asciidoc b/docs/reporting/watch-example.asciidoc
@@ -1,5 +1,12 @@
-For example, the following watch generates a report that contains the
-*Error Monitoring* dashboard and emails the report every hour:
+To automatically generate reports with a watch, you need to configure
+{watcher} to trust the {kib} server’s certificate. For more information,
+see <<securing-reporting, Securing Reporting>>.
+
+To configure a watch to email reports, you use the `reporting` attachment type
+in an `email` action. For more information, see
+{stack-ov}/actions-email.html#configuring-email[Configuring Email Accounts].
+
+For example, the following watch generates a PDF report and emails the report every hour:
 
 [source,js]
 ---------------------------------------------------------
@@ -18,7 +25,7 @@ PUT _watcher/watch/error_report
         "attachments" : {
           "error_report.pdf" : {
             "reporting" : {
-              "url": "http://0.0.0.0:5601/api/reporting/generate/dashboard/Error-Monitoring?_g=(time:(from:now-1d%2Fd,mode:quick,to:now))", <2>
+              "url": "http://0.0.0.0:5601/api/reporting/generate/printablePdf?jobParams=...", <2>
               "retries":6, <3>
               "interval":"1s", <4>
               "auth":{ <5>
@@ -40,11 +47,16 @@ PUT _watcher/watch/error_report
 <1> You must configure at least one email account to enable Watcher to send email.
 For more information, see
 {xpack-ref}/actions-email.html#configuring-email[Configuring Email Accounts].
-<2> This is an example Generation URL. You can copy and paste the URL for any
+<2> This is an example POST URL. You can copy and paste the URL for any
 report from the Kibana UI.
 <3> Optional, default is 40
 <4> Optional, default is 15s
 <5> Provide user credentials for a user with permission to access Kibana and
 {reporting}.
 //For more information, see <<secure-reporting>>.
 //<<reporting-app-users, Setting up a Reporting Role>>.
+
+NOTE: Reporting is integrated with Watcher only as an email attachment type.
+
+For more information about configuring watches, see
+{stack-ov}/how-watcher-works.html[How Watcher Works].