Installation

Package content

The Discngine TIBCO Spotfire® Connector package contains:

• Discngine.Connector.sdn: the distribution file that bundles together the TIBCO Spotfire® extensions,
• all the SPK files contained in the SDN file (if do not you want to install all of our extensions),
• Discngine-Connector.part0.zip: a TIBCO Spotfire® library export,
• Discngine-Connector-Authenticator-Spotfire10.zip: the java package needed to use Pipeline Pilot as an authenticator during the Web Player connection for Spotfire 10.0+,
• Discngine-Connector-js-api.zip: the JavaScript API,
• Discngine-Connector-js-api-4.1.zip: the JavaScript API of the Connector 4.1 (for backward compatibility),
• Discngine-Connector-PP-collection.zip: the Pipeline Pilot collection of components and example protocols,

Overview

To install the Discngine TIBCO Spotfire® connector the following steps are required:

1. Deployment of the Discngine Connector distribution packages on the TIBCO Spotfire® server.
2. Import of a TIBCO Spotfire® library folder on the server.
3. Installation of the collection on the Pipeline Pilot server.

There are also optional steps if you want to use the Discngine Authenticator or the Discngine Automation tasks.

Prerequisites

• TIBCO Spotfire® administrative rights on the TIBCO Spotfire® Server and Analyst 10.10 or higher. Please contact us for lower versions.

• BIOVIA Pipeline Pilot server 2017 R2 or above.

• Knime® Server 4.1 or above

• Access with administrative rights on the Pipeline Pilot server.

• To use the Discngine Automation tasks, two prerequisites should be noted:

  • the TIBCO Spotfire® Automation Services must be deployed on the TIBCO Spotfire® server. Please refer to the official documentation.

  • the TIBCO Spotfire® Client Job Sender tool must be installed on the Pipeline Pilot server. The procedure is described below. Please note that the TIBCO Spotfire® Client Job Sender tool is compatible with Windows servers only.

• Supported sketchers:

  • Chemaxon Marvin JS
  • BIOVIA Draw 2016 (requires BIOVIA Draw Plugin 2016)
  • Perkin Elmer Chemdraw (requires BIOVIA Draw Plugin 2016)

TIBCO Spotfire® extensions deployment

In this step you will deploy the SDN file we provide in the package on your TIBCO Spotfire® server. We strongly advise you to use either a test server or a test area. If you prefer to use a specific area, pay attention to the routing rules associated to the user/group who will test the Discngine Connector application in the Web Player. You can find further information in the official documentation.

1. Log in as an administrator on the TIBCO 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. If you upgrade the Connector from a version less than 5.x, you must first remove the "Discngine*" SPKs and save the area.
5. Click on the "Add packages" button, then choose the .sdn file into the Discngine Connector package.
6. Click on "Validate area", then "Save area".

TIBCO Spotfire® library

We provide in the package a file Discngine-Connector.part0.zip, so the import will create in your library a folder "Discngine Connector" containing the file "empty.dxp". This DXP may be useful if you want to start your web application without data at the beginning.

To import this folder:

1. Copy the file Discngine-Connector.part0.zip on the TIBCO Spotfire® server at the location path [TIBCO Spotfire root]\tss\[TIBCO Spotfire version]\tomcat\application-data\library\.
2. Open the TIBCO 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 Discngine-Connector.part0.zip.
5. Select "Library" as "Destination Folder".

We strongly recommend that you do not add your own files to the "Discngine" folder as we may update it in future versions and you may have problems updating our files while keeping yours.

Update the TIBCO Spotfire® services

Please follow instructions from the official documentation in order to update your TIBCO Spotfire® Web Player services.

Recommendations about the TIBCO Spotfire® Web Player configuration

We strongly recommend to configure HTTPS in order to secure the communication between clients and TIBCO Spotfire® Server. Please follow the official documentation.

Also, the FQDN (Fully Qualified Domain Name) must be used to reference the TIBCO Spotfire® server to avoid browser security issues (cross-site scripting).

Configuration of the Discngine Connector in TIBCO Spotfire®

1. Launch TIBCO Spotfire® Analyst client and log in to the TIBCO Spotfire® server (use an administrator account).
2. Open the Tools > Administration Manager.
3. Click on the "Preferences" tab.
4. For each relevant group(s) defined on your TIBCO Spotfire® server, and for each Discngine Connector product you have, do the following configurations (see the official documentation to have details on the group administration).

Discngine Client Automation

Edit the configuration of "DiscngineWebPanel", then:

• BaseURL: [mandatory] the target URL for the Client Automation. This is the URL that will be loaded in the Web Panel. If you want to use the SWAPP, set it to:

  http(s)://[server]:[port]/discngine/swapp
  

  Otherwise, to point to the "Default Client Automation Home Page", set it to:

  http(s)://[server]:[port]/protocols/Discngine/TIBCO%20Spotfire%20Enabled%20Protocols/Client%20Automation/Default%20Client%20Automation%20Home%20Page?$redirectfile=
  

  The link can also be generated by finding the protocol in Pipeline Pilot under Protocols/Discngine/TIBCO Spotfire Enabled Protocols/Client Automation/Default Client Automation Home Page. Right click on the protocol in the explorer and select "Create Protocol Link". Then select "Show File Result" and tick "Redirected" then "Copy to Clipboard".

  

• LicenseKey: [mandatory] a license key valid for the Client Automation.

• PeriodBeforeExpiration: [optional] the number of days before the license expiration during which you will be notified.

• StartDocumentPath: [optional] a document stored in the library to open with the Discngine Web Panel.

• StartPageName: [optional] the default title of the page created with the Discngine Web Panel.

• TempFolder: [optional] the temporary folder used during the export process to generate intermediate. Do not unless in some special cases.

• UseWebViewFeature: [optional] run the WebPanel on an Edge-like browser. This is an experimental feature.

Discngine Pipeline Pilot Data Functions

Edit the Configuration of "DiscnginePipelinePilotDataFunction", then:

• DefaultLibraryPath: the default library folder to store the Pipeline Pilot Data Functions. The path uses the same rules as Windows folder (avoid special characters: : * ? “ < > |).
• LicenseKey: the license key we provided to you.
• PeriodBeforeExpiration: the number of days before the license expiration during which you will be notified.
• ServerRoot: the URL of the Pipeline Pilot server: https://[server]:[port]/
• StoreSessionIdinDoc: specifies whether or not the Pipeline Pilot session identifier should be saved in the TIBCO Spotfire® document.
• UseSBDFAsSource: if you have Pipeline Pilot Data Functions that use the STDF format as source already registered, set this preference to False, otherwise set it to True.
• XMLDBRoot: the base folder on the server where the protocols are found. Usually "Protocols" but you can set it to a subfolder if you want.

Edit the Developer Mode configuration to set a unique user/password to connect to the data function. User will not need to connect when executing a data function. Use it with caution as it is not secure at all:

• DeveloperMode (T/F): When put to true this configuration will be used, otherwise it's ignored. It's false by default.
• PipelinePilotUserName: Pipeline pilot user name to connect to.
• PipelinePilotUserPassword: Pipeline pilot user password. It's not encrypted.

Discngine Automation

Edit the configuration of "DiscngineAutomation", then:

• LicenseKey: the license key we provided to you.

The Automation Services service(s) must be restarted. Please follow the official documentation.

Deployment of the Connector Pipeline Pilot collection

The Connector Pipeline Pilot collection contains:

• a set of components,
• a set of protocols,
• the JavaScript API,
• the SWAPP,
• a debug application.

In this section you will deploy this collection, either from scratch or by updating it, and also deploy the JavaScript API 4.1 if necessary.

Installation from scratch

1. Unzip the file Discngine-Connector-PP-collection.zip from the Discngine Connector package in a short location, some protocols have long names.

2. Log in to the Pipeline Pilot server.

3. Copy the folder tibcoconn\ into the folder [scitegic_root]\apps\discngine (create the folder if it is the first Discngine collection you are installing).

4. Open the command line prompt as an administrator from the windows start menu (Right click -- execute as administrator).

5. Change the directory to [scitegic_root]\bin (or [scitegic_root]\linux_bin if you are on a Linux server).

6. Install the Discngine Connector collection executing the following command:

   .\pkgutil.exe -i discngine/tibcoconn
   

7. Linux servers only - To be able to use the SWAPP, the public folder $(sciroot)/public/Discngine/SWAPP must be accessible in reading for all users, and in writing for every user who will need to register or update protocols in the SWAPP. When installing the package, this folder and especially the menu.json file inside are created as writable. However, this will only be effective for the group to which the user performing the installation belongs. If the user is an admin, it is very likely that other users will not be able to open the document in writing. For this reason, we recommand to set the chmod value of this folder and the menu.json file to at least 766.

8. Restart the Apache Server:

   • open the Pipeline Pilot server administration page
   • navigate to Setup > Manage Server in the left pane
   • press the "Restart Apache" button

The "HTML TIBCO Spotfire Viewer" components and the SWAPP need some information about your TIBCO Spotfire® environment. You can set the values directly into the parameters of the component, or set the global properties declared for the package.

Pipeline Pilot collection upgrade

1. Unzip the file Discngine-Connector-PP-collection.zip from the Discngine Connector package in a short location, some protocols have long names.

2. Log in to the Pipeline Pilot server.

3. Uninstall the Discngine Connector collection by executing the following command:

   .\pkgutil.exe -u discngine/tibcoconn
   

4. Backup or remove the folder [scitegic_root]\apps\discngine\tibcoconn.

5. Copy the folder discngine\tibcoconn from the package to [scitegic_root]\apps\discngine.

6. Open the command line prompt as an administrator from the windows start menu (Right click -- execute as administrator).

7. Change the directory to [scitegic_root]\bin (or [scitegic_root]/linux_bin if you are on a Linux server).

8. Install the Discngine Connector collection by executing the following command:

   .\pkgutil.exe -i discngine/tibcoconn
   

9. If they still exist, uninstall the following collections and remove their folders from [scitegic_root]\apps\discngine:

   .\pkgutil.exe -u discngine/tibcoconn_examples
   .\pkgutil.exe -u discngine/design
   

10. If you upgrade from version 5.x to 5.2, the Pipeline Pilot server must be restarted.

11. Make sure all required Global Properties are set in the server setup section.

12. Linux servers only - To be able to use the SWAPP, the public folder $(sciroot)/public/Discngine/SWAPP must be accessible in reading for all users, and in writing for every user who will need to register or update protocols in the SWAPP. When installing the package, this folder and especially the menu.json file inside are created as writable. However, this will only be effective for the group to which the user performing the installation belongs. If the user is an admin, it is very likely that other users will not be able to open the document in writing. For this reason, we recommand to set the chmod value of this folder and the menu.json file to at least 766.

13. Restart the Apache Server:

    • open the Pipeline Pilot server administration page
    • navigate to Setup > Manage Server in the left pane
    • press the "Restart Apache" button

Global Properties

In the administration portal, go to Setup > Global Properties and set the value of the following global properties for the package Discngine/Discngine TIBCO Spotfire Connector:

Backward compatibility with the Discngine Connector 4.1

To ensure the backward compatibility with your protocols developped with the Discngine Connector 4.1, you should also copy the JavaScript API 4.1 into the Pipeline Pilot Collection:

1. Unzip the file Discngine-Connector-js-api-4.1.zip from the Discngine Connector package.
2. Copy the content on the Pipeline Pilot server to this location: [scitegic_root]\apps\discngine\tibcoconn\web\js\.

TIBCO Spotfire® Automation Services

The Automation Services can be used in two different ways: using the Client Job Sender tool, or using the REST API. The use of these two solutions is described below.

The Client Job Sender is an executable compatible with Windows only, and that will be hosted on the Pipeline Pilot server. This solution requires the deployment of the Client Job Sender tool, its configuration and a little configuration in the Connector.

Using the REST API, available from the TBCO Spotfire® 7.13, requires no deployment, just a little configuration on the Spotfire server and in the Connector.

We strongly recommend using the REST API because it is more secure and easier to set up.

The Client Job Sender tool

The TIBCO Spotfire® Client Job Sender must be installed on the Pipeline Pilot server. Please note that this tool is compatible with Windows servers only.

The Job Sender tool and its configuration file are downloaded as part of the Automation Services bundle. To install and configure them, follow these steps:

1. Copy the two files Spotfire.Dxp.Automation.ClientJobSender.exe and Spotfire.Dxp.Automation.ClientJobSender.exe.Config in the same directory on the Pipeline Pilot server ([ClientJobSender directory]).

2. Fill the configuration file Spotfire.Dxp.Automation.ClientJobSender.exe.Config with your settings. Set at least the user name and its password. This user must be a member of the TIBCO Spotfire® group Automation Services Users. For more details about this configuration file, see the official documentation.

Now, a global property must be set for the "Run Client Job Sender" Pipeline Pilot component:

1. Open the Pipeline Pilot server administration page.
2. Navigate to Setup > Global Properties in the left panel.
3. Choose "Discngine/Discngine TIBCO Spotfire Connector" into the package list.
4. Fill the Client Job Sender executable path in the property "JobSenderPath".

The Automation Services REST API

From TIBCO Spotfire® version 7.13 a REST API is available to trigger Automation Services jobs from an external application. The official documentation is here.

This API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server. In this section, we will register a client to obtain the credentials needed in the Connector components to use the REST API. There will be two steps: the first one must be done by a TIBCO Spotfire® administrator, the other by a Pipeline Pilot administrator.

On the TIBCO Spotfire® side

1. On the computer running TIBCO 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. Export the active server configuration (the configuration.xml file) by using the export-config command. Example:

   > .\config export-config
   

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

   > .\config register-api-client --name="AutomationServicesAPIClient" -S"api.rest.automation-services-job.execute" --client-profile=other -Gclient_credentials
   

   The "--name" parameter may have a different value than the one given as an example, but 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. Examples:

   > .\config list-oauth2-clients
   # Basic information on registered clients, including the <Client ID>
   > .\config show-oauth2-client -i <Client ID>
   

4. After successful completion of the command register-api-client, the Client ID and the Client Secret will be shown. They must be communicated to the Pipeline Pilot administrator.

5. After you have finished running commands, upload the modified configuration back to the TIBCO Spotfire® database by using the import-config command. The configuration that you import becomes the active configuration for that server or cluster. Example:

   > .\config import-config --comment="what was changed"
   

6. Restart TIBCO Spotfire® Server, refer to the official documentation if needed.

On the Pipeline Pilot side

To complete the setup of the Connector to use the Automation Services REST API, you now just have to fill the Client ID and the Client Secret previously generated into Package-defined Global Protocol Properties.

1. Open the Pipeline Pilot server administration page.
2. Navigate to Setup > Global Properties in the left panel.
3. Choose "Discngine/Discngine TIBCO Spotfire Connector" into the package list.
4. Fill the Client ID in the property "AutomationServicesClientID".
5. Fill the Client Secret in the property "AutomationServicesClientSecret".

REST API to Upload SBDF Files to the TIBCO Spotfire® Library

Available from TIBCO Spotfire® version 10.2, the Library REST API lets external applications upload Spotfire Binary Data Format (SBDF) files to the Spotfire library. The official documentation is here.

This API uses the OAuth 2.0 protocol for authentication and authorization, with the Spotfire Server itself as Authorization Server. In this section, we will register a client to obtain the credentials needed in the Connector components to use the REST API. There will be two steps: the first one must be done by a TIBCO Spotfire® administrator, the other by a Pipeline Pilot administrator.

On the TIBCO Spotfire® side

1. On the computer running TIBCO 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. Export the active server configuration (the configuration.xml file) by using the export-config command. Example:

   > .\config export-config
   

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

   > .\config register-api-client --name="LibraryUploadAPIClient" -S"api.rest.library.upload" --client-profile=other -Gclient_credentials
   

   The "--name" parameter may have a different value than the one given as an example, but 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. Examples:

   > .\config list-oauth2-clients
   # Basic information on registered clients, including the <Client ID>
   > .\config show-oauth2-client -i <Client ID>
   

4. After successful completion of the command register-api-client, the Client ID and the Client Secret will be shown. They must be communicated to the Pipeline Pilot administrator to be set in the Global Properties section.

5. After you have finished running commands, upload the modified configuration back to the TIBCO Spotfire® database by using the import-config command. The configuration that you import becomes the active configuration for that server or cluster. Example:

   > .\config import-config --comment="what was changed"
   

6. Restart TIBCO Spotfire® Server, refer to the official documentation if needed.

On the Pipeline Pilot side

To complete the setup of the Connector to use the Library Upload REST API, you now just have to fill the Client ID and the Client Secret previously generated into Package-defined Global Protocol Properties.

1. Open the Pipeline Pilot server administration page.
2. Navigate to Setup > Global Properties in the left panel.
3. Choose "Discngine/Discngine TIBCO Spotfire Connector" into the package list.
4. Fill the Client ID in the property "LibraryUploadClientID".
5. Fill the Client Secret in the property "LibraryUploadClientSecret".

The Discngine Authenticator

Overview

With the Discngine Authenticator, end-users are authenticated using their Pipeline Pilot credentials, preserving the default authentication mechanism (NTLM, OpenID, Database, ...).

To do that, the Discngine Authenticator extends the TIBCO Spotfire® external authentication by checking the user ID against the Pipeline Pilot server using the Pipeline Pilot session ID.

TIBCO Spotfire® will get the Pipeline Pilot cookie in the browser containing the Pipeline Pilot Session ID. This cookie is generated by Pipeline Pilot, its name is the concatenation of the string 'SCISID' and the HTTP port, that is commonly 'SCISID9944'. If this session ID is correct, the Pipeline Pilot server will return the username and the domain to use on the TIBCO Spotfire® server.

Deployment

The Authenticator consists of a set of jar files. In this section, you will first copy these files to the dedicated location on TIBCO Spotfire® server, then configure the Spotfire external authentication.

So first of all, unzip the file Discngine-Connector-Authenticator-Spotfire[7|10].zip from the Discngine Connector package corresponding to your version of Spotfire and paste all the .jar files on the TIBCO Spotfire® server at the location [SpotfireServerDirectory]\tomcat\webapps\spotfire\WEB-INF\lib​\.

Then the TIBCO Spotfire® authentication must be configured. On the server, follow these steps:

• Open the TIBCO Spotfire® Server Configuration Tool.
• In the Configuration tab, go to the External Authentication page.
• Enable the external authentication.
• Choose the type "Custom Authenticator".
• Enter "com.discngine.PipelinePilotAuthenticator" as the Authenticator class name.
• Add the "pipeline_pilot_url" parameter. The value should be the URL of the Pipeline Pilot server, using the Fully Qualified Domain Name (for instance https://myPPserver.myDomain.com:9943).
• Add the "pipeline_pilot_port" parameter. The value should be the HTTP port of the Pipeline Pilot server (commonly 9944).