Settings

Each configuration can manage common settings and site-specific settings for devices in the fleet.

Common settings are those settings that have the same value applied to all devices managed by the configuration. An example of a common setting might be a timeout value for connections. All devices managed by the configuration use the same timeout value.
Site-specific settings vary in value across devices managed by the configuration. An example of a site-specific setting might be an IP address. The IP address assigned to each device differs so all devices can work on the same network.

Site-specific settings can be marked as required or optional.

The configuration scan fails when required site specific settings are not present.
If optional site-specific settings are not present the common setting is applied for that value.

Warning

The Remote Manager UI uses its own conventions when updating configurations and settings. Using different conventions might cause your configuration or settings not to work with the UI. The recommended approach is to use the UI or API to manage your configurations and settings, but not both. Some conventions of the UI include but are not limited to:

A specific naming for the device_fileset setting that allows the UI to separately manage files referenced by the configuration
Using optional settings attributes like @managed at every level of the configuration instead of utilizing the hierarchical nature of those values.
Leaving values out of the settings payload that are unset instead of setting them to an empty string or spaces.

Info

For historical reasons, an API payload describes each setting using a scope value. The scope of a setting is common, mixed, and matched. You can think of it as if the scope value describes where the setting comes from when being applied to a device.

common - The setting is applied from only the common value
mixed - Allow a site-specific setting. The setting is applied based on either the common or the site-specific value. If both are present, the site-specific value takes precedence. I.e. The site-specific value is optional.
matched - Require a site-specific setting. The setting is applied based only on the site-specific value. The scan fails for a device if the setting is not present in the site-specific settings for a device.

Configuration common settings

Settings are managed by using GET, PUT, DELETE methods of the /ws/v1/configs/inventory/{id}/settings API where {id} is the configuration ID.

Info

The payload for common settings is complex and its structure and valid values depends on the type of device. A good strategy for creating common settings payloads is to use the Remote Manager user interface to create a configuration by importing settings from a device into the configuration. Once you have a configuration, use the GET API to retrieve the settings. Continue to use the UI to experiment with the settings and their values for the type of devices you are managing.

GET Common settings

Consider a GET call to the /ws/v1/configs/inventory/6415/settings API. The API might return the following payload.

NOTE: Only 5 of the system settings are shown here, the full configuration settings contains hundreds of entries.

{
    "id": 6415,
    "customer_id": 57639,
    "system": {
      "#entries": [
        {
          "name": {
            "@managed": true,
            "@scope": "common",
            "#value": "TX64"
          },
          "contact": {
            "@managed": true,
            "@scope": "matched"
          },
          "location": {
            "@managed": true,
            "@scope": "mixed",
            "#value": "Rochester, MN"
          },
          "description": {
            "@managed": true,
            "@scope": "mixed"
          },
          "banner": {
            "@managed": false,
            "@scope": "common",
            "#value": "Welcome to the TX64"
          },
...etc...

Common settings payload elements

All entries in the settings tree follow the same format. The following table describes the elements of the settings payload shown above.

The system group represents a single group that contains a variety of different settings in the #entries list.
Each of those settings is marked @managed: true, which indicates that the setting is managed by the configuration. Set @managed to false so that the configuration does not manage/update the setting on the device. The ‘@managed’ setting is hierarchically applied by the system. If the @managed setting is set to false for a group, all settings in that group are set to false as well. If the @managed setting is set to true for a group, all settings in that group are set to true as well.
The name and banner settings are common. All devices in a scan will receive the same value for those settings, TX64 and Welcome to the TX64 respectively.
The contact setting is @scope: matched indicating it is a required site-specific setting. The value of the setting is determined by the value of the /system/1/contact site-specific setting. If the contact site-specific setting is not present in the site-specific, the configuration scan fails for the device missing the setting. See Site specific settings for more information about how to set site-specific settings.
The location setting is @scope: mixed indicating that it’s value is not required and can be a mix of either the value of the /system/1/location site-specific setting or the value in the associated #value field. See Site specific settings for more information about how to set site-specific settings.
Similarly, the description setting is @scope: mixed indicating that it’s value is not required and can be a mix of either the value of the /system/1/description site-specific setting or no value (since the associated #value field is absent).

PUT Common settings

A PUT to the /ws/v1/configs/inventory/{id}/settings API replaces the entire tree of existing settings with the new settings. The PUT payload is the same as the GET payload. Be sure to include all settings in the PUT payload, not just the settings you want to change.