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 v3.0.4.

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:

  • json

  • pdf (for JasperReports embedding targets)

  • excel

  • csv

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.

Configure Cadenza for Embedding

This section describes how Cadenza needs to be setup for using the Embedding API in embedding use cases.

Allow Cadenza to be Embedded in an Iframe

By default, is not allowed to be embedded in a page/application other than itself to prevent Clickjacking attacks.

One exception is when both applications are running on the same origin (for example behind a reverse proxy). If you are not on the same origin, see Securing Cadenza for more information on how to change the CSP configuration to allow embedding of your application in Cadenza.

Allow Third Party Cookies

If you embed Cadenza into your application (or the other way around,) and you are running on different origins you will need to configure Cadenza to allow its session cookies to be transferred when using different origins.

See Environment Variables, System Properties and Other Runtime Configuration Options for more information on how to configure the Secure and Samesite flag on cookies.

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!