Overview - cfg

The configuration server is essentially a key/value store. You can use the cfg command to read, update, and delete key values.

Reading the Value of a Key

You can read the current value of any key using the following command:

CODE

cfg {global|db <dataset_id>} <key>

Where:

global indicates that this is a global property, while db <dataset_id> indicates that this is a dataset-specific property.
<key> is the key you want to read. When reading or writing key values using the SuperADMIN console, keys are denoted by names separated by "." characters (for example: superweb2.concurrentUserLimits).

For example, to read the global property superweb2.rules.fieldExclusion, you would use the following command:

CODE

> cfg global superweb2.rules.fieldExclusion
superweb2.rules.fieldExclusion :
[
    {
        "limit":1,
        "fields":[
            "Age",
            "Age Groups"
        ]
    },
    {
        "limit":2,
        "fields":[
            "Area",
            "Occupation",
            "Gender"
        ]
    }
]

In this example the key has been set to an array of values (the items in an array are separated by commas and enclosed in square brackets). In this case the array contains two JSON objects (JSON objects are enclosed in curly brackets).

You can read an individual item from the array by using an index number in square brackets at the end of the key name. Array index numbering starts at zero, so to read the first item in the array you would use the following command:

CODE

> cfg global superweb2.rules.fieldExclusion[0]
superweb2.rules.fieldExclusion[0] :
{
    "limit":1,
    "fields":[
        "Age",
        "Age Groups"
    ]
}

In this case the items in the array are JSON objects. You can read the values of specific keys within those objects simply by adding the key name to the query. For example, to read the value of the fields key from within the first object in the fieldExclusion array you would use the following command:

CODE

> cfg global superweb2.rules.fieldExclusion[0].fields
superweb2.rules.fieldExclusion[0].fields :
[
    "Age",
    "Age Groups"
]

To read the value of the fields key from the second object within the fieldExclusion array you would use the same command but with the index value of 1 instead of 0:

CODE

> cfg global superweb2.rules.fieldExclusion[1].fields
superweb2.rules.fieldExclusion[1].fields :
[
    "Area",
    "Occupation",
    "Gender"
]

If you attempt to read the value of a key that has not been set, SuperADMIN displays "not found". For example:

CODE

> cfg global superweb2.rules.fieldExclusion[3]
superweb2.rules.fieldExclusion[3] : not found

Writing the Value of a Key

To write a value to a key, use the following command:

CODE

cfg {global|db <dataset_id>} <key> set <value>

Where:

global, db <dataset_id> and <key> use the same conventions as described above.
<value> must be one of the following:

JSON Object

A series of key/value pairs, separated by commas and enclosed in curly brackets. For example:

CODE

cfg global superweb2.rules.fieldExclusion[2] set {"limit":1,"fields":["Marital Status","Age","Area"]}

In the above example, since the fieldExclusion key takes an array of JSON objects, the "2" that is enclosed in square brackets instructs the system to add or replace the item at that position in the array. If you simply want to add an item onto the end of the existing array, then you can use the add command instead, as follows:

CODE

cfg global superweb2.rules.fieldExclusion add {"limit":1,"fields":["Marital Status","Age","Area"]}

When using add, if there are no existing values for this key then the array will be created automatically (with your specified value added at position 0).

Array

A set of values separated by commas, enclosed in square brackets. For example:

CODE

cfg global superweb2.rules.fieldExclusion[2].fields set ["Marital Status","Age","Area"]

Boolean

true or false. For example:

CODE

cfg db bank superweb2.zeroSuppression.rows set true

Numeric

A numeric value. For example:

CODE

cfg global superweb2.rules.fieldExclusion[2].limit set 1

String

A string, which must be enclosed in quotes. For example:

CODE

cfg global superweb2.rules.fieldExclusion[2].fields[0] set "Marital Status"

When you use the set command, SuperADMIN will replace any existing value for that key with your new value. If the key does not exist (i.e. no value has been set for it), then SuperADMIN will automatically create it.

SuperADMIN will accept any keys and any values, even if they are not valid SuperWEB2 configuration properties, or if you have set a key to the wrong value type (such as setting a key to a string value when it should be an array of values).

By default, if you set any invalid configuration properties, then SuperWEB2 will reject all configuration properties (even valid ones).

If you prefer, you can configure SuperWEB2 to ignore unknown properties while still accepting any valid configuration properties. To do this, you need to set the value of the configServer.failOnUnknownProperties property in SuperWEB2's configuration.properties file to false.

Add an Item to an Array

If a key takes an array value, then there is an additional command (add) that you can use to add an item to the end of the array.

For example, you might have used the set command to populate a key with an array:

CODE

> cfg global superweb2.rules.fieldExclusion[2].fields set ["Marital Status","Age","Area"]
superweb2.rules.fieldExclusion[2].fields : Updated
> cfg global superweb2.rules.fieldExclusion[2].fields
superweb2.rules.fieldExclusion[2].fields :
[
    "Marital Status",
    "Age",
    "Area"
]

If you then decide you want to add a single additional item to this array you can do so using the add command, rather than recreating the whole array (note that you can only add a single item to this array, and it must be specified without square brackets):

CODE

cfg global superweb2.rules.fieldExclusion[2].fields add "Occupation"

If you now read the value of this key you can see that the item has been added:

CODE

> cfg global superweb2.rules.fieldExclusion[2].fields
superweb2.rules.fieldExclusion[2].fields :
[
    "Marital Status",
    "Age",
    "Area",
    "Occupation"
]

Remove a Key

Use the remove command to remove an entire key and all its children:

CODE

cfg {global|db <dataset_id>} <key> remove

For example, the following command removes the entire fieldExclusion key, including all child values.

CODE

> cfg global superweb2.rules.fieldExclusion remove
superweb2.rules.fieldExclusion : Removed

If you attempt to read the value of the key, or of one of the child values, SuperADMIN displays "not found":

CODE

> cfg global superweb2.rules.fieldExclusion
superweb2.rules.fieldExclusion : not found
> cfg global superweb2.rules.fieldExclusion[2].fields
superweb2.rules.fieldExclusion[2].fields : not found

Remove an Item from an Array

You can also use the remove command to remove a single item from an array. Simply specify the index value of the item you want to remove (the indexes of the rest of the items in the array will be adjusted accordingly):

CODE

cfg {global|db <dataset_id>} <key>[<index>] remove

For example, suppose the saveTableLimits key currently has three values:

CODE

> cfg global superweb2.saveTableLimits
superweb2.saveTableLimits :
[
    {
        "limit":50,
        "groupId":"Users"
    },
    {
        "limit":150,
        "groupId":"administrators"
    },
    {
        "limit":50,
        "groupId":"managers"
    }
]

If you wanted to remove the set of limits that apply to administrators (which is currently the second item in the array), then you can do so using the following command:

CODE

> cfg global superweb2.saveTableLimits[1] remove
superweb2.saveTableLimits[1] : Removed

You can now read the value of this key to see that the item has been removed from the array:

CODE

> cfg global superweb2.saveTableLimits
superweb2.saveTableLimits :
[
    {
        "limit":50,
        "groupId":"Users"
    },
    {
        "limit":50,
        "groupId":"managers"
    }
]

When Do My Changes Take Effect?

Any changes you make to the configuration using the cfg command will be applied immediately; there is no need to restart the SuperWEB2 service.

If users are already logged in to SuperWEB2 then they may not see the changes immediately. If a user already has the dataset open when you make the change, then that user will not see the effect of any global changes or any changes specific to the currently open dataset until they reselect that dataset from the catalogue.

In addition, please note that any user account or group changes you make with the account command will not be applied to currently logged in users until they log out and log back in again. This may mean that your configuration changes are not fully applied until a user logs in again. For example, if you set the user query limits (using the cfg global superweb2.rules.groupQueryLimits command) then this change takes effect as soon as users reopen the dataset. However, if you have also moved a user into a particular group as part of this configuration change (using the account command) then the group change will not apply until that user logs in again.

Choose Whether to Format Output

To make it easier to read the configuration, by default SuperADMIN will "pretty print" the JSON. If you prefer, you can turn this feature off so that all of the JSON is printed on a single line with minimal spacing.

To change this setting, use the following command:

CODE

cfg pretty {true|false}

For example, by default output is pretty printed:

CODE

> cfg global superweb2.rules.fieldExclusion
superweb2.rules.fieldExclusion :
[
    {
        "limit":1,
        "fields":[
            "Age",
            "Age Groups"
        ]
    }
]
>

If you disable pretty printing, then the output is printed on a single line:

CODE

> cfg pretty false
Pretty print config: false
> cfg global superweb2.rules.fieldExclusion
superweb2.rules.fieldExclusion : [{"limit":1,"fields":["Age","Age Groups"]}]
>

This setting applies to both output printed on screen in the SuperADMIN Console, and output exported to a file.

You can always import pretty printed JSON from a file regardless of the current console output format setting, although any configuration you apply by typing commands into the console must always be on a single line with no carriage returns.