With the Spotfire® JavaScript API it is possible to embed Spotfire visualizations and dashboards into web pages. The API supports customized layout and enables integration with external web applications.
The JavaScript API can be used for a diverse set of scenarios:
The JavaScript API supports opening multiple views against the same analysis, where all views are automatically linked together. This gives a lot of flexibility when creating a mashup.
The key capabilities of the JavaScript API include:
This tutorial describes the important concepts and capabilities of the JavaScript API.
Download the latest TypeScript declaration file (d.ts), Spotfire JavaScript API (14.5). Using this is optional, but simplifies the development as it can provide code completion and documentation inside your preferred IDE.
The API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server. Authentication and authorization can also be delegated to an external Authorization Server or similar through the use of Token Exchange.
The web mashup acts as an API client towards the Spotfire Server. Each request from the mashup will include an access token, which the web mashup client establishes through an OAuth2 Authorization Code flow or through an OAuth2 Token Exchange flow. When using the Authorization Code flow most of the process will be handled by the JavaScript OAuth client included in the Spotfire server (/spotfire/js-api/oauth.js).
To use the Spotfire JavaScript API an OAuth2 API client must first be registered on the Spotfire Server.
Registration on the Spotfire Server is done using the register-api-client command of the Spotfire Server command-line configuration tool. Example:
register-api-client --name="JavaScript API client" -Sapi.js-api -Soffline --client-profile=user_agent -Gauthorization_code -Grefresh_token -Ahttps://example.com -Rhttps://example.com/foo/return
The -A argument specifies the allowed origin, where the Web Mashup will be running. The -R argument specifies the redirect URI to which the browser is returned after the user has authenticated (the OAuth redirect page). It must be the same value as given to the new redirectUri setting (see below). The redirect URI must reside on the same origin as specified in the -A argument.
The required scopes (-S argument) are api.js-api and offline. The required grant type (-G argument) is authorization_code. It is recommended to specify refresh_token as well for a better user experience. The grant type token_exchange is also supported but requires requires the mashup to provide a subject token, and that the Spotfire Server is properly configured.
Running the command above gives an output like this:
Successfully registered a new API client with the display name 'JavaScript API client':
Client ID: 12f4a3c33d377ed5c7ab476d69ea52d1.oauth-clients.spotfire.com
No client secret issued (public client)
To view the full client configuration, please use the 'show-oauth2-client' command.
To get a list of all existing clients, please use the 'list-oauth2-clients' command.
To delete a registered client, please use the 'delete-oauth2-client' command.
After registration the client ID given in the output must be set in the clientId setting of the web mashup.
Some notes:
security.oauth2.client.redirect-uri-must-use-https configuration property.--require-end-user-consent=false when registering the client.silent setting of the Web Mashup to true to attempt silent authentication.anonymous setting of the Web Mashup to true to request such a token.The user is authenticated when calling the spotfire.webPlayer.authenticate function. Depending on the settings this may be silent (by specifying silent or including a subjectToken) or initiate an OAuth authorization code flow.
The options in the authentication settings objects can be found here.
Once the authenticate method resolves, the mashup code should continue by calling the connect method. This performs several steps.
The options in the connect settings objects can be found here.
The openDocument method open the analysis in the specified HTML element, and return a document instance. This object contains most methods to control the behavior of the web mashup. Note that it is valid to call the openDocument method multiple times. Each opened document shares the application instance, and marking carries over between all instances. If you on the other hand want to open separate instances of a single (or different) Spotfire analyses, this can be achieved by calling connect multiple times.
Below is a basic example showing the required steps to open a Spotfire analysis using the JavaScript API, using the methods described above.
<html>
<head>
<script src="https://my.spotfire.com/spotfire/js-api/oauth.js"></script>
<script>
document.addEventListener('DOMContentLoaded' loadMashup);
function loadMashup() {
const server = "https://my.spotfire.com";
const clientId = "registered_client_id";
const redirectUri = "https://client.website.com/oauthEnd.html";
const path = "/user/my analysis";
/** Declare the version of the API */
spotfire.webPlayer.setApiVersion("14.5");
/** Authenticate the user */
const authSettings = { clientId, server, redirectUri };
spotfire.webPlayer.authenticate(authSettings).then(connect).then(open).catch(onError);
/** Connect to a specified analysis using the authentication token */
function connect(token) {
const connectSettings = { token, path };
return spotfire.webPlayer.connect(connectSettings);
}
/** Open the start page */
function open(application) {
application.openDocument("SpotfireContent");
}
function onError(err) {
console.error("Spotfire JavaScript API Error:", err.category, err.code, err.message);
}
}
</script>
</head>
<body>
<div id="SpotfireContent" />
</body>
</html>
The redirect page declared in the API client registration must be hosted on the same domain as the web mashup itself. If a customer has multiple web mashups it is sufficient to server all these with a single API client and a single redirect page. The redirect page only needs to call spotfire.webPlayer.oauthEnd().
<!DOCTYPE html>
<html>
<head>
<title>Generic OAuth Endpoint</title>
<script src="https://my.spotfire.com/spotfire/js-api/oauth.js"></script>
<script>
/** Processes the oauth result and redirects back. */
spotfire.webPlayer.oauthEnd();
</script>
</head>
</html>
The use of the Token Exchange grant enables users to be signed in using an access token from an external authorization server (or other trusted party) without having to authenticate again. This can be useful when, for example, embedding Spotfire into a portal that already authenticates users.
To use this grant, the mashup has to establish a subject token (adhering to the requirements described below). The subject token may either be created by the mashup itself (or rather a backend supporting it) or by an external authorization server. The subject token is then passed to the JavaScript API through the subjectToken parameter and is exchanged for an access token issued by the Spotfire Server. The Token Exchange grant must be explicitly enabled by configuring the Spotfire Server to trust tokens issued by the external authorization server.
In some cases it may be possible to use the silent authentication mechanism to achieve single sign on, as mentionened above. This is not possible in a vanilla setup of Spotfire as it requieres the existence of an authentication mechanism that does not require user interaction.
When registering the API client -Gtoken_exchange must be specified (together with -Grefresh_token -Gauthorization_code).
Configuration is done using the config-rfc-9068-token-exchange-authenticator command. The most basic configuration only requires setting the URI to the OAuth 2.0 Authorization Server Metadata document of the external Authorization Server. The metadata document MUST contain an issuer and a jwks_uri (with the keys needed to verify subject token signatures).
If no Metadata document is available, it is possible to instead configure an expected issuer (a string) and either a static JWKS or a JWKS URI with the key(s) needed to verify subject token signatures.
See the help for the config-rfc-9068-token-exchange-authenticator command for more configuration options.
The subject token issued by the mashup backend or an external authorization server must meet the requirements below.
aud claim must include the Spotfire Server Token Endpoint URI (http[s]://<hostname>[:<port>]/spotfire/oauth2/token).may_act claim.may_act claim then the value of the client_id sub-claim must be the client ID of the client using the token.scope claim.scope claim then the value must include the api.js-api and offline scopes.Below is an example of a token that meets all mandatory and optional requirements described above.
eyJraWQiOiI4YzE1YmMwMS0zZGY4LTQ0MmUtYTY2MS1iNTg5YTJjZWU5ODAiLCJ0eXAiOiJhdCtqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJqb2huZG9lIiwiYXVkIjoiaHR0cHM6Ly9zcG90ZmlyZS5leGFtcGxlLmNvbS9zcG90ZmlyZS9vYXV0aDIvdG9rZW4iLCJzY29wZSI6ImFwaS5qcy1hcGkgb2ZmbGluZSIsImlzcyI6Imh0dHBzOi8vYXMuZXhhbXBsZS5jb20iLCJtYXlfYWN0Ijp7ImNsaWVudF9pZCI6IjEyZjRhM2MzM2QzNzdlZDVjN2FiNDc2ZDY5ZWE1MmQxLm9hdXRoLWNsaWVudHMuc3BvdGZpcmUuY29tIn0sImV4cCI6MTczMTM0NTA2MywiaWF0IjoxNzMxMzM3ODYzLCJjbGllbnRfaWQiOiJyN3huaXBwMDJwIiwianRpIjoiZmMxOGVhYTEtMDIxNi00ZGI0LTgxODctODZmNjA5YzVkZDVkIn0.gCCXGRaEUH2YWuz9ivIML_sRL1E7zpXSBvgfuEDUEq9J6cKJVklw-A4QxjWLEhWRQnDHFrbL0puNPjFAGxqJpMVGJ3CwQ7MFUi7UiiI2lwMwWhcZjmoerVzk3G4OC_r0PVMhdV6wXfSs50Ka15sWIjGcnicx42i0h4wSqE0XAddDiIJ1wiAhFsUsBXzb8ZYqorAD3FwM5nAdY1OF8vdWaZVXqT4xAUL95sFy2Ididb5C5PltlJcszhN93UB0-Ukm7eIs2HrNj9HXWXMJ8VS_PdHRIShUPszyqADNMGByAg67YgtBL_w8ccv603pCeXkzCAlqN5Tx1rQxGo70J5dRGw
The payload of the token above is shown below.
{
"sub": "johndoe",
"aud": "https://spotfire.example.com/spotfire/oauth2/token",
"scope": "api.js-api offline",
"iss": "https://as.example.com",
"may_act": {
"client_id": "12f4a3c33d377ed5c7ab476d69ea52d1.oauth-clients.spotfire.com"
},
"exp": 1731345063,
"iat": 1731337863,
"client_id": "r7xnipp02p",
"jti": "fc18eaa1-0216-4db4-8187-86f609c5dd5d"
}
The initialization of a web mashup is usually the most error prone phase that may be difficult to debug. The initialization methods authenticate and connect can result in errors for different reasons. All errors are categorized and contain, in addition to a semi user friendly error message, also a code and a category to guide the developer of the mashup.
This category signals that the developer most likely has used the API in an incorrect way. The possible codes and messages are:
This category is used for errors that can occur during the authorization flow. These can be either configuration errors or merely an expected error if the end user, for example, does not consent to allow access to Spotfire.
These errors indicate that the configuration of the server is incorrect.
These errors might be temporary, due to network errors, or the user trying to manipulate the code.
Note that specifying an older API version does not change the running Spotfire version, nor does it change any Spotfire functionality. It does however limit the available JavaScript API in runtime, ensuring that the web mashup will function when connecting to an older Spotfire system.