Navigation
This documentation refers to the on-premises edition of MongoDB Charts. Read the Atlas service documentation to learn how to use MongoDB Charts with your Atlas project.

Embed Charts in Your Web Application

Overview

As a dashboard Author, you can enable embedding on your charts, allowing your visualizations to be embedded in external web sites. You can either require a verified signature to accompany each data request, or allow anyone with the chart’s identifying information to embed it in a web page.

Note

To view an embedded chart you must have network access to the MongoDB Charts server. If your on-premises deployment is behind a firewall, you may not be able to view embedded charts.

How to Choose an Access Level

If you want strict control over who can embed your charts, use the Verified Signature Required option. If your data is non-sensitive and you prefer a simpler embedding solution, use the Unauthenticated Access option.

Note

You can enable chart embedding with the verified signature required option even if you don’t currently have an embedding key, but you’ll need a key to generate a verified signature. If you have the UserAdmin role, you can generate an embedding key on the Admin Settings page. Otherwise, you must contact a UserAdmin and ask for an embedding key.

Procedure

1

Select a dashboard.

From your dashboard tab, select the dashboard containing the chart you wish to make embeddable.

2

Select a chart.

From the dashboard, click the ellipsis () button at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable embedding on the data source

If you have already enabled embedding on the data source this chart uses, you can skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Enable embedding options link.

4

Select the Unauthenticated tab in the dialog window.

Embed unauthenticated chart
5

Toggle the switch marked Enable unauthenticated access to On.

The HTML code necessary to embed the chart appears in the modal window. This HTML snippet is ready to copy and paste into an external web page.

Embed unauthenticated chart
1

Select a dashboard.

From your dashboard tab, select the dashboard containing the chart you wish to make embeddable.

2

Select a chart.

From the dashboard, click the ellipsis () button at the top-right of the chart to access its embedding information. Select Embed Chart from the dropdown menu.

3

Enable embedding on the data source

If you have already enabled embedding on the data source this chart uses, you can skip this step. If you haven’t yet enabled embedding on the data source, you can do so now. Click the Enable embedding options link.

4

Select the Verified Signature tab in the dialog window.

Embed unauthenticated chart
5

Toggle the switch marked Enable signed authentication access to On.

The HTML code which appears in the modal window shows the parameters which are required to embed a chart with authentication enabled, but it is not usable as-is. Continue with the subsequent steps to enable authenticated access.

6

Go to Admin Settings to acquire an embedding key.

Click the Admin Settings link below the HTML code snippet in the modal window.

Note

You must be a Charts UserAdmin to access the Admin Settings page. For UserAdmins, the Admin Settings link appears in the top right corner of the charts UI. As a non-admin user, you can still use embedded charts, but you will need to ask a UserAdmin for a key.

7

Generate an embedding key.

Click the Generate New Key button to create a new embedding key. Store the key in a safe place.

Warning

If you generate a new key, any previous keys become invalid. Ensure that all the existing embedded charts that use the old key are updated to use the new key.

8

Create the server-side code necessary for a verified signature.

Generating a verified signature to accompany data requests from embedded charts with authentication enabled requires server-side code. The verified signature creates a payload by generating a HMAC from your embedding key, a timestamp, and identifying data from your chart. The verified signature is valid for a limited time period specified in your server-side code.

Code examples demonstrating how to generate a verified signature are available for the following languages and platforms:

Embedded Charts Error Codes

If an embedded chart fails to render, an error code is displayed:

Error Code Error Cause
-1 Unknown error.
1 Invalid tenant ID. Check the tenant field in the iframe HTML and make sure it matches what you see in the Embed Chart modal window.
2 Item not found. Check the id field in the iframe HTML and make sure it matches what you see in the Embed Chart modal window.
3 Embedding not enabled. Check the settings in your chart’s Embed Chart modal window.
4 Embedding not allowed. Check the embedding settings in your chart’s data source.
5 Invalid payload. Your application server is not creating a usable signature.
6 Invalid autorefresh value specified. The autorefresh value must be an integer greater than 0.
7 Filter not allowed. A filter parameter was specified for a chart using anonymous embedding. Filters can only be used with verified signatures.
8 Filter not valid. A filter parameter contains an invalid value.