Mandatory Fields

It is possible to configure "mandatory fields" in SuperWEB2. Any fields or summation options that you set to be mandatory will be automatically added to all new tables. You can use this feature to change the default summation option for a dataset; see below for more details.

SuperWEB2 also supports "mandatory values", which allow you to specify that specific field items are mandatory if the corresponding field is included in a table. See Mandatory Values for more details.

You can identify mandatory fields in the field list by looking for a small red * indicator on the field icon. For example, in the field list shown here, the Female item from the Gender field is mandatory, as well as the entire Marital Status field:

When configuring mandatory fields you can choose whether users will be able to remove them from the table:

• If you activate the mandatory fields rule for new tables, then the items will be added on opening the dataset, but users can remove them.
• If you activate both the new tables rule and the edit rule, then users will be unable to remove the fields and summation options and they will always appear in tables created by your users.

If you wish, you can configure an additional setting to have mandatory fields automatically tabulated when a dataset opens.

You cannot make a field, valueset or field item mandatory if it also has field level security applied to it and the result of running the mandatory fields rule would require something to be added to the table that the user does not have access to. This is considered invalid configuration and will prevent the user from accessing the dataset in SuperWEB2.

For example, if you block access to an entire field then you cannot also make that field mandatory.

However, it is possible to configure a field to be mandatory if only some of the field items within it have field level security applied to them. This can be useful if you are restricting access to a subset of data for particular users, as it can be used to ensure that the results are always filtered according to the field with restricted values. 

When a field is configured as mandatory, users will not be able to concatenate another field onto the same axis as the mandatory field. If this were permitted it would allow users to circumvent the mandatory fields restriction by adding cells to the table that are not filtered by the mandatory field). 

If you are using the Open Data API then this can also be configured to enforce the mandatory fields rule. The Open Data API needs to be configured separately in its own configuration file. See Rules Engine - Open Data API for more details.

Configure Mandatory Fields

Step 1 - Activate the New Tables Mandatory Fields Rule

The first step is to activate the mandatory fields rule for new tables, by editing <tomcat_home>\webapps\webapi\WEB-INF\data\.repository\RulesEngine.xml in a text editor.

1. Locate the following section:

   XML

       <rules:RulesPipe name="NewTableRules">
           <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
       </rules:RulesPipe>

   

   Please note that the string <rules:rule-name name="MandatoryFieldsRule"/> appears in this file multiple times. You need to locate the one that is inside the NewTableRules section, which is located at the very end of the file.

2. Remove the comments from the rule:

   XML

       <rules:RulesPipe name="NewTableRules">
           <rules:rule-name name="MandatoryFieldsRule"/>
       </rules:RulesPipe>

3. Save your changes to the file.

Step 2 (Optional) - Configure Mandatory Fields to Be Required in Tables

If you want to prevent users from removing the mandatory fields from the table, then you should also make the following change in <tomcat_home>\webapps\webapi\WEB-INF\data\.repository\RulesEngine.xml:

1. Locate the following section:

   XML

       <rules:RulesPipe name="CDataOnlineEditRules">
           <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
           <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->

2. Remove the comments from the MandatoryFieldsRule:

   XML

       <rules:RulesPipe name="CDataOnlineEditRules">
           <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
           <rules:rule-name name="MandatoryFieldsRule"/>

3. Save your changes to the file.

Step 3 - Restart SuperWEB2

When you have finished activating the mandatory field rules, you need to restart Tomcat or the SuperWEB2 service to apply the change to RulesEngine.xml.

The remainder of the configuration for mandatory fields involves specifying which fields are mandatory. You do this using the SuperADMIN console.

You will not need to restart SuperWEB2 to pick up the changes you make in SuperADMIN, although if you currently have the dataset open in SuperWEB2, you will need to go back to the catalogue and reopen it to see any changes. This also applies to any other users; they will need to reselect the dataset from the catalogue before seeing the impact of any changes you make to the configuration in SuperADMIN.

Step 4 - Export the Current Mandatory Field Configuration

Although it is possible to set up mandatory fields using SuperADMIN commands, the easiest way to configure your mandatory field rules is to export the current mandatory field configuration (if any), make your changes in a text editor, and then import the updated rules.

Login to SuperADMIN and use the following command to export the current rules to a text file:

cfg db <dataset_id> superweb2.rules.mandatoryFields save <filename>

Where:

• <filename> is the full path to a text file to use to save the configuration. Do not use quotes, even if the path contains spaces. For example: E:\Exported Config\mandatoryfields.json
• <dataset_id> is the ID of the dataset you want to export the configuration for.

For example to export the mandatory fields configuration for the Retail Banking dataset (ID: bank), use the following command:

> cfg db bank superweb2.rules.mandatoryFields save E:\Configuration Exports\RetailBankingMandatoryFieldRules.json
superweb2.rules.mandatoryFields : dumped to 'E:\Configuration Exports\RetailBankingMandatoryFieldRules.json'

If there are currently no mandatory field rules configured for this dataset, then SuperWEB2 displays the message "not found". For example:

> cfg db bank superweb2.rules.mandatoryFields save E:\Configuration Exports\RetailBankingMandatoryFieldRules.json
superweb2.rules.mandatoryFields : not found

If this is the case, then you will need to start with a blank text file instead. You can use the example below as a basis for constructing your rules.

Step 5 - Update the Rules in the Text File

Once you have exported the current configuration, open the exported file in a text editor and make your changes (if there were no existing rules defined, create a new empty text file and use the example below as a basis for defining your rules).

The following example defines a dataset-specific rule. See the table below for more details.

[
    {
        "axis" : "Row",
        "field" : "SXV4__Retail_Banking__F_Customer__Cust_Open_Date_Cal_FLD",
        "values" : ["19721", "20013", "20054"],
        "valueSet" : "SXV4__Retail_Banking__C_Cal_Date_2"
    }, 
    {
        "field" : "SXV4__Retail_Banking__F_Account__Acc_Open_Date_Cal_FLD",
        "axis" : "Row",
        "values" : ["200202", "200312"],
        "valueSet" : "SXV4__Retail_Banking__C_Cal_Date_1"
    }, 
    {
        "field" : "SXV4__Retail_Banking__F_Customer__Gender_FLD",
        "axis" : "Subject",
        "values" : ["F"],
        "factTable" : "Customers"
    }, 
    {
        "field" : "SXV4__Retail_Banking__F_Customer__Marital_Status_FLD",
        "axis" : "Column"
    }, 
    {
        "axis": "Column",
        "factTable": "Customers",
        "field": "SXV4__Retail_Banking__F_Customer__Cust_Profit_FLD",
        "statFunction": "Mean"
    }
]

When constructing your rules, take care to ensure you use the right combination of brackets and commas:

• Each rule is enclosed in curly brackets.
• Rules are separated by commas.
• The full set of rules are enclosed in square brackets.

Parameters

The following table describes the settings in the example:

axis	The axis to add the field or summation option to (these terms are case sensitive): Row Column Wafer Subject (this adds the item to the table filter; when specifying that a field be added to the table filter, you must use the values property to specify exactly one value).	Required.
field	The full SXV4 ID of the field or summation option. You can obtain the field ID from SuperADMIN. Use the command cat <dataset_id> <field_name>. For example: CODE > cat bank Occupation [ XTAB Field : 'Occupation' ] [ ID : 'SXV4__Retail_Banking__F_Customer__Occupation_FLD' ] [ Value Set : 'SXV4__Retail_Banking__C_Occupation' ] In this example, the ID you need is SXV4__Retail_Banking__F_Customer__Occupation_FLD. In some cases you can also specify the field using its display name, but if you do this you must also specify the fact table the field belongs to, using the factTable property. You are recommended to use the ID in all cases if possible. You must use IDs if you are using multilingual datasets.	Required.
valueSet	The ID of the value set to add to the table. You can obtain the value set ID from SuperADMIN using the command cat <dataset_id> <field_name>.	Only required for hierarchical fields.  Specifying the value set does not restrict users to that particular value set of the hierarchy (for example they will still be able to navigate up and down to other levels of the hierarchy), however it sets the initial level of the hierarchy that is added to the table. If you do not specify a value set for a hierarchical field then the field will be added at the lowest level in the hierarchy.
values	An array listing all the field value IDs to add to the table. Specify each value in quotes, separated by commas and with square brackets at the start and end of the list. You can obtain the field value IDs from SuperADMIN using the command cat <dataset_id> <field_name> values.	Only required if you want to add specific values for the field (if not specified the entire field will be added).
factTable	The fact table the field belongs to.	Only required if using the display name to identify fields
statFunction	The statistical function to add, which can be one of the following: Sum Mean Median	Only required for summation options where you want to have a specific statistical function added to the table. If you are adding a continuous variable/numeric measure and you do not specify a statFunction  then the sum will automatically be used. If you are adding a record count, then do not specify a statFunction. The count will automatically be used.

Step 6 - Import the Modified Configuration

Once you have finished editing the configuration, use the following commands to import your updated mandatory fields configuration:

cfg db <dataset_id> superweb2.rules.mandatoryFields load <filename>

Where:

• <filename> is the full path to a text file to use to load the configuration. Do not use quotes, even if the path contains spaces. For example: E:\Exported Config\mandatoryfields.json
• <dataset_id> is the the ID of the dataset you want to import the configuration for.

For example:

> cfg db bank superweb2.rules.mandatoryFields load E:\Configuration Exports\RetailBankingMandatoryFieldRules.json
superweb2.rules.mandatoryFields : updated

Once you have imported your rules, go to the SuperWEB2 dataset catalogue and click New Table to verify that the table contains your mandatory fields.

Remove Mandatory Field Rules

To remove all the mandatory field rules from a specific dataset, use the following command (replace <dataset_id> with the ID of the dataset):

cfg db <dataset_id> superweb2.rules.mandatoryFields remove

For example:

cfg db bank superweb2.rules.mandatoryFields remove

If you just want to remove a specific rule, or a number of rules, the easiest way to do this is to export the rule configuration to a text file, delete the rules you want to remove, and then re-import the configuration.

Change the Default Summation Option with Mandatory Fields

In SuperWEB2 you must have at least one summation option in the table at all times. When you first add a field to the table, SuperWEB2 automatically adds the default summation option, which is configured in SuperCHANNEL when the SXV4 is created.

While the recommended method for changing the default summation is to update the SuperCHANNEL project and recreate the SXV4, if this is not an option you can use mandatory fields to specify a different default, by configuring one of the summation options to be mandatory.

The ability to change the default summation option is not a security feature and does not stop a user from manually applying a different summation option to the table. The default summation is simply intended to guide users when they first start creating a table.

To configure a record count as mandatory, specify the field ID but do not specify a statFunction. For example, to set the default summation for the sample Retail Banking dataset to a count of Accounts, added to the table filter, use a configuration similar to the following:  

[
    {
        "axis" : "Subject",
        "field" : "SXV4__Retail_Banking__F_Account_SUM"
    }
]

When configuring a continuous variable, you only need to specify a statFunction if you wish to use something other than sum. For example, the following configures the default summation to be the mean of account profit: 

[
    {
        "axis" : "Subject",
        "field" : "SXV4__Retail_Banking__F_Account__Acc_Profit_FLD",
        "statFunction" : "Mean"
    }
]

Configure Automatic Tabulation

By default, mandatory fields will not be tabulated when the user opens the dataset. If you wish to have them automatically tabulated, you can configure a setting in SuperADMIN.

To configure automatic tabulation for a given dataset, use the following command (replace <dataset_id> with the ID of the dataset):

cfg db <dataset_id> superweb2.rules.mandatoryFieldsAutoTabulate set "true"

For example:

cfg db bank superweb2.rules.mandatoryFieldsAutoTabulate set "true"

To disable automatic tabulation, change the setting to false. For example:

cfg db bank superweb2.rules.mandatoryFieldsAutoTabulate set "false"

There is a separate configuration setting, table.autoRetrieveDataDefault, in the configuration.properties file that controls whether tables are automatically tabulated by default. If you have set table.autoRetrieveDataDefault to true then any mandatory fields will be automatically tabulated regardless of whether mandatoryFieldsAutoTabulate is set to true or false.