Set Refiner user permissions and subject mappings

In deployments where a Permissioning Adapter supplies user permissions and subject mappings, you need to set up additional permissions and subject mappings when Caplin Refiner is used to filter or sort container subscriptions.

Setting user permissions

When Caplin Refiner receives a request for a filtered or sorted container, it requests the base container from the providing DataSource application (which is typically an Integration Adapter). For example, if Caplin Refiner receives a request for:

/FILTER/CTR/FI/ALL?filter=(CpnRate>5)

it requests the following base container from the providing DataSource application:

/CTR/FI/ALL

When the base container is returned, Caplin Refiner requests the constituent records of the container, and then applies the filter (in this example CpnRate>5) before responding to the container request.

This means that you must permission users to allow access to:

  • The constituent records of the base container.

  • The unfiltered container subject /CTR/FI/ALL

  • The filtered container subject prefix /FILTER/*

    The /* at the end of /FILTER means that users are permissioned for all filtered container subjects.

In this example, users could be permissioned just for the specific filtered container subject /FILTER/CTR/FI/ALL instead of the generic subject prefix /FILTER/*

You would typically use a Permissioning Adapter to either set up the required permissions itself, or obtain them from some other permissioning system; Liberator’s Permissioning Auth module then obtains the permissions from the Adapter and acts on them according to their settings. For more about this, see The Permissioning Auth module and Permissioning Adapters on the Liberator User authentication and permissioning page. You implement a Permissioning Adapter using the Permissioning API of the Caplin Integration Suite.

Setting subject mappings

Subject mapping (also called object mapping) allows Liberator to change the subject of a record before requesting it from the providing DataSource application. You can do this through configuration, as explained in Liberator’s Object mapping concept page, or you can implement more sophisticated mappings in the Liberator’s auth module (see Liberator User authentication and permissioning).

If the records of a container have their subjects mapped, or the container subject itself is mapped, Caplin Refiner must also apply these mappings if it filters or sorts the container.

When a container and/or its contents have their subjects mapped, the user must be permissioned to access the modified subjects rather than the original subjects.

Subject mapping suffixes

Suffix mappings are typically used to support price tiering. Price tiering allows users to receive different prices for the same instrument depending on the price band each user is in.

As an example, consider a client sending Liberator a request for the container /CTR/FI/ALL. The Liberator’s auth module can add to each of the instrument names in the container a suffix indicating the user’s price tier. For example, the subject /FI/US/A is mapped to /FI/US/A/TIER1. The Integration Adapter that supplies the instruments for /CTR/FI/ALL therefore sends back the price data for /FI/US/A/TIER1. Another user who is in a different price tier (TIER2) would receive the price for /FI/US/A/TIER2. The "tier" suffix isn’t visible to the user, because Liberator strips it from the subject names before sending the container contents back to the client.

If the container is to be filtered and/or sorted by Refiner, Refiner must be told about the mapping too. So when you code the Liberator’s Permissioning Auth module, as well as mapping the subject names of the instruments in the container, you must add some mapping information to the /FILTER request that’s sent to Refiner. In this example, the subscription request for the container therefore becomes:

/FILTER/CTR/FI/ALL/?filter=(bid>3);mapsuffix=/TIER1

The ;mapsuffix=/TIER1 at the end of the subscription request tells Refiner to add the suffix /TIER1 to the subjects of the container records and subscribe to those subjects on the relevant Integration Adapter(s). So if the record /FI/US/A/TIER1 matches the filter, Refiner returns this record to Liberator.

For more about how to implement subject mapping in Liberator’s Permissioning Auth module, see the SubjectMapper interface.

Subject mapping prefixes

An alternative way to map subject names is by adding prefixes. For example, if a client sends Liberator a request for the container /CTR/FI/ALL, the Liberator’s auth module could add the prefix /CUSTOMERTYPE1, to create a request for /CUSTOMERTYPE1/CTR/FI/ALL This container subscription request is directed to an Integration Adapter that supplies containers for "Type 1" customers only; a separate Adapter provides containers for "Type 2" customers, and so on.

The prefix is also added to the subject names of the individual container records. So if /CUSTOMERTYPE1/CTR/FI/ALL contains the record /FI/US/A, this record subject is mapped to /CUSTOMERTYPE1/FI/US/A and the record is requested from the Integration Adapter that supplies the FI instruments for "Type 1" customers.

As in the case of subject mapping suffixes, if the container is to be filtered and/or sorted by Refiner, Refiner must be told about the mapping too. So when you code the Liberator’s Permissioning Auth module, as well as mapping the container subject, and the subject names of the instruments in the container, you must add mapping information to the /FILTER request that’s sent to Refiner. In this example, the subscription request for the container therefore becomes:

/FILTER/CTR/FI/ALL/?filter=(bid>3);mapprefix=/CUSTOMERTYPE1

The ;mapprefix=/CUSTOMERTYPE1 at the end of the subscription request tells Refiner to add the prefix /CUSTOMERTYPE1 to the subjects of the records for container /CUSTOMERTYPE1/CTR/FI/ALL and subscribe to those subjects on the relevant Integration Adapter(s). So if the record /CUSTOMERTYPE1/FI/US/A matches the filter, Refiner returns this record to Liberator.

The subject mapping prefix is added to the container subject itself as well as to the subject of each record in the container. By contrast, a subject mapping suffix is only added to the subjects of the container’s records.
For more about how to implement subject mapping in Liberator’s Permissioning Auth module, see the SubjectMapper interface.

See also: