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.

The Embedding API consists of two parts: The Cadenza JS client and Direct HTTP endpoints.

  1. Cadenza JS Client — This is the recommended, main, and feature-richest way to use the Embedding API, using the browser postMessage mechanism for interactive embedding. It is further documented on GitHub.

  2. Direct HTTP Endpoints — This is a limited set of direct HTTP endpoints for basic usage that does not require communication between the embedding application and the one being embedded. It is further documented in this OpenAPI definition.

When to Use Which Part of the Embedding API

We generally recommend using 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.4.9.

The complete set of Embedding API features is only supported by the Cadenza JS client. However, there are a handful of scenarios for which using the Cadenza JS Client is not feasible. For these scenarios, a limited set of direct HTTP endpoints provides an alternative.

Scenario Possible Approaches

Multi-view embedding

Cadenza JS Client

Geometry creation and/or editing

Cadenza JS Client

Interactive embedding, two-way communication

Cadenza JS Client

Simple, single iframe embedding without postmessage communication

Cadenza JS Client or Direct HTTP Endpoints

Simple links for data export/download without embedding or interaction

Direct HTTP Endpoints or Cadenza JS Client

Server-side/backend access to Cadenza Embedding API

Direct HTTP Endpoints

Non-JavaScript environments

Direct HTTP Endpoints

Direct HTTP Endpoints

We use the OpenAPI specification to document all Embedding API operations that are available as direct HTTP URL invocations in addition to the Cadenza JS client. Note that this is intended only for technical APIs that are meant to be embedded in non-browser clients. The majority of the Embedding API features is only accessible via the Cadenza JS client.

The OpenAPI definition is available as embedding-api.yaml or can be viewed here.

The following sections provide some examples for how to use the direct HTTP endpoint URLs in common use cases.

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}

In non-JavaScript environments, these URLs can be used to embed a view in an iframe or create a link to an embedding target.

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">

Further examples, such as showing the PDF of a report or downloading the data from a table view, are documented as part of the OpenAPI definition.

Access Direct HTTP Endpoints from a Backend Application

Direct HTTP endpoints can also be used from a backend application, e.g. to fetch data or to use non-interactive API features that do not require an embedded view, such as calculating geometry intersections.

This requires a valid authentication context, which can for instance be achieved through JWT or API key authentication. The API key authentication procedure is documented as part of the Management API, including Python examples for direct HTTP Endpoint access.

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 administrator:configuration:embedding.adoc 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 ExternalLinkKey in 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!

Enable Cadenza JS Development Sandbox in Cadenza

The Cadenza JS development sandbox is a simple custom application that can be used to play around with the embedding functionality. It can be enabled using npm or by setting an environment variable, see the Cadenza JS client documentationon for details.

Example: Enable the Cadenza.js Sandbox by setting the environment variable
CADENZA_ENABLE_EMBEDDING_SANDBOX=true
This environment variable should not be set in production!