Installing the Watchlist Service

The Watchlist Service provides server-hosted, persisted watchlists that can be shared between a user's devices. To use the Watchlist Service in your client application, use Caplin Trader's Watchlist API.

If you are upgrading to Caplin Platform 7, see Upgrading to Caplin Platform 7.



Transformer version required:

  • Watchlist Service 7 requires Transformer 7
  • Watchlist Service 6.2 (minimum 6.2.2) requires Transformer 6.2 (minimum 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.

Installing the service

To install Transformer's Watchlist Service: 

  1. Activate and configure Transformer's Persistence Service
  2. Deploy the Watchlist Service blade

1. Activate and configure Transformer's Persistence Service

The Watchlist Service is dependent on the Persistence Service, which is included with Transformer 6.2.3 and later.

For Transformer 6.2.3+:

  1. Activate the Persistence Service. See Activating the Persistence Service 6.2.
  2. Check the column widths of the Persistence Service's database table, and alter the database table if required.
    1. The key column must be at least 100 characters wide
    2. The value column must be wide enough to accommodate the serialised form of the largest watchlists in your application. As a guide, a watchlist of eight currency pairs serialises to approximately 350 characters.

For Transformer 7.0+:

  1. Activate the Persistence Service. See Activating the Persistence Service 7.
  2. If you are using database-backed persistence (recommended), create the table and trigger required by the Watchlist Service 7.
    1. To create the table and trigger, adapt the Watchlist Service's SQLite bootstrap script to the SQL syntax of your database. The bootstrap script can be found within the Watchlist Service's deployment kit: <blade-root>/Transformer/etc/bootstrap.sql
    2. Warning: do not skip the creation of the database trigger. The trigger is essential to the correct operation of the Watchlist Service.

2. Deploy the Watchlist Service blade

The Watchlist Service is packaged as an optional Caplin-supplied Service blade, CPB_WatchlistService-<version>.zip.

For instructions on how to deploy a service blade, see Deploy a Caplin-supplied blade.

Re-enable Webcentric support (6.2 only)

Webcentric-persisted watchlists were deprecated from version 6.2.2 of the Watchlist Service, and discontinued from version 7 of the Watchlist Service.

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.


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.


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


Assign users the following permissions.

Product set Permission Namespace Action Authorisation

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

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

// VIEW permissions
java.util.HashSet<String> viewProductSets = new java.util.HashSet<String>();
user.permit(viewProductSets, Constants.DEFAULT_PERMISSION_NAMESPACE, "VIEW");

See also: