Visualization Publishing - Options

👤 This documentation is intended for Site Administrators. For users looking for a non-programatic solution to sharing dashboards externally, refer to the documentation on Shared Dashboards and Scheduled Email Reports.

Note: Visualization Publishing is the updated name for Embeding dashboards and chart in Sisense for Cloud Data Teams.

Note: Whitelabeled Visualization Publishing are an add-on feature. Site administrators can contact their Account Manager for additional information.

<div>
<UL>
<LI><a href="#JSONOptions">JSON Options</a></LI>
<UL>
<LI><a href="#Dashboard">Dashboard</a></LI>
<LI><a href="#Chart">Chart</a></LI>
<LI><a href="#EmbedVersion">Visualization Publishing Version</a></LI>
<LI><a href="#DaterangeFilter">Daterange Filter</a></LI>
<LI><a href="#AggregationFilter">Aggregation Filter</a></LI>
<LI><a href="#CustomFilters">Custom Filters</a></LI>
<LI><a href="#UnusedFilters">Unused Filters</a></LI>
<LI><a href="#VisibleFilters">Visible Filters</a></LI>
<LI><a href="#ChartBorders">Chart Borders</a></LI>
<LI><a href="#DataLatency">Data Latency</a></LI>
<LI><a href="#ExpirationDate">Expiration Date</a></LI>
<LI><a href="#Puttingialltogether">Putting it all Together</a></LI>
</UL>
<LI><a href="#CurlCommands">Curl Commands</a></LI>
<UL>
<LI><a href="#Create">Create</a></LI>
<LI><a href="#List">List</a></LI>
<LI><a href="#Delete">Delete</a></LI>
</UL>
<LI><a href="#PostMessages">Post Messages</a></LI>
<UL>
<LI><a href="#FilterChange">Filter Change</a></LI>
<LI><a href="#EmbedSize">Size</a></LI>
<LI><a href="#Drilldown">Drilldown</a></LI>
<LI><a href="#RefreshTrigger">Refresh Trigger</a></LI>
</UL>
<LI><a href="#LookingforMore">Looking for More?</a></LI>
</UL>
</div>

<HR>

‍

JSON Options

A summary of the Visualization Publishing request can be found on the documentation here. The below options review additional parameters that can be defined in the encoded data JSON blob.

Dashboard

The dashboard number can be found in the dashboard's URL. i.e. if the URL looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name

then the dashboard number is 10, and the JSON blob will say

"dashboard": 10,

Chart

To publish a single chart, the user will include the chart parameter after the dashboard parameter.

The chart number can be found by clicking the hamburger menu of the chart and clicking "Share Link". If the URL from that link looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name/example-chart-name?widget=1234

The chart number is the widget ID. In this example it is 1234 so the JSON blob will say

"dashboard": 10,
"chart":1234,

Published Version

The default embed version is "true." In case the extra padding from the embed should be removed, use embed version "v2":

"embed": "v2"

Note: To remove the "Powered by Sisense for Cloud Data Teams" footer from published dashboards, site administrators must contact their Customer Success Manager for additional information.

Daterange Filter

When using the pre-built daterange filter options or selecting a number of days before the current date, include it using:

"daterange": {"days": 7}

When using a custom range, the user must specify the start and end dates:

"daterange": {"start": "2015-01-01", "end": "2015-01-01"}

When using Current Week, Last Week, or Current Month, use the following syntax:

"daterange": {"unit": "week", "frame": "last"}
"daterange": {"unit": "week", "frame": "current"}
"daterange": { “unit”: “month”, “frame”: “current”}

If the daterange parameter is not included, the dashboard will default to including all dates.

Additional Custom Daterange Filters

When using an additional custom daterange filter option or selecting a number of days before the current date, include it using:

filters: [{"name": "custom_daterange_filter_name", "value": {"days": 60 }}]

Aggregation Filter

To include the dashboard aggregation in the JSON blob, add the following on its own line in the blob:

"aggregation": "daily"

If the aggregation parameter is not included, the dashboard will default to using "daily" as the aggregation period.

Custom Filters

If the user wants to pass custom filters to the Visualization Publishing, include them like so:

"filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}]

If there are multiple filter values to be included for the same filter, there are the options to either include it twice or pass an array:

"filters": [{"name": "Filter1", "value": "1234"}, {"name": "Filter1", "value": "5678"}]
"filters": [{"name": "Filter1", "value": ["1234", "5678"]}]

To include child filters, an additional parameter that specifies the group (parent value) must be included. This will always be equivalent to the value of the parent filter being included:

"filters": [{"name": "ParentFilter", "value": 1234}, {"name": "ChildFilter", "value": "5678", "group": "1234"}]

When using filters in the chart titles, the display value, which is populated into the chart title, must be included. The JSON blob cannot be used with the array syntax to ensure proper parsing:

"filters": [{"name": "Filter1", "value": "1234", "display": "Display1"}]

Unused Filters

If the user is not using a filter, simply omit it from the blob and no value will be passed for it.

Visible Filters

If the filters should be accessible to the end user of the Visualization Publishing, include the filter names in the JSON blob as visible filters. The selected filters must be visible on the underlying dashboard in Sisense as well.

"visible": ["Filter2", "Filter3", "aggregation", "daterange"]

Chart Borders

Turn chart borders off by setting them to off:

"border": "off"

Data Latency

By default Published dashboards will reflect the current state of the in-app dashboard. If there are special requirements around the freshness of the data or if the Published dashboard references different filter combinations than are used in the in-app dashboard, add a time threshold to the request:

"data_ts": 1446069112

The data_ts value is integer seconds since the epoch (Note: millisecond precision is not supported). Charts with data older than this timestamp will show loading and get scheduled to refresh when page loads. Typically, the data_ts parameter should be a dynamic value if the Published dashboard is meant to continuously refresh. These data_ts parameters pull the current epoch time (in seconds) and subtract the desired refresh interval (in seconds). For best results, Sisense recommends a refresh interval no more frequent than every 10 minutes (600 seconds).

Below are a few examples of dynamic data_ts parameters:

Salesforce

data_ts: Math.trunc(new Date().getTime() / 1000) - 600

Ruby on Rails

data_ts: Time.now.getlocal('-07:00').to_i - (10 * 60)

Python 2

import time;
data_ts: time.time()-600

Python 3

import datetime;
data_ts: datetime.datetime.now().timestamp() - 600

Expiration Date

Limit how long the Published dashboard link is valid with

"expires_at": 1456069112

The expires_at value is integer seconds since the epoch. Accessing the Published dashboard after this time will show a message explaining the dashboard has expired.

Add the following parameter to allow viewers of the shared dashboard to continue viewing it past the expiration time. After the expiration time, viewers will not be ejected from viewing the dashboard until they refresh the page or close their browser.

"maintain_sessions_after_expiration": true

Putting It All Together

After each piece is assembled, the final product will look something like this:

{
"dashboard": 7863,
"chart":1234,
"embed": "v2",
"aggregation": "daily",
"daterange": {"start": "2015-01-01", "end": "2015-01-01"},
"filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}],
"visible": ["Filter2", "Filter3", "aggregation", "daterange"],
"border": "off",
"data_ts": 1446069112,
"expires_at": 1456069112
}

Using the method outlined in our Visualization Publishing documentation and the example API key of e179017a-62b0-4996-8a38-e91aa9f1, this JSON would yield the below URL to be Published:

https://www.periscopedata.com/api/embedded_dashboard?data=%7B%22dashboard%22%3A+7863%2C%22chart%22%3A1234%2C%22embed%22%3A+%22v2%22%2C%22aggregation%22%3A+%22daily%22%2C%22daterange%22%3A+%7B%22start%22%3A+%222015-01-01%22%2C+%22end%22%3A+%222015-01-01%22%7D%2C%22filters%22%3A+%5B%7B%22name%22%3A+%22Filter1%22%2C+%22value%22%3A+%22value1%22%7D%2C+%7B%22name%22%3A+%22Filter2%22%2C+%22value%22%3A+%221234%22%7D%5D%2C%22visible%22%3A+%5B%22Filter2%22%2C+%22Filter3%22%2C+%22aggregation%22%2C+%22daterange%22%5D%2C%22border%22%3A+%22off%22%2C%22data_ts%22%3A+1446069112%2C%22expires_at%22%3A+1456069112%7D&signature=64bad6870355f661812557b19f67ab003b2c50757a1b0570bdcf28e9b7ef2663

‍

Curl Commands

There are three API endpoints for creating, listing, and deleting Published dashboard and chart links. For each, the site_name can be found in the dashboard's URL. i.e. if the URL looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name

then the site_name is example-site. The API_KEY can be found in the "Billing and Authentication" section of the gear menu in the bottom left corner.

Create

The create command allows creation of a shared dashboard link via API. The JSON format for filters in the create API is the same as the API for Published dashboards laid out above.

curl https://app.periscopedata.com/api/v1/shared_dashboard/create --data-binary '{"dashboard":1000,"filters":[{"name":"Site","value":41,"display":"US"}]}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

Once the shared dashboard link has been created, additional Visualization Publishing options, such as the data_ts and expires_at parameters, must then be appended to the end of the generated url following a '?'. For example:

https://app.periscopedata.com/shared/abcdefgh123456?embed=v2&border=off&data_ts=1521674700

List

The list command will return a list of open shared dashboard links for the specified dashboard ID.

curl https://app.periscopedata.com/api/v1/shared_dashboard/list --data-binary '{"dashboard":1000}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

Delete

The Delete command will delete the referenced shared dashboard. The token to be used is the last part of a shared dashboard URL. i.e. if the shared URL looks like

https://app.periscopedata.com/shared/9dda9dda-9dda-9dda-9dda-9dda9dda9dda

then the token is 9dda9dda-9dda-9dda-9dda-9dda9dda9dda.

curl https://app.periscopedata.com/api/v1/shared_dashboard/delete --data-binary '{"token":"9dda9dda-9dda-9dda-9dda-9dda9dda9dda"}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

PostMessages

Published dashboard and charts release three different PostMessages to communicate with the outer webpage and allows one PostMessage to communicate with the Published dashboard.

Published Dashboard Filter Change

When a user changes a filter set on a Published chart or dashboard, Sisense will send a PostMessage in the following format. The PostMessage contains the complete list of filters applied to the Published dashboard. The format of the parameters will follow the same convention as the Visualization Publishing API. The webpage code can use this information to send filter combinations to the Render API add-on or to send information on filter usage within Published dashboards.

{
     event_type: "viewport_changed",
     aggregation: "weekly",
     daterange: {"start": "2015-01-01", "end": "2015-01-01"},
     filters: [{"name": "Filter1", "value": "1234"}...]
}

Note: Please click here for more information on the Render API add-on.

Published Dashboard Size

Upon page load, Sisense will send a PostMessage with the size of the dashboard or chart. The message will be in the following format, with the height and width of the dashboard/chart, which can then be used to properly size the iFrame for the Published dashboard.

{
     event_type: "dashboard_resize",
     dashboard_height: 100,
     dashboard_width: 200
}

Published Dashboard Drilldown

When a user clicks on a Published chart with drilldowns enabled, Sisense will send a PostMessage in the following format. The PostMessage contains the new dashboard ID and the new/updated filters and values. The webpage code can use this information to update the JSON used to create the Published Dashboard URL.

{
    event_type: "drilldown",
    destination_dashboard_id: 1234,
    filter_values: [ { filter_name: "foo", column_value: "bar" }, ... ]
}

With the information from the PostMessage, the website code can be written to create a new JSON to create a new URL for the target dashboard. This new JSON blob has the same available parameters from above, and is entirely controlled by the user.

Published Dashboard Refresh Trigger

While the data_ts parameter checks data freshness and triggers query refreshes on a Published dashboard page load, this PostMessage allows the outer webpage to trigger query refreshes while the page is open, without the need to refresh the browser page. If the iframe code is:

<html><body><iframe src="https://app.periscopedata.com/shared/...." height=800 width=1000></iframe></body></html>

Then the Javascript API to call would be:

$('iframe').contentWindow.postMessage({event_type: "refresh_charts"}, "*")

This PostMessage can be triggered using a setInterval() method or attached to a button to trigger the charts to refresh either manually or on a schedule. The max refresh rate using this trigger is once a minute, though once every ten minutes is recommended.

Note: Enabling this API on Published dashboards is NOT recommended for sites that already experience heavy query load or query queues on their site. Publicly Published dashboards can increase the number of queries run against a connection and increasing the number of refreshes requested may cause further delay and queuing. Published Dashboards that use this API should be restricted to dashboards with few charts and low runtimes.

Looking for More?

Try our community page for guidance on topics like: