RulesEngine.xml

This file defines rules that control table creation. For example, you can use the rules to restrict the maximum number of cells in a table, or to specify mandatory fields that must be included in all tables.

If you make any changes to the rules, you will need to restart Tomcat or the SuperWEB2 service to see the changes in the browser.

TableCellsNumberRule

The TableCellsNumberRule rule defines the maximum number of cells permitted in a table. For example:

<rules:EditRule name="TableCellsNumberRule"
    applicableOperations="add;drillup;drilldown"
    implClassName="au.com.str.webapi.services.database.manager.rules.impl.TableCellsNumberRule">
  <rules:impl-class-init>
<rules:init-param name="maxElementCount" value="40000000"/>
<rules:init-param name="disableMaxElementCount" value="false"/>
  </rules:impl-class-init>
</rules:EditRule>

The maxElementCount parameter specifies the maximum number of cells permitted in a table. The default setting is 40000000 (40 million).

The maximum table size will also be restricted by the user query limits configured in SuperADMIN. These include default limits and any user-specific limits that have been configured.

The applicableOperations attribute specifies that the rule is applied when adding fields to a table, and also when drilling up or down through a hierarchical field (as this action will change the total number of cells in the table).

We do not recommended increasing this limit or changing the applicable operations.

Please contact support if you have a requirement to process a table larger than the default limit.

HierarchyLevelRule

By default, SuperWEB2 will allow users to mix items from different levels of a hierarchy in a table. For example, users can add both cities and states from the Area field in the Retail Banking dataset. If you wish, you can prevent this by activating the HierarchyLevelRule.

The following sample rule for hierarchy levels is defined in the rules file:

<rules:EditRule name="HierarchyLevelRule_All" applicableOperations="add"
        implClassName="au.com.str.webapi.services.database.manager.rules.user.ExternalRule">
<rules:impl-class-init>
<rules:init-param name="extImplClassName" value="au.com.str.webapi.services.database.manager.rules.user.LevelRule"/>
<rules:init-param name="maximumLevels" value="1"/>
<rules:init-param name="fieldName" value="allFields"/>
<rules:init-param name="databaseID" value="allDatabases"/>
</rules:impl-class-init>
</rules:EditRule>

This rule sets the maximum number of levels that can be in the table at once to 1, and will apply to all fields and all datasets.

To activate this rule:

1. Locate the following section:

   XML

    <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <!-- <rules:rule-name name="HierarchyLevelRule_All"/> -->

2. Remove the comments from the HierarchyLevelRule_All element:

   XML

   <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <rules:rule-name name="HierarchyLevelRule_All"/>

3. Save your changes and restart SuperWEB2 or the Tomcat service.

This will apply the rule to all datasets and fields. Alternatively, if you want the rule to only apply to specific datasets or fields:

1. Create a copy of the HierarchyLevelRule_All rule.
2. Change its name to something unique.
3. Edit the <rules:init-param name="fieldName" value="allFields"/> or <rules:init-param name="databaseID" value="allDatabases"/> statements and set the value to the ID of the field or dataset you want the rule to apply to.
4. Add your new rule to the CDataOnlineEditRules section.
5. Save your changes and restart SuperWEB2 or the Tomcat service.

SummationOptionsRule

The SummationOptionsRule prevents the addition of summations and classifications to a table at the same time. This rule is enabled by default.

To disable this rule and allow summations and classifications to be added to a table at the same time:

1. Locate the following section:

   XML

    <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <!-- <rules:rule-name name="HierarchyLevelRule_All"/> -->
           <rules:rule-name name="DemographicVariablesRule"/>
   <rules:rule-name name="TableCellsNumberRule"/>
   <!--<rules:rule-name name="checkAddToDimensionRule"/> -->
   <!--<rules:rule-name name="checkDoubleCountingRule"/> -->
   <rules:rule-name name="SummationOptionsRule"/>

2. Comment out the SummationOptionsRule element:

   XML

    <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <!-- <rules:rule-name name="HierarchyLevelRule_All"/> -->
   <rules:rule-name name="DemographicVariablesRule"/>
   <rules:rule-name name="TableCellsNumberRule"/>
   <!--<rules:rule-name name="checkAddToDimensionRule"/> -->
   <!--<rules:rule-name name="checkDoubleCountingRule"/> -->
   <!--<rules:rule-name name="SummationOptionsRule"/> -->

3. Save your changes and restart SuperWEB2 or the Tomcat service.

DutyOfCareRule

When a dataset contains multiple fact tables, it is important to know which one is being counted. The "duty of care" settings are designed to prevent users from creating potentially erroneous tables, and to ensure that they will always know what is being counted in the cross tabulation. For example, the sample Retail Banking dataset has two fact tables: customers and accounts. Users need to understand whether the table is counting the number of customers or the number of accounts owned by those customers (which will be a different value, because a customer could have more than one account).

The duty of care rule allows you to control how the default summation option is determined.

The duty of care rule does not apply if the user manually adds a summation option to the table. In this case the user's choice will be used instead.

Do not enable DutyOfCareRule and OverrideDefaultSummationRule at the same time.

Both of these rules add an explicit summation if there is no summation in a table, so only one will ever take effect at a time. Each rule sets the summation in different ways, so using them together can result in undefined behaviour.

The duty of care rule is not enabled by default. To activate and configure the rule:

1. Locate the following section:

   XML

    <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <!-- <rules:rule-name name="HierarchyLevelRule_All"/> -->
           <rules:rule-name name="DemographicVariablesRule"/>
   <rules:rule-name name="TableCellsNumberRule"/>
   <!--<rules:rule-name name="checkAddToDimensionRule"/> -->
   <!--<rules:rule-name name="checkDoubleCountingRule"/> -->
   <rules:rule-name name="SummationOptionsRule"/>
   <!--<rules:rule-name name="DutyOfCareRule"/> -->

2. Remove the comments from the DutyOfCareRule element:

   XML

    <rules:RulesPipe name="CDataOnlineEditRules">
   <!-- <rules:rule-name name="OverrideDefaultSummationRule"/>    -->
   <!-- <rules:rule-name name="MandatoryFieldsRule"/> -->
   <!-- <rules:rule-name name="DBSummationOptionsRule"/> -->
   <!-- <rules:rule-name name="GuestUserCellLimitRule"/> -->
   <!-- <rules:rule-name name="noConcatenationRule"/> -->
    <rules:rule-name name="GroupQueryLimitRule"/>
   <!-- <rules:rule-name name="HierarchyLevelRule_All_Old"/> -->
   <!-- <rules:rule-name name="HierarchyLevelRule_All"/> -->
   <rules:rule-name name="DemographicVariablesRule"/>
   <rules:rule-name name="TableCellsNumberRule"/>
   <!--<rules:rule-name name="checkAddToDimensionRule"/> -->
   <!--<rules:rule-name name="checkDoubleCountingRule"/> -->
   <rules:rule-name name="SummationOptionsRule"/>
   <rules:rule-name name="DutyOfCareRule"/> 

3. You may also wish to modify the rule itself. The following is the default duty of care rule:

   XML

   <rules:EditRule name="DutyOfCareRule"
      applicableOperations="all"
      implClassName="au.com.str.webapi.services.database.manager.rules.impl.DutyOfCareRule">
     <rules:impl-class-init>
   <rules:init-param name="Fields selected from a single fact table" value="use fact table"/>
   <rules:init-param name="Fields selected from multiple fact tables" value="user selects fact table"/>
     </rules:impl-class-init>
   </rules:EditRule>

   There are two parameters, each of which can have two possible values:

   Fields selected from a single fact table
   default	When all the fields in the table come from a single fact table, the default summation for the dataset will be used.
   use fact table	When all the fields in the table come from a single fact table, the default summation will be a count of the fact table that the fields come from.

   Fields selected from multiple fact tables
   default	When the fields in the table come from multiple fact tables, the default summation for the dataset will be used.
   user selects fact table	When the fields in the table come from multiple fact tables, the user will be prompted to select which fact table they want to count:

4. Save your changes and restart SuperWEB2 or the Tomcat service.

GuestUserCellLimitRule

This rule can be used to prevent guest users from creating large tables. The rule is disabled by default (meaning that there is no restriction on the size of tables that can be created by guest users).

For more details on enabling this rule, see Prevent Guest Users from Creating Large Tables.

DBSummationOptionsRule

The DBSummationOptionsRule rule can be used to restrict users to a single summation option per table. By default, this rule is commented out, and users can add multiple summation options to a table.

If you have configured any mandatory summation options using the mandatory fields rule, then you cannot use the DBSummationOptionsRule.

To restrict users to a single summation option per table:

1. Uncomment the following section of RulesEngine.xml:

   XML

   <rules:EditRule name="DBSummationOptionsRule"
      applicableOperations="add"
      implClassName="au.com.str.webapi.services.database.manager.rules.impl.DatabaseSummationOptionsRule">
     <rules:impl-class-init>
   <rules:init-param name="dbid" value="*"/>
     </rules:impl-class-init>
   </rules:EditRule>

2. If you only want to apply the summation options rule to a subset of the datasets, change the value of the dbid parameter to a comma separated list of dataset IDs. For example:

   XML

   <rules:init-param name="dbid" value="bank,people,census"/>

   If you want to apply the rule to all datasets then you can leave this set to *

3. Locate the following section:

   XML

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

4. Remove the comments from the DBSummationOptionsRule:

   XML

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

5. Save your changes and restart Tomcat or the SuperWEB2 service.

OverrideDefaultSummationRule

You can use this rule to change the default summation options for your datasets.

The  OverrideDefaultSummationRule has been deprecated, as the mandatory fields rule now supports summation options and is the recommended method for configuring a specific summation option to be required in a table.

See Mandatory Fields for more details on configuring mandatory fields. Alternatively, see Change Default Summation Option for more information on using the OverrideDefaultSummationRule.

Do not enable OverrideDefaultSummationRule and DutyOfCareRule at the same time.

Both of these rules add an explicit summation if there is no summation in a table, so only one will ever take effect at a time. Each rule sets the summation in different ways, so using them together can result in undefined behaviour.

MandatoryFieldsRule

This rule allows you to specify that certain fields are mandatory (they must be included in all tables). For more information, see Mandatory Fields.

MandatoryValuesRule

This rule allows you to specify that specific field items are mandatory if the corresponding field is included in a table. For more information, see Mandatory Values.

QuantileFilterRules / FieldExclusionRule

You can use these rules to configure field exclusion rules for quantile ranges. For more information, see Configure Quantiles and Ranges.