Upload SBDF Files to the Spotfire Library on Spotfire Server

Introduction

By using a configuration option on the Spotfire Server and Spotfire Enterprise Runtime for R (TERR), you can now upload SBDF files to the Spotfire library on Spotfire Server.

The API call you use determines whether you are scripting for a service-to-service upload, or if you just want to upload an SBDF file to your user folder. (For both of these methods, the credentials you get from running the API calls persist with the server as long as it is deployed.)

• You can use the register-api-client command to create a client ID and client secret (similar to user name and password). Using this method, you can script a service to have access to the entire Spotfire library, automatically uploading SBDF files as needed. This method is described in the reference topic for the TERR function uploadSBDF. See that topic, available from your TERR installation for more information. (From the TERR console, type ?SpotfireData::uploadSBDF.)
• You can write the API call to create a client ID, with which you can then get an access token. Using this method, you can gain access to your Spotfire library folder, and write an SBDF file from a TERR console or from RStudio.

This article provides example code (with placeholders) for the second method: to create a client ID, to authenticate the client using oauth2, and then to run a TERR script, uploading an SBDF file directly to your Spotfire library folder.

Note:  For information about the configuration options, see the Spotfire Server Installation and Administration Guide. For information about the authentication and authorization API, see Section 2 of the documentation for Spotfire Spotfire Server Library API.  (https://docs.tibco.com/products/spotfire-server)

Prerequisites

• You must have administrative access to the computer where Spotfire Server is installed, and you must have access to the administrative tools on the Spotfire Server.

Note:  The Spotfire Server administrator can run the API calls to generate the client ID, and then pass it on to you to complete the task from your TERR script.

• You must have installed Spotfire Enterprise Runtime for R version 5.1 or later.
• You must install the CRAN packages openssl, httr, and httpuv.

Generating the Client ID

To access a specific folder in the Spotfire library on the Spotfire Server, you must have an access token. To get the access token, first generate a client ID.

1. On the computer running Spotfire Server, open a command line as an administrator.
2. 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.

3. Register the client endpoint for use by the API.

   config register-api-client --name="TERR" -Sapi.rest.library.upload --client-profile=native -Gauthorization_code

   Response: You are prompted to provide the tool password.

4. Enter the tool password.

   Response: Successfully registered a new API client with the display name 'TERR':

   Client ID: <GUID and other text assigned by server>

   No client secret issued (public client)

   To view the full client configuration, please use the 'show-oauth2-client' command.

You now have a client ID. You can use this client ID in the TERR script to generate the access token.

Generating the access token

To access a specific folder in the Spotfire library on the Spotfire Server, you must have an access token, which you can get using a TERR script. These steps walk you through generating the access token.

1. Open the TERR console or an R Studio instance.
2. At the command prompt, load the following libraries.

   library(openssl)
   library(httr)
   library(httpuv)

    
3. Create an object to specify the clientID, and an object to specify the URL to the Oauth2 area on the Spotfire Server where the client ID was created.

   clientID <- <GUID and other text assigned by server>"
   spotfireURL <- "http://<spotfire server address>/spotfire/oauth2"

    
4. Override the redirect URI port to run the web server. (This step is provided as a precaution; in the case where your system does not bind to the default port.)

    Sys.setenv(HTTR_PORT=60000)

    
5. Create objects for the oauth endpoint and app.

   oep<-oauth_endpoint(base_url=spotfireURL, authorize="auth", access="token")
   oapp<-oauth_app("spotfire", clientID, redirect_uri="http://localhost:60000/")

    
6. Calculate a random PKCE code verifier value to be used in the authentication exchange.

   The code verifier (code_verifier) is a high-entropy cryptographic random string using the unreserved characters (A-Z, a-z, 0-9, -, ., _, and ~) from Section 2.3 of RFC3986, with a minimum of length of 43 characters and a maximum length of 128 characters.

   base64encodewithoutpadding <- function(x) {
       res <- openssl::base64_encode(x)
            res <- gsub('\\+', '-', res)
            res <- gsub('\\/', '_', res)
            res <- gsub('=+$', '', res)
            res
        }
   
   cver <- base64encodewithoutpadding(openssl::rand_bytes(32))
   cchl <- base64encodewithoutpadding(openssl::sha256(charToRaw(cver)))
   auth_extra <- list(code_challenge=cchl, code_challenge_method="S256")
   token_extra <- list(code_verifier=cver)

    
7. Create the token.

   token <- oauth2.0_token(oep, oapp, scope=c("api.rest.library.upload"), 
        query_authorize_extra=auth_extra, user_params=token_extra, cache=FALSE)

   When you have created the token, TERR launches a Spotfire instance and you are prompted to log in.
8. Provide your credentials.

   Response:: You are prompted to return to your TERR script.

   Note: The access token expires after about an hour, so use it only for the length of your TERR session or script. You can rerun this script to generate a new access token when you need it.

   You can now upload the SBDF file, passing in the file path, the library directory, the Spotfire library URL, and the access token. See the help for SpotfireData::uploadSBDF in the TERR reference for more information.

9. Upload the file, supplying the token$credentials you obtained above in the accessToken parameter

   uploadSBDF("my-sbdf.sbdf", libraryDir="/mydir/", libraryURL="http://myserver/spotfire", 
        accessToken=token$credentials$access_token, overwrite=TRUE)