Security Filters section

This section is about the Security Filters section of the Data Model Security page and how to add Security Selections and use Custom Selection Scripts.

In the Security filters section of the Data Model Security page, you can configure and apply security selections to the Security Profile. These are filters you can configure when creating or editing a security profile which allow you to restrict access to data in Cubes or Entities, both in the Capsules/Presentations environment and in the Data Model designer space. You can do this by applying a selection to the Entity members associated with the desired Cube or feature: users affected by these selection will only have access to values and data within the applied selection.

Add security selection

To add a security selection, access or create a security profile and click on "ADD SECURITY SELECTION" to open the Select window and configure a security selection by choosing the desired Entity members that you want the security profile to have access to. Only data related to the selected Entity members will be visible to the user associated with this security profile, as described in the "Security filters" paragraph of Data Model Profile options.

For example, if the "France" member of the "Country" Entity is selected, a user associated with the security profile with this security filter applied will only see data and values related to the "France" member.

Custom Selection Scripts

A Custom Selection Script allows Developers to manually write selection command scripts that override the filtering criteria of the lower levels of Data Model security applied to users via their assigned Security Profiles and Roles. The scripts automatically filter the data displayed in Board Platforms based on Entity members defined in the script and run-time Substitution Formula values.

Security Override !

When both manual security selections and scripts exist on the same Profile/Role, Board applies the manual security selections first, then executes the script(s) in top-to-bottom order; if both target the same Entity, the Custom Selection Script(s) override the manual selections.

The Custom Selection Script can make use of variables like @User or any custom User Metadata defined in the Subscription Hub to provide execution-time evaluation of data access rights.

The combined results are then further filtered dynamically with the "based on Cube" and "Cube visibility rules", to be finally narrowed for the last time by the UI-level filters, e.g. Screen, Layout, Pager, and Procedure Selects.

The multiple levels of Board security generally restrict access to data in a layered fashion, each further limiting the data space accessible to any given user, with the notable exception of these Custom Selection Scripts, which have the capacity to expand the accessible space by virtue of their "overriding" nature.

This facility is particularly useful to make aggregate data from a Cube available to users in a summary form when those users cannot access all of the underlying details, or when very particular dynamic filtering is required using Substitution Formulas and custom user metadata.

If you are defining authoritative, model-wide restrictions, put the script in the Security Profile; you can then reserve Role-level scripts for additional, Platform-scoped filtering without overlapping the same Entities. In theory, Security Profile script selects take priority over the Role scripts if there is a conflict, but Developers are encouraged to carefully test such complex filtering.

An example of the syntax for this command is as follows:

SELECT EntityName=Member1,Member2,Member3,etc.  

SELECT Country=France,Italy

With the @var function, you can retrieve a member code from user metadata variables using the syntax:

SELECT EntityName=@var(metadata)

SELECT Country=@var(country)

To add a Custom Selection Script, enter a Custom selection script in the "Custom Selection Script" field by using the following syntax: SELECT EntityName=Member1,Member2,Member3,etc. (i.e. SELECT Country=France,Italy). See Add and manage User metadata to use selection scripts based on custom user metadata defined in the Subscription Hub.

To define the desired members, you must enter their member code in the script.

Typically the Custom Selection Script is used to dynamically filter data displayed in Board for each user by using Substitution Formulas or Metadata variables. For example, you can configure a "Country" Metadata variable, enter the country of each user in the Subscription Hub, and then use it in the Custom Selection Script so that users can access data only related to their country. This way, the user’s access to data is dynamically filtered by their country - based on their "Country" Metadata value -, rather than creating multiple security profiles with fixed country selections and associating those profiles with multiple user Roles.
See Add and manage User metadata to use Custom Selection Scripts based on custom user metadata defined in the Subscription Hub.

Add special Select options for Entities with an Unbalanced hierarchy

The special Select options that you can use in the Select window on an Entity member of an unbalanced hierarchy, are also available in the Custom Selection Scripts that you can configure under the "Security filters" section in a Data Model Security Profile or under the "Select" section in a Role.

The Selection script syntax for the Entities with an unbalanced hierarchy is the following:

Select EntityName = FunctionName(MemberCode1, MemberCode2;InclusiveBoolean;HierarchyLevel;IncludeNonLeafBoolean)

You can find the explanation for each syntax parameter below:

• EntityName. This parameter is the name of the Entity on which you want to apply a selection.

• FunctionName. This parameter is the name of the special Select option you want to apply to a member of an unbalanced hierarchy. The options can be the following:

  • Ancestors

  • Descendants

  • Parent

  • Leaves

  • Children

  Read more about Selections with unbalanced Entities for information about these functions.

• MemberCode. This parameter is the code of the Entity member that you want to use for the selection. You can add as many member codes as you like by using the comma character as a separator.

  You must use double quotes in the case where a member code contains spaces or special characters:

  Select Entity = FunctionName(MemberCode1,"MemberCode,;{}[]@=()2"...)

  This means that you should not use the double quotes character as part of an Entity name or Entity member code since it is a reserved character for the Custom Selection Script syntax.

• InclusiveBoolean. This parameter is a boolean (True or False) that you can use to include or exclude the MemberCode parameters used in the selection. For example, if you have an Entity with an unbalanced hierarchy where the members are FatherMember -> ChildMember1 and ChildMember2 and you perform the following selection: Select Entity = Descendant(FatherMember;false) then the applied selection will include data only related to ChildMember1 and ChildMember2, but not FatherMember.

  This parameter is true by default, therefore the MemberCode parameters are included in the selection unless specified otherwise.

• (Only applicable to Ancestors and Descendants functions) HierarchyLevel. This parameter is a number value that you can use to specify the levels of the hierarchy that will be included in the selection. For example, if you have a hierarchy of 6 levels and you enter the number "3" as the HierarchyLevel parameter, then the selection will include data only related to ancestor or descendant members that are within 3 levels away from the selected member in the hierarchy.

  The default value of this parameter is "0", which equals the "ALL" option in the Select window, and therefore includes all levels of the hierarchy.

• (Only applicable to Ancestors and Descendants functions) IncludeNonLeafBoolean. This parameter is a boolean (True or False) that you can use to include or exclude non-leaf members of the Entity on which you are applying the selection

  This parameter is true by default, therefore the non-leaf members of the Entity are included in the selection unless specified otherwise.

Here are a couple of important notes to keep in mind regarding the special Select options:

• Like in the Select window, you can add multiple special Select commands in the same script, like in the following example:

  Select EntityName = FunctionName1(MemberCode1;InclusiveBoolean...) Select EntityName = FunctionName2(MemberCode2;InclusiveBoolean...)

  In the case of multiple Select commands, Board will unite all the selection script commands and include data related to members that appear in at least one of the script commands.

• You can add multiple functions to the same selection script command by using the comma character between functions, and you can also use the same function more than once on the same Entity, like in the following example:

  Select EntityName = FunctionName1(MemberCode2;InclusiveBoolean...), FunctionName2(MemberCode2;InclusiveBoolean...), FunctionName3(MemberCode2;InclusiveBoolean...)

• You can retrieve a member code from metadata variables using the @var function, like in the following example:

  Select EntityName = FunctionName(@var(Metadata);InclusiveBoolean)

• Applying a special Select option to an Entity with an unbalanced hierarchy, might cause the hierarchy of the selection result to look different from the original hierarchy depending on the configuration of the selection script. Consider the following example:

  

  In this case, applying the selection script, like in the image above, to the Entity with an unbalanced hierarchy, causes the displayed hierarchy to appear differently from the original. This is correctly displayed since, for example in this specific case, the Leaves function selects leaf members ("Child-1", "Child-2", "Child-3.1" and "Child-3.2" members) that are descendants of the selected member ("Father" member) and excludes Nodes ("Child-3" member) from the selection. Therefore, the position of the node descendants is displayed in a different order in the hierarchy when this type of selection is applied.

Select Entity based on Cube feature

The "Select Entity based on Cube" Dynamic Selection feature in the Security filters section can be used as a security selection filter in a Data Model Security Profile and under the "Select" section in a Role. This gives administrators much better flexibility and efficiency in dynamically managing user access to the data of a Platform.

This feature applies a selection based on Entity members that have a non-zero value on the chosen Cube. The security filters are applied in the following order, from top to bottom:

1. Security selections

2. Custom Selection Scripts

3. Dynamic Selections (Entities based on Cube)

Board applies these selections in a funnel-like way, narrowing the selection down after applying each selection feature.

For example, consider the configuration of the following selections:

Order of Selections based on Cube

The selections are applied in the following order:

1. The Security selections (in blue) are applied first, therefore denying users access to data related to all countries.

   The security selection is used to select which member of an Entity the user can access. In this particular example, the Entity "Country" has an empty member called "no access" for this exact purpose. When selecting "no access" as the Entity member that can be accessed by this security profile, you are restricting access to all other members, meaning all countries.

2. The Custom Selection Scripts (in yellow and green) are applied second, therefore granting users access to data related to their country, based on the value of the "Country" metadata of each user, and from the member "Food" of the "Product Group" Entity.

3. The Dynamic Selection (in red) will be applied last, therefore granting users access to data related to the members of the "Product Group" Entity members that have a non-zero value on the "Product group by country" Cube.

Given the data set in the image below, if the "country" metadata value of a user is "Italy", then each selection filter from the above example is applied in the following way:

The various selections are singularly applied to the data highlighted in the image above. In this case, since the selections are applied together in the order described above, then a user associated with a security profile with the configurations above would only have access to the following data:

Add a Dynamic Selection

To add a Dynamic Selection in the security selection filters, proceed as follows:

1. Go to the "Security filters" section in a Data Model Security Profile in the Data Model Security page.

   You can also add a Dynamic Selection from the "SELECT" menu and then the desired Data Model menu in the Roles page.

2. Select the desired Entity from the "Entity" dropdown list.

3. Select the desired Cube from the "Cube" dropdown list.

4. Click the blue check mark on the right to add the Dynamic Selection.

Here are a couple of important notes to keep in mind regarding the Dynamic Selections:

• You can add multiple Dynamic Selections. In this case, Board will apply them in sequential order from top to bottom, narrowing the selection down after each execution. You can change the order of the Dynamic Selections by dragging and dropping them as desired.

• You can add multiple Dynamic Selections on the same Entity and/or the same Cube.

• The Dynamic Selections are executed in Keep mode.

• In the case where an Entity that is already configured in a Dynamic Selection is deleted, Board will deny access to data related to the members of that Entity.

• In the case where the Relationships of an Entity that is already configured in a Dynamic Selection are edited causing the Cube dimensioned by that Entity to become less aggregate, Board will deny access to data related to the members of that Entity.

• In the case where an Entity that is already configured in a Dynamic Selection is removed from the dimensions of the Cube configured in that Dynamic Selection, Board will deny access to data related to the members of that Entity.

• In the case of Data Model Security Profiles, the various selections, including the Dynamic Selection, are applied before the Cube Visibility rules.