Skip to main content
Skip table of contents

Configure Field Level Security

Field Level Security (FLS) allows you to control access to specific fields, summation options, values and value sets on a per-user or per-group basis.

Note

  • You cannot use field level security to hide field groups.
  • Field level security settings do not apply to users who are SuperADMIN administrators. Do not attempt to configure any field level security for these users.
  • Do not apply field level security to the default summation option. This must always be available to all users.
  • If you have weighted databases, do not apply field level security to the main weight.
  • Before you start configuring permissions, make sure you understand the Permissions Model - Inheritance and Conflicts.

To implement FLS you need to log in to SuperADMIN and use the cat command.

The basic syntax is as follows:

TEXT 
cat <dataset_id> [ <item> ] access {<user>|<group>} read {true|false}

Where:

ParameterDescription
<dataset_id>
The ID of the dataset.
<item>

The ID of the item to apply security to. This can be a field, summation option, value, or value set. You can also omit this to apply the permission to the whole dataset.

In some cases you can use the item's display name (the name displayed to end users in the client) instead of the ID.

  • If a field's display name is unique within this dataset, you can use the display name instead.

  • If a field's display name is not unique, you must use the field ID.

  • If the item does not have a display name (e.g. it is a value set) then you must use the ID.

If the item is nested within a hierarchy (e.g. it is a value within a value set), then you must specify each level of the hierarchy, separated by spaces.

For example, the following command sets security on the value Victoria, which is nested beneath Area/State:

cat bank 'Area' 'SXV4_Retail_Banking_C_State' 'Victoria' access vicuser1 read true

See the section on working with hierarchies below.

{<user>|<group>}
The user or group this setting applies to.
{true|false}
  • Set to true to allow access to the field for the specified user or group.
  • Set to false to deny access to the field for the specified user or group.

Examples:

ExampleDescription
cat bank 'Customer Profit' access bankusers read false
Denies access to the Customer Profit summation option for all users in the bankusers group.
cat bank 'Area' 'SXV4__Retail_Banking__C_State' 'Victoria' access vicuser1 read true

Allows access to the value Victoria for the user vicuser1.

In this example Victoria is a value within a hierarchy, so each level of the hierarchy is specified.

How Do I Find the Field Display Names or IDs?

Fields have both a display name (the name that is displayed to end users in the client) and a unique internal identifier. You can only use the display name in the cat command if it is unique within the dataset.

If you attempt to use a display name that is not unique, SuperADMIN displays an error message:

TEXT 
> cat bank Customers access vicuser1 read false
[3] values found for [Customers]. Use item ID instead of Name

Use these commands to find the display name or ID of a field:

CommandDescription
cat <dataset_id> fields
Displays all the fields in the specified dataset, showing the field type and display name.
cat <dataset_id> <field>
Displays the properties for the specified field, this includes the ID and any value sets attached to the field.
Click here to see worked examples of these commands in use...

Display the Dataset Fields

To view the list of dataset fields, use the command cat <dataset_id> fields

This example shows the list of fields in Retail Banking. Each field is listed with its type and display name.

TEXT 
> cat bank fields
[ Summation Field : 'Customers' ]
[ Summation Field : 'Customer Profit' ]
[ Summation Field : 'Accounts' ]
[ Summation Field : 'Account Profit' ]
[ Summation Field : 'Average Account Balance' ]
[ Field Group: 'Customers' ]
    [ XTAB Field : 'Age' ]
    [ XTAB Field : 'Age Groups' ]
    [ XTAB Field : 'Gender' ]
    [ XTAB Field : 'Marital Status' ]
    [ XTAB Field : 'Occupation' ]
    [ XTAB Field : 'Area' ]
    [ XTAB Field : 'Customer Mail Indicator' ]
    [ XTAB Field : 'Individual \ Company' ]
    [ XTAB Field : 'Customer Open Calendar Date' ]
    [ XTAB Field : 'Customer Open Financial Date' ]
    [ XTAB Field : 'Customer Open Quarter' ]
    [ XTAB Field : 'Customer Open Month' ]
    [ XTAB Field : 'Customer Open Week' ]
    [ XTAB Field : 'Customer Open Day of Month' ]
    [ XTAB Field : 'Customer Open Day of Week' ]
[ Field Group: 'Accounts' ]
    [ XTAB Field : 'Product Type' ]
    [ XTAB Field : 'Account Open Calendar Date' ]
    [ XTAB Field : 'Account Open Financial Date' ]
    [ XTAB Field : 'Account Open Quarter' ]
    [ XTAB Field : 'Account Open Month' ]
    [ XTAB Field : 'Account Open Week' ]
    [ XTAB Field : 'Account Open Day of Month' ]
    [ XTAB Field : 'Account Open Day of Week' ]
    [ XTAB Field : 'Last Transaction Calendar Date' ]
    [ XTAB Field : 'Last Transaction Financial Date' ]
    [ XTAB Field : 'Last Transaction Quarter' ]
    [ XTAB Field : 'Last Transaction Month' ]
    [ XTAB Field : 'Last Transaction Week' ]
    [ XTAB Field : 'Last Transaction Day of Month' ]
    [ XTAB Field : 'Last Transaction Day of Week' ]
[ Field Group: 'Customers' ]
    [ Field: 'Customer Key (PK)' ]
    [ Field: 'Customer Open Date (Date)' ]
    [ Field: 'Birth Date' ]
    [ Field: 'X_Coord' ]
    [ Field: 'Y_Coord' ]
[ Field Group: 'Accounts' ]
    [ Field: 'Account Key (PK)' ]
    [ Field: 'Account Open Date (Date)' ]
    [ Field: 'Last Transaction Date (Date)' ]
    [ Field: 'FK_Cust_Key' ] 

The following field has the display name Customer Profit:

TEXT 
[ Summation Field : 'Customer Profit' ]

As this name is unique you can use it instead of the ID.

However, the display name Customers is used in 3 places in this dataset. If you attempt to use a display name that is not unique, SuperADMIN displays an error message:

TEXT 
> cat bank Customers access vicuser1 read false
[3] values found for [Customers]. Use item ID instead of Name

Find a Field's ID

To find a field ID, use the command cat <dataset_id> <field>

This example shows the details for all items with the display name Customers in the Retail Banking dataset:

TEXT 
> cat bank Customers
[ Summation Field : 'Customers' ]
    [ ID : 'SXV4__Retail_Banking__F_Customer_SUM' ]
 [ Field Group: 'Customers' ]
    [ XTAB Field : 'Age' ]
    [ XTAB Field : 'Age Groups' ]
    [ XTAB Field : 'Gender' ]
    [ XTAB Field : 'Marital Status' ]
    [ XTAB Field : 'Occupation' ]
    [ XTAB Field : 'Area' ]
    [ XTAB Field : 'Customer Mail Indicator' ]
    [ XTAB Field : 'Individual \ Company' ]
    [ XTAB Field : 'Customer Open Calendar Date' ]
    [ XTAB Field : 'Customer Open Financial Date' ]
    [ XTAB Field : 'Customer Open Quarter' ]
    [ XTAB Field : 'Customer Open Month' ]
    [ XTAB Field : 'Customer Open Week' ]
    [ XTAB Field : 'Customer Open Day of Month' ]
    [ XTAB Field : 'Customer Open Day of Week' ]
    [ ID : 'SXV4__Retail_Banking__Customers_XGRP' ]
 [ Field Group: 'Customers' ]
    [ Field: 'Customer Key (PK)' ]
    [ Field: 'Customer Open Date (Date)' ]
    [ Field: 'Birth Date' ]
    [ Field: 'X_Coord' ]
    [ Field: 'Y_Coord' ]
    [ ID : 'SXV4__Retail_Banking__Customers_DGRP' ]

Note that you cannot apply Field Level Security to a Field Group.

Display Details of Value Sets

To see details of value sets, use the command cat <dataset_id> <field> for a field that has value sets attached to it.

This example show that the Age field has only one value set. The 'Age Groups' field has two value set branches:

TEXT 
> cat bank Age
[ XTAB Field : 'Age' ]
    [ ID : 'SXV4__Retail_Banking__F_Customer__Age_FLD' ]
    [ Value Set : 'SXV4__Retail_Banking__C_Age' ]

> cat bank "Age Groups"
[ XTAB Field : 'Age Groups' ]
    [ ID : 'SXV4__Retail_Banking__F_Customer__Age_Group_FLD' ]
    [ Value Set : 'SXV4__Retail_Banking__C_Age_Five_Group_1' ]
        [ Value Set : 'SXV4__Retail_Banking__C_Age_Group_0' ]
    [ Value Set : 'SXV4__Retail_Banking__C_Age_Ten_Group_1' ]
        [ Value Set : 'SXV4__Retail_Banking__C_Age_Group_0' ]

Working with Hierarchies

In the sample Retail Banking dataset, the Area field is the top level of a geographic hierarchy.

To explore the hierarchy, use the command cat bank <field>

TEXT 
 > cat bank Area
[ XTAB Field : 'Area' ]
    [ ID : 'SXV4__Retail_Banking__F_Customer__Area_FLD' ]
    [ Value Set : 'SXV4__Retail_Banking__C_State' ]
        [ Value Set : 'SXV4__Retail_Banking__C_Geography_2' ]
            [ Value Set : 'SXV4__Retail_Banking__C_Geography_1' ]
                [ Value Set : 'SXV4__Retail_Banking__C_Geography_0' ]

To set security on an item in the hierarchy, you must specify the full "path" to the value, with each level of the hierarchy separated by a space.

For example:

TEXT 
> cat bank 'Area' 'SXV4__Retail_Banking__C_State' 'Victoria' access vicuser1 read true
> cat bank 'Area' 'SXV4__Retail_Banking__C_State' 'New South Wales' 'Sydney' access vicuser1 read false
Click here to see more examples of exploring the hierarchy...

To see the values of a value set, use the command cat bank <field> <value_set> values

This example shows the values for the SXV4__Retail_Banking__C_State value set:

TEXT 
> cat bank Area "SXV4__Retail_Banking__C_State" values
[ Value : 'Null' (id:2147483647) ]
[ Value : 'New South Wales' (id:1) ]
[ Value : 'Victoria' (id:2) ]
[ Value : 'Queensland' (id:3) ]
[ Value : 'South Australia' (id:4) ]
[ Value : 'Western Australia' (id:5) ]
[ Value : 'Tasmania' (id:6) ]
[ Value : 'Northern Territory' (id:7) ]
[ Value : 'Australian Capital Territory' (id:8) ]
[ Value : 'Unknown' (id:-1) ]

This example shows the values for the SXV4__Retail_Banking__C_Geography_2 value set:

TEXT 
> cat bank Area SXV4__Retail_Banking__C_Geography_2 values
[ Value : 'Null' (id:2147483647) ]
[ Value : 'Sydney' (id:105) ]
[ Value : 'Hunter' (id:110) ]
[ Value : 'Illawarra' (id:115) ]
[ Value : 'Richmond-Tweed' (id:120) ]
[ Value : 'Mid-North Coast' (id:125) ]
[ Value : 'Northern' (id:130) ]
[ Value : 'North Western' (id:135) ]
[ Value : 'Central West' (id:140) ]
[ Value : 'South Eastern' (id:145) ]
[ Value : 'Murrumbidgee' (id:150) ]
[ Value : 'Murray' (id:155) ]
[ Value : 'Far West' (id:160) ]
[ Value : 'Off-Shore Areas & Migratory' (id:185) ]
[ Value : 'Melbourne' (id:205) ]
[ Value : 'Barwon' (id:210) ]
[ Value : 'Western District' (id:215) ]
[ Value : 'Central Highlands' (id:220) ]
[ Value : 'Wimmera' (id:225) ]
[ Value : 'Mallee' (id:230) ]
[ Value : 'Loddon' (id:235) ]
.......

You can also explore the hierarchy by adding specific labels to the commands:

TEXT 
> cat bank Area values
[ Value : 'Null' (id:2147483647) ]
 [ Value : 'New South Wales' (id:1) ]
 [ Value : 'Victoria' (id:2) ]
 [ Value : 'Queensland' (id:3) ]
 [ Value : 'South Australia' (id:4) ]
 [ Value : 'Western Australia' (id:5) ]
 [ Value : 'Tasmania' (id:6) ]
 [ Value : 'Northern Territory' (id:7) ]
 [ Value : 'Australian Capital Territory' (id:8) ]
 [ Value : 'Unknown' (id:-1) ]

> cat bank Area "Tasmania" values
[ Value : 'Greater Hobart' (id:605) ]
 [ Value : 'Southern' (id:610) ]
 [ Value : 'Northern' (id:615) ]
 [ Value : 'Mersey-Lyell' (id:620) ]
 [ Value : 'Off-Shore Areas & Migratory' (id:685) ]

> cat bank Area "Tasmania" "Northern" values
[ Value : 'Greater Launceston' (id:61505) ]
 [ Value : 'Central North' (id:61510) ]
 [ Value : 'North Eastern' (id:61515) ]

> cat bank Area "Tasmania" "Northern" "North Eastern" values
[ Value : '7214' (id:7214) ]
 [ Value : '7216' (id:7216) ]
 [ Value : '7255' (id:7255) ]
 [ Value : '7260' (id:7260) ]
 [ Value : '7261' (id:7261) ]
 [ Value : '7262' (id:7262) ]
 [ Value : '7263' (id:7263) ]
 [ Value : '7264' (id:7264) ]
 [ Value : '7265' (id:7265) ]

Finding Value Set Values

To set security on a value set value you also need to specify the full "path" to the value.

You can find the values using the command:

TEXT 
cat <dataset_id> <item> values

For example:

TEXT 
> cat bank Occupation values
[ Value : 'Clerical' (id:2) ]
 [ Value : 'Executive & Managerial' (id:1) ]
 [ Value : 'Home Duties' (id:7) ]
 [ Value : 'Independent Means; Retired; Pensioner; Unemployed' (id:8) ]
 [ Value : 'Primary production' (id:4) ]
 [ Value : 'Professional' (id:0) ]
 [ Value : 'Sales' (id:3) ]
 [ Value : 'Self employed' (id:A) ]
 [ Value : 'Staff' (id:X) ]
 [ Value : 'Tradesmen' (id:5) ]
 [ Value : 'Transport & Recreation' (id:6) ]
 [ Value : 'Unemployed' (id:J) ]
 [ Value : 'Unknown' (id:N) ]
 [ Value : 'Not Applicable' (id:-1) ]

The values correspond to the display names shown in SuperSTAR clients, and the IDs (e.g. id:J) are the codes for each value.

To set Field Level Security on one of the values you need to specify the full path to the value. For example:

TEXT 
cat bank Occupation 'Executive & Managerial' access vicuser1 read false

Changing Settings for All Values in a Value Set in Bulk

It is also possible to use a single command to allow or deny access to all the values in a value set. This is useful for cases where you have a large value set and you want to give a user access to a small number of the values in it. Previously, you had to specifically deny access to every value individually. Now, you can run one command that denies access to all the values and then enable just the specific individual ones.

To do this, use the following commands:

Allow or deny access to all the values in the specified field

TEXT 
cat <dataset_id> <field> values access {<user>|<group>} read {true|false}

Allow or deny access to all the values in the specified value set

TEXT 
cat <dataset_id> <field> <valueset> values access {<user>|<group>} read {true|false}

You need to specify the full path to the value set, as described above.

Example

For example, the following commands prevent user2 from accessing any values on the Age field, except for 18, 19 and 20:

TEXT 
cat bank Age values access user2 read false
cat bank Age '18' access user2 read true
cat bank Age '19' access user2 read true
cat bank Age '20' access user2 read true

If you subsequently decide you want to allow user2 to access all of the values on Age, you can revert the setting by running this command:

TEXT 
cat bank Age values access user2 read true
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close