Embedding API Documentation

The Embedding API is a set of web services and a set of events that are transmitted to Cadenza and back to the custom application using the postMessage browser mechanism.

This documentation only describes some of the most basic embedding scenarios that require no communication between the embedding application and the one being embedded. You can find these basic scenarios documented in Link to Embedding Targets. This covers cases like showing a workbook view in an iframe or downloading a workbook view’s data as CSV.

For more complex uses cases that are not covered in that section, please use the Cadenza JS client to interact with the Embedding API in the browser. We do not support using the postMessage API directly, please always use the library. Find the documentation on GitHub or in the cadenza.js folder in the Cadenza distribution.

The recommended version of Cadenza JS for use with this Cadenza version is v10.3.9.

In the dialog for creating an embedding target in Cadenza, you’re offered to copy the URL of the embedding target in the following format:

{publicCadenzaUrl}/w/{embeddingTargetId}

This section provides examples for how to use these URLs in common use cases.

Example: Link to an Embedding Target
<a href="{embeddingTargetUrl}">My Embedding Target</a>
Example: Show an Embedding Target in an Iframe
<iframe src="{embeddingTargetUrl}" width="1280" height="900">
Example: Show the PDF of a JasperReports Embedding Target in an Iframe
<iframe src="{embeddingTargetUrl}?dataType=pdf" width="800" height="600">
Example: Download the Data of a Table Embedding Target as CSV
<a href="{embeddingTargetUrl}?dataType=csv" download>My Embedding Target</a>

These data types are supported:

  • for table view or indicator view embedding targets

    • csv

    • excel

    • json

  • for JasperReports and report embedding targets

    • pdf

Example: Customize the name of the downloaded file
<a href="{embeddingTargetUrl}?dataType=csv"
   download="My-Embedding-Target.csv">
  My Embedding Target
</a>

By default, the file name is generated from the name of the workbook view and the current date.

Downloading Data via a Static Link from a Backend Application

Static links can also be used to download data from a non-interactive backend application. The authentication procedure required to do this is documented as part of the Management API, including a python example.

Configure Cadenza for Embedding

When preparing for an embedding scenario with Cadenza you should configure it according to your particular context, specifically whether you are running the embedding application and the embedded application on different origins or not. Our How to Configure Cadenza for Embedding documentation describes what settings are required in the different scenarios.

If you want to go beyond simple iframe embedding, and you want to interact with the embedded view then you must take care to configure Cadenza such that postMessage communication is possible.

Enable postMessage Communication Between Cadenza and a Custom Application

Cadenza uses the postMessage browser API to communicate between your custom application and itself. When posting a message, Cadenza defines the expected target origin for the message, so that the message is not delivered to a malicious site with another origin. Conversely, only messages from the expected origin are accepted.

There are three options to make the postMessage communication between Cadenza and a custom application work:

  • Put both behind a proxy server that serves both on the same origin. By default, Cadenza uses its own origin as the target origin.

  • Define an external link for the custom application in the Cadenza Management Center and pass the ID of the link along with its repository name to the Cadenza JS client (see docs). Cadenza will resolve the target origin from that link.

  • For developing a custom application, the above options might be too cumbersome. To set the target origin to * (= any origin), enable the net.disy.cadenza.postMessageAnyOrigin feature toggle when starting Cadenza.

Example: Enable the feature toggle in the setenv.sh.
-Dnet.disy.cadenza.postMessageAnyOrigin=true
This feature toggle should not be used in production!