Installation

## Package content

The Discngine LiveDesign Connector for Spotfire package contains:

• /spotfire_packages_14.6 and /spotfire_packages_14.0: folders containing the Spotfire package files for Spotfire versions 14.6 and 14.0 respectively (same content for each folder)
  • Discngine.DataSource.LiveDesign.spk: the Analyst extensions for the LiveDesign DataSource
  • Discngine.DataSource.LiveDesign.Web.spk: the Web Player extensions for the LiveDesign DataSource
  • Discngine.Renderers.spk: the Discngine Renderers extensions
  • Discngine.LiveDesign.Connector.sdn: the Spotfire distribution package that simplifies the deployment of all extensions
• /library: a folder containing the entry point document to be imported in the Spotfire library
• /web: a folder containing the gadget application to be deployed on the LiveDesign server
• PoweredBy.md: a file containing the list of third-party components used and their associated license for the Connector
• Renderers-PoweredBy.md: a file containing the list of third-party components used and their associated license for the Renderer

This package is available in the download center.

Prerequisites

• Licenses
  • License keys are required to use the Connector, please contact us to get them.
• Spotfire
  • Version 14.0+ or 14.6+ (LTS)
  • Administrator group membership and remote access to the Spotfire server
• LiveDesign
  • Version 2023+ or 2024+ or 2025+
  • Administrator role and SSH access to the LiveDesign server
• Network opened from the Spotfire Web Player servers and users workstations to the LiveDesign server (see more details here)

Spotfire

Deploy packages

In this step you will deploy the SDN file we provide in the package on your Spotfire server.

1. Log in as an administrator on the Spotfire server web portal
2. Go to the Deployments & Packages area
3. Select the deployment area on which you want to deploy the Discngine Connector extensions
4. Click on the "Add packages" button, then choose the .sdn file into the Discngine Connector package
5. Click on "Validate area", then "Save area"

Update Web Player services

Update the corresponding Web Player services to install the Web Player tool.

See Spotfire official documentation for more information.

Edit Web Player configuration

To import data from LiveDesign to Spotfire, the Web Player worker service will have to write temporary files on the server's %TEMP% directory. The Web Player configuration must allow this.

Create configuration

1. Open a shell with administrator rights ("run as administrator") from the Spotfire server (not the node manager if they are on different servers)

2. Export the current config directory of your Web Player service area

   %SPOTFIRE_HOME%\tomcat\spotfire-bin> config export-service-config --deployment-area="<Your Area>" --force --capability=WEB_PLAYER
   

   This will create a config directory under the spotfire-bin directory.

3. Retrieve the path of the temporary folder of the Spotfire node manager service

   • If the account used is Local Service, Local System, or Network services, or any service account, the default temporary folder is usually %WINDOWS%\temp
   • If the account used is a generic account, please contact your system administrator to get the information

4. Edit the file config\root\Spotfire.Dxp.Worker.Host.exe.config

   • Open this file with administrator rights
   • Search and modify the following section (AllowedFilePaths) to add a string element containing the path to the temporary folder (<string><Path To Temporary Folder></string>)
     
   • Save the file

5. Import the config with a new name

   %SPOTFIRE_HOME%\tomcat\spotfire-bin> config import-service-config --config-name="<New Configuration Name>"
   

Select configuration

1. Go to the Spotfire administration website in Nodes & Services > Network
2. Select the Web Player service for the corresponding area
3. Click on the "Edit" button
4. Select the newly imported configuration
5. Click on "Save", then Spotfire will restart the Web Player node.

Activate license features

For each relevant group defined on your Spotfire server, check that the following license features are enabled as described in the official documentation:

• Access to Extensions
• Spotfire Web Client
• Discngine LiveDesign Connector
• Discngine Renderers

Set preferences

In Spotfire Analyst, go to Tools > Administration Manager, open the Preferences tab and fill the Discngine LiveDesign Connector preferences for the user groups to which you want to grant access to the LiveDesign Connector tool.

Example of filled preferences :

The LiveDesignServerUrl value is specific to each environment and must be the URL of the LiveDesign server that should be connected with Spotfire.

By default the DefaultLibraryPath value must be "LDConnector" (if you select "Library" in next section point 5), but if you change the location of this folder, it must be its new path.

SSO configuration

The GadgetUri value must be filled for SSO authentication to work correctly. It must be the uri of the gadget on the LiveDesign server, which is set as location in the gadget configuration. It must start with "/".

To allow LiveDesign SSO authentication, you must add the following URLs to the whitelist of the Application > ApplicationPreferences > Whitelist for Allowed URIs Spotfire preferences:

• https://<livedesign server>
• https://<livedesign server>/*

Import library

Importing the provided LDConnector.part0.zip file in the library will create the folder "LDConnector" containing the file "empty.dxp".

To import this folder:

1. Copy the LDConnector.part0.zip file on your Spotfire server shared directory, by default at the location [Spotfire root]\tss\[Spotfire version]\tomcat\application-data\library\.
2. Open the Spotfire Analyst client and log in using an administrator account.
3. Open Tools > Library Administration.
4. Click on "Import" and "Browse" to select the file LDConnector.part0.zip. Select "Include permissions" and "Replace existing item".
5. Choose your "Destination Folder". We recommend to select "Library". Then click on "OK".

Define access rights to the imported library folder according to the following indications:

• All the LiveDesign Connector users need to have at least Browse + Access rights on the LDConnector folder
• Template designers must have Browse + Access + Modify rights on the LDConnector folder (if you wish to be more restrictive, you can apply these rights on specific projects folders)

Register API client

From Spotfire version 12, all web mashup applications can use an OAuth authentication flow. The official documentation is here.

The JavaScript mashup API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as authorization and authentication server. In this section, we will register a client to obtain the identifier needed in the Connector Gadget, which is a mashup application, to authenticate to Spotfire. This identifier must be communicated to a LiveDesign administrator in order to fill the "location" in the admin panel.

1. On the computer running Spotfire Server, open a command line as an administrator and change the directory to the location of the config.bat file (config.sh on Linux). The default location is <server installation dir>/tomcat/spotfire-bin. To execute commands on a local computer rather than the server computer, refer to the official documentation.

2. To register a new client, use the command register-api-client and the following parameters:

   .\config register-api-client --name="Discngine LiveDesign Connector Gadget" -S"api.js-api" -Soffline --client-profile=user_agent -Gauthorization_code -Grefresh_token -Ahttps://<livedesign server> -Rhttps://<livedesign server>/<gadget uri>/oauth_endpoint.html
   

   The <gadget uri> placeholder used in "-R" parameter must be replaced by the gadget endpoint defined during gadget deployment. Most of the time it will be livedesign/gadgets/connector/spotfire, check with a LiveDesign administrator. The "--name" parameter can have a different value than the one given as an example. The other parameters must not be changed.

   If needed you can list the registered OAuth2 clients using the command list-oauth2-clients. The command show-oauth2-client will allow you to see the full configuration of a client.

3. After successful completion of the command register-api-client, the Client ID will be shown. It must be communicated to the LiveDesign administrator in order to fill the "location" in the admin panel.

Edit server configuration

1. Open a shell with administrator rights ("run as administrator") from the Spotfire server (not the node manager if they are on different servers)

2. Export the active server configuration

   %SPOTFIRE_HOME%\tomcat\spotfire-bin> config export-config --force
   

   This will create a configuration.xml file under the spotfire-bin directory.

3. Replace the value of the content security policy directive property with your previous directive plus https://<livedesign server> and https://<livedesign server>:*

   %SPOTFIRE_HOME%\tomcat\spotfire-bin> config set-config-prop -n security.content-security-policy.directive -v <value>
   

   Important: if you do not know the actual content security policy directive, open the configuration.xml file and search for the content-security-policy section (name can be different according to Spotfire versions) to make sure to keep the previous values in the directive.

4. Import the configuration

   %SPOTFIRE_HOME%\tomcat\spotfire-bin> config import-config --comment="LiveDesign server added to CSP"
   

5. Restart the Spotfire server as described in Spotfire official documentation

LiveDesign

The LiveDesign part of the installation involves deploying and configuring the Spotfire Connector Gadget. As many LiveDesign gadgets, it is a web application and needs to be hosted on the LiveDesign server. The deployment procedure is different if the LiveDesign server is on-premise (legacy installation process) or on cloud (see below).

Deploy on server

For the following steps, we assume that your LiveDesign instance is hosted on cloud and deployed by Schrödinger. You will probably need to contact your Schrödinger architect to perform them.

1. Download the helm chart here

   • This is an example of a helm chart file that you can use or take inspiration from to deploy the gadget to suit your needs
   • Note that this zip package can be used for the LiveDesign Connector for Pipeline Pilot or for the LiveDesign Connector for Spotfire

2. Unzip the folder and open the README.md file located at the root

   • This file explains the procedure for the two gadgets

3. Follow the instructions under the LiveDesign Spotfire gadget section

Configure in admin panel

The last step is the configuration of the gadget in the LiveDesign administration tool.

Go to LiveDesign Admin Panel > Properties > CUSTOM_TOOLS and declare the gadget.

If the Register API client step has been done:

[
  // ... other gadgets
  {
    "categoryName": "Discngine",
    "gadgets": [
        {
            "name": "Spotfire Connector",
            "location": "<gadget uri>index.html?spotfireConnectorJsApiClientId=<client id>&spotfireConnectorJsApiRedirectUrl=https://<livedesign server><gadget uri>oauth_endpoint.html"
        }
    ]
  }
]

If not:

[
  // ... other gadgets
  {
    "categoryName": "Discngine",
    "gadgets": [
        {
            "name": "Spotfire Connector",
            "location": "<gadget uri>"
        }
    ]
  }
]

Placeholders:

• <gadget uri>:
  • /livedesign/gadgets/connector/spotfire/ for cloud deployment if the provided helm chart has been followed
  • /livedesign/spo for on-premise deployment (legacy, not recommended)
• <livedesign server>: the uri of your LiveDesign server
• <client id>: the registered API client ID, ask to the Spotfire administrator

Validation

Once the installation is completed on both Spotfire and LiveDesign side, validate that everything is working as expected. This check can be done either directly with a user, or by a Spotfire or LiveDesign administrator. In this latest case, the administrator needs to be sure to respect some prerequisites:

• Have a LiveDesign account
• Have access to at least one project and one LiveReport in LiveDesign
• Have a Spotfire account
• Have access to the imported Spotfire library folder
• Be in the good Spotfire group to have the Connector license features and preferences set

To validate the installation, follow this tutorial.

Note: if the tester does not have a Spotfire Business Author or Analyst license, it is possible to skip the Add visualizations section.