Reporting: Update docs (#23993)

docs/sources/enterprise/reporting.md

@@ -39,10 +39,45 @@ Currently only Organization Admins can create reports.
 1. Select the layout option for generated report: **Portrait** or **Landscape**.  
 1. Enter scheduling information. Options vary depending on the frequency you select.
 1. **Save** the report.
+1. **Send test mail** after saving the report to verify that the whole configuration is working as expected.
 
 {{< docs-imagebox img="/img/docs/enterprise/reports_create_new.png" max-width="500px" class="docs-image--no-shadow" >}}
 
-## Send test mail
+### Scheduling
+
+Scheduled reports can be sent on a weekly, daily, or hourly basis. You may also disable scheduling for when you either want to pause a report or send it via the API.
+
+All scheduling indicates when the reporting service will start rendering the dashboard. It can take a few minutes to render a dashboard with a lot of panels.
+
+#### Hourly
+
+Hourly reports are generated once per hour. All fields are required.
+
+* **At minute -** The number of minutes after full hour when the report should be generated.
+* **Time zone -** Time zone to determine the offset of the full hour. Does not currently change the time in the rendered report. 
+
+#### Daily
+
+Daily reports are generated once per day. All fields are required.
+
+* **Time -** Time of day in 24 hours format when the report should be sent.
+* **Time zone -** Time zone for the **Time** field.
+
+#### Weekly
+
+Weekly reports are generated once per week. All fields are required.
+
+* **Day -** Weekday which the report should be sent on.
+* **Time -** Time of day in 24 hours format when the report should be sent.
+* **Time zone -** Time zone for the **Time** field.
+
+#### Never
+
+> Only available in Grafana Enterprise v7.0+.
+
+Reports which are scheduled to never be sent have no parameter and will not be sent to the scheduler. They may be manually generated from the **Send test email** prompt or via the API.
+
+### Send test mail
 
 > Only available in Grafana Enterprise v7.0+.
 
@@ -55,9 +90,17 @@ The last saved version of the report will be sent to selected emails. You can us
 
 {{< docs-imagebox img="/img/docs/enterprise/reports_send_test_mail.png" max-width="500px" class="docs-image--no-shadow" >}}
 
+## Send report via the API
+
+You can send reports programmatically with the [send report]({{< relref "../http_api/reporting.md#send-report" >}}) endpoint in the [HTTP APIs]({{< relref "../http_api" >}}).
+
 ## Rendering configuration
 
-When Grafana generates a report, it will render each panel separately and then put them together in a PDF file. You can configure the per-panel rendering request timeout and the maximum number of concurrent calls to the rendering service. These options are available in the [configuration]({{< relref "../installation/configuration.md">}}) file.
+When generating reports, each panel renders separately before being collected in a PDF. The per panel rendering timeout and number of concurrently rendered panels can be configured.
+
+To modify the panels' clarity you can set a scale factor for the rendered images. A higher scale factor is more legible but will increase the file size of the generated PDF.
+
+ These options are available in the [configuration]({{< relref "../installation/configuration.md">}}) file.
 
 ```ini
 [reporting]
@@ -65,8 +108,19 @@ When Grafana generates a report, it will render each panel separately and then p
 rendering_timeout = 10s
 # Set maximum number of concurrent calls to the rendering service
 concurrent_render_limit = 4
+# Set the scale factor for rendering images. 2 is enough for monitor resolutions
+# 4 would be better for printed material. Setting a higher value affects performance and memory
+image_scale_factor = 2
 ```
 
+## Report time range
+
+Reports use the saved time range of the dashboard. Changing the time range of the report is done by saving a modified time range to the dashboard.
+
+The page header of the report displays the time range for the dashboard's data queries. Dashboards set to use the browser's time zone will use the time zone on the Grafana server.
+
+If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. We advise always setting the time zone to UTC for dashboards when using a remote renderer to avoid this. 
+
 ## Troubleshoot reporting
 
 To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration]({{< relref "../installation/configuration.md#filters" >}}) for more information.

docs/sources/http_api/_index.md

@@ -43,3 +43,4 @@ dashboards, creating users and updating data sources.
 
 * [Data Source Permissions API]({{< relref "datasource_permissions.md" >}})
 * [External Group Sync API]({{< relref "external_group_sync.md" >}})
+* [Reporting API]({{< relref "reporting.md" >}})

docs/sources/http_api/reporting.md

@@ -0,0 +1,70 @@
++++
+title = "Reporting API"
+description = "Grafana Enterprise APIs"
+keywords = ["grafana", "enterprise", "api", "reporting"]
+aliases = ["/docs/grafana/latest/http_api/reporting/"]
+type = "docs"
+[menu.docs]
+name = "Reporting API"
+parent = "http_api"
++++
+
+# Reporting API
+
+This API allows you to interact programmatically with the [Reporting]({{< relref "../enterprise/reporting.md" >}}) feature.
+
+> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../enterprise" >}}).
+
+
+## Send a report
+
+> Only available in Grafana Enterprise v7.0+.
+
+> This API endpoint is experimental and may be deprecated in a future release. On deprecation, a migration strategy will be provided and the endpoint will remain functional until the next major release of Grafana.
+
+`POST /api/reports/email`
+
+Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
+
+### Example request
+
+```http
+POST /api/reports/email HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "id":"3",
+  "useEmailsFromReport": true
+}
+```
+
+### JSON Body Schema
+
+Field name | Data type | Description
+---------- | ---- | -----------
+id | string | ID of the report to send. It is the same as in the URL when editing a report, not to be confused with the ID of the dashboard. Required.
+emails | string | Comma-separated list of emails to which to send the report to. Overrides the emails from the report. Required if **useEmailsFromReport** is not present.
+useEmailsFromReport | boolean | Send the report to the emails specified in the report. Required if **emails** is not present.
+
+### Example response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 29
+
+{"message":"Report was sent"}
+```
+
+### Status Codes
+
+Code | Description
+---- | -----------
+200 | Report was sent.
+400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
+401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}).
+403 | User is authenticated but is not authorized to generate the report.
+404 | Report not found.
+500 | Unexpected error or server misconfiguration. Refer to body and/or server logs for more details.

docs/sources/menu.yaml

@@ -350,6 +350,8 @@
       link: /http_api/playlist/
     - name: Preferences API
       link: /http_api/preferences/
+    - name: Reporting API
+      link: /http_api/reporting/
     - name: Snapshot API
       link: /http_api/snapshot/
     - name: Teams API