Filter objects for discoverability

Syntax

$base.filterSecurity()

filterSecurity($base)

Description

Applies the discover right of the logged-in user to a value and removes all business objects that the user is not allowed to discover.

Every object source in a secured TL-Script (references, referers, container, object functions) already delivers only objects the user may discover. filterSecurity remains as a safety net for values assembled from unsecured sources.

The check is applied recursively:

  • A single business object that the user must not discover becomes null.
  • From a collection, the elements that must not be discovered are removed; the kind of collection (list or set) is preserved.
  • Values that are not business objects (e.g. numbers or strings) remain unchanged.

Usage

The overall result of a script does not have to be secured: it is filtered automatically when the application executes the script, unless security was explicitly switched off for that script. A trailing filterSecurity at the end of a script is therefore redundant.

The function is needed to secure a value within an evaluation – e.g. a partial result that the script itself renders or passes on to another context. It should not be applied to every intermediate step: if used too early, subsequent steps may lose objects that are needed for the computation (e.g. for a filter), even though the final result itself would be discoverable.

Parameters

Name Type Type Description Mandatory Default
base Any value The value to secure: a business object, a collection of business objects or a primitive value. yes

Return value

Type: Same type as the argument

The given value, containing only the business objects that the logged-in user is allowed to discover.

Examples

Example 1

all(`myModule:Contract`).map(c -> $c.get(`owner`)).filterSecurity()

Output: The owners of all contracts, restricted to the persons that the logged-in user is allowed to discover. In a secured script, the reference access already delivers only discoverable owners, so the call does not change the result there.

Example 2

$contract.get(`owner`).filterSecurity()

Output: The owner of the contract if the logged-in user is allowed to discover it, otherwise null.

Example 3

all(`myModule:Contract`).filter(c -> $c.get(`owner`) != null).filterSecurity()

Output: The contracts with an owner that the logged-in user is allowed to discover. In a secured script, all and the reference access already deliver only discoverable objects, so the trailing filterSecurity is redundant there. Note that discovering an object does not allow reading its attributes.