Mandatory Values

The mandatory values feature allows you to specify that certain field items are mandatory if any item from the corresponding field is included in a table. For example, if you specify that the field item Male is mandatory, then this will be automatically added to the table whenever the user adds any field items from the Gender field.

The mandatory values feature differs from the mandatory fields feature in that the field items are only added when there is at least one item from that field in the table. In the above example, where Male is set as mandatory, it will not be added to the table unless there is at least one field item from Gender in the table.

Step 1 - Activate the Mandatory Values Rule

The first step is to activate the mandatory values rule to run whenever a user makes a change to a table.

Open <tomcat_home>\webapps\webapi\WEB-INF\data\.repository\RulesEngine.xml in a text editor.

Locate the CDataOnlineEditRules section:

XML

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

Please note that the string <rules:rule-name name="MandatoryValuesRule"/> appears in this file multiple times. You need to locate the one that is inside the CDataOnlineEditRules section.

Remove the comments from the MandatoryValues rule:

XML

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

Save your changes to the file.

Step 2 (Optional) - Configure Mandatory Values to Be Added to Saved Tables

If you also require the mandatory values to be added to any saved tables that the user opens that include items from fields with mandatory values, then you should also make the following change in <tomcat_home>\webapps\webapi\WEB-INF\data\.repository\RulesEngine.xml:

Locate the NewTableRules section:

XML

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

Remove the comments from the MandatoryValuesRule:

XML

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

Save your changes to the file.

Step 3 - Restart SuperWEB2

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

The remainder of the configuration involves specifying which values 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 Values Configuration

Although it is possible to set up mandatory values using SuperADMIN commands in the console, the easiest way to configure your rules is to export the current mandatory 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.mandatoryValues 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\MandatoryValues.json
<dataset_id> is the ID of the dataset you want to export the configuration for.

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

CODE

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

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

CODE

> cfg db bank superweb2.rules.mandatoryValues save E:\Configuration Exports\RetailBankingMandatoryValues.json
superweb2.rules.mandatoryValues : 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).

CODE

[
    {
        "field": "SXV4__Retail_Banking__F_Customer__Occupation_FLD",
        "values": [
            "5",
            "0",
            "X",
            "3"
        ]
    },
    {
        "field": "SXV4__Retail_Banking__F_Account__Product_Type_FLD",
        "values": [
            "B",
            "T",
            "P"
        ]
    },
    {
        "field": "SXV4__Retail_Banking__F_Customer__Area_FLD",
        "valueSet": "SXV4__Retail_Banking__C_Geography_2",
        "values": [
            "205"
        ]
    }
]

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:

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.

valueset

(Only required for hierarchical fields)

The ID of the value set the field item belongs to. You can obtain the value set ID from SuperADMIN using the command cat <dataset_id> <field_name>.

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. Alternatively, you can obtain the values by creating a table in SuperWEB2 with the field items in it, and using the table menu to switch from labels to codes.

Step 6 - Import the Modified Configuration

Once you have finished editing, use the following command to import your updated configuration:

CODE

cfg db <dataset_id> superweb2.rules.mandatoryValues 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\MandatoryValues.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.mandatoryValues load E:\Configuration Exports\RetailBankingMandatoryValues.json
superweb2.rules.mandatoryValues : updated

You can check your rules have imported correctly using the following command:

CODE

cfg db <dataset_id> superweb2.rules.mandatoryValues

For example:

CODE

> cfg db bank superweb2.rules.mandatoryValues

[
    {
        "field": "SXV4__Retail_Banking__F_Customer__Occupation_FLD",
        "values": [
            "5",
            "0",
            "X",
            "3"
        ]
    }
]

Once you have imported your rules, go to the SuperWEB2 dataset catalogue and click New Table, then add an item from each relevant field to verify that the mandatory field items are also added.

Remove Mandatory Values Rule

To remove all the mandatory value 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.mandatoryValues remove

For example:

CODE

cfg db bank superweb2.rules.mandatoryValues 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.