Mandatory Fields - SuperWEB2

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.

By default, users will be able to remove these fields from the table if they want, but if you wish you can also activate a rule to prevent users from removing the fields. If you choose to configure this then it will not be possible to create a table that does not include all of the mandatory fields.

Step 1 - Activate the Mandatory Fields Rule

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

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

Remove the comments from the rule:

XML

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

Save your changes to the file.

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

If you want to prevents 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:

Locate the following section (this is the other instance of <rules:rule-name name="MandatoryFieldsRule"/> that appears in the file):

XML

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

Remove the comments from the MandatoryFieldsRule:

XML

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

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 SuperADMIN.

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:

CODE

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 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:

CODE

> 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:

CODE

> 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.

CODE

 [
    {
        "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",
        "factTable" : "Customers"
    }, {
        "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",
        "factTable" : "Customers"
    }
]

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 field as a table filter; when specifying that a field be added to the table filter, you must use the `values` property to specify exactly one value.
field	The full SXV4 ID of the field. You can obtain the field ID in SuperADMIN. Use the command `cat <dataset_id> <field_name>`. For example: CODE `> cat people Occupation [ XTAB Field : 'Occupation' ] [ ID : 'SXV4__PeopleNonMl__People__Occupation_FLD' ] [ Value Set : 'SXV4__PeopleNonMl__Occupation' ]` In this example, the ID you need is `SXV4__PeopleNonMl__People__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.
valueSet	(Optional). The ID of the value set to add to the table. You only need to specify this for hierarchical fields. You can obtain the value set ID from SuperADMIN using the command `cat <dataset_id> <field_name>`.
values	(Optional). An array listing all the field value IDs to add to the table. If you do not specify the values then all values for this field or value set will be added. 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`.
factTable	The fact table the field belongs to. This is 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:

CODE

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:

CODE

> 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.

Removing 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):

CODE

cfg db <dataset_id> superweb2.rules.mandatoryFields remove

For example:

CODE

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.