Embedding report widgets in external web sites

Last updated: Mon Feb 04 23:45:56 GMT 2019

Whether running a network operations center or a service status page, customers may wish to embed a Reports widget on an external web page. The embedded widget can then provide the same information via the external web page that would otherwise require a ThousandEyes login.

What is an Embedded Widget?

An embedded widget is a link to a Reports widget that that you can use in the HTML source code of a web page.  An embedded widget will show the original Reports widget's content, allowing users to interact with the content using mouse-over to display detailed series values. The content of the widgets will automatically update as new data becomes available.

The HTML code to create an Embedded widget is automatically generated by the ThousandEyes platform, allowing users to copy and paste into their page's HTML source code.

Update frequency

The embedded widget updates data automatically every 5 minutes - there's no need to refresh the page containing the widget.  Each data point in the widget is the average of source data points in a time range from the source (test data, alert data, etc...).  The time range of source data points per widget data point depends on the total number of days of data shown in the widget. 

Days of dataWidget point containsEmbedded Widget Updates every
< 1 day5 mins of data5 mins
1-14d1 hour of data5 mins
14-30d2 hours of data5 mins
30-50d4 hours of data5 mins
50-90d6 hours of data5 mins

For example, with an HTTP Server test as the source of data, and a Report widget displaying 12 hours of test data, each embedded widget data point will be the average of 5 minutes of test data.  If the frequency of the test is 2 minutes, each embedded widget data point will be the average of either 2 or 3 test data points.

Creating the embedded widget source code

To create the HTML code for an embedded widget, select a report widget in a report, and click the menu on the upper right corner of the widget. Then select the Embed Widget option from the menu that pops up.

107855293-1_widget_menu.png

Before you create the HTML code for an embedded widget, you'll need to check a box that acknowledges that anybody can embed this code in an external site.  Embedded widgets are managed using a unique, randomly generated key, similar to how we handle share links.  Any user who possesses the code with the link to the widget can access the data -- there are no IP address restrictions, and access does not require authentication.  It is important that users understand the impact of making their data available outside of the system before accepting these risks.

Screen_Shot_2016-02-07_at_2.02.03_PM.png

Once you accept the option, you'll be shown a dialog that lists the content used by the embedded widgets.

embeddings.png

  1. Widget code: The HTML iframe code to embed this content in an external site.
  2. Data range: Change the data range displayed in the embedded widget to be different from the source widget's range. You can show as much as 90 days of data or as little as 1 hour of data.  Keep in mind that the widget self-updates as new data is available, so this accounts for a rolling number of days/hours of data for the tests configured in the widget.
  3. Preview widget: A preview of the embedded widget is shown.

 

Inserting embedded widget code into a web page

The ThousandEyes platform provides an iframe code snippet which can be inserted into the source code of a web page.  This iframe is configured to use 100% of both the height and width of the parent container. The iframe is typically inserted into a an HTML div element of a page.  

Each widget will contain a header line, which contains the widget name, and the ThousandEyes logo.  This header is 75px in height, and is only shown once per widget.

Screen_Shot_2016-03-28_at_5.40.46_PM.png

If you have groupings defined (for example, one pie chart per continent), then you may have multiple charts to render, which will increase the minimum height of a particular widget.

Recommended minimum container sizing is as follows:

  • Number widgets
    • Width: 300px per card
    • Height: 200 pixels per row of cards
  • Table widgets
    • Width: 450px
    • Height: dependent on the number of rows included in the table
  • Time series and Stacked Area Time Series widgets
    • Width: As wide as possible.  The x-axis scales with the widget width, so a wider time series chart makes for an easier-to-read chart.
    • Height: 225px per chart, plus the header
  • Bar and Column Chart widgets
    • The chart sizes for bar charts will vary based on the orientation of data.  Irrespective of the type of chart chosen, the chart will scale to the width allowed by the container.  You can have a small available area with smaller columns, or a wider area, which will impact the size of the columns.
  • Screen_Shot_2016-03-28_at_5.28.44_PM.pngScreen_Shot_2016-03-28_at_5.29.54_PM.png
    • For bar charts (horizontal orientation)
      • Width: 610px
      • Height: 370px
    • For column charts (vertical orientation)
      • Width: 610px
      • Height: varies based on number of data series and groupings. In general, at least 600px is recommended.
  • Pie charts
    • Width: the amount of available width controls how many pie charts get placed on each row.  For each 505px of width, a pie chart will be placed in the available area.  (1010px, 2 pie charts will be shown in each row)
    • Height:
      • 75px for header
      • 68px for legend
      • 300px per row of pie charts

Managing embedded widgets

Users can manage embedded widgets by from the Sharing > Embedded Widgets page.  Expand an entry on the page to show the Embed management.  Users with appropriate permissions can remove access to the embedded widget by unchecking the "Allow anyone to embed this widget onto external sites." checkbox, and can change the length of time shown.

Permissions

To create embedded widgets, users must have the following permission assigned to their role(s):

  • "Embed own widgets" will allow users to create embedded widgets from their own reports
  • "Embed widgets for all users in account group" allows users to create embedded widgets from any report visible to your account group.