Reporting Manual

 


Embed scheduled reports

Embed scheduled reports

Report embedding lets you bring the results of your reports to large numbers of report stakeholders. With report embedding, you can embed scheduled reports in external (non-Splunk) websites, dashboards, and portals. Embedded reports can display results in the form of event views, tables, charts, maps, single values, or any other visualization type. They use the same formatting as the originating report.

Note: You can't embed a report until it is scheduled to run on a regular interval. An embedded report always displays the results from its last scheduled run. So if an embedded report is set up to run every four hours over the past 24 hours, it will always display results for a previous 24 hour period that were obtained within the last four hours. This design reduces load on your Splunk Enterprise instance. This also means that newly embedded reports are blank until their first scheduled run.

Embedded reports do not have all the features of reports as viewed in Splunk Enterprise. For example, embedded reports do not have drilldown functionality, support for workflow actions, table sorting, or field expansion. Embedded reports also cannot support real-time searches.

In Splunk Enterprise, your ability to embed scheduled reports is tied to the embed_report capability. By default this capability is restricted to the Power User role and any role that inherits it, such as the Admin role. A user without this capability cannot enable or disable embedding for a scheduled report.

Once a report is embedded it cannot be edited. You must disable embedding for a report in order to edit it. See "Embed a report," below, for more information.

Important: Before you embed reports you should set up a string value of your choice for the embedSecret parameter in server.conf. This will ensure that all of your embedded reports will migrate properly to future versions of Splunk Enterprise. See the subsection "Set the embedSecret parameter for upgrade and migration purposes", below.

Embed a report

If you have the capability to embed reports, you will be able to embed any report that you can see on the Reports listing page.

1. Go to the Reports listing page and locate the report that you would like to embed.

Note: Before embedding the report you should run it and adjust its result formatting if necessary. Whatever you define here will dictate how the report will display results after you embed it in an external site. You cannot edit embed-enabled reports.

2. To embed the report, click Edit and select Embed.

Alternatively you can expand the row for the report and click Edit next to 'Embedding.
If the report is not already scheduled, the Report Must Be Scheduled dialog appears. Click Schedule Report to schedule the report. For more information, see "Schedule reports," in this manual.
If the report is already scheduled Splunk Enterprise opens the Enable Report Embedding dialog. It also opens this dialog when you schedule the report after encountering the Report Must Be Scheduled dialog.

3. In the Enable Report Embedding dialog, click Enable Embedding to embed the report.

The Embed dialog appears with a few lines of code that you can paste into an HTML-based web page.

4. Copy the code out of the Embed dialog and paste it into the HTML-based web page into which you want to embed the report.

5. Click Done to close the Embed dialog.

Note: A newly embedded report will not show data or visualizations until its first scheduled run. So if your report is scheduled to run every hour and you embed the report halfway through an hour, you'll have to wait for approximately 30 minutes before it displays anything.

After you embed a report, you can get its embedding code from the Embed dialog whenever you want. There are two ways to open the Embed dialog and get the code. Start by going to the Reports listing page and then:

  • Click Edit for the embed-enabled report and select Embed.
  • Expand the report's row and click Edit on the "Embedding" line.

You can embed a single report in multiple web pages. It will use the same display formatting as the originating report wherever it appears.

Disable report embedding

There are two reasons you might want to disable embedding for a report:

  • You want to edit the report (update its search string or display formatting). Embedded reports cannot be edited.
    • If you disable embedding for a report, edit it, and then enable embedding for it again, you will have to wait until the report runs on its schedule to see your changes reflected in the external website(s) in which the report is embedded.
  • You want to revoke access to the report via the external website(s) in which it is embedded. .

To disable a report, open the Embed dialog for the report and click Disable embedding.

Configure embedded report functionality

Report embedding can work for users who have the embed_reports capability associated with their role without any additional .conf file configuration. However, there are a few configuration settings that Splunk Enterprise administrators should be aware of. The most important of these is embedSecret, which should be defined in server.conf before you start embedding reports.

Set the embedSecret parameter for upgrade and migration purposes

Important: This setting is not required for the current version of Splunk Enteprise (6.1.x). It is required for upgrade to the next major release (6.2 or higher) if you have already set up embedded reports. Ideally you should define an embedSecret value before you embed any reports. Any embedded reports that you set up before you define an embedSecret value may be broken by the upgrade process, meaning that they will fail to display in the sites in which they are embedded.

When you embed reports, the URLs that are generated to point to the reports in your Splunk Enterprise instance normally can only be used on the search head on which they were generated. If you set a string value for the embedSecret parameter in server.conf all search heads in a search head pool can use the same URL.

You can set any string value for embedSecret. Think of it as a sort of password. The embedSecret parameter has no value by default.

Bypass SSO authentication if necessary

When Splunk Enterprise embeds a report in an external web page, it makes several HTTP requests to various resources that in some cases may invoke the SSO authentication system. To get around this, you can update the embed_uri parameter in web.conf with an alternative URI IP address, host, or port prefix. This hardcodes the path so it always goes through an externally accessible IP address or host name.

Note: If you have set an explicit value for the root_endpoint parameter in web.conf you will need to append the root_endpoint value to whatever you define for embed_uri.

For example if you've set

root_endpoint = /splunkui

and you want to set embed_uri to http://foobar:8088, then you'll need to append the root_endpoint value to it like this:

embed_uri = http://foobar:8088/splunkui

By default the embed_uri parameter is empty. It will resolve to the client browser window.location.protocol + "//" + window.location.host.

Change the footer beneath the embedded report

By default embedded reports will display a footer that includes the Splunk logo. You can change this to a text string if you'd like. Go to the embed_footer parameter in web.conf and enter a different string. You can't use HTML markup.

While the default setting of embed_footer = splunk> displays the Splunk logo as the footer, you can't use this parameter to insert alternative icons or images.

Disable report embedding globally

You can disable report embedding for all users of a particular Splunk Enterprise instance. In server.conf, change the value of the allowEmbedTokenAuth parameter from true to false.

The embed.enabled parameter

The saved searches endpoint adds the embed.enabled parameter to scheduled report stanzas in savedsearches.conf when those reports are embedded. The embed.enabled parameter determines whether or not a given report is enabled for embedding. It is set to 1 if it is enabled.

This documentation applies to the following versions of Splunk: 6.1 , 6.1.1 , 6.1.2 , 6.1.3 , 6.1.4 , 6.1.5 , 6.2.0 , 6.2.1 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!