# 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](../../../caplin-trader/4/watchlist-api/index.md).

Transformer hosted watchlists are available from version 6.2.2 of the CPB_WatchlistService blade. Prior to version 6.2.2, watchlist configurations were persisted to the Webcentric database. Support for [Webcentric](../../../caplin-trader/4/webcentric/index.md)-persisted watchlists is disabled by default from version 6.2.2 of the CPB_WatchlistService blade, but may be [re-enabled](#re-enable-support-for-webcentric-persisted-watchlists) if required.

## Requirements

To use Transformer hosted watchlists, you will need:

* Transformer 6.2.3 or greater
* CPB_WatchlistService 6.2.2 or greater

## Installing the service

To install Transformer’s Watchlist Service:

1. [Activate the Persistence Service](#activate-the-persistence-service)
2. [Deploy the Watchlist Service blade](#deploy-the-watchlist-service-blade)
3. +[Optional]+ [Re-enable support for Webcentric-persisted watchlists](#re-enable-support-for-webcentric-persisted-watchlists)
4. [Configure permissioning](#configure-permissioning)

### Activate the Persistence Service

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

See [Activating the Persistence Service](transformer-activating-the-persistence-service.md), in conjunction with the notes below:

* Of the Persistence Service’s two blades, only the PersistenceService blade must be activated.
* With regard to the Persistence Service’s database schema: 
  * the size of the 'key' column must be at least 100 characters.
  * the size of the 'value' column must be calculated with regard to the maximum number of watchlist entries supported by your applications. As a rough guide, a watchlist of eight currency pairs serialises to approximately 350 characters.

### Deploy the Watchlist Service blade

The Watchlist Service is packaged as an optional Caplin-supplied [Service blade](../deployment-framework/cdf-blade-types.md#service-blade), CPB_WatchlistService-<version>.zip.

For instructions on how to deploy a service blade, see [Deploy a Caplin supplied blade](../deployment-framework/cdf-deploy-a-caplin-supplied-blade.md).

### Re-enable support for Webcentric-persisted watchlists

Support for [Webcentric](../../../caplin-trader/4/webcentric/index.md)-persisted watchlists is disabled by default from version 6.2.0 of the Watchlist Service. If you intend to run both Webcentric and Transformer persisted watchlists during a transition period, you must re-enable support for Webcentric-persisted watchlists.

To re-enable support for Webcentric-persisted watchlists, 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](../liberator/liberator-user-authentication-and-permissioning.md).

#### 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](https://docs.caplin.com/developer/api/cis/latest/com/caplin/permissioning/package-summary.html).

```java
// 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:**

* [Caplin Trader 4: Watchlist API](../../../caplin-trader/4/watchlist-api/index.md)
* [Caplin Deployment Framework](../deployment-framework/index.md)