Conditional Annotations

Conditional annotations give you advanced control over when a particular annotation is shown. For example, you can configure an annotation to show when a particular combination of fields appears in a table.

There are three steps involved in configuring conditional annotations:

Step 1 - Create the Annotation Repository

The actual annotations themselves (the symbol and text to display) are defined in the same way as standard static annotations: you need to create a SQLite DB file and add all your annotations to the AnnotationDetails table.

You do not need to define any assignment rules in the database file; just add the symbols and descriptions to the AnnotationDetails table. You will define the rules for conditionally showing or hiding the annotations in a text file in the next step.

Step 2 - Create the Annotation Rules File

The annotation rules file is a text file that defines the conditions for showing or hiding specific annotations.

Rules File Location

By default, SuperSERVER expects the annotation rules file to be named <database_filename>.sxv4.anno_rules.csv and saved in the same directory as the SXV4 file it relates to. For example:

If the Database File Is...	The Rules File Should Be...
C:\ProgramData\STR\SuperSERVER SA\databases\people.sxv4	C:\ProgramData\STR\SuperSERVER SA\databases\people.sxv4.anno_rules.csv
C:\ProgramData\STR\SuperSERVER SA\databases\RetailBanking.sxv4	C:\ProgramData\STR\SuperSERVER SA\databases\RetailBanking.sxv4.anno_rules.csv
E:\Databases\SurveyResults2013.sxv4	E:\Databases\SurveyResults2013.sxv4.anno_rules.csv

It is possible to use a different location for the rules file if you wish. You can configure this when you create and apply the annotations method in the final step below.

Rule Construction

Each annotation rule set takes the form of a rule definition, which can optionally be followed by any number of additional conditions related to that annotation rule. Annotation rule sets take the following form:

TEXT

ANNO, <rule_id>, <annotation_symbol>, {SHOW|HIDE}, {FIELD|FIELDITEM}, <fact_table>, <field> [, <value_set_name>, <value_set_code> ]
<rule_id>, {SHOW|HIDE}, [ {FIELD|FIELDITEM}, <fact_table>, <field> [, <value_set_name>, <value_set_code> ] ]+
...

The first line in the rule set configures a specific annotation to be shown or hidden by default if a particular field or field item appears in the table.

The second (and subsequent lines) are optional; if present, they provide additional conditions for the rule set:

The additional conditions can have multiple fields or field items specified on a single line, in which case they are evaluated as logical "AND" (the specific condition will only apply if all of the fields or items listed on that line are present).
When the additional conditions are specified as separate lines, they are evaluated in order until one of the rules is hit. That means if they are all SHOW rules or all HIDE rules, then they are evaluated as a logical "OR" (they will apply if any of the rules hit). However, if the conditions are a mix of SHOW and HIDE rules then the first rule that hits will be the one that is used.

This allows you to construct some advanced conditions, for example you can show a particular annotation if a specific field appears in the table except when another field, field item, or combination of fields and field items appear in the table. See below for some examples.

The rule definitions take the following values:

<rule_id>	An ID for the rule set. Give each rule set a unique numeric ID, starting at 1. This ID is used to link the additional conditions with the main rule definition.
<annotation_symbol>	The annotation symbol that this rule set relates to. This must match a symbol that is specified in the `AnnotationDetails` table in the SQLite database.
{SHOW\|HIDE}	Whether to show or hide the annotation if the condition matches.
{FIELD\|FIELDITEM}	Whether this condition applies to an entire field or a specific field item.
<fact_table>	The fact table that the field belongs to. This is the original fact table name that was used when the SXV4 was created. If you do not know the fact table name then you can find it by using the command `cat <dataset_id> <field>` in SuperADMIN. This command returns an `ID` value in the format `SXV4__<dataset>__<fact_table>__<field>_FLD`. For example, in the following output the fact table name is `F_Customer`: CODE `> cat bank Gender [ XTAB Field : 'Gender' ] [ ID : 'SXV4__Retail_Banking__F_Customer__Gender_FLD' ] [ Value Set : 'SXV4__Retail_Banking__C_Gender' ]`
<field>	The name of the field, as defined in the SXV4. This can also be obtained using the the `cat <dataset_id> <field>` command in SuperADMIN.
<value_set_name>	(Only required for `FIELDITEM` conditions). The name of the value set this field item belongs to. You can also find this by using the command `cat <dataset_id> <field>`. The value set name is returned in the `Value Set` response, which takes the following format: `SXV4__<dataset>__<value_set>`. In the above example, the value set is `C_Gender`.
<value_set_code>	(Only required for `FIELDITEM` conditions). The code of the individual field item this condition applies to. You can either obtain this from SuperWEB2 (by switching the table to show codes) or by using the following command in SuperADMIN: `cat <dataset_id> <valueset_id> <values>`. The codes are returned as the `id` value. For example: CODE `> cat bank SXV4__Retail_Banking__C_Gender values [ Value : 'Male' (id:M) ] [ Value : 'Female' (id:F) ] [ Value : 'Unknown' (id:U) ] [ Value : 'Not Applicable' (id:-1) ]`

Example Rule Definitions

The following are some example rule definitions.

Show the annotation with symbol * when Gender appears in the table, except when Occupation also appears in the table:

CODE

ANNO, 1, *, SHOW, FIELD, F_Customer, Gender
1, HIDE, FIELD, F_Customer, Occupation

Show the annotation with symbol # when Area appears in the table, except when Marital Status - Single also appears in the table:

CODE

ANNO, 2, #, SHOW, FIELD, F_Customer, Area
2, HIDE, FIELDITEM, F_Customer, Marital_Status, C_Marital_Status, S

Show the annotation with symbol D only if all of the following appear in the table: Marital Status - Married, Area, and Product Type - Credit Card:

CODE

ANNO, 3, D, HIDE, FIELDITEM, F_Customer, Marital_Status, C_Marital_Status, M
3, SHOW, FIELD, F_Customer, Area, FIELDITEM, F_Account, Product_Type, C_Product_Type, C

Show the annotation with symbol @ if Occupation appears in the table, except if either (or both) Gender or Marital Status - Married also appear in the table:

CODE

ANNO, 4, @, SHOW, FIELD, F_Customer, Occupation
4, HIDE, FIELD, F_Customer, Gender
4, HIDE, FIELDITEM, F_Customer, Marital_Status, C_Marital_Status, M

Show the annotation with symbol $ if Marital Status - Divorced and Product Type - Credit Card appears in the table, except when Product Type - Credit Card and Gender - Male both appear in the table:

CODE

ANNO, 5, $, HIDE, FIELDITEM, F_Customer, Marital_Status, C_Marital_Status, D
5, HIDE, FIELDITEM, F_Account, Product_Type, C_Product_Type, C, FIELDITEM, F_Customer, Gender, C_Gender, M
5, SHOW, FIELDITEM, F_Account, Product_Type, C_Product_Type, C

Show the annotation with symbol !! if both Gender - Male and Marital Status - Married appear in the table:

CODE

ANNO, 6, !!, HIDE, FIELDITEM, F_Customer, Gender, C_Gender, M
6, SHOW, FIELDITEM, F_Customer, Martial_Status, C_Marital_Status, M

Step 3 - Use Methods to Enable Conditional Annotations for the Dataset

Conditional annotations are implemented using a Data Control module, annotationrules.dll (or annotationrules.so on Linux), which must be located in the SuperSERVER program files directory. The module does not run by default so you need to create a method that activates it in SuperADMIN and apply this to any datasets where you want to use the feature.

If you are using the default rules file location for all your datasets (i.e., each dataset has its own rules file, located in the same directory as its corresponding SXV4 file and named <database_filename>.sxv4.anno_rules.csv) then you only need to create one data control method, which you can apply to any datasets where you want to use conditional annotations. However, if you want to use non-default locations for the rules files then you will need to create multiple methods, with each method definiting the specific rules file location that you want to use.

Define the Method in SuperADMIN

Use the SuperADMIN method command to create the method:

CODE

method addmethod <method_id>
method <method_id> adddcplugin <dc_plugin_id> annotationrules

Replace <method_id> and <dc_plugin_id> with ID values of your choice. For example:

CODE

> method addmethod annotation_rules_method
> method annotation_rules_method adddcplugin annotationplugin annotationrules

If you want to use a custom location for your rules file, add this to the method:

CODE

method <method_id> <dc_plugin_id> addproperty RulesTable <path>

Replace the IDs with the values you used when you created the method, and replace <path> with the full path to the rules file you want to use. You must escape any Windows style directory separators (\) in the path with a backslash. For example:

CODE

> method annotation_rules_method annotationplugin addproperty RulesTable "C:\\path\\to\\anno_rules.csv"

Use the cat command to apply the method to your datasets:

CODE

cat <dataset_id> addmethod <method_id>

For example:

CODE

> cat bank addmethod annotation_rules_method