Skip to main content

How to set up Spotfire

Setup takes about 10 minutes, plus about 30 minutes if you also set up usage data.

Introduction

Connecting Spotfire to Foundational allows Foundational to read your Spotfire metadata, build lineage from your analyses back to their data sources, and show downstream impact. Foundational connects with OAuth 2.0 client credentials.

Optionally, Foundational can also show how people use your analyses: views per day, who viewed each analysis, when it was last viewed, and which analyses nobody uses. For this, Foundational needs read access to the database where Spotfire Server writes its action log (Part 2).

To make the connection, you need to complete Part 1. Part 2 is optional:

  • Part 1: Set up the Spotfire connection
    ​

  • Part 2: Add usage data from the action log


Prerequisites

Ensure you have:

  • Access to the Spotfire Server command-line tool.
    ​

  • Permission to register API clients on the Spotfire Server.
    ​

  • The Spotfire Server URL.
    ​

  • Added Foundational IP addresses to the allowlist. See the article Allowing IP access to Foundational.

Note: To complete Part 2, you need a Spotfire Server administrator and a database administrator for the action-log database.


Access permissions

All access is read-only. Foundational reads metadata and never changes your content.

  • The API client reads the Spotfire library: analyses, information links, data sources and their relationships.
    ​

  • The optional action-log database user reads the ACTIONLOG table only.


Part 1: Set up the Spotfire connection

Step 1: Create API client credentials in Spotfire

Use the Spotfire Server command-line tool to register an OAuth 2.0 API client for Foundational.

  1. Open a terminal on the computer that runs Spotfire Server and has the command-line tools.
    ​

  2. Run this command:
    ​

    config register-api-client \
    --name "Foundational" \
    -S api.library.read \
    --client-profile=other \
    -G client_credentials \
    --token-endpoint-auth-method=client_secret_basic

  3. Copy the Client ID and Client Secret. Spotfire shows the secret only once. You need both in step 2.

The command uses these parameters:

  • --name: A descriptive name for the API client.
    ​

  • -S api.library.read: Read-only access to library analyses, information links and data sources.
    ​

  • --client-profile=other: A client that is not a browser.
    ​

  • -G client_credentials: The OAuth 2.0 client credentials grant.
    ​

  • --token-endpoint-auth-method=client_secret_basic: Foundational sends the client ID and secret with HTTP Basic authentication.

Step 2: Connect Foundational to Spotfire

  1. In Foundational, open the Connectors & Integrations page.
    ​

  2. In BI & Analytics, select the Spotfire card and click Connect.
    ​

  3. Click Add Account.
    ​

  4. The initial setup screen opens. Click Start Setup.
    ​

  5. The Set Up New Connection screen opens. Enter the details:
    ​

    • Instance name (optional): A name that tells this Spotfire server's analyses apart in lineage, for example Field Main. If you leave it blank, Foundational uses the server address.
      ​

    • Base URL: The base URL of your Spotfire Server, for example https://spotfire.example.com.
      ​

    • Port: The port of your Spotfire Server. The default is 443.
      ​

    • Client ID: The client ID from step 1.
      ​

    • Client Secret: The secret from step 1.
      ​

    • Action Log Database Type: Leave Not configured, unless you have already completed Part 2, steps 1 to 3. In that case, enter the fields from Part 2, step 4.
      ​

  6. Click Next.
    ​

  7. The final setup screen opens. To complete the connection, click Save.

Foundational now scans your Spotfire library for lineage.

Step 3: Check the connection

On the Connectors & Integrations page, select the Spotfire card. The connection's card on the Spotfire page shows its status. Any setup problem shows as a warning on the card.


Part 2 (optional): Add usage data from the action log

Skip this part if you only need lineage. The connection works without it. The connection's card on the Spotfire page then shows a notice that the action-log database isn't configured.
​

Spotfire records who opens each analysis in its action log. Foundational reads it to show views, viewers and last-viewed dates, and to find analyses nobody uses.

The action log is off by default, and Spotfire's REST API cannot read it. A Spotfire Server administrator must turn it on and write it to a database that Foundational can read.
​

Step 1: Turn on action logging to a database

Use the Spotfire Server configuration tool or the config-action-logger command. Spotfire's Action logs and system monitoring describes both. In the configuration tool, open the Configuration tab and click User Action Log in the Configuration Start list.

  1. Turn on Enable database logger. Foundational cannot read log files, so file logging alone is not enough. You can log to both.
    ​

  2. Log at least these categories, which record the events that open an analysis:
    ​

    • library: The server loads an analysis file (load_content).
      ​

    • library_wp: An analysis opens in the Web Player, in a browser (load, clone).
      ​

    • library_pro: An analysis opens in Spotfire Analyst, the installed client (load).
      ​

    • analysis_as: Automation Services jobs, such as scheduled exports and emails.
      ​

  3. Set Enable web service to Yes. Spotfire then accepts log events from the Web Player and Analyst. Without it, Spotfire does not write Web Player and Analyst opens, and only library events appear. By default, the web service accepts all hosts and categories. The Web service configuration section lists them. If you narrow the categories, keep library_wp, library_pro and analysis_as. To set this on the command line, run:
    ​

    config config-action-log-web-service --allowedHosts=".*" --categories="all"

  4. Keep enough history. Spotfire can delete action-log rows older than a set number of hours. Keep at least 90 days (2,160 hours), and preferably 365 days (8,760 hours).
    ​

  5. Restart the Spotfire Server and the Web Player services if the configuration tool asks you to.

Spotfire writes the log to a table named ACTIONLOG in a SQL Server, Oracle or PostgreSQL database.

Step 2: Create a read-only database user

Create a database user for Foundational that can only read ACTIONLOG. Use the example for your database.

SQL Server

USE <action_log_database>;
CREATE LOGIN foundational_reader WITH PASSWORD = '<password>';
CREATE USER foundational_reader FOR LOGIN foundational_reader;
GRANT SELECT ON dbo.ACTIONLOG TO foundational_reader;


​Oracle (replace <action_log_schema> with the schema that owns ACTIONLOG )

CREATE USER foundational_reader IDENTIFIED BY "<password>";
GRANT CREATE SESSION TO foundational_reader;
GRANT SELECT ON <action_log_schema>.ACTIONLOG TO foundational_reader;
CREATE SYNONYM foundational_reader.ACTIONLOG FOR <action_log_schema>.ACTIONLOG;

Foundational reads the table as ACTIONLOG . On Oracle, if the table sits in another schema, you need the synonym.

PostgreSQL

CREATE ROLE foundational_reader LOGIN PASSWORD '<password>';
GRANT CONNECT ON DATABASE <action_log_database> TO foundational_reader;
GRANT USAGE ON SCHEMA public TO foundational_reader;
GRANT SELECT ON actionlog TO foundational_reader;

Step 3: Let Foundational reach the database

Allow connections from Foundational's IP addresses to the database's host and port. See Allowing IP access to Foundational. If the internet cannot reach the database, route the connection through your Foundational on-prem agent instead.

Step 4: Add the database to the connection

  1. In Foundational, open the Connectors & Integrations page and select the Spotfire card. The Spotfire page shows one card per connection. On the connection's card, click Edit (the pencil icon). The form is the same as in Part 1, step 2.
    ​

  2. Set Action Log Database Type to SQL Server, Oracle or PostgreSQL, and enter:
    ​

    • Action Log Host: The database server's hostname or IP address.
      ​

    • Action Log Port (optional): The default is 1433 for SQL Server, 1521 for Oracle and 5432 for PostgreSQL.
      ​

    • Action Log Database: The database that holds ACTIONLOG. For Oracle, enter the service name.
      ​

    • Action Log User and Action Log Password: The user name and password of the read-only user from step 2.
      ​

    • Action Log CA Certificate (optional, recommended): Upload the CA certificate (.pem, .crt or .cer) that signed the database server's TLS certificate. If the server's certificate is self-signed, upload that certificate instead. Foundational then encrypts the connection and checks the server's certificate against it. Without it, SQL Server may accept the login unencrypted. Oracle and PostgreSQL never send the password in clear. On Oracle, Foundational connects over TCPS when you upload a certificate. Set Action Log Port to your TCPS listener's port (often 2484).
      ​

  3. Click Save.

When you save, Foundational connects to the database and reads ACTIONLOG. The connection saves even if this check fails, because lineage does not need the action log. If something is missing, the connection's card on the Spotfire page shows a warning that says what to fix:

Message

What to do

The Spotfire action-log database isn't configured on this connector.

Complete steps 1 to 4, or ignore the notice if you only need lineage.

Foundational can't reach the Spotfire action-log database at <host:port>.

Check the host and port, and the allowlist or on-prem agent (step 3).

The Spotfire action-log database refused the login of <user>.

Check the user, password and database (or Oracle service name).

The TLS connection to the Spotfire action-log database failed.

Check that the uploaded CA certificate signed the server's certificate, that the certificate names the Action Log Host you entered, and that the server accepts TLS. On Oracle, use the port of a TCPS listener.

<user> can't read the Spotfire action-log table ACTIONLOG.

Grant SELECT on ACTIONLOG. On Oracle, also create the synonym (step 2).

The Spotfire action-log table ACTIONLOG is empty.

Turn on action logging to the database (step 1).

The Spotfire action log has no analysis opens.

Add the categories in step 1.

The Spotfire action log has no analysis opens from the Web Player or Analyst.

Set Enable web service to Yes (step 1, item 3).

After you fix the problem, click Re-check on the connection's card.

To stop reading usage data, set Action Log Database Type back to Not configured and save. Foundational then removes the stored database user, password and CA certificate. The card shows the not-configured notice again.

Did this answer your question?