Caplin Trader 4.8.0

Interface: module:caplin/services/security/PermissionService

module:caplin/services/security/PermissionService

This class returns permissioning data for the currently logged in user. This class allows you to query the product permissions of the currently logged in user, or the permissions they have when they are trading on behalf of another user.

The methods of the PermissionService class fall into three distinct categories. Methods in the first category return permissioning data when called. This category can be used by the classes of your application that respond to user interactions. An example of where this category could be employed would be in the code that responds to user attempts to open a trade ticket. In this case the permission is determined when the user initiates the action.

Methods that return permissioning data when called are:

Methods in the second category allow you to register listeners that subscribe to current and future product permissions. This category can be used to register the classes of your application that need to be notified when user permissions change.

An example of where this category would be employed is in the code responsible for displaying trade tiles. Trade tiles are typically grouped in one or more panels on the screen and are always on display. If a user permission changes, this may require the status of one or more trade tiles to change; for example, the button that allows the user to trade from the tile may need to be disabled. By attaching a permission listener to the tile its status can be changed independently of what the user is doing; it is not be necessary for the user to initiate an action on the trade tile for the change in permission to take effect.

Methods that register or remove listeners are:

Methods in the third (and final) category allow you to retrieve user attributes. A user can be assigned any number of attributes in the form of name/value pairs. User attributes are not processed by the Permissioning Auth Module and therefore do not affect permissioning directly. A typical use would be to send information to Caplin Trader about the maximum tradable amount that a user is permitted to trade. Your application could then use this information to limit the tradeable amounts shown to the user.

Methods that return the value of a user attribute when called are module:caplin/security/permissioning/PermissionService#getUserAttribute and module:caplin/security/permissioning/PermissionService#getToboUserAttribute. Methods that register a subscription listener to current and future values of a user attribute are module:caplin/security/permissioning/PermissionService#addAttributeListener and module:caplin/security/permissioning/PermissionService#addToboUserAttributeListener.

Trading on behalf of (TOBO)

When a logged in user is 'trading on behalf of' (TOBO) another user, the permissions that are sent to and cached by the permissioning library depend on the permissioning mode the Permissioning Auth Module is configured to run in.

If the permissioning mode is SalesUser, only permissions for the logged in user are sent to the permissioning library. In this mode, the methods that return product permissions always return permissions for the logged in user, even if that user is trading on behalf of another user.

If the permissioning mode is SalesIntersectCustomerUser, permissions for both the logged in user and the user they are trading on behalf of are sent to and cached by the permissioning library. In this mode, the permissions returned by the methods of this class are the logical AND of the logged in user and the user they are trading on behalf of.

For permissions that reside in specified namespaces, the permissioning library can be configured to return permissions for the logged in user only, even if that user is trading on behalf of another user and the permissioning mode is SalesIntersectCustomerUser. For further information about setting up this configuration, refer to the document Caplin Trader: Permissioning Configuration XML Reference.

Implementations:

Members

(static, readonly) ALL :String

A constant that is passed to module:caplin/security/permissioning/PermissionService#addPermissionSetListener to indicate that the listener is subscribing to 'ALL' permissions.
Type:
  • String
Implementations:
  • module:caplin/services/testing/PermissionServiceStub.ALL

(static, readonly) ALL_ACTIONS :String

A constant that is passed to module:caplin/security/permissioning/PermissionService#addPermissionSetListener to indicate that the listener is subscribing to 'all actions'.
Type:
  • String

(static, readonly) ALL_PRODUCTS :String

A constant that is passed to module:caplin/security/permissioning/PermissionService#addPermissionSetListener to indicate that the listener is subscribing to 'all products'.
Type:
  • String

(static, readonly) ALLOW :String

A constant that is passed to module:caplin/security/permissioning/PermissionService#addPermissionSetListener to indicate that the listener is subscribing to 'ALLOW' permissions.
Type:
  • String
Implementations:
  • module:caplin/services/testing/PermissionServiceStub.ALLOW

(static, readonly) DENY :String

A constant that is passed to module:caplin/security/permissioning/PermissionService#addPermissionSetListener to indicate that the listener is subscribing to 'DENY' permissions.
Type:
  • String
Implementations:
  • module:caplin/services/testing/PermissionServiceStub.DENY

(static, readonly) NO_PERMISSION :String

A constant that indicates that the item has no permissions.
Type:
  • String

Methods

addAttributeListener(attributeName, listener)

Registers a listener that subscribes to current and future values of a single user attribute. After calling this method, the registered listener will be notified of the value of the user attribute.

This is the value assigned to the logged in user. To be notified of the value assigned to the user they are trading on behalf of, call module:caplin/security/permissioning/PermissionService#addToboUserAttributeListener instead.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onAttributeChanged, which is called when the listener is first registered and also when the value of the attribute changes.

Parameters:
Name Type Description
attributeName string The name of the user attribute that you want to subscribe to.
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:

addGlobalPermissionListener(product, action, listener) → {int}

Registers a listener that subscribes to current and future permissions for an action on a single product in the global (default) namespace. After calling this method, the registered listener will be notified of the permission that the user has for the requested action on the specified product.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onSinglePermissionChanged, which is called when the listener is first registered and also when the product permission changes.

Note: If you want to specify a different namespace, then use module:caplin/security/permissioning/PermissionService#addPermissionListener instead.

Parameters:
Name Type Description
product string The name of the product that the subscription is for (for example '/FX/EURUSD').
action string The action that the subscription is for (for example 'TRADE').
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#canUserPerformGlobalAction
  • module:caplin/security/permissioning/PermissionService#removeListener
Returns:
A unique indentifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/PermissionService#removeListener).
Type
int

addPermissionListener(product, namespace, action, listener) → {int}

Registers a listener that subscribes to current and future permissions for an action on a single product in a given namespace. After calling this method, the registered listener will be notified of the permission that the user has for the requested action on the specified product.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onSinglePermissionChanged, which is called when the listener is first registered and also when the product permission changes.

Note: If you want to specify the global (default) namespace, then use module:caplin/security/permissioning/PermissionService#addGlobalPermissionListener instead.

Parameters:
Name Type Description
product string The name of the product that the subscription is for (for example '/FX/EURUSD').
namespace string The namespace in which the product permission resides (for example 'tenors').
action string The action that the subscription is for (for example 'TRADE').
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#canUserPerformAction
  • module:caplin/security/permissioning/PermissionService#removeListener
Returns:
A unique identifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/PermissionService#removeListener).
Type
int

addPermissionSetListener(product, namespaceopt, type, listener) → {int}

Registers a listener that subscribes to a set of current and future permissions on a single product in a given namespace. You can subscribe to module:caplin/security/permissioning/PermissionService#ALL permissions, module:caplin/security/permissioning/PermissionService#ALLOW permissions, or module:caplin/security/permissioning/PermissionService#DENY permissions.

After calling this method, the registered listener will be notified of the set of actions in the given namespace for which the user has the requested permission. A typical use would be to subscribe to the set of permitted tenors on a product.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onPermissionsChanged, which is called when the listener is first registered and also when a product permission changes.

Parameters:
Name Type Attributes Description
product string The name of the product that the subscription is for (for example '/FX/EURUSD').
namespace string <optional>
 The namespace in which the product permission resides (for example 'tenors'). If null, then the permission resides in the global (default) namespace.
type string The type of permission that the subscription is for (module:caplin/security/permissioning/PermissionService#ALL, module:caplin/security/permissioning/PermissionService#ALLOW, or module:caplin/security/permissioning/PermissionService#DENY).
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#getAllowPermissions
  • module:caplin/security/permissioning/PermissionService#getAllPermissions
  • module:caplin/security/permissioning/PermissionService#getDenyPermissions
  • module:caplin/security/permissioning/PermissionService#removeListener
Returns:
A unique identifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/PermissionService#removeListener).
Type
int

addPermissionTypeListener(product, namespace, action, type, listener) → {number}

A convenience method for #addPermissionListener that allows the type to be filtered.
Parameters:
Name Type Description
product string The name of the product
namespace string The namespace in which the product permission resides
action string The action the subscription is for
type string The type of permission that the subscription is for
listener PermissionServiceListener The listener that will receive permission updates
Implementations:
Returns:
A unique identifier that allows the removal of the listener
Type
number

addProductPermissionsListener(products, namespaceopt, action, isAuthorized, listener) → {int}

Registers a listener that subscribes to current and future permissions on a set of products. You can subscribe to products for which an action is either alllowed or denied.

After calling this method, the registered listener will be notified of the subset of products for which the user has the requested permission for the requested action.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onPermissionsChanged, which is called when the listener is first registered and also when a permission changes for any product in the given set of products.

Parameters:
Name Type Attributes Description
products Array.<string> An array of strings representing the set of products that the subscription is for.
namespace string <optional>
 The namespace in which the product permission resides (for example 'tenors'). If null, then the permission resides in the global (default) namespace.
action string The action that the subscription is for (for example 'TRADE').
isAuthorized boolean The type of permission that the subscription is for (true for allowed permissions and false for denied permissions).
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#getPermissionedProducts
  • module:caplin/security/permissioning/PermissionService#getUnpermissionedProducts
  • module:caplin/security/permissioning/PermissionService#removeListener
Returns:
A unique identifier that allows the listener to be removed from the listener register (see module:caplin/security/permissioning/PermissionService#removeListener).
Type
int

addToboUserAttributeListener(attributeName, listener)

Registers a listener that subscribes to current and future values of a single user attribute. After calling this method, the registered listener will be notified of the value of the user attribute.

This is the value assigned to the user that the logged in user is trading on behalf of. To be notified of the value assigned to the logged in user, call module:caplin/security/permissioning/PermissionService#addAttributeListener instead.

The listener that you register must implement module:caplin/services/security/PermissionServiceListener#onAttributeChanged, which is called when the listener is first registered and also when the value of the attribute changes.

If the user is not trading on behalf of any other user, null is passed to the listener when it is first registered.

Parameters:
Name Type Description
attributeName string The name of the user attribute that you want to subscribe to.
listener module:caplin/services/security/PermissionServiceListener The listener object that will receive the subscription updates.
Implementations:

canUserPerformAction(product, namespace, action) → {boolean}

Determines whether an action on a product is allowed or denied in a given permissioning namespace.

Note: If you want to specify the global (default) namespace, then use module:caplin/security/permissioning/PermissionService#canUserPerformGlobalAction instead.

Parameters:
Name Type Description
product string The name of the product (for example '/FX/EURUSD').
namespace string The namespace in which the product permission resides (for example 'tenors').
action string The action on which the permission may be granted (for example 'TRADE').
Implementations:
Returns:
true if the action is allowed, false if the action is denied.
Type
boolean

canUserPerformGlobalAction(product, action) → {boolean}

Determines whether an action on a product is allowed or denied in the global (default) namespace.

Note: If you want to specify a different namespace, then use module:caplin/security/permissioning/PermissionService#canUserPerformAction instead.

Parameters:
Name Type Description
product string The name of the product (for example '/FX/EURUSD').
action string The action on which the permission may be granted (for example 'TRADE').
Implementations:
Returns:
true if the action is allowed, false if the action is denied.
Type
boolean

dispose()

Disposes of any listeners and resources that were used by the service.
Implementations:
  • module:caplin/services/testing/PermissionServiceStub#dispose

getAllowPermissions(product, namespaceopt, sortFunctionopt) → {Array.<string>}

Returns the set of actions that are allowed on a product within a given namespace. A typical use would be to retrieve the set of allowed tenors on a product.
Parameters:
Name Type Attributes Description
product string The name of the product (for example '/FX/EURUSD').
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If null, then the permissions reside in the global (default) namespace.
sortFunction function <optional>
 An optional function used to sort the list of permissions returned from the PermissionEngine, if not passed in, the permissions will be returned unsorted.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#getAllPermissions
  • module:caplin/security/permissioning/PermissionService#getDenyPermissions
  • module:caplin/security/permissioning/PermissionService#addPermissionSetListener
Returns:
An array of strings representing actions that are allowed on the product.
Type
Array.<string>

getAllPermissions(product, namespaceopt) → {Array.<string>}

Returns the entire set of permissioned actions on a product within a given namespace. The entire set includes the actions that are allowed and the actions that are denied.
Parameters:
Name Type Attributes Description
product string The name of the product (for example '/FX/EURUSD').
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If null, then the permissions reside in the global (default) namespace.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#getAllowPermissions
  • module:caplin/security/permissioning/PermissionService#getDenyPermissions
  • module:caplin/security/permissioning/PermissionService#addPermissionSetListener
Returns:
An array of strings representing all permissioned actions on the product (allowed and denied).
Type
Array.<string>

getDenyPermissions(product, namespaceopt) → {Array.<string>}

Returns the set of actions that are denied on a product within a given namespace. A typical use would be to retrieve the set of denied tenors on a product.
Parameters:
Name Type Attributes Description
product string The name of the product (for example '/FX/EURUSD').
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If null, then the permissions reside in the global (default) namespace.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#getAllPermissions
  • module:caplin/security/permissioning/PermissionService#getAllowPermissions
  • module:caplin/security/permissioning/PermissionService#addPermissionSetListener
Returns:
An array of strings representing actions that are denied on the product.
Type
Array.<string>

getPermissionedProducts(products, namespaceopt, action) → {Array.<string>}

Given a list of products, returns the subset of that list on which a specified action is allowed.
Parameters:
Name Type Attributes Description
products Array.<string> An array of strings representing the list of products being queried.
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If null, then the permissions reside in the global (default) namespace.
action string The action being queried.
Implementations:
Returns:
An array of strings representing the subset of products on which the action is permitted.
Type
Array.<string>

getToboAllowedProducts(namespaceopt, action) → {Array.<string>}

Returns the products that have 'Allow' permission for a given namespace and action.

The allowed products are always for the user that the logged in user is trading on behalf of. To get allowed products for the logged in user only, call module:caplin/security/permissioning/PermissionService#getUserAllowedProducts instead.

Parameters:
Name Type Attributes Description
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If omitted or set to null, the product permissions reside in the global (default) namespace.
action string The action that is allowed (for example '1-Week').
Implementations:
Returns:
An array of strings representing the allowed products. Each string in the array could be a JavaScript regular expression that matches more than one product. The array will be empty if the logged in user is not trading on behalf of another user.
Type
Array.<string>

getToboDeniedProducts(namespaceopt, action) → {Array.<string>}

Returns the products that have 'Deny' permission for a given namespace and action.

The denied products are always for the user that the logged in user is trading on behalf of. To get denied products for the logged in user only, call module:caplin/security/permissioning/PermissionService#getUserDeniedProducts instead.

Parameters:
Name Type Attributes Description
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If omitted or set to null, the product permissions reside in the global (default) namespace.
action string The action that is denied (for example '1-Week').
Implementations:
Returns:
An array of strings representing the denied products. Each string in the array could be a JavaScript regular expression that matches more than one product. The array will be empty if the logged in user is not trading on behalf of another user.
Type
Array.<string>

getToboUserAttribute(attributeName) → {string}

Gets the current value of a user attribute.

This is the value assigned to the user that the logged in user is trading on behalf of. To get the value assigned to the logged in user, call module:caplin/security/permissioning/PermissionService#getUserAttribute instead.

Parameters:
Name Type Description
attributeName string The name of the user attribute that you want the value of.
Implementations:
Returns:
The value of the user attribute, or null if the user is not trading on behalf of another user.
Type
string

getUnpermissionedProducts(products, namespaceopt, action) → {Array.<string>}

Given a list of products, returns the subset of that list on which a specified action is denied.
Parameters:
Name Type Attributes Description
products Array.<string> An array of strings representing the list of products being queried.
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If null, then the permissions reside in the global (default) namespace.
action string The action being queried.
Implementations:
Returns:
An array of strings representing the subset of products on which the action is denied.
Type
Array.<string>

getUserAllowedProducts(namespaceopt, action) → {Array.<string>}

Returns the products that have 'Allow' permission for a given namespace and action.

The allowed products are always for the logged in user only, even if they are trading on behalf of another user. To get allowed products for the user they are trading on behalf of, call module:caplin/security/permissioning/PermissionService#getToboAllowedProducts instead.

A typical use would be to get the users (as an array of products) that the logged in user can trade on behalf of (TOBO). By convention, the namespace of such products is 'TradeOnBehalfOf' and the action is 'ChangeTradeOnBehalfOfUser'. For further information about TOBO, refer to the document Caplin Platform: Permissioning Overview And Concepts.

Parameters:
Name Type Attributes Description
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors' or 'TradeOnBehalfOf'). If omitted or set to null, the product permissions reside in the global (default) namespace.
action string The action that is allowed (for example '1-Week' or 'ChangeTradeOnBehalfOfUser').
Implementations:
Returns:
An array of strings representing the allowed products. Each string in the array could be a JavaScript regular expression that matches more than one product.
Type
Array.<string>

getUserAttribute(attributeName) → {string}

Gets the current value of a user attribute.

This is the value assigned to the logged in user. To get the value assigned to a user they are trading on behalf of, call module:caplin/security/permissioning/PermissionService#getToboUserAttribute instead.

Parameters:
Name Type Description
attributeName string The name of the user attribute that you want the value of.
Implementations:
Returns:
The value of the user attribute.
Type
string

getUserDeniedProducts(namespaceopt, action) → {Array.<string>}

Returns the products that have 'Deny' permission for a given namespace and action.

The denied products are always for the logged in user only, even if they are trading on behalf of another user. To get denied products for the user they are trading on behalf of, call module:caplin/security/permissioning/PermissionService#getToboDeniedProducts instead.

Parameters:
Name Type Attributes Description
namespace string <optional>
 The namespace in which the product permissions reside (for example 'tenors'). If omitted or set to null, the product permissions reside in the global (default) namespace.
action string The action that is denied (for example '1-week').
Implementations:
Returns:
An array of strings representing the denied products. Each string in the array could be a JavaScript regular expression that matches more than one product.
Type
Array.<string>

removeListener(listenerId)

Removes a listener from the listener register. The removed listener will no longer be notified of current or future product permissions.
Parameters:
Name Type Description
listenerId int The unique identifier that was returned when the listener was registered.
Implementations:
See:
  • module:caplin/security/permissioning/PermissionService#addPermissionListener
  • module:caplin/security/permissioning/PermissionService#addGlobalPermissionListener
  • module:caplin/security/permissioning/PermissionService#addProductPermissionsListener
  • module:caplin/security/permissioning/PermissionService#addPermissionSetListener