Installing the Watchlist Service

The Watchlist Service is a Transformer module that provides server-hosted, persisted watchlists that can be shared between a user’s devices.

To connect to the Watchlist Service from your client application, use Caplin Trader’s Watchlist API.

If you are upgrading from Transformer 6 to Transformer 7, see Upgrading to Caplin Platform 7. There are breaking changes between Watchlist Service 6 and Watchlist Service 7.

Requirements

The Watchlist Service you need depends on the version of Transformer you deploy:

Transformer Supported Watchlist Service

7.1.3+

7.1+

7.0 to 7.1.2

7.0+

6.2†

6.2

† The Watchlist Service is not supported on versions of Transformer earlier than 6.2.3.

Upgrading to the Watchlist Service 7

Summary of important changes in the Watchlist Service 7:

  • Support for Webcentric-persisted watchlists has been discontinued.

  • The Watchlist Service 7 persists watchlists to a new database table. To preserve users' saved watchlists, you must migrate data to this new table.

For detailed upgrade instructions, see Upgrading to the Caplin Platform 7.

Deploying the Watchlist Service 7

To install Transformer’s Watchlist Service 7:

  1. Activate and configure Transformer 7’s Persistence Service. See Activating the Persistence Service 7.

  2. Copy the Watchlist Service 7 installation kit to your Deployment Framework’s kits/ directory

  3. Run the command below from the root of your Deployment Framework to deploy the Watchlist Service:

    ./dfw deploy

  4. If you have configured the Persistence Service to persist data to a relational database server, create the database tables required by the Watchlist Service.

    A reference DDL script for SQLite can be found at kits/WatchlistService/Transformer/etc/bootstrap.sql. Adapt this script to the syntax and data types of your relational database server.

    File: kits/WatchlistService/Transformer/etc/bootstrap.sql
    CREATE TABLE IF NOT EXISTS TF_WATCHLIST_PERSISTENCE (
    WATCHLIST_USER VARCHAR(250) NOT NULL,
    WATCHLIST_ID VARCHAR(250) NOT NULL,
    WATCHLIST_DATA TEXT NOT NULL, (1)
    WATCHLIST_POSITION NUMBER, (2)
    PRIMARY KEY (WATCHLIST_USER, WATCHLIST_ID)
);

CREATE TRIGGER IF NOT EXISTS TF_WATCHLIST_PERSISTENCE_ADD_POSITION (3)
    AFTER INSERT ON TF_WATCHLIST_PERSISTENCE
FOR EACH ROW WHEN NEW.WATCHLIST_POSITION IS NULL
BEGIN
    UPDATE TF_WATCHLIST_PERSISTENCE
        SET WATCHLIST_POSITION = (
            SELECT COUNT(*) - 1
            FROM TF_WATCHLIST_PERSISTENCE
            WHERE WATCHLIST_USER = NEW.WATCHLIST_USER
        )
    WHERE rowid = NEW.rowid;
END;
    1 For WATCHLIST_DATA, choose a high-capacity character type such as TEXT or CLOB.
    2 For WATCHLIST_POSITION, choose an integer type.
    3 The name of the trigger is arbitrary. Customise it to suit the limits of your database. For example, trigger names in Oracle cannot be longer than 32 characters.
    Do not skip the creation of the database trigger. The trigger is essential to the correct operation of the Watchlist Service.

  5. Run the command below from the root of your Deployment Framework to restart components in your framework:

    ./dfw start

Deploying the Watchlist Service 6

To install Transformer’s Watchlist Service 6:

  1. Activate and configure Transformer 6.2’s Persistence Service. See Activating the Persistence Service 6.2.

  2. Copy the Watchlist Service 6 installation kit to your Deployment Framework’s kits/ directory

  3. Run the command below from the root of your Deployment Framework to deploy the Watchlist Service:

    ./dfw deploy

  4. Run the command below from the root of your Deployment Framework to restart components in your framework:

    ./dfw start

  5. To re-enable support for Webcentric-persisted watchlists in the Watchlist Service 6.2, edit the file <Framework-root>/global_config/overrides/WatchlistService/blade_config/watchlist.conf and set the configuration macro USE_COMPATIBLE_WATCHLIST to ENABLED.

    define USE_COMPATIBLE_WATCHLIST      ENABLED

Configure permissioning

To allow users to interact with the Watchlist Service, configure Liberator’s Permissioning Service according to the specification below. For more information about permissioning, see User Authentication and Permissioning.

Rules

Define a rule that triggers when users contribute messages to the watchlist control subject. The strings used for the 'permission namespace' and 'action' are arbitrary; you are free to customise them to your own naming scheme.

Message Subject Rule Type Permission Namespace Action Action Ref Product Ref

^/PRIVATE/WATCHLIST/%u/CONTROL

WRITE

WATCHLIST

WATCHLIST_OPERATION

-

ALL_PRODUCTS

Permissions

Assign users the following permissions.

Product set Permission Namespace Action Authorisation

.*

WATCHLIST

WATCHLIST_OPERATION

ALLOW

^/PRIVATE/WATCHLIST/%u/.*

-

VIEW

ALLOW

^/FILTER/PRIVATE/WATCHLIST/%u/.*

-

VIEW

ALLOW

Java Permissioning Integration API example

See the code below for an example of how to set the rules and permissions using the Java Permissioning Integration API.

// Rules
permissioningDataSource.createActionRule("^/PRIVATE/WATCHLIST/%u/CONTROL",
    "WATCHLIST", "WATCHLIST_OPERATION", Constants.ALL_PRODUCTS);

// WRITE permissions
java.util.HashSet<String> allProducts = new java.util.HashSet<String>();
allProducts.add(".*");
user.permit(allProducts, "WATCHLIST", "WATCHLIST_OPERATION");

// VIEW permissions
java.util.HashSet<String> viewProductSets = new java.util.HashSet<String>();
viewProductSets.add("^/PRIVATE/WATCHLIST/%u/.*");
viewProductSets.add("^/FILTER/PRIVATE/WATCHLIST/%u/.*");
user.permit(viewProductSets, Constants.DEFAULT_PERMISSION_NAMESPACE, "VIEW");

See also: