Configure Field Exclusion Rules - SuperWEB2

You can use the field exclusion rules to limit the number of fields from a defined group that can be added to the table at any one time. This feature is typically used to restrict the number of sub-state geographies that can be added into a table at the one time.

Step 1 - Confirm that the Field Exclusion Rule is Active

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

2. Locate the following section and confirm that the FieldExclusionRule is active and not commented out:

   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="DemographicVariablesRule"/>
     <rules:rule-name name="TableCellsNumberRule"/>
     <rules:rule-name name="HierarchyLevelRule_All"/> 
     <rules:rule-name name="checkAddToDimensionRule"/>
     <rules:rule-name name="checkDoubleCountingRule"/>
     <rules:rule-name name="AutoRecodeItemRule"/>
     <rules:rule-name name="SummationOptionsRule"/>
     <rules:rule-name name="DutyOfCareRule"/>        
     <rules:rule-name name="FieldExclusionRule"/>   
   </rules:RulesPipe>

3. Save your changes to the file (if any).

Step 2 - Define the Field Exclusion Rules

To define the field exclusion rules you need to edit <tomcat_home>\webapps\webapi\WEB-INF\classes\fieldExclusionRule.properties

There may be multiple copies of this file for different languages and locales with names like fieldExclusionRule_en.properties, and fieldExclusionRule_en_AU.properties.

You may wish to delete the localised versions so that you only have to maintain a single set of field exclusion rules in fieldExclusionRule.properties. If you choose not to delete the other versions then you will need to complete these steps in all copies of the file. The properties file that is used will be selected based on the language settings in the user's browser and the set of supported locales defined in the faces-config.xml configuration file (see Multilingual and Localisation Support - SuperWEB2 for more information about localisation and how SuperWEB2 uses the properties files).

The rules are defined as a list of fields and a maximum number. Users will not be able to add more than the maximum number of fields from this group to the table.

The format of the rule definition is as follows:

<database_id>/<field>,<field>,<field>,<field>=<max_number>

Where:

• <database_id> is the ID of the database this rule applies to (you can obtain the database ID by using the cat command in SuperADMIN). To create a rule that applies to all databases, use the * character.
• <field>,<field>,<field>,<field> is a comma separated list of field names that make up the group. If there are spaces in the field names then you must escape the spaces with the \ character.
• <max_number> is the maximum number of fields from this group that can be included in a table at any one time.

For example, the following rule specifies that only one of these three fields (Age, Area and Marital Status) can be added to the table at any one time:

bank/Age,Area,Marital\ Status=1

When you have finished defining your rules, save your changes to the file and restart Tomcat or the SuperWEB2 service.

You can now verify your rule in SuperWEB2:

Notes:

• If a recode exists under a field that has the field exclusion rule applied, the same error will occur if a user tries to add the recode to a table and it exceeds the limit.
• The rule also applies to hierarchical fields. If a user attempts to add a value from a field with multi-level hierarchies, an error will occur if the limit is exceeded.

Optional - Multiple Rules for a Single Database

You can only define one rule for a given database in the fieldExclusionRule.properties file. If you attempt to define multiple rules for a single database, then only the last rule listed in the file will be applied.

If you want to have multiple rules for one database then you need to create a copy of the fieldExclusionRule.properties file and define the additional rules there, then add a reference to the copied file into RulesEngine.xml.

There is a slight performance penalty associated with having multiple rules for the same database.

1. Create a copy of fieldExclusionRule.properties and give the file the name fieldExclusionRule2.properties
2. Define your second rule in the second properties file.
3. Open <tomcat_home>\webapps\webapi\WEB-INF\data\.repository\RulesEngine.xml in a text editor.

4. Locate the following section of the file:

   XML

   <rules:EditRule name="FieldExclusionRule"
         applicableOperation="add"
         implClassName="au.com.str.webapi.services.database.manager.rules.impl.FieldExclusionRule">
     <rules:impl-class-init>
       <rules:init-param name="resource" value="fieldExclusionRule"/>
     </rules:impl-class-init>
   </rules:EditRule>

5. Make a copy of this section, changing the name and value to fieldExclusionRule2:

   XML

   <rules:EditRule name="FieldExclusionRule"
         applicableOperation="add"
         implClassName="au.com.str.webapi.services.database.manager.rules.impl.FieldExclusionRule">
     <rules:impl-class-init>
       <rules:init-param name="resource" value="fieldExclusionRule"/>
     </rules:impl-class-init>
   </rules:EditRule>
   <rules:EditRule name="FieldExclusionRule2"
         applicableOperation="add"
         implClassName="au.com.str.webapi.services.database.manager.rules.impl.FieldExclusionRule">
     <rules:impl-class-init>
       <rules:init-param name="resource" value="fieldExclusionRule2"/>
     </rules:impl-class-init>
   </rules:EditRule> 

6. 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="DemographicVariablesRule"/>
     <rules:rule-name name="TableCellsNumberRule"/>
     <rules:rule-name name="HierarchyLevelRule_All"/> 
     <rules:rule-name name="checkAddToDimensionRule"/>
     <rules:rule-name name="checkDoubleCountingRule"/>
     <rules:rule-name name="AutoRecodeItemRule"/>
     <rules:rule-name name="SummationOptionsRule"/>
     <rules:rule-name name="DutyOfCareRule"/>        
     <rules:rule-name name="FieldExclusionRule"/>  
   </rules:RulesPipe>

7. Add your new rule to the list:

   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="DemographicVariablesRule"/>
     <rules:rule-name name="TableCellsNumberRule"/>
     <rules:rule-name name="HierarchyLevelRule_All"/> 
     <rules:rule-name name="checkAddToDimensionRule"/>
     <rules:rule-name name="checkDoubleCountingRule"/>
     <rules:rule-name name="AutoRecodeItemRule"/>
     <rules:rule-name name="SummationOptionsRule"/>
     <rules:rule-name name="DutyOfCareRule"/>        
     <rules:rule-name name="FieldExclusionRule"/>  
     <rules:rule-name name="FieldExclusionRule2"/> 
   </rules:RulesPipe>

8. Save your changes to the file and restart Tomcat or the SuperWEB2 service.