configuration.properties

Location	<tomcat_home>\webapps\webapi\WEB-INF\classes\configuration.properties

SuperWEB2 and the Open Data API 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.

The following properties are available in this configuration file.

Each property has a default value (indicated in the tables below). If you do not give the property an explicit value then it will use its default.

SuperWEB2 Settings

Global Settings

Property Description

global.enableUserRegistration

Whether to enable the built in user registration system:

true	Enable user registration.
false	(Default) Do no enable user registration.

The user registration system is disabled by default and will not appear as an option on the login page. Enabling it through this configuration activates the registration option, but the feature will not work without additional configuration (for example you need to configure the email server for sending registration messages).

More information: User Registration

global.enableMapView

Whether to display the Map View tab:

true	(Default) Enable Map View.
false	Do not enable Map View.

global.enableGuidedTutorial

Whether to enable the guided tour:

true	(Default) Enable the tour. It will be displayed on first login and accessible from the top-right menu.
false	Users will not be shown the tour on first login and will not be able to access the tour from the menu.

More information: Customise the Interactive Tour

global.enableNewFeatureTutorial

Whether to enable the new features popup. This can be used to display information about new data or new features that have been added to SuperWEB2.

true	(Default) Enable the new features popup.
false	Do not enable the new features popup.

global.enableGuestAccess

Whether to allow guest access to SuperWEB2:

true	(Default) Allow guest access.
false	Do not allow guest access.

More information: Configure Guest Access

global.enableRecordView

Whether to enable or disable the Record View feature:

true	(Default) Enable Record View.
false	Disable Record View.

If you choose to disable Record View using this property it will be disabled for all users, regardless of any SuperADMIN user settings.

This setting hides the RecordVIEW button from the SuperWEB2 interface. If you are blocking access to Record View for security reasons, you may also wish to disable Record View at the SuperSERVER level. See Configure Record View Permissions for more details.

In earlier versions this property was set in web.xml

More information: Enable or Disable Record View

global.enableGraphView

Whether to display the Graph View tab:

true	(Default) Enable Graph View.
false	Do not enable Graph View.

global.labelSortType

The algorithm used when sorting labels in SuperWEB2:

natural_case	(Default) This is the recommended setting for languages using primarily non-accented characters. Numbers will be sorted in natural numerical order (for example, 1, 2, 5, 45).
natural_collated	This setting orders strings taking locale, case and accents into account (for example Ö will be sorted after O). This option involves a high processing overhead and is only recommended if there are no large value sets or catalogues and the languages in use require it. Do not use this option if you have millions of items to be sorted.
case	This is a subset of the collation rules that is optimised to only look at case differences if the rest of the string is the same ignoring case. Numbers sort in first digit order (for example: 1, 2, 45, 5). This option involves minimum processing overhead, but is only recommended if natural number ordering would not make sense for the data.
character	This setting uses a simple character-by-character string comparison. Numbers sort in first digit order, capital letters appear firstly in order, then lower case letters appear after. This is the fastest sorting option but is not generally recommended.

global.sessionPollTime

The session poll time used to keep the session active, in milliseconds.

Both Table View and Map View have REST endpoints that fail if the session times out. To keep the session active, the server is polled at regular intervals. As a general rule you should set the interval to 60000ms (1 minute) less than the configured session timeout. Set this to 0 to disable polling.

The default is 540000 (9 minutes).

global.auth.

urlParameter.enabled

The ability to use an external login form with direct URLs relies on HTTP Basic Authentication, and has been disabled by default for security reasons.

If you wish to continue using this feature, it can be enabled by adding the property global.auth.urlParameter.enabled=true to the SuperWEB2 configuration.properties file. This property does not appear in the file by default.

See Use Direct URLs to Open a Specific Dataset or Table for more details.

SuperADMIN Settings

Property Description

superAdmin.zmq.address

The address for connecting to SuperADMIN. This should typically be left blank, in which case it will use the value from the AdministrationServerCatalog.xml file.

superAdmin.zmq.subscriptionPort

The subscription port for connecting to SuperADMIN. The default is 9002.

superAdmin.zmq.messagePort

The message port for connecting to SuperADMIN. The default is 9003.

superAdmin.zmq.reconnectionInterval

The time between subsequent attempts to reconnect to SuperADMIN if the connection is broken and the initial, immediate reconnection attempt fails. Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

The default is 1m (1 minute).

superAdmin.zmq.socketTimeout

The time to wait without receiving a heartbeat (or any other message) from SuperADMIN before resetting the underlying
connection. This should be at least 2-3 times the heartbeat duration. When this timeout is reached, it is assumed that
the underlying connection with SuperADMIN has been broken due to a network error and needs to be reset.

Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

The default is 5m (5 minutes).

superAdmin.zmq.synchronisedStateTimeout

The time to wait without receiving a heartbeat (or any other message) from SuperADMIN before considering any cached state (such as the contents of the Open Data API cache) to be out of date. This value should be the maximum time you are willing to allow that state to possibly be out of sync with SuperADMIN when experiencing communication issues (for example for a permission change or deleted dataset to take effect). It should also be greater than the value of superAdmin.zmq.socketTimeout to allow at least one reconnection attempt.

Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

The default is 1h (1 hour). Set this to 0 to disable the timeout.

File and Confidentiality Settings

Property Description

file.defaultTxdEncoding

The codepage to use when loading saved system tables (TXD files that have been saved to <tomcat_home>\webapps\webapi\WEB-INF\resources\txd) and loading TXDs files through the SuperWEB2 interface.

The default value is UTF-8.

This setting is useful when loading TXDs that were created with versions of SuperCROSS prior to 9.0:

Any TXDs created with SuperCROSS 9.0 will be Unicode and therefore work correctly regardless of what codepage setting you configure here.
For TXDs created with earlier releases, these will only work if they either contain only English/ASCII characters, or they only contain characters supported by the codepage configured here.

In earlier releases, this setting was configured in the web.xml file (as TXDEncodingType). It moved to configuration.properties in version 9.9.8.

cube.showNaNAsZero

Whether to display 0 or a custom string if there are cells with no records contributing to the result:

true	(Default) Show cells that have no contributors as 0.
false	Display the `notANumberString` string configured in CubeCatalog.xml.

See Configure Settings for Concealment and Cells with No Contributors for more information.

confidentiality.
requireConfidentialityModule

Whether to prevent the release of datasets that do not have confidentiality modules applied to them.

true

Users will only be able to access datasets that they have permission to access that also have a data control method property of ConfidentialityModule applied to them.

Datasets without confidentiality applied will not be available regardless of other permission settings.

false

(Default) Datasets will be available to users based on the standard SuperADMIN permissions.

confidentiality.
requireSpecificModules

Whether to prevent the release of datasets that do not have a specific Data Control API module applied to them.

If any modules are specified, then users will only be able to access datasets that have at least one of those modules applied (the user must also have standard permission to access the dataset).

This property accepts a comma separated list of modules. For example, the following prevents access to datasets that do not have either perturbation or the confidentiality rule modules applied to them:

CODE

confidentiality.requireSpecificModules=perturbation,
confidentialityrule

Catalogue Settings

Property Description

catalogue.sortDatabases

Whether to sort the list of Datasets shown in the catalogue screen:

true	(Default) Datasets will be sorted in alphabetical order.
false	Datasets will be shown in the order they were added to the catalogue in SuperADMIN

More information: Change the Sort Order of Tables and Datasets

catalogue.folderExpansionDepth

catalogue.databaseFolderExpansionDepth

How many levels of folders should initially be expanded when a user opens the Catalogue page in SuperWEB2.

folderExpansionDepth is a global setting that applies to all lists of datasets and tables, while databaseFolderExpansionDepth applies only to the dataset list.

If databaseFolderExpansionDepth is not set, it will default to the value of folderExpansionDepth (if neither is set then they both default to -1).

-1

(Default) All folders expanded. Recommended for small catalogues or catalogues with no folders. For example:

0

The tree will initially be fully collapsed. Not recommended.

For example:

1 or more

The tree will initially be expanded to the specified number of levels. For example:

1 level:

2 levels:

catalogue.infoPanel.
displayDatabaseMetadataDescription

Whether to read the text for the catalogue page from the metadata database. This setting only applies when metadata server has been set up and is only used for datasets that have been set to multilingual in SuperADMIN.

true	SuperWEB2 will look for a description in the `<id>_desc` column of the `db_domain` table in the metadata database and use this if it is present. It will fall back to using the static HTML pages if there is no description available.
false	(Default) SuperWEB2 will use the static HTML pages saved on the server.

More information: Use the Metadata Server to Store the Data Catalogue Information Pages - SuperWEB2

catalogue.openDatasetBehaviour

Whether to load the default table, if configured, when opening a dataset other than by clicking New Table (for example when double-clicking, via search or through a direct URL):

newTable	(Default) Create a new table.
defaultTable	Open the default table, if configured.
enforceDefaultTable	Open the default table, if configured, and hide the New Table button on the Dataset catalogue page.

More information: Getting Started

catalogue.hiddenSystemTxdPrefix

Whether to hide system tables that start with a specified case-sensitive prefix. This allows for hiding system tables in the Table section of the Datasets page and in search results.

These items can still be opened via direct URLs, but they will not be visible to users in the catalogue. Leave blank to hide none (default).

catalogue.searchResultLimit

The maximum number of results to return for a catalogue search. This setting applies independently to each of the non-dataset and non-table result types (fields, values, synonyms and metadata). The default is 2000.

If a user runs a search that exceeds the limit, a message will be displayed indicating that the search results have been capped and advising the user to perform a more specific search to see the full set of search results.

More information: Search

Schema Tree Settings

Property Description

schemaTree.expandOnSelection

Whether to automatically expand a field in the tree when a user selects the Select all at level drop-down list. This property takes the following values:

true	Automatically expand the field.
false	(Default) Do not automatically expand the field.

More information: Automatically Expand the Fields when Selecting All

schemaTree.hierarchicalFieldDepthLimit

The maximum number of levels of hierarchy to show in the Select all at level drop-down list.

Set this to a negative value if you do not want to limit the levels of hierarchy. The default setting is -1.

schemaTree.showSummationOptions

Whether to show the summation options in the customise table panel in Table View.

true	(Default) Show the summation options.
false	Do not show the summation options.

schemaTree.selectAtLevelShowsValuesetName

Which labels to show in the Select all at level drop-down:

true	(Default) Show the valueset label.
false	Show the label of the first item in each valueset. Changing this property to `false` means that SuperWEB2 more closely matches the behaviour of SuperCROSS (when selecting all the Subitems from a level of the hierarchy in the Define Recode window).

More information: Configure Field Drop-down Labels

schemaTree.schemaFolderExpansionDepth

How many levels of folders (field groups) to expand automatically when opening a dataset:

-2	All folders that contain a field in use in the table will be expanded. This setting is recommended if your datasets have very large schemas and are typically accessed through saved tables.
-1	(Default) All folders will be expanded. This setting is recommended for all cases except very large schemas (datasets that have a large number of fields or a large number of folders, in which case it may cause performance issues).
0	No folders will be expanded.
Integer value of 1 or above	Folders will be expanded to the specified level (for example, set this to 2 to expand the first two levels of folders). This setting is recommended for large schemas with lots of folders.

schemaTree.suppressSum

This setting was previously defined in the web.xml configuration file.

Whether to prevent users adding the SUM measure to a table.

true	Prevent users from adding the SUM measure to a table (this does not prevent them from being loaded from saved tables).
false	(Default) Do not prevent users from adding the SUM measure to a table.

Table Settings

Property Description

table.
showCurrentName

Whether to show the name of the currently open table in Table View (when opening a saved table):

true	(Default) Show the table name.
false	Do not show the table name.

table.
maximumFootnoteLength

When you have recodes (custom groups) in your table, a footnote automatically appears at the bottom of the table indicating which individual items make up the recode. You can use this setting to control whether this recode footnote is truncated.

This setting specifies the maximum length of recode footnotes in a table prior to truncation. The default is 120.

table.
annotations

Whether to display annotations beneath the table. This property takes the following values:

true	(Default) Display annotations if available.
false	Do not display annotations.

More information: Configure Display of Annotations

table.
enableTablesTab

Whether to display a list of saved tables for the current dataset in a tab Table View:

true	(Default) Display the Tables tab in Table View.
false	Do not display the Tables tab in Table View.

More information: Save and Reload Tables

table.
annotationPanelExpanded

Whether to automatically expand annotations. This property takes the following values:

true	(Default) Automatically expand the annotations.
false	Do not automatically expand annotations.

More information: Configure Display of Annotations

table.
defaultRSEView

The default display mode for tables with Relative Standard Error values. This property takes the following values:

0	(Default) Show data values only.
1	Show data values and RSE values next to each other.
2	Show RSE values only.

More information: Configure Relative Standard Error

table.
autoRetrieveDataDefault

Whether to retrieve data in Table View automatically by default:

true	The Automatically Retrieve Data option on the Retrieve Data button will be on by default.
false	(Default) The Automatically Retrieve Data option will be off by default.

This property sets the default/initial behaviour. Users can still turn automatic data retrieval on or off if they prefer, regardless of whether this property is set to true or false.

table.
enableConcatenation

Whether to allow users to concatenate fields in tables:

true	(Default) Concatenation is enabled.
false	Concatenation is disabled. Fields will be nested in the table axes instead.

More information: Disable Concatenation

table.
enableUdfCreation

Whether to allow users to create user defined fields, such as ranges and quantiles. Setting this option to false will remove the Range button from the Summation Options section of the field list in Table View.

true	(Default) Allow users to create user defined fields.
false	Do not allow users to create user defined fields.

While setting this option to false will prevent the creation of new ranges and quantiles, it will not prevent any existing user defined fields from being used or deleted.

More information: Remove the Range Option

table.
enablePrintButton

Whether to display the Print Table button in Table View:

true	(Default) Show the Print Table button.
false	Do not show the Print Table button.

table.
enableAddToWafer

Whether to allow users to add fields to wafers in Table View:

true	(Default) Allow users to add fields to wafers.
false	Do not allow users to add fields to wafers.

table.
totalsInitialState

Whether to show totals by default when adding fields to the table. This setting does not apply when loading a saved table (which will load the totals state from the saved table).

nototals	Hide all totals initially.
alltotals	Show all totals initially.
outermosttotals	(Default) Show totals for outermost fields only.

More information: Disable Automatic Totals

table.
enableDrillUpAndDrillDown

Whether to allow users to drill up and down (navigate) through hierarchical fields in tables.

true	(Default) Allow users to drill up and down through hierarchical fields in tables.
false	Do not allow users to drill up and down through hierarchical fields in tables.

table.
useSavedTableLanguage

Whether to use the saved table language when opening a saved system table (a TXD saved from SuperCROSS and stored in the txd directory on the SuperWEB2 server).

true	When a user opens a saved system table, SuperWEB2 will use the dataset language saved in the TXD, rather than the user's currently selected dataset language.
false	(Default) When a user opens a saved system table, SuperWEB2 will continue to use the currently selected dataset language.

table.
displayMetadataAsAnnotations

Whether to display metadata as annotations at the bottom of the table. This setting only applies to multilingual datasets that have been configured to use metadata server for descriptive metadata.

true	SuperWEB2 will scan for descriptive metadata and display it at the bottom of Table View in an annotations table.
false	(Default) SuperWEB2 will not display the descriptions at the bottom of the table.

More information: Display Metadata as Annotations Below the Table

table.
enableDerivations

Whether to allow users to create derivations in tables:

true	(Default) Allow users to create derivations.
false	Do not allow users to create derivations.

More information: Derivations

table.
derivation.
allowCommaAsDecimalSeparator

Whether to accept commas as the decimal separator when creating and editing derivations in Table View.

true	When specifying a derivation formula, `.` or `,` will be accepted as decimal separators. In addition, the appropriate decimal separator for the current locale will be used when displaying existing derivation formulas.
false	(Default) Only the `.` character will be accepted as the decimal separator.

More information: Derivations

table.
enableOpenTxdFile

Whether to allow administrators to open TXD files in SuperWEB2.

true

Administrator users will have access to an Open TXD File button in Manage Tables. This can be used to open a TXD file in SuperWEB2.

Even if enabled, this option is available to administrator users only.

Opening a TXD in this way does not save the table by default: you will need to manually save the table after opening it if you want it to be available in future SuperWEB2 sessions.

false

(Default) The Open TXD File button will not be available.

Use of HTML in TXD-file table headings represents a potential security vulnerability. This vulnerability is partially mitigated by the fact that generally only Administrator users have access to create and upload TXD files that include HTML. However, to further mitigate against this vulnerability, the table.escapeHeadingHtml setting, by default, escapes HTML to entity characters within table headings during the uploading of TXD files to SuperWEB2.

table.
removeUnusedTotalsFromCube

Whether to completely remove totals or just hide them when a user toggles off totals in SuperWEB2:

true

When a user toggles off totals in SuperWEB2, the totals will be removed from the table.

This will result in faster tabulations, but may cause more tabulations to take place (a re-tabulation would be required to add the totals back to the table).

Please note that the total may not be removed immediately. If the table has already been tabulated, then the total will be hidden and queued for removal on the next tabulation-breaking change (such as adding or removing a field).

Totals will not be removed in cases where removing the total would break other features (such as derivations, percentages or ordering).

false

(Default) Totals are always present when supported. When a user toggles totals off in SuperWEB2, the totals will be hidden but not removed from the table.

This will reduce the need for re-tabulations, but tabulations may take longer due to the need to calculate totals.

The appropriate setting for your system will depend on the types of tables your users create. For non-additive tables, each total that is present will double the tabulation time. If your users create a lot of non-additive tables then you are recommended to set this property to true.

For additive tables the performance benefit is negligible. If your users mostly create additive tables then you are recommended to leave this property set to false for the convenience of avoiding re-tabulation when re-enabling totals.

table.
escapeHeadingHtml

Whether to escape HTML in the table heading (supplied in a TXD file).

true	(Default) HTML imported in the table heading is escaped (i.e. HTML is not rendered as HTML).
false	HTML imported in the table heading is not escaped (i.e. HTML is rendered as HTML).

This setting mitigates a potential security threat by preventing HTML within the table heading of TXD files being rendered as HTML when the file is opened in SuperWEB2.

table.
priorityCalculation

The priority calculation to use when table queries are submitted to SuperSERVER for tabulation. By default, all jobs are submitted with a priority of 0.

The following example configures it to use the cell count based calculation:

CODE

table.priorityCalculation=au.com.str.webapi.
services.database.manager.cube.sxv4.
priority.CellCountBasedPriorityCalculation

table.
priorityCalculationConfig

A configuration string to be passed to the priority calculation class set in table.priorityCalculation . For example:

CODE

table.priorityCalculationConfig=1000,3.16227766

table.
largeTableMode.
previewDataSize

The number of row and column cells to show in the table preview when SuperWEB2 enter large table mode.

You can set this property to any positive integer value. If you do not give the property a value, it will use the default (3).

More information: Configure Settings for Large Tables

table.
largeTableMode.
thresholdTotal

The total cell threshold including wafers for entering large table mode. If the entire table (rows, columns and wafers) has more than this number of cells, SuperWEB2 will enter large table mode. This is primarily used to assist with tabulation performance and download size on the server side. For client rendering performance, thresholdRendered should be used.

You can set this property to any positive integer value. If you do not give the property a value, it will use the default (1000000). To disable this option, set the value to -1.

More information: Configure Settings for Large Tables

table.
largeTableMode.
thresholdRendered

The total cell threshold excluding wafers for entering large table mode. If the visible part of the table (rows and columns, excluding wafers) has more than this number of cells, SuperWEB2 will enter large table mode. This is used primarily for rendering performance on the client side. To assist with tabulation performance and download size on the server side, thresholdTotal should be used.

You can set this property to any positive integer value. If you do not give the property a value, it will use the default (100000). To disable this option, set the value to -1.

More information: Configure Settings for Large Tables

table.
largeTableMode.
thresholdRow

The row threshold for entering large table mode. If the table has more than this number of rows, SuperWEB2 will enter large table mode.

You can set this property to any positive integer value. If you do not give the property a value, it will use the default (8000). To disable this option, set the value to -1.

More information: Configure Settings for Large Tables

table.
largeTableMode.
thresholdColumn

The column threshold for entering large table mode. If the table has more than this number of columns, SuperWEB2 will enter large table mode.

You can set this property to any positive integer value. If you do not give the property a value, it will use the default (1000). To disable this option, set the value to -1.

More information: Configure Settings for Large Tables

Custom Data Settings

Property Description

customData.
requireTotalsAppropriate

Whether to allow custom data group recodes for fields that are not Totals Appropriate enabled.

true	(Default) Prevents custom data group recodes from being created for fields that are not Totals Appropriate enabled.
false	Allows custom data group recodes to be created for fields that are not Totals Appropriate enabled.

Open Data API Behaviour

When customData.requireTotalsAppropriate is set to true in the Open Data API version of configuration.properties, the Open Data API returns an error if a group recode is created for a non-totals-appropriate field.

Error example

CODE

{
"message": 
  "Query contains a group 
   recode for a field that 
   does not allow group recodes: 
str:field:tot_app_gender:
F_Customer:Gender",    
"errorType": 
  "INAPPROPRIATE_GROUP_RECODE",    
"component": 
  "str:field:tot_app_gender:F_Customer:Gender"
}

recordview.maxCells

The maximum number of cells of data that a user can download at a time from Record View.

You can set this property to any integer value. If you do not give the property a value, it will use the default (100,000).

More information: Enable or Disable Record View

graphView.maxCells

The maximum size of a table that can be visualised in Graph View. By default, there is a limit of 1,000 cells; if users create tables with more than this number of cells then they will not be able to access Graph View.

If necessary, you can increase the cell limit to a higher amount.

The limit only applies to the number of cells in the currently selected wafer, not the number of cells in the table as a whole.

Set this to 0 to disable access to Graph View.

graphView.maxFields

The maximum number of fields that the user can graph. As wafers and filters do not appear in the graph directly, only rows and columns count towards the limit.

Set this to 0 to disable access to Graph View.

More information: Graph View

Download Settings

Property

Description

download.enableQueueManager

Whether to enable the Job Queue Manager. This property takes the following values:

true	Use the Job Queue Manager.
false	(Default) Do not use the Job Queue Manager.

More information: Configure JQM

download.
allowDuplicateQueueManagerTableNames

Whether to allow duplicate table names in the job queue:

true	(Default) Allow duplicate table names.
false	Do not allow duplicate table names.

More information: Configure JQM

download.formatNumbers

Whether to format cell data in downloads. This setting is intended to be used if your users are working with extremely large tables (millions of cells), as it can provide a performance boost that dramatically reduces the time taken to download a table.

true	(Default) Cells will be formatted according to the configured precision settings for the summation options.
false	No formatting will be applied. Turning off formatting will speed up the download of very large tables.

More information: Set Precision for Summation Options

download.enableExcel2003

Whether the option to download tables in Excel 2003 format should be available.

true	(Default) Allow table downloads as Excel 2003 files.
false	Do not allow table downloads as Excel 2003 files.

download.enableExcel2007

Whether the option to download tables in Excel 2007 format should be available.

true	(Default) Allow table downloads as Excel 2007 files.
false	Do not allow table downloads as Excel 2007 files.

download.enableOpenDataApiQuery

Whether to allow users to download a table as an Open Data API query.

true	(Default) Allow table downloads as Open Data API queries.
false	Do not allow table downloads as Open Data API queries.

More information: Use SuperWEB2 to Build API Queries

download.enableTxd

Whether to allow users to download queries in TXD format (via the Download Table drop-down in Table View):

all	All users will be able to download tables in TXD format.
admin	(Default) Administrator users will be able to download tables in TXD format.
none	No users will be able to download tables in TXD format.

More information: Download Tables

Configuration Server Settings

Property Description

configServer.failOnUnknownProperties

What to do if any invalid or unknown SuperWEB2 configuration properties have been set using the SuperADMIN cfg command.

true	(Default) If there are unknown properties in the configuration, this will cause an error and none of the SuperWEB2 configuration from SuperADMIN will be applied.
false	If there are unknown properties in the configuration, these will be ignored, but valid configuration properties will still be applied.

More information: SuperADMIN cfg command

Help and Metadata Settings

Property Description

```
helpLink.default
```
```
helpLink.catalogue
```
```
helpLink.tableView
```
```
helpLink.graphView
```
```
helpLink.mapView
```
```
helpLink.customData
```
```
helpLink.myTables
```
```
helpLink.derivations
```

These parameters define the URLs for the online help.

You should not need to change these settings unless you want to replace the supplied user guide with your own customised version.

These properties can be localised to enable you to provide different help files translated for different languages. If you have online help in multiple languages, you can create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the relevant localised versions of these settings in it.

In addition, the property names were renamed to better reflect where they appear. For backwards compatibility reasons, both the old and new names of the properties can continue to be used.

More information: Customise the Online Help

metadata.
scanForDescriptions

Whether to scan for metadata in the metadata database:

true

SuperWEB2 will scan the metadata database for descriptions, and automatically display a metadata link in the field list if a description is present for the current dataset language.

The first time you open a particular dataset in SuperWEB2 it may take some time to display the field list while SuperWEB2 scans the metadata database.

false

(Default) SuperWEB2 will not scan for metadata.

More information: Display Metadata Icons

metadata.tableIcons

Whether to display metadata in Table View, Graph View and Map View. For Table View, this setting only applies to the table itself. The metadata.scanForDescriptions setting controls the display of icons in the field list.

none	No icons are displayed.
sa	(Default if `metadata.scanForDescriptions` is set to `false`). Display icons for elements that are configured in SuperADMIN. See Display Metadata Icons for more details.
md	(Default if `metadata.scanForDescriptions` is set to `true`). Display icons for elements that have descriptions configured in Metadata Server.
all	Display icons for all elements.

More information: Display Metadata Icons

metadata.
cacheSpec

The cache settings for metadata in SuperWEB2. By default, SuperWEB2 is configured to cache data from the Metadata Server for 1 day. You can change this by editing this setting.

There are a number of options you can set (see http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/cache/CacheBuilderSpec.html for full details of the syntax), but the main change you are likely to want to make is to change how often SuperWEB2 automatically refreshes its cache. To do this, use the following setting:

CODE

metadata.cacheSpec=expireAfterAccess=<duration>

Replace <duration> with the time between cache refreshes. Use the values d, h, m, or s to denote days, hours, months, or seconds.

For example, the following setting configures SuperWEB2 to refresh its cache every 10 minutes:

CODE

metadata.cacheSpec=expireAfterAccess=10m

More information: Clear Metadata Cache

externalLink.
dataConfidentialityURL

The URL to link to from the data confidentiality footnote in Table View.

This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it.

externalLink.
metaInfoBaseURL

The base URL to link to for SuperWEB2 metadata.

This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it.

More information: Metadata

Login Settings

Property Description

login.
requireTerms

Whether to show a terms and conditions screen during login. The user must accept the terms in order to log in.

true	Show a terms and conditions screen.
false	(Default) Do not show a terms and conditions screen.

More information: Add a Terms and Conditions Screen

login.
requireTermsVersion

The current version of the terms and conditions. Normally, users only need to accept the terms and conditions once. However, if your terms change then you can change this value to force all users to accept the new terms on their next login.

More information: Add a Terms and Conditions Screen

login.
guest.
username

The username for the account to use for guest access.

More information: Configure Guest Access

login.
guest.
password

The password to use for guest access.

More information: Configure Guest Access

login.
guest.
implicit.
username

The username for the account to use for guest access when a direct URL is used. If not specified, this will fall back to the value of login.guest.username.

More information: Configure Guest Access

login.
guest.
implicit.
password

The password to use for guest access when a direct URL is used. If not specified, this will fall back to the value of login.guest.password.

More information: Configure Guest Access

login.
enableIeWarning

Whether to display a warning on the login screen to users of Internet Explorer 11, indicating that the browser they are using is no longer supported.

true	(Default) Display the warning.
false	Do not display the warning.

externalLink.
loginURL

The URL of the SuperWEB2 login page.

This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it.

externalLink.
STRWebSiteURL

A link used in the standard footer section at the bottom of SuperWEB2.

This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it.

More information: Customise Header, Footer and Logo

link.
home

The destination the user will be redirected to when using the /home direct URL. By default this link will go to the Dataset catalogue.

If you want to change this, you can either specify

A link starting with /, in which case it will be treated as a link relative to the server root.
A link starting with http:// or https://, in which case it will be treated as an absolute link.
Any other link, in which case it will redirect relative to the context directory.

More information: Use Direct URLs to Open a Specific Dataset or Table

Map and Graph View Download Settings

Property	Description
pdfTemplateFonts	A list of fonts to embed in the downloaded PDF, separated by commas. You may need to configure font embedding if your PDF template uses a font that is not one of the default Adobe fonts. If you use a non standard font, then you can embed this in the PDF to ensure that it will display correctly regardless of whether users have that font installed on their computer. Specify the full path to the font file. If you want to embed multiple fonts, use commas to separate them. For example: CODE `pdfTemplateFonts=C:/Windows/Fonts/ARIALUNI.TTF, C:/Windows/Fonts/mingliu.ttc` This property has been renamed from `externalLink.pdfTemplateFonts` to `pdfTemplateFonts`. For backwards compatibility reasons, both the old and new keys will work. This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
graph.graphPdfTemplate	The name and location of the template for graph view downloads. This can either be a relative path, in which case it will be relative to the context directory (by default this is <tomcat_home>\webapps\webapi) or an absolute path for the file system (for example `/opt/STR/templates/SWDownloadGraph.pdf`). The filename must include the `.pdf` extension. You must escape any backslashes in the file path with an additional slash. For example: `C:\\templates\\SWDownloadGraph.pdf` This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
map.mapPdfTemplate	The name and location of the template for map view downloads. This can either be a relative path, in which case it will be relative to the context directory (by default this is <tomcat_home>\webapps\webapi ) or an absolute path for the file system (for example `/opt/STR/templates/SWDownloadMap.pdf`). The filename must include the `.pdf` extension. You must escape any backslashes in the file path with an additional slash. For example: `C:\\templates\\SWDownloadMap.pdf` This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
map. mapPdfDocumentPropertyAuthor	The value to set for the Author document property in PDF map downloads. This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
map. mapPdfDocumentPropertyKeywords	The Keywords to set in the document properties in PDF map downloads. This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
map. mapPdfDocumentPropertyApplication	The value to set for the Application document property in PDF map downloads. This property can be localised for different languages. To do this, create a new file called configuration_<locale>.properties (where <locale> is the relevant 2 character lower case ISO 639 language code) and include the localised version of this setting in it. More information: Branding PDF Downloads
kmz.author	The author name that will be embedded in KMZ files downloaded from Map View. More information: Branding KMZ Downloads
kmz.atomLink	A web link that will be embedded in the extended parameters field in KMZ files downloaded from Map View. More information: Branding KMZ Downloads
kmz.copyright	A copyright statement that will be embedded in KMZ files downloaded from Map View. More information: Branding KMZ Downloads
kmz.logoOverlayPath	The full path to the location of a logo image on the server. This will be embedded in KMZ files downloaded from Map View. More information: Branding KMZ Downloads
map.mapPdfMaxCacheItemSize	The number of PDFs to cache on the server after generating them. More information: Branding PDF Downloads
map.mapArcGISEndpointPattern	The pattern to use when setting the ArcGIS endpoint URI. This is used to extract the service name and layer index for caching. The default value is `.?\/services\/(.?)\/.?\/([0-9]?).*` More information: Caching Map Data
map.mapCacheLocation	The location of the directory to store cache information for mapping. Make sure that the directory exists and that the user running Tomcat has permission to write to it. You must escape any backslashes in the file path with an additional slash. For example: CODE `map.mapCacheLocation=c:\\str\\sw2MapCache` Forward slashes do not need to be escaped. For example: CODE `map.mapCacheLocation=/STR/sw2MapCache` If no directory is specified, then SuperWEB2 will use the default location: <tomcat_home>\work\Catalina\localhost\webapi More information: Caching Map Data
map.mapCacheSize	The maximum size of the in memory map data cache. This does not affect the size of the disk cache, which is not capped. The default value is `-1` (no limit). Use `b`, `kb`, `mb`, `gb` or `tb` to specify the unit (Kilobytes, Megabytes, Gigabytes or Terabytes). For example: CODE `map.mapCacheSize=1gb` More information: Caching Map Data
map.mapCacheExpiryTime	The expiry time for in memory cache entries. This does not affect the disk cache which can be manually expired by deleting the files. The default value is `-1`, which does not set a limit on cache entry age. More information: Caching Map Data
map.useCacheForFeatureQueries	This property can be used to disable the use of the cache for feature queries. It is not present in configuration.properties by default, but if required the following property can be added to disable the cache: CODE `map.useCacheForFeatureQueries=false` More information: Caching Map Data

User Preferences Settings

Property

Description

preferences.usersCanEditPreferences

Whether users can access the Account page options in SuperWEB2.

true	(Default) Users can access the Account options in SuperWEB2 (located on the main menu).
false	Users can not access the Account options in SuperWEB2.

More information: Change the Sort Order of Tables and Datasets

preferences.usersCanChangePassword

Whether users can change their password in SuperWEB2 (via the Account page).

true	(Default) Users can change their password in SuperWEB2.
false	Users can not change their password in SuperWEB2.

preferences.usersCanDeleteAccount

Whether users can delete their account in SuperWEB2 (via the Account page).

true	(Default) Users can delete their account in SuperWEB2.
false	Users can not delete their account in SuperWEB2.

preferences.
usersCanChangeContactPreferences

Whether users can opt in or out of email updates from the Account page.

true	Users can change their contact preference in SuperWEB2.
false	(Default) Users cannot change their contact preference in SuperWEB2.

More information: Regulatory and Privacy Compliance

preferences.allowContactDefault

Whether the default setting for the user contact preference is opt in or opt out:

true	By default, any user who has not explicitly consented to contact will be opted in.
false	(Default) By default, any user who has not explicitly expressed a contact preference will be opted out of email contact.

More information: Regulatory and Privacy Compliance

CSV Download Settings

Property Description

csv.
outputEncodingPreference

The output encoding to use for CSV files downloaded from SuperWEB2. By default, CSV files will be downloaded in UTF-8 encoding. You may need to change this to use a specific Windows codepage in some cases.

For example, some versions of Microsoft Excel (including Excel 2003) have a bug that causes them not to support UTF-8 encoding when CSV files are opened either by double clicking the file or selecting Open from the download option in a web browser.

If your users are experiencing problems opening downloaded CSV files in Excel, you may need to set SuperWEB2 to use a specific Windows codepage.

See this page for a list of available codepages. When configuring SuperWEB2, you need to use the value from the Name column.

For example, to use the Windows CP-1252 codepage, you would configure SuperWEB2 using one of the following values:

CODE

csv.outputEncodingPreference=CP1252

Or:

CODE

csv.outputEncodingPreference=Windows-1252

csv.
inputEncodingPreference

The input encoding to use when uploading user recode files. If this is not set it will fall back to the value of csv.outputEncodingPreference

numberFormat.
enableCustomUDFValueFormat

Whether to use custom number formatting for values in range and quantile labels.

true	Use the custom number formatting and precision defined in `numberFormat.customUDFValueFormat`.
false	(Default) Use the default number formatting and precision.

More information: Configure Quantiles and Ranges

numberFormat.
customUDFValueFormat

The number formatting to use for values in range and quantile labels. See http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html for details of how to specify the number formatting. Note that:

This format will only be applied if numberFormat.enableCustomUDFValueFormat is set to true.
The formatting applies to Table View only; it is not applied to table downloads.
The number formatting and precision setting only apply to the {Min} and {Max} values. They do not apply to any {Rse} value in the label.

More information: Configure Quantiles and Ranges

udr.
maxQueryParams

The size of chunks to use when connecting to the user data repository.

Some relational databases have a limit on the number of parameters that can be used in the WHERE clause of a SELECT query. Queries that are likely to overrun this limit are broken up into chunks and run in parts to avoid errors.

The default setting for this value is 1000, which should work for all supported databases.

udr.
insecureRest.enabled

The ability to upload saved tables to the catalogue in the SuperADMIN console using the cat addtable command has been disabled by default, due to a potential security issue.

If you wish to continue using this feature, it can be enabled by adding the property udr.insecureRest.enabled=true to the SuperWEB2 configuration.properties file. This property does not appear in the file by default.

The communication between SuperADMIN and SuperWEB2 involved in the process of uploading tables uses a specific header in all requests, X-STR-Auth. Should you choose to enable this feature, you should reduce the risk by ensuring that the X-STR-Auth header is stripped from any external requests via a reverse proxy or the Web Application Firewall. Please contact support for advice if you intend to enable this feature.

More information: cat and Configure Folders and Shared Tables

Open Data API Settings

The following settings apply to the Open Data API only. While they appear in the standard version of configuration.properties supplied with SuperWEB2, changing them in that version of the file will have no effect. The Open Data API has its own copy of the configuration.properties file (located in <tomcat_home>\webapps\webapi#rest#v1\WEB-INF\classes). If you want to configure the Open Data API then you must make the changes in the API's copy of the configuration file.

Property Description

openDataApi.schema.pageSize

If a query to the Open Data API returns a large number of results then it will be paginated. By default, this occurs when there are more than 100 objects in the result set. You can use this setting to increase of decrease the limit for pagination.

More information: Configure API Performance Settings

openDataApi.schema.
numberOfRateLimitPerPeriod

The number of requests that any given API key can make within a one hour period.

This property has been deprecated. It can still be used, but you are strongly recommended to remove this from your configuration and use the new rateLimit.global, rateLimit.schema and rateLimit.table properties instead.

More information: Configure API Performance Settings

openDataApi.table.
maximumResponseCellLimit

The maximum number of cells that can be returned to a client via the /table API endpoint. By default this is set to 1,000,000. It is designed to prevent excessively large tables from being sent to the client.

More information: Configure API Performance Settings

openDataApi.table.
maximumRequestItemLimit

The maximum number of field items that a user can query via the /table API endpoint. By default this is set to 1,000,000. It is designed to prevent clients from overwhelming the server with large requests.

More information: Configure API Performance Settings

openDataApi.table.
disableSingleUdf

Whether to allow the use of Single UDFs in queries. This setting is provided as a security measure.

true	Do not allow queries that result in a Single UDF to be tabulated. If a query that results in a Single UDF is submitted to the API, it will return an HTTP 422 response with a message indicating that single UDFs are not permitted.
false	(Default) Allow queries that result in a Single UDF to be tabulated.

openDataApi.
rateLimit.
global

The number of requests that any given API key can make within a one hour period. If you do not want to impose any limits, set this to -1.

More information: Configure API Performance Settings

openDataApi.
rateLimit.
schema

The number of requests to the /schema endpoint that any given API key can make within a one hour period. If you do not want to impose any limits, set this to -1 .

If you have also set a limit using the .global property then /schema requests will be stopped as soon as either of the limits are reached.

More information: Configure API Performance Settings

openDataApi.
rateLimit.
table

The number of requests to the /table endpoint that any given API key can make within a one hour period. If you do not want to impose any limits, set this to -1 .

If you have also set a limit using the .global property then /table requests will be stopped as soon as either of the limits are reached.

More information: Configure API Performance Settings

openDataApi.
auth.
cacheSize

The maximum number of entries stored in the authentication cache. This cache is designed to speed up authentication in situations where the authentication process is slow (for example because the Open Data API and the authentication server are separated by a slow network connection).

If the authentication process is fast, then you are recommended to disable the authentication cache by setting this value to 0.

The default is 10000, meaning that up to 10,000 authentication entries will be stored in the cache.

More information: Configure the Cache

openDataApi.
auth.
cacheExpiryTime

How quickly an authentication entry will expire from the cache. Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

For example, openDataApi.auth.cacheExpiryTime=4h specifies that entries expire after 4 hours.

The default is 10m (10 minutes).

More information: Configure the Cache

openDataApi.
table.
cacheSizeUnits

The units to use when setting the size of the table cache. This setting applies to the value specified for the openDataApi.table.cacheSize property, and can be one of the following:

mb	`openDataApi.table.cacheSize` is the total size of the cache in megabytes.
gb	`openDataApi.table.cacheSize` is the total size of the cache in gigabytes.
entries	(Default) `openDataApi.table.cacheSize` represents the number of individual table query results to cache.

More information: Configure the Cache

openDataApi.
table.
cacheSize

The size of the cache in either megabytes, gigabytes or total entries (depending on the value of openDataApi.table.cacheSizeUnits).

To disable the table cache entirely, set this to 0 . Or set this to a negative number if you do not want to impose an upper limit on the cache size.

The default is 4000.

More information: Configure the Cache

openDataApi.
table.
cacheExpireAfter

Whether the cache expiry time is reset when a result is accessed from the cache:

access	(Default) Each successive repeat query will reset the expiry time. This means that common queries will be cached for longer.
write	Entries expire based on the time they were created regardless of usage.

More information: Configure the Cache

openDataApi.
table.
cacheExpiryTime

How quickly a table result will expire from the cache. Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

For example, openDataApi.table.cacheExpiryTime=4h sets table entries to expire after 4 hours. Depending on the openDataApi.table.cacheExpireAfter setting, this will either be 4 hours after the initial query, or 4 hours after the last time this particular table result was accessed.

The default is 1d (1 day).

More information: Configure the Cache

openDataApi.
table.
referenceType

Whether the table cache should use soft or hard memory references to hold its contents:

soft	(Default) The cache can free up memory before the configured limits are hit (this may result in more cache misses)..
hard	The cache can only free up memory when the configured limits are hit.

More information: Configure the Cache

openDataApi.
schema.
cacheSizeUnits

The units to use when setting the size of the schema cache. This setting applies to the value specified for the openDataApi.schema.cacheSize property, and can be one of the following:

mb	`openDataApi.schema.cacheSize` is the total size of the cache in megabytes.
gb	`openDataApi.schema.cacheSize` is the total size of the cache in gigabytes.
entries	(Default) `openDataApi.schema.cacheSize` represents the number of individual schema query results to cache.

More information: Configure the Cache

openDataApi.
schema.
cacheSize

The size of the cache in either megabytes, gigabytes or total entries (depending on the value of openDataApi.schema.cacheSizeUnits).

To disable the schema cache entirely, set this to 0. Or set this to a negative number if you do not want to impose an upper limit on the cache size.

The default is 1000 .

More information: Configure the Cache

openDataApi.
schema.
cacheExpireAfter

Whether the cache expiry time is reset when a query is accessed from the cache:

access	(Default) Each successive repeat query will reset the expiry time. This means that common queries will be cached for longer.
write	Entries expire based on the time they were created regardless of usage.

More information: Configure the Cache

openDataApi.
schema.
cacheExpiryTime

How quickly a schema result will expire from the cache. Specify the value as an integer, followed by one of the following units:

d	Days
h	Hours
m	Minutes
s	Seconds

For example, openDataApi.schema.cacheExpiryTime=4h sets schema entries to expire after 4 hours. Depending on the openDataApi.schema.cacheExpireAfter setting, this will either be 4 hours after the initial query, or 4 hours after the last time this particular schema result was accessed.

The default is 1d (1 day).

More information: Configure the Cache

openDataApi.
schema.
referenceType

Whether the schema cache should use soft or hard memory references to hold its contents:

soft	(Default) The cache can free up memory before the configured limits are hit (this may result in more cache misses).
hard	The cache can only free up memory when the configured limits are hit.

More information: Configure the Cache