Create new protocols

  • Updated on Feb 21, 2025
  • 5 minute(s) read
  • CW
 Prev Next

Pipeline Pilot collection

The Pipeline Pilot protocols designed for the SWAPP use components from the Connector collection and output an HTML file. These components generate some JavaScript code calling the Connector API and the file combines all these calls together. This file is read by the SWAPP and parsed in the result page. The JavaScript code is then executed and allows the interaction with the current Spotfire document.

SWAPP example protocols

Example Protocols are available under Protocols\Discngine\Spotfire Enabled Protocols\Client Automation\SWAPP Examples. Those are a good starting point to help you understand the way the SWAPP proceed.

Template Protocols can be used by clicking File > New Protocol from Template and selecting a protocol from the 'Discngine SWAPP' folder.

SWAPP components

The SWAPP is bundled with a few components to manipulate the data easily.

Data Table Reader Data Table Reader

When using the "TIBCO Spotfire Data Table" input type, the data table selected by the user will be uploaded to the job directory or synced if the Real Time Synchronization is on. This component takes as input parameter the name of the data table and will simply retrieve the uploaded SBDF file from the relevent source.

SWAPP HTML Fragment SWAPP HTML Fragment

This component is used to compile all the calls from the Connector 5.0 components to HTML and javascript. You can chose to either create an HTML file automatically or use the generated HTML in the pass port if you wish to use it further. If you use any of the Connector components in your protocol, the SWAPP HTML Fragment component must be used for the SWAPP to be able to execute your updates.

Send Options to SWAPP Form Send Options to SWAPP Form

When using a REST API Resource input type, you can specify a Pipeline Pilot protocol as endpoint for the API Resource.
When doing so, the protocol must be callable through HTTP and must return a JSON response containing either an Array of values (number or strings) or an array of objects with at least a value key and optionally a label key. To help you implement the response, you can use the Send Options to SWAPP Form component and pipe it all the records you want to send, with at least a value parameter specified. Then, simply define a Result Parameter in the Web Service tab of the protocol settings with the same name as that you used in the Send Options to SWAPP Form, and with type Byte Array.

You can find example REST Endpoints in the SWAPP Examples folder, like REST Resource and REST Resource for Property Calculation.

More detailed instructions can also be found in the tutorial.

Update Synchronization Cache Data Update Synchronization Cache Data

When using the Real Time Synchronization, data tables are uploaded to Pipeline Pilot and kept in sync in the cache. If your protocol updates your data table, for example by adding columns, the next call to the Real Time Synchronization API will cause the whole data table to be synced with Pipeline Pilot. To prevent this and speed up your protocols, you can use the Update Synchronization Cache Data component to enforce caching data once it has been modified. You can find example usage in the Example Protocols of the SWAPP.

Protocol's layout

General layout

The protocol should respect a general layout which can include the following steps:

General protocol layout in Pipeline Pilot

  1. Input and preprocess data: To get data from a data table in the current Spotfire document, use the Data Table Reader component. Each row will be read and passed to the next component. If you only need a reference to a data table in the Spotfire document, use the Input Data Table component.
  2. Process data: Process each record, using native Pipeline Pilot components.
  3. Edit data: Apply data modifications to the current Spotfire document using components such as Add Data Table from Data Flow or Add Columns from Data Flow.
  4. Edit document: Add visualizations and pages using respectively visualization components and Add Page component.
  5. Compile Javascript: Use the SWAPP HTML Fragment component is used to translate all the instructions from the Connector Components to the corresponding calls of the Connector JavaScript API. The output HTML and JavaScript are written into an output.html file. This file will be loaded by the SWAPP, its HTML displayed in the result page and its JavaScript executed.

Example

This example protocol is available under Discngine/TIBCO Spotfire Enabled Protocols/Client Automation/SWAPP Examples/Add SMILES to Data Table. It takes an input table containing molecular records, computes the SMILES of each record and adds them either as a new column or a new data table. To test it, you can use the data table created by the Load Maybridge example protocol.

Example protocol in Pipeline Pilot

The protocol can be split into 4 steps:

  1. We use the Data Table Reader component. Each row will be read and passed to the next component.
  2. We process each row, calculate SMILES and add it to the input data.
  3. Depending on the user's choice, we either add the new columns to the input table or add a new table. Let's focus on the first option. We subsequently call the Add Data Columns Template and Table Plot components which respectively add the new columns and draw/update the Table plot.
  4. The SWAPP HTML Fragment component is used to generate the HTML and JavaScript code which will be executed from the result page of the protocol.

Layout rules

Two main rules needs to be followed when designing a protocol for the SWAPP:

  • The visualization components are preceded by a reference of their main data table
  • The page components are preceded by the visualizations they will include

Examples

Protocol layout example 1

This example protocol:

  • Adds "Page 1" with:
    • "Bar Chart" on "Table 1"
    • "Table Plot" on "Table 1"
  • Adds "Page 2" with:
    • "Scatter Plot" on "Table 1"

Protocol layout example 2

This example protocol:

  • Adds "Page 1" with:

    • "Bar Chart" on "Table 1"
    • "Table Plot" on "Table 2"

  • Adds "Page 2" with:

    • "Scatter Plot" on "Table 2"

    Protocol's parameters

Parameters available at the protocol level will be available in the corresponding protocol in the SWAPP.

Protocol parameters in Pipeline Pilot vs in SWAPP

Known limitations:

  • Indexed grouped parameters cannot be used dynamically in the SWAPP
  • Parameter scripts are not understood by the SWAPP