` of the form field (replace `
` with the ID you used for the form field). This will be used to display your custom validation error message (if any):
XML
2. In the `` section at the top of the file, add a new custom validator within the `$(document).ready()` function
For example, the following Javascript validates that the company name entered by the user is at least 5 characters long:
JavaScript
var checkCompanyAndShowError = function () {
var $company = $("#userRegistration-company");
var $companyError = $("#userRegistration-company-error");
var isCompanyValid = $company.val().length > 5;
if ($company.val().length <= 5) {
userRegistration.showFieldError($company, $companyError, "#{labels['register.signUpForm.error.company']}");
} else {
userRegistration.hideFieldError($company, $companyError);
}
return isCompanyValid;
};
3. Add any new properties to the **common_labels.properties** file. In this example, the error message itself uses the property `register.signUpForm.error.company`:
register.signUpForm.error.company=Please enter at least 5 characters
4. Locate the form validator section:
JavaScript
var formValidator = function () {
return window.userRegistration.checkEmailAndShowError();
};
Update the validation code to check your new validation function in addition to the existing check that they have entered an email. For example:
JavaScript
var formValidator = function () {
var isValidEmail= window.userRegistration.checkEmailAndShowError();
var isValidCompany = checkCompanyAndShowError();
return isValidEmail && isValidCompany;
};
For example:
You will need to restart Tomcat or the SuperWEB2 service to apply any changes you make to the **common_labels.properties** file.
---
version: "9.21"
language: "en"
---
# Add your Support Contact Email to Error Messages
There are some login error messages included with SuperWEB2 that contain an email address link for the user to contact support. For example:
By default, these support links are configured to use a dummy email address (**support@example.com**). Before going into production, you should update these messages so that they use your real support email.
To update the links, you need to edit **\\\webapps\\webapi\\WEB-INF\\classes\\common_labels.properties**.
There may be multiple copies of this file for different languages and locales, with names like **common_labels_en.properties** , and **common_labels_en_AU.properties** . You need to make these changes in all versions of the file. The properties file that is used will depend on the language settings in the end user's web browser and the set of supported locales defined in the **faces-config.xml** configuration file (see [Multilingual and Localisation Support](https://docs.wingarc.com.au/superstar/9.21/multilingual-and-localisation-support.md) for more information about localisation and how SuperWEB2 uses the properties files).
1. Open the file in a text editor.
2. Search the file for all the instances of `mailto:support@example.com` and change the email address to your real support email.
3. For example, change these lines from:
login.error.accountLocked=Account locked, please contact support.
login.error.serverUnreachable=The system is currently unavailable. Please contact support or try again later.
login.error.internalServer=The system has encountered an internal error and you have been logged out. Please try again or contact support if this problem persists.
login.error.accountNoDatabaseAccess=Your user account does not have access to any datasets, please contact support.
register.invalidResponse.description=Please try again or contact support if this problem persists.
register.resendLink.notSent.description=Reload the page and try again. Please contact support if this problem persists.
register.notProcessed.description=Please click on the link from your email and try this again. Please contact support if this problem persists.
To:
login.error.accountLocked=Account locked, please contact support.
login.error.serverUnreachable=The system is currently unavailable. Please contact support or try again later.
login.error.internalServer=The system has encountered an internal error and you have been logged out. Please try again or contact support if this problem persists.
login.error.accountNoDatabaseAccess=Your user account does not have access to any datasets, please contact support.
register.invalidResponse.description=Please try again or contact support if this problem persists.
register.resendLink.notSent.description=Reload the page and try again. Please contact support if this problem persists.
register.notProcessed.description=Please click on the link from your email and try this again. Please contact support if this problem persists.
4. Apply this change to all versions of this file for all the languages in use on your deployment.
5. Save your changes and restart Tomcat or the SuperWEB2 service.
---
version: "9.21"
language: "en"
---
# Adding Multiple Fields to an Axis: Nesting and Concatenation
You can add multiple fields to one axis in your table. You have two different options for doing this: nesting the fields, and concatenating them.
In this example, the **Gender** and **Marital Status** fields are nested on the row axis:
In this example, **Gender** and **Marital Status** are concatenated on the row axis:
In this example, **Gender** and **Marital Status** are nested on the wafer:
In this example, **Gender** and **Marital Status** are concatenated on the wafer:
Concatenation is enabled in SuperWEB2 by default, but it is possible your administrator may have disabled this feature on your deployment. If this is the case you will be able to nest fields in your tables but not concatenate them.
Some features are not available when you have nested or concatenated fields in your table. For example, mapping will not be available if you concatenate or nest a geographic field (although mapping will still be available if the nesting or concatenation is only on the opposite axis to the one that contains the geographic field).
In addition, if your administrator has configured mandatory fields then you will not be able to concatenate another field onto the same axis as the mandatory field (as this would allow you to circumvent the mandatory field restriction).
## Nesting Fields
There are two ways you can nest fields on an axis. The best one to choose will depend on whether you want to add all a field's items or whether you want to select specific items within the field.
### Drag and Drop
This method is the quickest way to start building up a table. It adds all of the items for a particular field at once with a simple drag and drop technique.
1. Click and drag the first field towards the table. As you start to do this, the **Row** , **Column** and **Wafer** options appear. Drop the field onto one of these options:
2. Click and drag the second field onto the same option:
3. SuperWEB2 nests the fields in the table:
The first field you added will be nested at the outermost level; if you want to change this you can rearrange the fields within the table by dragging and dropping the field names:
### Use the Add to Row or Add to Column Button
This method is a better option if you only want specific items from a field.
1. Select the check boxes next to the items you want to add from the first field and click **Add to Row** , **Column** , or **Wafer**:
2. Select the check boxes next to the items you want to add from the second field and click the button again:
3. SuperWEB2 nests the fields in the table:
## Concatenating Fields
There are two ways you can concatenate fields on an axis. The best one to choose will depend on whether you want to add all a field's items or whether you want to select specific items within the field.
### Drag the Fields to the Table
This method is the quickest way to concatenate two fields in a table. It adds all of the items for a particular field at once with a simple drag and drop technique.
1. Click and drag the first field towards the table. As you start to do this, the **Row** , **Column** and **Wafer** options appear. Drop the field onto one of these options:
2. Click and drag the second field. As you start to do this, drop zones become available inside the table on the last item of any existing fields. Drag and drop the new field onto the drop zone:
3. SuperWEB2 concatenates the fields:
When you are using this method to concatenate fields on a wafer, the drop zone is the name of the existing field that is already in the wafer:
### Select Field Items from Multiple Fields
This method can be a better option if you want to select which items from a field you are adding to the table.
1. Select the check boxes next to the field items from multiple fields, then click **Add to Row** , **Column** , or **Wafer**:
2. SuperWEB2 concatenates the fields in the table (the ordering is based on the order you selected the check boxes; in this example we selected items from the **Gender** field first):
If your administrator has disabled concatenation, then the fields will be nested instead.
---
version: "9.21"
language: "en"
---
# Advanced Confidentiality Rule Options
By default, the confidentiality rule will apply to all tables created from any dataset that the method has been applied to in SuperADMIN. From release 9.6 onwards, some additional configuration options have been added. For example, you can now configure the confidentiality rule so that it only applies when specific fields are in the table.
This section describes these additional options:
## Apply the Confidentiality Rule only when Specific Fields or Summation Options are in the Table
The confidentiality rule module now supports a `FIELDS` property, which takes a list of field codes or labels (separated by semi-colons). When this property is set, the confidentiality rule will only apply if at least one of the specified fields is in the table.
For example, the following method will only apply when the **Gender** or **Marital Status** fields appear in a table:
method addmethod conditionalconfid mandatory "Conceal values 10 or less when Gender or Marital Status in table"
method conditionalconfid adddcplugin confrule confidentialityrule
method conditionalconfid confrule addproperty RULESET "THRESHOLD(10)"
method conditionalconfid confrule addproperty FIELDS "Marital Status;Gender"
Once you have defined the method, you can apply it to a dataset in the usual way. For example:
cat bank addmethod conditionalconfid
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Age** by **Gender**, values 10 and under are concealed:  | **Age** by **Area**, values 10 and under are not concealed:  |
### Summation Options
Prior to version 9.9.3, the `FIELDS` property only supported classification fields. From version 9.9.3 onwards, summation options or measures can now also be specified. Specify summation options using the `FIELDS` property in the same way as classifications. Both lables and IDs are supported. For example:
method conditionalconfid confrule addproperty FIELDS "Marital Status;Customer Profit;Gender"
method conditionalconfid confrule addproperty FIELDS "F_Customer:Marital_Status;F_Customer:Cust_Profit;F_Customer:Gender"
### Notes and Examples for Specifying Fields
| **Specifying the fact table** | You can optionally specify the fact table that a field belongs to (for example because you have a field with the same label in multiple fact tables but you only want the rule to apply to one of those fields). Specify the code or label of the fact table, followed by a colon, and then the code or label of the field. For example, the following setting applies confidentiality to the **Marital Status** field in the **Customers** table and the **Product Type** field in the **Accounts** table. It also applies to any instances of a field called **Gender**, regardless of which fact table it appears in: method conditionalconfid confrule addproperty FIELDS "Customers:Marital Status;Accounts:Product Type;Gender" |
| **Using codes instead of labels** | The `FIELDS` property accepts both field labels and codes. Using codes, the above example could be rewritten as: method conditionalconfid confrule addproperty FIELDS "F_Customer:Marital_Status;F_Account:Product_Type;Gender" You can obtain the field and fact tables codes from SuperADMIN by using the following command: cat For example, to obtain the code for **Marital Status** in the sample Retail Banking dataset (id: `bank`): > cat bank "Marital Status" [ XTAB Field : 'Marital Status' ] [ ID : 'SXV4__Retail_Banking__F_Customer__Marital_Status_FLD' ] [ Value Set : 'SXV4__Retail_Banking__C_Marital_Status' ] The codes are returned in the field ID, which takes the following format: `SXV4_______FLD`. In the example shown here, the fact table code is `F_Customer` and the field code is `Marital_Status` If you choose to specify the fact table as well as the field (such as `F_Customer:Marital_Status`), then you must use either the codes for both the fact table and field, or the labels for both. You cannot use a combination of the two, such as a fact table code followed by a field label. |
| **Multilingual datasets** | If you have a multilingual dataset, then you can still use either labels or codes to specify your list of fields. If specifying labels, you must use the label from the original language used when the SXV4 was channelled. |
| **Weighted datasets** | For weighted datasets, you must use the field codes. To find the correct code, first obtain the value of the `` expression from the formula XML file and then use this to query SuperADMIN for the correct code to use. For example: You will need to replace `%MEASURE` with the relevant weighting when querying SuperADMIN. For example: > cat survey 'Number of Persons' [ Summation Field : 'Number of Persons' ] [ ID : 'SXV4_2018SURVEY__FACTTABLE__ITEM_1889318_VAR_FLD' ] > cat survey 'Number of Households' [ Summation Field : 'Number of Qualifications' ] [ ID : 'SXV4_2018SURVEY__FACTTABLE__ITEM_1889317_VAR_FLD' ] In the above example, the relevant codes are `ITEM_1889318_VAR` and `ITEM_1889317_VAR`. |
| **User Defined Fields** | The confidentiality rule also applies if there are any User Defined Fields (UDFs) in the table that are derived from one of the fields specified in the `FIELDS` property. This includes: * Summation UDFs (in this case, the confidentiality rule will apply to the entire table, even if there are other summation options used in the table that are not derived from a specified field). * Classification UDFs. * UDFs where the specified field is used as a filter even if it is not the main field being transformed (for example in multiple level UDFs and quantiles). The above applies recursively, so that a UDF based on a UDF that is based on one of the specified fields will also count for the purposes of determining whether to apply the confidentiality rule. |
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
## Set Different Thresholds for Totals and Non Totals
It is now possible to set a different threshold value depending on whether the cell is a total or a regular table cell. The `THRESHOLD` property now takes an optional second parameter that can be set to `TOTALS` or `NONTOTALS` to indicate which cells the threshold applies to. When setting both thresholds, specify two `THRESHOLD` properties, separated by the `|` character.
For example, the following method applies a threshold of 5 to non totals and 10 to total cells:
method addmethod differenttotals mandatory "Conceal values of 5 or less in regular cells and 10 or less in totals"
method differenttotals adddcplugin confrule confidentialityrule
method differenttotals confrule addproperty RULESET "THRESHOLD(5,NONTOTALS)|THRESHOLD(10,TOTALS)"
Once you have defined the method, you can apply it to a dataset in the usual way. For example:
cat bank addmethod differenttotals
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The example table shown here has no threshold rule applied to it.  | With the above threshold rules, the low value cells are concealed. In the highlighted cells, values of 6 and 8 in regular table cells have not been concealed (as they are above 5). However, a value of 8 has been concealed in the total column.  |
## Set Different Frequency Rules for Totals and Non Totals
It is also possible to set a different frequency rule for totals and non totals. The `FREQ` rule now takes an optional additional parameter that can be set to `TOTALS` or `NONTOTALS`. When setting both frequency rules, specify two `FREQ` properties, separated by the `|` character.
For example, the following method applies a frequency rule of 3 to non totals and 5 to total cells:
method addmethod differentfreqs mandatory "Conceal regular cells with 5 contributors or fewer and conceal totals with 10 contributors or fewer"
method differentfreqs adddcplugin confrule confidentialityrule
method differentfreqs confrule addproperty RULESET "FREQ(3,,NONTOTALS)|FREQ(5,,TOTALS)"
The double comma is required, as the `TOTALS` / `NONTOTALS` parameter is the *third* parameter accepted by the `FREQ` property (the second parameter is only used in cases where you want to specify a different cube when determining whether to conceal the results; see [Record Count](https://docs.wingarc.com.au/superstar/9.21/record-count.md) for more details on this setting).
Once you have defined the method, you can apply it to a dataset in the usual way. For example:
cat bank addmethod differentfreqs
---
version: "9.21"
language: "en"
---
# Advanced Exclusion Rules
This page describes the new exclusion rule capability introduced in version 9.21. For the original field exclusion rule feature, see [Field Exclusion Rules](https://docs.wingarc.com.au/superstar/9.21/field-exclusion-rules.md). The new rule works independently of the existing feature.
In most cases you will want to disable the existing feature when using the new rules as all the existing capability can now be applied using the new feature.
You can use the exclusion rules feature to limit the combinations of items from particular groups that can be added to the table at any one time. The new exclusion rule capability allows you to create more advanced and flexible rules, as it allows you to define groups and then choose how you want those groups to be combined. For example, you can create groups that are only applied when some other group's limit is reached or exceeded.
In addition, the new feature allows you to specify rules that apply at the value set level.
## Step 1 - Confirm that the new Exclusion Rule is Active
1. Open **\\\webapps\\webapi\\WEB-INF\\data\\.repository\\RulesEngine.xml** in a text editor.
2. Locate the `CDataOnlineEditRules` section:
XML
Remove the comments around the `ExclusionRule` (you may also want to comment *out* the existing `FieldExclusionRule` at this point, as shown below):
XML
3. In addition, locate the `QuantileFilterRules` and `NewTableRules` sections:
XML
Remove the comments around the `ExclusionRule` in both cases:
XML
4. Save your changes to the file.
5. Restart SuperWEB2 or Tomcat to apply the changes.
### Step 2 - Check for existing Exclusion Rules in SuperADMIN
Before starting to create or update rules, you should check whether there are any existing exclusion rules defined. Login to SuperADMIN and use the following command (replace `` with the ID of the dataset):
cfg db superweb2.rules.exclusion
SuperWEB2 will either display the list of existing rules (if some rules are already defined), or display `"not found"`.
The easiest way to define or update the rules is to use a text editor and then import the complete configuration. If there are existing rules defined then you should export those first and use that file; otherwise you can start from an empty text file. To export the existing configuration, use the following command (replacing `` with the dataset ID, and `` with the full path and filename of the location to save the file on disk; do not use quotes even if the path contains spaces):
cfg db superweb2.rules.exclusion save
### Step 3 - Define the Groups and Rules
The advanced exclusion rules feature is very flexible, and allows you to construct complex rules from simple building blocks. The basic structure of the overall configuration is as follows:
JSON
{
"groups": {
...
}
"rules": {
"root": { ... }
}
}
#### Groups:
* Within the `"groups"` section, you can define as many groups as you need, each with their own unique name of your choice.
* Groups can include fields and value sets (value sets allow you to refer only to specific levels in a hierarchical field, such as a particular level of geography).
* All elements need to be referenced using their IDs. Display names are not supported:
* For fields you specify them using the fact table ID and field ID.
* For value sets you specify them using the fact table ID, field ID, and value set ID.
* Value sets are applied explicitly, so if you want to block everything in a hierarchy from a certain level down, you need to specify each individual value set in the group.
* Groups can optionally include a `"limit"` setting, which acts as a default limit for that group (the limit can also be defined/overridden when the group is used in the `"rules"` section).
The following shows an example of some group configuration (items in `<` and `>` would be replaced with the relevant values):
JSON
"groups": {
"": {
"fields": [
{ "fact": "", "field": "" },
{ "fact": "", "field": "" },
{ "fact": "", "field": "" }
],
"limit": 2
},
"": {
"fields": [
{ "fact": "", "field": "", "valueSets": [ "", "" ... ] }
]
},
"": {
"fields": [
{ "fact": "", "field": "" },
{ "fact": "", "field": "" }
]
}
...
}
All defined groups must be used in at least one rule. If there are groups defined that are not used, SuperWEB2 will reject the configuration, block access to the dataset, and generate an error in its log file.
Fact table IDs, field IDs and value set IDs are validated at run time in SuperWEB2 (they are not validated when the configuration is loaded in SuperADMIN). If SuperWEB2 detects that an ID is invalid then it will reject the configuration, block access to the dataset, and generate an error in its log file.
#### Obtaining Fact Table, Field and Value Set IDs
You can find the IDs you need for the configuration in SuperADMIN by typing `cat `. For example:
> cat bank Age
[ XTAB Field : 'Age' ]
[ ID : 'SXV4__Retail_Banking__F_Customer__Age_FLD' ]
[ Value Set : 'SXV4__Retail_Banking__C_Age' ]
The reported ID value is in the following format; you will need the individual components, which are separated by double underscores, in your configuration):
SXV4_______FLD
For value sets, typing `cat ` for the parent field will return all the value sets. For example:
> cat bank Area
[ XTAB Field : 'Area' ]
[ ID : 'SXV4__Retail_Banking__F_Customer__Area_FLD' ]
[ Value Set : 'SXV4__Retail_Banking__C_State' ]
[ Value Set : 'SXV4__Retail_Banking__C_Geography_2' ]
[ Value Set : 'SXV4__Retail_Banking__C_Geography_1' ]
[ Value Set : 'SXV4__Retail_Banking__C_Geography_0' ]
Each value set ID is in the following format; you will need the final part of this ID for your configuration, in addition to the fact table and field IDs:
SXV4______
#### Rules Overview:
The `"rules"` section is where you define your rules themselves:
* It must include exactly one instance of `"root"`, which is the starting point for your chain of rules.
* You can define as many other rules as you need to within the `"rules"` section, and combine them together in a chain.
* `"root"` must contain one of the following:
* `"any"`, set to a list of other rules enclosed in square brackets. This means that if any one of the listed rules is triggered, the table will be blocked;
* `"all"`, set to a list of other rules enclosed in square brackets. This means that the table will only be blocked if all the listed rules are triggered (in the case where if/then rules are included in the list, this means that *both* the if and the then conditions need to be satisfied); or
* An individual rule. In this case this will be the only rule applied.
All defined rules must be used in the chain. If there are rules defined that are not used, SuperWEB2 will reject the configuration, block access to the dataset, and generate an error in its log file.
#### Types of Rules:
The following rule types are supported:
* `"activate"`: this rule triggers when the specified limit is reached for the specified group. When defining the rule you must specify the group it applies to and the limit (this can be either in the group definition or in the rule; if both are set then the limit at rule level takes precedence).
* `"exclude"`: this rule type is the same as `"activate"` except that it triggers when the limit is exceeded.
* `"if"` ... `"then"`: this rule type combines two other rules: the `"then"` rule will only be applied when the `"if"` rule is triggered.
The following shortcut rule types are also supported:
* `"mutuallyLimiting"`, which must be set to a list of two groups enclosed in square brackets. The referenced groups must have a `"limit"` set at group level. This rule means that the table will be blocked only when the limits from both groups are exceeded. Each group can individually exceed its configured limit when the other group does not exceed its limit.
* `"mutuallyExclusive"`, which must be set to a list of two groups, enclosed in square brackets. The referenced groups do not need to have their own limits defined at group level. This rule means that if any item from one of the groups is in the table, all of the items in the other group will automatically be blocked from being added to the table.
* `"ifAct"` ... `"thenEx"`, which is a shortcut for defining an if/then rule with an activation and exclusion group. It requires limits to be set at group level. See the example below for more details.
#### Example Rule Definitions
This example defines three sets of if/then rules and will block the table if any one of the rules is triggered:
JSON
"rules": {
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"root": { "any": [ "", "", "" ] }
}
This example just has a single rule, that triggers when this group exceeds the specified limit:
JSON
"rules": {
"root": { "exclude": "", "limit": }
}
This example shows how the above rules could be combined in the `"any"`/`"all"` lists under `"root"`:
JSON
"rules": {
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"": { "activate": "", "limit": },
"": { "exclude": "", "limit": }
"": { "if": "", "then": "" },
"root": { "any": [ { "exclude": "", "limit": }, "", "", "" ] }
}
Following are some examples of complete configuration that can be tested against the sample Retail Banking dataset:
Original Field Exclusion-style Rules
This rule replicates the original field exclusion rule feature, allowing a maximum of any two fields from the group of Gender, Occupation or Marital Status:
JSON
{
"groups": {
"field_exclusion_group": {
"fields": [
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Occupation" },
{ "fact": "F_Customer", "field": "Marital_Status" }
]
}
},
"rules": {
"root": { "exclude": "field_exclusion_group", "limit": 2 }
}
}
This example shows how multiple groups can be combined, allowing a maximum of two out of the first group and a maximum of one out of the second group:
JSON
{
"groups": {
"field_exclusion_group_1": {
"fields": [
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Occupation" },
{ "fact": "F_Customer", "field": "Marital_Status" }
]
},
"field_exclusion_group_2": {
"fields": [
{ "fact": "F_Customer", "field": "Age" },
{ "fact": "F_Account", "field": "Product_Type" }
]
}
},
"rules": {
"rule_1": { "exclude": "field_exclusion_group_1", "limit": 2 },
"rule_2": { "exclude": "field_exclusion_group_2", "limit": 1 },
"root": { "any": [ "rule_1", "rule_2" ] }
}
}
If/Then Rule Examples
This rule shows an example of an if/then rule. In this case:
* If there is at least one of Gender, Marital Status or Occupation in the table, then Postcodes (the lowest level of Area) cannot be in the table.
* Other levels of geography can be tabulated against one or more of those three fields.
* There is no restriction on tabulating Gender, Occupation and Marital Status against each other when postcodes is not in the table.
* Postcodes can be added to the table whenever those three fields are *not* in the table, and can be tabulated against any other field.
JSON
{
"groups": {
"field_exclusion_group": {
"fields": [
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Occupation" },
{ "fact": "F_Customer", "field": "Marital_Status" }
]
},
"lower_level_area" : {
"fields": [
{ "fact": "F_Customer", "field": "Area", "valueSets": [ "C_Geography_0" ] }
]
}
},
"rules": {
"area_activate": { "activate": "field_exclusion_group", "limit": 1 },
"area_exclude": { "exclude": "lower_level_area", "limit": 0 },
"root": { "if": "area_activate", "then": "area_exclude" }
}
}
The following is another example with multiple groups and multiple if/then rules: the two lower-level Area fields will be blocked if there are any two fields from the first group or any field from the second group in the table:
JSON
{
"groups": {
"field_exclusion_group_1": {
"fields": [
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Occupation" },
{ "fact": "F_Customer", "field": "Marital_Status" }
]
},
"field_exclusion_group_2": {
"fields": [
{ "fact": "F_Account", "field": "Product_Type" },
{ "fact": "F_Customer", "field": "Age" }
]
},
"lower_level_area" : {
"fields": [
{ "fact": "F_Customer", "field": "Area", "valueSets": [ "C_Geography_1", "C_Geography_0" ] }
]
}
},
"rules": {
"area_activate_1": { "activate": "field_exclusion_group_1", "limit": 2 },
"area_exclude_1": { "exclude": "lower_level_area", "limit": 0 },
"area_v_rule_1": { "if": "area_activate_1", "then": "area_exclude_1" },
"area_activate_2": { "activate": "field_exclusion_group_2", "limit": 1 },
"area_exclude_2": { "exclude": "lower_level_area", "limit": 0 },
"area_v_rule_2": { "if": "area_activate_2", "then": "area_exclude_2" },
"root": { "any": [ "area_v_rule_1", "area_v_rule_2" ] }
}
}
The following example is functionally the same as the previous one, but using the `"ifAct"` and `"thenEx"` shortcuts instead (as shown in this example, when using the shortcuts, the limits must be defined at group level):
JSON
{
"groups": {
"field_exclusion_group_1": {
"fields": [
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Occupation" },
{ "fact": "F_Customer", "field": "Marital_Status" }
],
"limit": 2
},
"field_exclusion_group_2": {
"fields": [
{ "fact": "F_Account", "field": "Product_Type" },
{ "fact": "F_Customer", "field": "Age" }
],
"limit": 1
},
"lower_level_area" : {
"fields": [
{ "fact": "F_Customer", "field": "Area", "valueSets": [ "C_Geography_1", "C_Geography_0" ] }
],
"limit": 0
}
},
"rules": {
"area_v_rule_1": { "ifAct": "field_exclusion_group_1", "thenEx": "lower_level_area" },
"area_v_rule_2": { "ifAct": "field_exclusion_group_2", "thenEx": "lower_level_area" },
"root": { "any": [ "area_v_rule_1", "area_v_rule_2" ] }
}
}
The rules section for the previous example could also be further simplified as follows using the `"ifAct"` and `"thenEx"` shortcuts:
JSON
"rules": {
"root": { "any": [ { "ifAct": "field_exclusion_group_1", "thenEx": "lower_level_area" }, { "ifAct": "field_exclusion_group_2", "thenEx": "lower_level_area" } ] }
}
Mutually Limiting Examples
This example shows how the `"mutuallyLimiting"` shortcut can be used. In this example users will be blocked from adding more than two items from both groups in the same table. So, for example: Age by Gender by Marital Status would be permitted on its own, but would be blocked if both Company and Product Type are also in the table.
JSON
{
"groups": {
"group1": {
"limit": 2,
"fields": [
{ "fact": "F_Customer", "field": "Age" },
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Marital_Status" },
{ "fact": "F_Customer", "field": "Occupation" }
]
},
"group2": {
"limit": 2,
"fields": [
{ "fact": "F_Customer", "field": "Cust_Mail_Ind" },
{ "fact": "F_Customer", "field": "Company" },
{ "fact": "F_Account", "field": "Product_Type" }
]
}
},
"rules": { "root": { "mutuallyLimiting": [ "group1", "group2" ] } }
}
Mutually Exclusive Examples
This example shows how the `"mutuallyExclusive"` shortcut can be used. In this example, any one field from `"group1"` blocks all fields from `"group2"`, and vice versa. There is no restriction on adding multiple fields from one group when there is nothing from the other group in the table.
Although there are limits set at the group level in the example configuration, these limits are not used as they are overridden by the `"mutuallyExclusive"` rule.
JSON
{
"groups": {
"group1": {
"limit": 3,
"fields": [
{ "fact": "F_Customer", "field": "Age" },
{ "fact": "F_Customer", "field": "Gender" },
{ "fact": "F_Customer", "field": "Marital_Status" },
{ "fact": "F_Customer", "field": "Occupation" }
]
},
"group2": {
"limit": 2,
"fields": [
{ "fact": "F_Customer", "field": "Cust_Mail_Ind" },
{ "fact": "F_Customer", "field": "Company" },
{ "fact": "F_Account", "field": "Product_Type" }
]
}
},
"rules": { "root": { "mutuallyExclusive": [ "group1", "group2" ] } }
}
### Step 4 - Upload Your Rule Configuration
Once you have finished configuring your rules, upload them to the SuperADMIN configuration server using the following command:
cfg db superweb2.rules.exclusion load
## Optional Configuration
### Define a Custom Error Message for Rule Breaches
When a user's selection breaches one of your configured rules, SuperWEB2 displays a standard error message. The text of this message is defined by the `fieldExclusion.failure` property defined in **CDataOnlineEditRules.properties** (and the equivalent versions for other UI languages), which is located in **\\\webapps\\webapi\\WEB-INF\\data\\.repository\\**.
You may wish to edit this message to reflect your preferred message to users when they exceed one of the configured limits.
fieldExclusion.failure=Error: Table contains an excluded set of items.
---
version: "9.21"
language: "en"
---
# Advanced JQM Configuration
This section describes some advanced configuration adjustments you may want to make to Job Queue Manager. You should [install Job Queue Manager and confirm that the basic functionality is working](https://docs.wingarc.com.au/superstar/9.21/configure-jqm.md) before making any of these changes.
## Job Expiry and Removal
By default, jobs will not be removed from the database. [Click here to find out how to configure SuperWEB2 to automatically remove old jobs from the database](https://docs.wingarc.com.au/superstar/9.21/job-expiry-and-removal.md).
### Date Format
You can change the format used to display the time a job was added to the job queue and time it will expire. [Learn more.](https://docs.wingarc.com.au/superstar/9.21/configure-date-display.md)
### Server Outages
You can configure how often Job Queue Manager checks for server and network outages. You can also configure it to send an email when it loses connection and again when it reconnects. [Learn more](https://docs.wingarc.com.au/superstar/9.21/superstar-server-outages.md).
### Job Queue Status and Priorities
Administrators can configure how Job Queue Manager prioritises jobs. See [Job Queue Manager Priority](https://docs.wingarc.com.au/superstar/9.21/job-queue-manager-priority.md) for more details.
It is also possible to review the status of jobs and check for errors by reviewing the database directly. [Learn more about the possible job statuses and what they mean](https://docs.wingarc.com.au/superstar/9.21/manage-the-job-queue.md).
### SuperWEB2 Customisations
If you have customised SuperWEB2, then you must make sure that any customised resources (such as custom table labels, copyright statements, and language resources) are available to Job Queue Manager. [Learn more](https://docs.wingarc.com.au/superstar/9.21/customised-resources.md).
### Compression Level
Job Queue Manager compresses the data when it writes output to the database. You can change the compression level to either reduce the file size or increase the processing speed. [Learn more](https://docs.wingarc.com.au/superstar/9.21/compression.md).
### Queue Processing Frequencey
By default, Job Queue Manager checks for new jobs to process every 10 seconds. You can change this setting. [Learn more](https://docs.wingarc.com.au/superstar/9.21/queue-processing-frequency.md).
### Display Name
If you have multiple Job Queue Manager instances running against the same database, you may wish to set the display name. This name is displayed in the database, and will allow you to tell which jobs belong to which Job Queue Manager instance. [Learn more](https://docs.wingarc.com.au/superstar/9.21/display-name.md).
### Field Level Security and Data Control
If you are using field level security, you are recommended to set this up before creating saved tables and queries in SuperWEB2. Changes to field level security may cause problems with existing saved tables. [Learn more...](https://docs.wingarc.com.au/superstar/9.21/field-level-security-and-data-control.md)
### Support for Concealment and Not a Number
If you have modified SuperWEB2's default settings for Concealment or Not a Number, you need to make the same configuration changes to Job Queue Manager. Learn more about changing the Job Queue Manager settings for [concealment](https://docs.wingarc.com.au/superstar/9.21/concealment.md) and [NaN support](https://docs.wingarc.com.au/superstar/9.21/cells-with-no-contributors.md).
### Logging
You can configure the amount of logging information that Job Queue Manager writes to its log files. [Learn more](https://docs.wingarc.com.au/superstar/9.21/logging-jqm.md).
---
version: "9.21"
language: "en"
---
# aggregated data
See [summary data](https://docs.wingarc.com.au/superstar/9.21/summary-data.md).
---
version: "9.21"
language: "en"
---
# annotation
Additional information associated with a table or chart.
For example, a symbol in a cell to denote a special condition (such as **Not Available**).
There are two parts to an annotation: a symbol in the cell and a footnote text for the symbol.
---
version: "9.21"
language: "en"
---
# Annotation Repository Schema
The annotation repository schema supports the following functions:
* Add/delete an annotation
* Update an annotation's symbol
* Update an annotation's description
* Enforce the uniqueness of annotation symbols
* Add/delete database assignments
* Add/delete field assignments
* Add/delete field value assignments
* Add/delete cell assignments
* Update assignments with a new annotation symbol
The annotation repository schema is represented in the following database entity diagram:
The tables in the annotation repository schema are:
| **Table** | **Description** | **Primary Key** | **Foreign Key** |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|-------------------------------------------------------------------|
| `AnnotationDetails` | Stores annotation symbols and descriptions. | `AnnotationID` | |
| `DbAssignment` | Stores database annotation assignments. | | Refers to the primary key in the `AnnotationDetails` table. |
| `FieldAssignment` | Stores field annotation assignments. | `UniqueCode` | `AnnotationID`. Refers to the primary key in `AnnotationDetails`. |
| `FieldValueCodeAssignment` | Stores field value annotation assignments. | `UniqueCode` | `AnnotationID`. Refers to the primary key in `AnnotationDetails`. |
| `Annotation` | Stores the joins between `AnnotationDetails` and `CellAssignment`. | `AnnotationAssignID` | `AnnotationID`. Refers to the primary key in `AnnotationDetails`. |
| `CellAssignment` | Stores cell assignment. All records that share the same `AnnotationAssignID` will be used to identify the position of cells. When a measure is used, `ValueSetName` and `FieldValueCode` must be left empty (") and not be set to null. | | `AnnotationAssignID`. Refers to the primary key in `Annotation`. |
---
version: "9.21"
language: "en"
---
# Annotations
The SuperSERVER annotation functionality allows you to automatically show additional information or explanatory notes when particular fields and values appear in a table.
The clients display the annotations beneath the table. For example:
You can enable annotations for a field (for example: **Gender** ), a field value (for example: **Male**), an individual cell value (a specific combination of fields) or an entire dataset.
You can also use [conditional annotations](https://docs.wingarc.com.au/superstar/9.21/conditional-annotations.md) to provide further control over when a particular annotation is shown (for example, to show a particular annotation when a given field appears in the table, except when another specific field is also in the table).
You are recommended not to create more than 100,000 annotations on any particular table.
SuperSERVER stores annotations in a relational database called the static annotation repository, which you need to create using a public domain relational database implementation called [SQLite](http://www.sqlite.org/).
The annotation repository must be stored in a file named **\.sxv4.sqlite.db**, saved in the same directory as the SXV4 database file it relates to. For example:
| **If the Database File Is...** | **The Annotation Repository Must Be...** |
|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| **C:\\ProgramData\\STR\\SuperSERVER SA\\databases\\RetailBanking.sxv4** | **C:\\ProgramData\\STR\\SuperSERVER SA\\databases\\RetailBanking.sxv4.sqlite.db** |
| **C:\\ProgramData\\STR\\SuperSERVER SA\\databases\\people.sxv4** | **C:\\ProgramData\\STR\\SuperSERVER SA\\databases\\people.sxv4.sqlite.db** |
| **E:\\Databases\\SurveyResults2013.sxv4** | **E:\\Databases\\SurveyResults2013.sxv4.sqlite.db** |
From version 9.9.3 onwards, SuperSERVER supports two types of annotation: static annotations, which can be assigned to specific datasets, fields, values and cells, and [conditional annotations](https://docs.wingarc.com.au/superstar/9.21/conditional-annotations.md), which provide advanced control over when the annotation is shown (for example you can configure annotations to only display if a specific combinations of fields appear in the table). [Learn more](https://docs.wingarc.com.au/superstar/9.21/conditional-annotations.md).
The following steps explain how to create your own annotation repositories.
## Step 1 - Create your SQL Scripts
The first step is to create a script file containing all the SQL statements required to populate your annotation database. SuperSERVER is supplied with a number of files to help you with this step, which you can find in **C:\\ProgramData\\STR\\SuperSERVER SA\\etc\\annotations** (or the equivalent directory if you installed to a different location):
* **schema.sql** contains SQL statements for creating an empty annotation repository. You do not need to edit this file; you will use it in the next step to create an empty annotation repository, ready to be populated with your annotations.
* **RetailBanking.sql** and **financial.sql** contain examples of the SQL required to populate the annotation repository. You can use these as a template for writing the SQL insert statements you need to populate your own annotation repository.
* **RetailBanking.sxv4.sqlite.db** and **Financial.sxv4.sqlite.db** are examples of pre built annotation repositories for the sample databases. You can test these out by copying them to the same directory as the sample SXV4 databases (**C:\\ProgramData\\STR\\SuperSERVER SA\\databases** by default).
To setup your SQL scripts:
1. Make a copy of either **RetailBanking.sql** or **financial.sql** and save it in the same directory as your database. Rename it to match the name of your SXV4.
2. Open the SQL file in a text editor.
3. Make sure that your SQL file is encoded in UTF-8 without a Byte Order Mark. This step is particularly important if you will be using non-ASCII characters, as it will allow you to use the full range of unicode characters in your annotations.
The way to check and set the text file encoding depends on your text editor (not all text editors allow you to do this). For example in Notepad++ you can do this using the **Encoding** menu:
If you are using non-ASCII characters, you must also ensure that your annotations schema includes the `FileInfo` table with the `FileVersion` set to `2`. This table will be created automatically if you use the supplied **schema.sql** file to create your initial annotation repository.
4. Modify the SQL insert statements to define the annotations you want for your database.
As you will see if you inspect the sample files (**RetailBanking.sql** or **financial.sql**), there are a number of tables you need to populate to set up your annotations:
| **Table** | **Description** |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `AnnotationDetails` | Each row in this table contains an individual annotation. There are three columns in this table: |-------------------------|-----------------------------------------------------------------------------| | **Column** | **Description** | | `AnnotationID` | A unique ID used in the other tables to refer to this annotation. | | `AnnotationSymbol` | A symbol that will be displayed in the clients to identify this annotation. | | `AnnotationDescription` | The text content of the annotation to display in the clients. | |
| `DBAssignment` | Use this table to assign an annotation to the entire database. The annotation will be shown for all tables created using this database. This table contains a single column (`AnnotationID`). Set this to the ID of the annotation (from the `AnnotationDetails` table) that you want to assign to this database. |
| `FieldAssignment` | Use this table to assign an annotation to a specific field. The annotation will be shown whenever this field appears in the table. There are three columns in this table: set `AnnotationID` to the ID of the annotation you want to assign, and use `TableName` and `FieldName` to identify the field it applies to. You must use the underlying ID of the table and field (from the source database), rather than their display names. |
| `FieldValueCodeAssignment` | Use this table to assign an annotation to a specific field value. |
| `CellAssignment` | Use this table to assign annotations to specific cell values. This table works in conjunction with the `Annotation` table. |
| `Annotation` | Use this table to store joins between the `AnnotationDetails` and `CellAssignment`. |
| `FileInfo` | This table sets the annotation file version. It must contain a single row with the values `FileVersion` and `2`. This table will be created and populated automatically in your annotation repository if you use the supplied **schema.sql** file to create your initial annotation repository. This table is required if you are using non-ASCII characters in annotations (i.e., your annotations include Unicode characters). The `FileInfo` table was added to the annotations schema in SuperSTAR 9.0. It will be created automatically if you use the supplied **schema.sql** file to create a new annotation repository. However, if you have an existing annotations repository that was created before SuperSTAR 9.0 then it may not contain this table. You will need to manually add the `FileInfo` table to your repository in order to support Unicode characters in your annotations. |
### Step 2 - Check the SQLite Version
To configure the static annotations, you need the SQL command line utility **sqlite.exe** . A version of this utility is provided with SuperSERVER, in **C:\\Program Files\\STR\\SuperSERVER SA** . You can also download it from [www.sqlite.org](http://www.sqlite.org/).
SuperSERVER requires SQLite version 3.3 or above. You can check the version you have installed using the following command from a command prompt:
C:\>sqlite -version
3.7.4
C:\>
### Step 3 - Create the Annotation Repository
Once you have finished creating your own SQL script file, you can use SQLite to create the static annotation repository file.
1. Open a command prompt and navigate to the directory containing the SXV4 database. For example:
C:\>cd /d "E:\Databases\"
2. Use the command `sqlite .sxv4.sqlite.db` to start SQLite and begin creating the repository file.
For example:
E:\databases>sqlite SurveyResults2013.sxv4.sqlite.db
SQLite version 3.7.4
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite>
3. Run the supplied schema script to set up the empty repository. You can either use a relative or an absolute path to the **schema.sql** file, but you must use forward slashes. For example:
sqlite> .read "C:/ProgramData/STR/SuperSERVER SA/etc/annotation/schema.sql"
4. Run the SQL file you created in the previous step. You can either use a relative path (relative to the current directory) or an absolute path, but must use forward slashes. For example:
sqlite> .read SurveyResults2013.sql
5. Close SQLite:
sqlite> .exit
C:\ProgramData\STR\SuperSERVER SA\databases>
You can now start one of the SuperSTAR clients and open the database to see your annotations in use.
There is no additional SuperSERVER configuration required for it to start using your annotations. As long as the SQLite database file is in the same directory as the SXV4 database (and the SXV4 has been added to the SuperSERVER database catalogue in SuperADMIN), then the server will automatically send the annotations to the clients to display.
### Updating the Annotations
If you need to make further changes to the annotation repository, you can simply:
1. Edit the SQL file to contain your new annotations.
2. Delete the existing **.sqlite.db** file.
3. Repeat Step 3 above to recreate the annotations.
Alternatively, you can use a tool like SQLite Browser (available from ) to make changes to your SQLite database file without recreating it from scratch.
In some cases you may not be able to delete or update the existing **.sqlite.db** file because it is locked by the SuperSERVER process (**scsa.exe** ). In this case you may need to use SuperADMIN to remove the database from the SuperSERVER database catalogue first so that SuperSERVER releases its file lock on the **.sqlite.db** file. You can then add the database back to SuperSERVER once you have rebuilt your annotation repository.
### Multilingual Annotations
If you are using the [Metadata Server](https://docs.wingarc.com.au/superstar/9.21/metadata-server.md) to display your datasets in multiple languages, then you can also translate your dataset annotations.
You need to create a table in your metadata database called `fnote_` for each dataset that has annotations, and make sure this is referenced in the `ss_fnote` column of the `db_domain` table.
You can then populate your `fnote_` table with the translations of your annotations: add the annotation symbol to the `ss_code` column and the translated text to the `_name` column. See [Reference](https://docs.wingarc.com.au/superstar/9.21/reference.md) for more details on populating the `fnote_` table.
### Using a Graphical Editor to Populate the Annotations Database
As an alternative to using the command line interface to create your SQLite DB file, there are several third party browser tools for editing SQLite files. For example:
If you decide to use one of these tools to edit your file, then you simply use the supplied **schema.sql** file to populate the initial schema of the repository and then add your annotations via the editor GUI.
### Learn More
There are some other ways you can create annotations and have them display with the table:
* Users can create annotations directly in SuperCROSS, although those annotations are not saved to the server. Users who create their own annotations can view them during the current SuperCROSS session and save them with the table. [Learn more about annotations in SuperCROSS](https://docs.wingarc.com.au/superstar/9.21/annotations-sx.md).
* You can write your own Data Control module to add your custom annotations. See [Annotations](https://docs.wingarc.com.au/superstar/9.21/annotations-2.md) for more information.
---
version: "9.21"
language: "en"
---
# Annotations
SuperSERVER maintains a separate database for storing annotation information. For details of the database schema and facilities supported by the SuperSERVER annotation subsystem, see [Annotations 4](https://docs.wingarc.com.au/superstar/9.21/annotations-2.md).
The following functions allow access to the annotation facilities within SuperSERVER.
## AddSymbolDescriptionT()
Add an annotation symbol and description to the results.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddSymbolDescriptionT(JobInfoT* JobInfo, const char* Symbol, const char* Description)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Symbol** | Input | The symbol (or ID) for the annotation. | | **Description** | Input | The annotation description. | |-----------------|-------|----------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. For example because you attempted to add a duplicate symbol. | |-------|------------------------------------------------------------------------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### GetALLSymbolDescriptionT()
Retrieve all annotations.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
GetALLSymbolDescriptionT(JobInfoT* JobInfo, const SymbolDescriptionT** Values, int* Len)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Values** | Output | An array containing the returned annotation symbols and descriptions. | | **Len** | Output | The length of the returned array. | |-------------|--------|-----------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| If the operation is successful, but the result set is empty, then `Len` will be set to zero and `Values` will be `NULL`. |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### AddDatabaseAnnotationT()
Assign a database annotation to the tabulation request.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddDatabaseAnnotationT(JobInfoT *JobInfo, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Symbol** | Input | The symbol for the annotation to assign. | |-------------|-------|------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### DeleteDatabaseAnnotationT()
Delete a database annotation from the tabulation request.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
DeleteDatabaseAnnotationT(JobInfoT *JobInfo, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Symbol** | Input | The symbol for the annotation to delete. | |-------------|-------|------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### GetDatabaseAnnotationT()
Retrieve all the database annotations for the tabulation request.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
GetDatabaseAnnotationT(JobInfoT *JobInfo, const char*** Values, int* Len)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Values** | Output | An array of returned values. | | **Len** | Output | The length of the returned results. | |-------------|--------|-------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| If the operation is successful, but the result set is empty, then `Len` will be set to zero and `Values` will be `NULL`. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### AddFieldAnnotationT()
Assign an annotation to a field.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddFieldAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension to assign the annotation to. | | **Symbol** | Input | The symbol for the annotation to add. | |-----------------|-------|--------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### DeleteFieldAnnotationT()
Delete an annotation from a field.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
DeleteFieldAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension to delete the annotation from. | | **Symbol** | Input | The symbol for the annotation to delete. | |-----------------|-------|----------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### GetFieldAnnotationT()
Retrieve all annotations from a specified field.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
GetFieldAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, const char*** Values, int* Len)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension to get the annotation for. | | **Values** | Output | An array of returned values. | | **Len** | Output | The length of the returned results. | |-----------------|--------|------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| If the operation is successful, but the result set is empty, then `Len` will be set to zero and `Values` will be `NULL`. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### AddFieldValueAnnotationT()
Assign an annotation to a field value.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddFieldValueAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, int WhichItem, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension. | | **WhichItem** | Input | The index of the item within the field to assign the annotation to. | | **Symbol** | Input | The symbol for the annotation to assign. | |-----------------|-------|---------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### DeleteFieldValueAnnotationT()
Delete an annotation from a field value.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
DeleteFieldValueAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, int WhichItem, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension. | | **WhichItem** | Input | The index of the item within the field to delete the annotation from. | | **Symbol** | Input | The symbol for the annotation to delete. | |-----------------|-------|-----------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### GetFieldValueAnnotationT()
Retrieve all annotations for a field value.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
GetFieldValueAnnotationT(JobInfoT *JobInfo, int Dimension, int FieldOffset, int WhichItem, const char*** Values, int* Len)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Dimension** | Input | The dimension index within the data cube. | | **FieldOffset** | Input | The field index within this dimension. | | **WhichItem** | Input | The index of the item within the field to get the annotations from. | | **Values** | Output | An array of returned values. | | **Len** | Output | The length of the returned results. | |-----------------|--------|---------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| If the operation is successful, but the result set is empty, then `Len` will be set to zero and `Values` will be `NULL`. |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### AddCurrentCellAnnotationT()
Assign an annotation to the current cell.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddCurrentCellAnnotationT(JobInfoT *JobInfo, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Symbol** | Input | The annotation symbol to assign. | |-------------|-------|------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### DeleteCurrentCellAnnotationT()
Delete an annotation from the current cell.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
DeleteCurrentCellAnnotationT(JobInfoT *JobInfo, const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Symbol** | Input | The annotation symbol to delete. | |-------------|-------|------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### GetCurrentCellAnnotationT()
Get all annotations for the current cell.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
GetCurrentCellAnnotationT(JobInfoT *JobInfo, const char*** Values, int* Len)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **Values** | Output | An array of returned values. | | **Len** | Output | The length of the returned results. | |-------------|--------|-------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| If the operation is successful, but the result set is empty, then `Len` will be set to zero and `Values` will be `NULL`. |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
### AddCellAnnotationT()
Assign an annotation to a particular cell.
| **Available To** | `PrepareJob` | `PerformJob` | `CleanUpJob` |
|------------------|--------------|--------------|--------------|
C++
AddCellAnnotationT(JobInfoT *JobInfo, const int* CellLocation, int Len ,const char* Symbol)
| **Arguments** | | **JobInfo** | Input | Information about the current job. | | **CellLocation** | Input | An array of dimension item indexes identifying a cell in the data cube. | | **Len** | Input | The length of `CellLocation`. | | **Symbol** | Input | The annotation symbol to assign. | |------------------|-------|-------------------------------------------------------------------------| |
| **Returns** | | **1** | Success. | | **0** | The operation failed. | |-------|-----------------------| |
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
---
version: "9.21"
language: "en"
---
# Annotations
The annotation functionality lets you create annotations and assign them to values in the table. Annotations can be assigned to various table components such as databases, fields, field values, and data cells (cross section of two or more field values).
An annotation contains two parts:
* Annotation symbol assignments - This is used to associate an annotation symbol with a table item.
* Annotation description -This contains detailed descriptive information for the annotation symbol.
Annotations can be assigned to the following elements within a table:
* Database - Setting an annotation for a database. The symbol will display in the title, next to the database name.
* Field - Setting an annotation for a field. The field can be across-tabulation or measure field. This annotation will display next to the field name in the table's title.
* Field value (category) - Setting an annotation for a field value. The field must be across-tabulation field. This annotation will display next to that value in the column, row or wafer of the table.
* Data cell:
* Setting an annotation for a combination of field values. The symbol will display in all the cells that correspond to this combination.
* Setting an annotation for a combination of field values and a measure field. The symbol will display in all the cells that correspond to this combination.
You are recommended not to create more than 100,000 dynamic annotations on any particular table.
Using the Data Control API, you can assign annotations to the table dynamically during cross-tabulation. See [Module Callback API](https://docs.wingarc.com.au/superstar/9.21/module-callback-api.md) for more information about the callbacks you need to use for this.
## Defining an Annotation Assignment
### Database
A database annotation assignment can be defined by associating a database identifier with at least one annotation symbol. It can be described as:
[Database identifier] → [symbol, symbol , ...]
#### Field
Annotation assignment on a cross-tabulation/measure field can be defined by associating a field identifier with at least one annotation symbol. A cross-tabulation/measure identifier consists of a table name to which this field belongs and a field name. This assignment can be described as:
[Table Name, Field Name] → [symbol, symbol,, ...]
#### Field value (category)
Annotation assignment on a field value (category) can be defined by associating the field value identifier with at least one annotation symbol. A field value identifier consists of a table name to which this field belongs, a field name, a value set name and a value set value code. This assignment can be described as:
[Table Name, Field Name, Value Set Name, Value Set Value Code] → [symbol, symbol, ...]
#### Data cell
Annotation assignment on a data cell can be defined by associating a combination described in Table Items with at least one annotation symbol. The assignment can be described as:
[ (Table Name, Field Name, Value Set Name, Value Set Value Code)+] → [symbol, symbol, ...]
and
[ (Table Name, Field Name, Value Set Name, Value Set Value Code)+, (Table Name, Field Name) ] →
[symbol, symbol, ...]
A measure field can only be described as (Table Name, Field Name).
---
version: "9.21"
language: "en"
---
# Annotations Sample Code
The **etc\\annotation** directory (**C:\\ProgramData\\STR\\SuperSERVER SA\\etc\\annotation**) contains sample code for the annotations:
* **etc\\annotation\\Financial.sxv4.sqlite.db**
* **etc\\annotation\\README.txt**
* **etc\\annotation\\financial.sql**
* **etc\\annotation\\schema.sql**
The annotation engine uses a Public Domain relational database implementation, SQLite, available from [http://www.sqlite.org](http://www.sqlite.org/).
The SuperSERVER installation includes the necessary run-time components of SQLite to allow annotations to be processed by the server. However, to configure annotations in the database it is necessary to obtain an SQL command line utility, **sqlite3.exe**.
You can download this for Windows and Linux installations from the 'downloads' page at [http://www.sqlite.org](http://www.sqlite.org/).
The SuperSERVER implementation requires at least version 3.3 to operate correctly.
SQLite is often shipped automatically with Linux installations, but this may be an older (incompatible) version of SQLite (for example GNU/Linux 2.6.13-15-smp ships with SQLite v2.8.16).
To determine the version of a previously installed **sqlite3.exe** from a DOS shell or Linux command prompt invoke the command:
PowerShell
> sqlite3 -version
## Create a new Annotations Database
The SuperSERVER implementation associates the SQLite database with a SuperSERVER database by name. For example, annotations for the Retail Banking sample database would be stored in a file called **Retail Banking.sxv4.sqlite.db**.
To create a new annotations database perform the following steps:
1. Open a command prompt.
2. Change directory to the database directory of the SuperSERVER installation.
3. Run the command:
PowerShell
> sqlite3 .sxv4.sqlite.db
4. At the SQLite command prompt run following command to configure the schema:
PowerShell
sqlite> .read ..\etc\annotation\schema.sql
5. Add annotations using SQL Insert statements (from the sqlite3 command prompt) for your table.
To exit SQLite type the EOF character (normally **Ctrl-D**).
---
version: "9.21"
language: "en"
---
# Annotations
You can add annotations to cells, fields, and the table header. For example, you can use them to add notes, explain the recodes used or provide information about certain cell values within the table.
The annotations appear at the bottom of the table with reference markers against the relevant cells:
By default, all the annotations you add appear in the table footer, even if you remove the items they refer to from the table. To change this, right-click the footer and select **Filter Annotation Footnotes**. When this option is selected, the list of annotations in the footer dynamically updates to only show annotations for items that currently appear in the table.
Your system administrator may have [configured annotations at the server level](https://docs.wingarc.com.au/superstar/9.21/annotations.md). If this is the case, then any annotations you add in SuperCROSS will display in addition to the server-level annotations. Annotations you create in SuperCROSS will not be saved to the server; they will be visible during the current session and will be saved with the table when you save to certain formats (see below).
## Create or Edit Annotations
To add or edit an annotation, do the following.
| **To Annotate...** | **Do This...** |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Individual cells | Select the cell or cells and then do one of the following: * Right-click and select **Annotate Cells \> Annotate Selected Cells**; or * Select **Edit \> Data Area \> Annotate Cells \> Annotate Selected Cells**. |
| Fields or field values | Right-click the row, column, or wafer where the field appears and select either: * **Assign Annotations \> Annotate Selected Field** to annotate the field you clicked; or * **Assign Annotations \> Annotate Selected Field Value** to annotate the individual field value that you clicked. |
| Table Header | Right-click the table header and select one of the options from the **Assign Annotations** menu. The options will depend on the fields in your table |
The **Annotate**window displays.
Here you can add and remove annotations:
| **To Do This...** | **Do This...** |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Add a New Annotation | To add a new annotation: 1. Click **Add New**. 2. In the **Symbol** field, enter the symbol that will display in the table next to the annotated item (up to 10 characters). 3. In the **Description** field, enter the text of the annotation (this is the text that displays in the table footer area). This can be up to 224 characters. If you are entering a long annotation, click **\>\>\>** to access a larger text area at the bottom of the window. 4. Select the **Assigned** check box next to the annotation to assign it to the field, field value, cell or table header item. 5. Click **OK**. |
| Remove an Annotation | To delete an annotation, select it in the list and click **Delete**. This will remove the annotation completely. If you want to keep the annotation in the list, but remove it from the selected field, field value, cell or table header, select the annotation and click **Clear Assignments**. |
### Save Annotations
Annotations will be saved with the table when you save it to any of the following formats:
* SuperCROSS (.SCS)
* Excel 97 or 2003 (.XLS)
* Excel 2007 or 2010 (.XLSX)
* XML
For more information, see [Saving](https://docs.wingarc.com.au/superstar/9.21/saving.md).
### Limitations of Annotations
* Annotations on fields where there are duplicated field names in different fact tables are not supported when loading **scs** files in table view.
* RSE Annotations are not supported (RSE can still be used as part of the summation options).
* Annotation of derivations or cells with derivations is not supported.
* Annotation of a concatenated field is not supported, but you can annotate the underlying fields by using the right-click menu on the table title area.
* Updating the multilingual description of an annotation from SuperCROSS is not supported in multilingual mode. The user supplied description will be used in preference to any translations. You can update the metadata database by other means. If translations are required, add the annotations to the **sqlite.db** file, and the translations to the metadata database.
---
version: "9.21"
language: "en"
---
# Antlr 2 License
We reserve no legal rights to the ANTLR--it is fully in the public domain. An individual or company may do whatever they wish with source code distributed with ANTLR or the code generated by ANTLR, including the incorporation of ANTLR, or its output, into commerical software.
We encourage users to develop software with ANTLR. However, we do ask that credit is given to us for developing ANTLR. By "credit", we mean that if you use ANTLR or incorporate any source code into one of your programs (commercial product, research project, or otherwise) that you acknowledge this fact somewhere in the documentation, research report, etc... If you like ANTLR and have developed a nice tool with the output, please mention that you developed it using ANTLR. In addition, we ask that the headers remain intact in our source code. As long as these guidelines are kept, we expect to continue enhancing this system and expect to make other tools available as they are completed.
---
version: "9.21"
language: "en"
---
# API Administration
As a SuperWEB2 administrator, you can control who has access to the Open Data API, and how often they are allowed to issue requests.
This section describes the administration options available to you:
* [Install](https://docs.wingarc.com.au/superstar/9.21/install-odapi.md)
* [Restrict Access to the API](https://docs.wingarc.com.au/superstar/9.21/restrict-access-to-the-api.md)
* [Rules Engine - Open Data API](https://docs.wingarc.com.au/superstar/9.21/rules-engine-open-data-api.md)
* [Configure API Performance Settings](https://docs.wingarc.com.au/superstar/9.21/configure-api-performance-settings.md)
* [Configure the Cache](https://docs.wingarc.com.au/superstar/9.21/configure-the-cache.md)
* [Required IIS Configuration](https://docs.wingarc.com.au/superstar/9.21/required-iis-configuration.md)
## configuration.properties
The Open Data API and SuperWEB2 each have their own **configuration.properties** file that contain the same settings. You need to update both files if you also want to apply the same property settings to the Open Data API. For more information about the properties, see [**configuration.properties**](https://docs.wingarc.com.au/superstar/9.21/configuration-properties.md).
| **Location** | **\\\webapps\\webapi#rest#v1\\WEB-INF\\classes\\configuration.properties** |
|--------------|------------------------------------------------------------------------------------------|
---
version: "9.21"
language: "en"
---
# API Cache
The Open Data API automatically caches table, schema and authentication results, as well as any data from [metadata server](https://docs.wingarc.com.au/superstar/9.21/metadata-server.md) where applicable (such as dataset and field labels). The API will return the results from the cache rather than requerying the server where possible.
The API provides very flexible configuration options that allow you to control exactly how long data is cached for (see [Configure the Cache](https://docs.wingarc.com.au/superstar/9.21/configure-the-cache.md) for more details). In addition, the cache will automatically be cleared in situations where you make changes to datasets, saved tables, and user permissions that invalidate the current contents. For example, if you remove a user's access to a dataset entirely, then any cached results for that dataset will be cleared for the corresponding user. Similarly, changes to Field Level Security will cause any affected cached contents to be cleared.
However, you may still find you need to manually clear the cache in some cases. You can use the `/cache` endpoint to manually clear:
* The entire Open Data API cache.
* The table, schema or authentication cache for a specific user.
* The table or schema cache for a specific dataset.
* The metadata cache. You may need to clear this cache if you change the dataset, field and valueset labels in your metadata database.
## Overview
| **Endpoint** | `https:///webapi/rest/v1/table/cache` | Clear the entire table cache. |
| | `https:///webapi/rest/v1/table/cache?userId=` | Clear the table cache for the specified user. |
| | `https:///webapi/rest/v1/table/cache?datasetId=` | Clear the table cache for the specified dataset. |
| | `https:///webapi/rest/v1/table/cache?userId=&datasetId=` | Clear the table cache for the specified dataset for the specified user. |
| | `https:///webapi/rest/v1/schema/cache` | Clear the entire schema cache. |
| | `https:///webapi/rest/v1/schema/cache?userId=` | Clear the schema cache for the specified user. |
| | `https:///webapi/rest/v1/schema/cache?datasetId=` | Clear the schema cache for the specified dataset. |
| | `https:///webapi/rest/v1/schema/cache?userId=&datasetId=` | Clear the schema cache for the specified dataset for the specified user. |
| | `https:///webapi/rest/v1/auth/cache` | Clear the entire authentication cache |
| | `https:///webapi/rest/v1/auth/cache?userId=` `https:///webapi/rest/v1/auth/cache?apiKey=