Schedule reports

A scheduled report is a report that runs on a scheduled interval, and which can trigger an action each time it runs. There are two actions available for scheduled reports: Send email and Run a script.

You can schedule reports and define their report actions two ways:

• You can use the Edit Schedule dialog
• You can open a report in Settings and define a schedule for it

Restrictions on report scheduling

You can only create scheduled reports if your role includes the schedule_search capability. See About defining roles with capabilities, in the Securing Splunk Enterprise Manual.

Open the Edit Schedule dialog

There are three ways to open the Edit Schedule dialog.

The Edit Schedule dialog is divided into two parts. In the first part you schedule a report. In the second part, you define the scheduled report actions.

To create or update a scheduled report in Settings, navigate to Settings > Searches, reports, and alerts. See Schedule reports in Settings, in this topic.

After saving a search as a report

Use this method to schedule a report right after you create it.

1. Create a search and run it.
2. Save the search as a report.
   Do not enable a time range picker. Scheduled reports cannot include time range pickers, because they always run on a set schedule.
3. In the Your Report Has Been Created dialog, click Schedule.

See Create and edit reports, in this manual.

From the Reports listing page

Use this method to schedule an existing report.

1. Navigate to the reports listing page.
2. Locate a report that you want to schedule, and expand it.
3. On the Schedule line, click Edit.
   
   

Alternate method:

1. Navigate to the reports listing page.
2. Locate the report that you want to schedule
3. Click Edit for that report and select Edit Schedule.

Schedule a report with the Edit Schedule dialog

You can use the Edit Schedule dialog to define a report schedule for a report.

Scheduled reports cannot include time range pickers. When you schedule a report that includes a time range picker, Splunk software removes the picker from the report.

Scheduled reports can only run as owner. When you schedule a report that has been shared to run as user, Splunk software updates that setting so it runs as owner. See Determine whether to run reports as the report owner or report user.

Prerequisites

Review the following topics.

• Learn how to open the Edit Schedule dialog
• Design a report schedule using standard cron notation.
• Prioritize concurrently scheduled reports in Splunk Web (for more information about the Schedule Priority and Schedule Window settings)

Steps

1. Open the Edit Schedule dialog.
2. Select Schedule Report.
3. Enter the Schedule for the report.
   You can select a predefined Schedule for your report, or you can define a custom schedule using standard cron notation.
4. Enter the Time range for the report.
   Time range is the time range for which the report collects data. It defaults to the time range that you have set for the report. Specify a new time range to override the default.
5. (Optional) Select a Schedule Priority for the report.
   Use Schedule Priority to raise the scheduling priority of this search. Use with discretion. Only roles with the edit_search_schedule_priority capability can see Schedule Priority or set it to a value other than Default.
6. (Optional) Select a Schedule Window for the report to run within.
   When there are many scheduled reports set to run concurrently, you can set Schedule Window to specify how long the report scheduler can defer this report and cause it to yield to higher-importance reports. Only roles with the edit_search_schedule_window capability can see Schedule Window or set it to a value other than No Window.
7. Click Next to define actions for your scheduled report.

See Define actions for your scheduled report.

To create or update a scheduled report in Settings, see Schedule reports in Settings.

Design a report schedule using standard cron notation

You can use standard cron notation to define a custom delivery schedule. When you select the Cron option, a field appears in which you can enter the cron schedule.

Note: Splunk software uses five parameters for cron notation, not six. Splunk software does not use the sixth parameter for year, common in other forms of cron notation.

The following parameters:

(* * * * *)

correspond to:

minute hour day month day-of-week.

Here are some cron examples:

*/5 * * * *       : Every 5 minutes
*/30 * * * *      : Every 30 minutes
0 */12 * * *      : Every 12 hours, on the hour
*/20  * * * 1-5   : Every 20 minutes, Monday through Friday
0 9 1-7 * 1       : First Monday of each month, at 9am.

Define actions for your scheduled report with the Edit Schedule dialog

A scheduled report can perform the following actions each time it runs:

• Send emails with the results to a set of recipients. These emails can provide the report results in text format, or they can include the report results as CSV or PDF attachments.

• Run a script that accesses the report results. Your script can post the results of the report to a external system for further processing or archiving on a regular schedule.

Note: You can use these scheduled report actions to export search results. For a summary of other search result export methods, see Export search results in the Search Manual.

Define a Send Email action

This procedure shows you how to use the Edit Schedule dialog to set up a Send Email action for your scheduled report.

You cannot set up this kind of action without first configuring email notification for your Splunk deployment in Settings. See Email notification action in the Alerting Manual.

1. Enter the Edit Schedule dialog, define the report schedule if necessary, and click Next.

See "Schedule a report," in this topic.

2. Select Send Email to create an email action.

The Edit Email Options dialog opens.

3. Provide a comma-separated list of To email recipients.

4. (Optional) Provide a comma-separated list of CC, and BCC email recipients.

Click Show CC and BCC to see the CC and BCC fields.

5. Set the email Priority.

Enforcement of priority depends on your email client.

6. (Optional) Provide the email Subject and Message.

You can use tokens in email subject and message text to provide a wide variety of information to your users. See Use tokens in scheduled report email subjects and bodies in this topic.

7. (Optional) For Include, select options to include or attach information about the search and its results.

In the email, you can include:

• A link to the related report.
• A link to the results of the run of the report that the email represents.
• The search string for the scheduled report.
• The results of the report run, in the form of an inline table, CSV file, or raw event list.

You can also attach the results of the report run in the form of a CSV file or a PDF. See Include results in scheduled report emails in this topic.

8. (Optional) Change the email Type to Plain Text.

Type is set to HTML & Plain Text by default.

9. Click Save to save your email action settings.

See Run a script in this topic for details on configuring scripts.

If you have Splunk Enterprise, you can also configure report email actions in the alert_actions.conf or savedsearches.conf configuration files. Use alert_actions.conf to configure global properties. Use savedsearches.conf to configure individual reports. See Configure alerts in savedsearches.conf in the Alerting Manual.

For more information about generating and emailing PDF files of report results, see Generate PDFs of your reports and dashboards in this manual.

The following figure shows a scheduled report email with results delivered as text in the body of the email:

Define a Run a Script action

You can specify a script that runs each time a scheduled report runs. This procedure shows you how to use the Edit Schedule dialog to set up a Run a Script action for your scheduled report.

1. Enter the Edit Schedule dialog, define the report schedule if necessary, and click Next.

See "Schedule a report," in this topic.

2. Select Run a Script to create an email action.

The Filename field appears.

3. Provide the Filename of your script.

The script must be at the following location in your Splunk Enterprise instance: $SPLUNK_HOME/bin/scripts

4. Click Save to save your script action settings.

See Run a Script action example, in this topic.

Use tokens in scheduled report email subjects and bodies

A token is a type of variable that represents data generated by a search job. Splunk Enterprise provides various tokens that you can use to include information generated by a search in the fields of an email. For scheduled report delivery, you can use tokens in the following fields of an email:

• Subject
• Message
• Footer

Access the value of a token with the following syntax:

$<token-name>$

For example, place the following token in the subject field of a scheduled report delivery to reference the app containing the report.

Search results from $app$

Tokens available for email notifications

This section lists common tokens you can use in scheduled email delivery of reports. There are four categories of tokens that access data generated from a search. The context for using the tokens differ.

The following table lists all categories of tokens. Tokens from all categories are available for scheduling report delivery.

Category	Description	Context
Search metadata	Information about the search.	Scheduled PDF delivery of dashboards Alert actions from search Scheduled reports
Server information	Information about the Splunk Enterprise server	Scheduled PDF delivery of dashboards Alert actions from search Scheduled reports
Search results	Access results of a search	Alert actions from search Scheduled reports
Job information	Data specific to a search job	Alert actions from search Scheduled reports

In addition to the common tokens listed in this topic, the savedsearches.conf and alert_actions.conf files list attributes whose values are available from tokens. To access these additional attribute values, place the attribute between the $ token delimiters.

Tokens that access search metadata

Common tokens that access information about a search. These tokens are available from the following contexts:

• Alert actions
• Scheduled reports
• Scheduled PDF delivery of dashboards

Here are some of the common tokens available.

Token	Description
$action.email.hostname$	Hostname of the email server.
$action.email.priority$	Priority of the search.
$app$	Name of the app containing the search.
$cron_schedule$	Cron schedule for the app.
$description$	Description of the search.
$name$	Name of the search.
$next_scheduled_time$	The next time the search runs.
$owner$	Owner of the search.
$results_link$	(Alert actions and scheduled reports only) Link to the search results.
$search$	The actual search.
$trigger_date$	(Alert actions only) The date that triggers the alert.
$trigger_time$	(Alert actions only) The scheduled time the alert runs.
$type$	Indicates if the search is from an alert, report, view, or the search command.
$view_link$	Link to view the saved report.
$alert.severity$	Severity level of the alert.
$alert.expires$	Time the alert expires.

Tokens available from results

From results, you use the result.<fieldname> token to access the first value of a specified field in search results. This token is available from the following contexts:

• Alert actions
• Scheduled reports

Token	Description
$result.fieldname$	Returns the first value for the specified field name from the first result in the search. The field name must be present in the search.

Tokens that access job information

Common tokens that access data specific to a search job, such as the search ID or messages generated by the search job. These tokens are available from the following contexts:

• Alert actions
• Scheduled reports

Token	Description
$job.earliestTime$	Initial time a search job starts.
$job.eventSearch$	Subset of the search that contains the part of the search before any transforming commands.
$job.latestTime$	Latest time recorded for the search job.
$job.messages$	List of error and debug messages generated by the search job.
$job.resultCount$	Number of results returned by the search job.
$job.runDuration$	Time, in seconds, that the search took to complete.
$job.sid$	Search ID.
$job.label$	Name given to the search job.

Tokens available from server

Common tokens that provide details about your Splunk deployment. These tokens are available for the scheduled PDF delivery of dashboards.

The following table lists some of the common tokens that are available.

Token	Description
$server.build$	Build number of the Splunk software.
$server.serverName$	Server name hosting the Splunk deployment.
$server.version$	Version number of the Splunk deployment.

Deprecated email notification tokens

The following tokens from prior releases of Splunk software are deprecated.

Token	Description
$results.count$	(Deprecated) Use $job.resultCount$.
$results.url$	(Deprecated) Use $results_link$.
$results.file$	(Deprecated) No equivalent available.
$search_id$	(Deprecated) Use $job.id$.

Run a Script action example

You can set up a Run a Script action that sends results of the report to an external system each time it runs. It does this by running a script that calls an API that sends the report results to the external system.

For security reasons, place all scripts in either of the following locations of your Splunk Enterprise instance:

$SPLUNK_HOME/bin/scripts

$SPLUNK_HOME/etc/<AppName>/bin/scripts

You can also configure running a scheduled report script with a shell script or batch file. Make this configuration in the savedsearches.conf configuration file. See Configure scripted alerts in the Alerting Manual.

If you are having trouble with your scheduled report scripts, check out this excellent topic on troubleshooting alert scripts on the Splunk Community Wiki.

For more information about the Run a script alert action, see Set up alert actions in the Alerting Manual.

Schedule a report in Settings

You can schedule reports through the Searches, Reports, and Alerts page in Settings.

Scheduled reports cannot include time range pickers. When you schedule a report that includes a time range picker, Splunk software removes the picker from the report.

Scheduled reports can only run as owner. When you schedule a report that has been shared to run as user, Splunk software updates that setting so it runs as owner. See Determine whether to run reports as the report owner or report user.

Prerequisites

Review the following topics.

• Design a report schedule using standard cron notation
• Prioritize concurrently scheduled reports in Splunk Web (for more information about the Schedule Priority and Schedule Window settings)
• Define actions for your scheduled report
• Create scheduled real-time reports for dashboards
• Use summary indexing for increased reporting efficiency in the Knowledge Manager Manual.

Steps

1. Open Settings and select the Searches, reports, and alerts link.
2. Click the name of a report that you want to schedule.
3. On the report detail page, select Schedule this search to open up the scheduling and alerting options for the report.
4. Select a Schedule type.
   

   Option	Description
   Basic	Lets you select a preset schedule period from a list, such as Run every 5 minutes or Run every day at midnight.
   Cron	Lets you define a custom schedule period using standard cron notation.

5. (Optional) Select a Schedule Window for the report to run within.
   When there are many scheduled reports set to run concurrently, you can set Schedule Window to specify how long the report scheduler can defer this report and cause it to yield to higher-priority reports. Only roles with the edit_search_schedule_window capability can see Schedule Window or set it to a value other than No Window.
6. (Optional) Select a Schedule Priority for the report.
   Use Schedule Priority to raise the scheduling priority of this search. Use with discretion. Only roles with the edit_search_schedule_priority capability can see Schedule Priority or set it to a value other than Default.
7. To make the report behave like a report that has been scheduled with the Edit Schedule dialog, set the alert Condition to Always.
   This ensures that the alert actions you define are performed each time Splunk Enterprise runs the report.
8. Set Alert mode to Once per search.
   Do not activate Throttling for scheduled reports. Do not set Expiration and Severity for scheduled reports.
9. (Optional) Define the alert actions required for your scheduled report. Do not define alert actions for a scheduled report that runs in real-time.
10. (Optional) Select Summary Indexing if you want the scheduled search to populate data into a summary index.
    See the documentation of the summary indexing functionality to learn more about these settings. You do not need to set up summary indexing for searches that already benefit from report acceleration.
11. Click Save to save your changes.

Create scheduled real-time reports for dashboards

Use scheduled real-time reports when you want your dashboards to display incoming data in real time. You can create scheduled real-time reports in Settings.

When you use unscheduled real-time reports for dashboard panels, they relaunch each time the dashboard is loaded by a user. If several users load the same dashboard you can quickly reach the real-time concurrent search limit for your Splunk implementation. After you reach this limit, you cannot launch more real-time reports.

Manage this by backing dashboard panels with scheduled real-time searches. Scheduled real-time reports begin running when you create them. When a user loads a dashboard with panels that use scheduled real-time searches, those panels just display the results of the real-time reports already in progress. New real-time reports are not launched.

See Add panels to dashboards in Dashboards and Visualizations.

Enable others to access a scheduled report

If you have a role that gives you write access to the knowledge objects in your app (such as the Power or Admin roles), you can set or change the report permissions so it is available to other Splunk users at an app or global level. See Set report permissions, in this manual.

For more information about managing permissions for Splunk knowledge objects, read Manage knowledge object permissions in the Knowledge Manager Manual.

Manage the priority of concurrently scheduled reports

Depending on how you configure your Splunk deployment, you might be able to run only one scheduled report at a time. Under this restriction, when you schedule multiple reports to run at approximately the same time, the Splunk search scheduler works to ensure that all of your scheduled reports get run consecutively for the period of time over which they are supposed to gather data. However, there are cases where you may need to have certain reports run ahead of others in order to ensure that current data is obtained, or to ensure that gaps in data collection do not occur (depending on your needs).

You can configure the priority of scheduled reports through edits to savedsearches.conf. For more information about this feature, see Configure the priority of scheduled reports in this manual.