Mandatory Fields

It is possible to configure "mandatory fields" in SuperWEB2. Any fields that you set to be mandatory will be automatically added to all new tables.

Fields that are configured as mandatory can be identified in the field list by 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 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.

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 to (these terms are case sensitive): Row Column 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.
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

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.

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"