v1/configs

Use the v1/configs API to create, update, or retrieve managed device configurations.

A managed configuration is a set of rules that define how devices are configured and how they are kept in compliance. A managed configuration can be applied to groups of devices. The configuration is applied to all devices in the group that match the type and vendor ID specified in the configuration.

A managed configuration can be applied to multiple groups, but a group can have only one active (enabled) configuration for a given type and vendor ID.

Scanning occurs when a device in the group is first connected to Remote Manager and when the configuration is scheduled to scan the device. A scan can be done manually and other events in the system can also trigger a scan. See the scan_frequency field for more information about conditions that trigger a scan.

See the Automations and Firmware APIs for more information about creating and managing automations and firmware.

URI

https://<hostname>/ws/v1/configs

Formats

HTTP method	Format	Description	Parameters
GET	/ws/v1/configs	Get a summary of the /ws/v1/configs APIs.
GET	/ws/v1/configs/compliance	Get a summary of configuration compliance.	group orderby cursor size query
GET	/ws/v1/configs/compliance/{id}	Get configuration compliance for a device.
GET, PUT, DELETE	/ws/v1/configs/inventory/{id}/settings	Get, update, or delete settings for a managed configuration.
GET, PUT, DELETE	/ws/v1/configs/inventory/{id}/settings/device	Get, update, or delete site-specific managed configuration settings for a device or all devices.	device_id, device_name
GET, POST	/ws/v1/configs/inventory/{id}/settings/device/bulk	Get or update site-specific managed configuration settings for all devices.
GET, POST	/ws/v1/configs/inventory	Get or create a managed configuration.	group orderby cursor size query
GET, PUT, DELETE	/ws/v1/configs/inventory/{id}	Get, update, or delete a managed configuration.
GET	/ws/v1/configs/scan/bulk/history/{device_id}	Get the managed configuration scan history for a device in CSV format.
GET, DELETE	/ws/v1/configs/scan/history/{device_id}	Get or clear the managed configuration scan history for a device.	cursor size
POST	/ws/v1/configs/scan_now	Initiate a configuration scan.

Configuration JSON Object

An example configuration is shown below.

{
    "alert": true,
    "created": "2023-06-21T17:39:20.290Z",
    "customer_id": 57639,
    "description": "Configuration for storefront cellular backup routers",
    "device_fileset": "configuration-6748-fileset",
    "enabled": true,
    "firmware_version": "23.6.1.46",
    "groups": [
        "Stores"
    ],
    "id": 6415,
    "images": [
        {
            "name": "Network Safety Scanner",
            "version": "1.0.0"
        }
    ],
    "last_scan": "2023-06-22T08:00:03.233Z",
    "last_update": "2023-06-21T17:43:18.163Z",
    "maintenance_window_handling": "cancel",
    "name": "Store Routers",
    "on_remediate": {
        "automation_name": "Set Update Tags",
        "reboot": true
    },
    "on_scan": {
        "automation_name": "Start LEDs Flashing"
    },
    "on_success": {
        "automation_name": "Stop LEDs Flashing"
    },
    "remediate": true,
    "scan_files": true,
    "scan_frequency": "daily",
    "scan_python": false,
    "scan_settings": true,
    "type": "Digi TX64",
    "vendor_id": 4261412874
}

Configuration Fields

alert

Indicates whether the managed configuration sends alerts when devices are detected as not in compliance.

created

Timestamp that indicates when the managed configuration was created.

customer_id

Unique customer ID for the Remote Manager customer.

description

Optional description of the managed configuration.

device_fileset

The name of the fileset used by the configuration to load files on to the scanned devices. See the Files API for more information about creating, uploading and removing files from filesets.

enabled

Boolean that indicates whether the managed configuration is enabled.

firmware_version

Firmware version for the managed configuration.

flash_firmware_policy

This value is only valid if the configuration applies to XBee devices, more specifically, devices with the XBee vendor ID (0xFE000006).

Whether the configuration should flash the firmware or not. It has three possible values:

‘always’: always flash firmware.
‘if_different’: flash firmware only if the device’s firmware version is different from the one in the xbee_profile.
’never’: never flash firmware.

groups

The list of groups that the managed configuration applies to. The configuration applies to all devices matching the type field in the groups specified.

id

Unique ID for the managed configuration.

images

The list of Digi Accelerated Linux (DAL) images that describe Digi containers that should be initialized on the system. See the images fields below for more information.

last_scan

Timestamp that indicates when the managed configuration last scanned any devices.

last_update

Timestamp that indicates when the managed configuration was last updated.

maintenance_window_handling

Indicates how the managed configuration handles devices not being in maintenance windows. Can be one of

‘allow’ - Allow the configuration scan to run normally for the devices that are currently in service (not in a maintenance window)
‘reject’ - Reject the configuration scan of the device immediately at the beginning. If the device transitions to in-service (not in a maintenance window) during the scan, allow the scan to continue.
‘cancel’ - Cancel the configuration scan at any time when the device transitions to in-service during the scan.

modem_firmware_versions

The list of Modem Firmware information for the managed configuration.

name

Name of the managed configuration.

on_remediate

Set of actions to take if the scan detects a device that is not in compliance and makes it compliant. See the On Remediate Actions section below for more information.

on_scan

The set of actions to take at the beginning of a configuration scan for a device. See the On Scan Actions section below for more information.

on_success

The set of actions to take after a configuration scan for a device is successful. A successful scan occurs if the device is already in compliance or if the scan successfully makes the device compliant. See the On Success Actions section below for more information.

remediate

Boolean that indicates if the configuration should remediate (bring into compliance) devices that are detected as non-compliant.

scan_files

Boolean that indicates the configuration should scan files in the device fileset for compliance.

scan_frequency

The frequency at which the configuration scans devices for compliance.

manual - Scanning happens manually or if new devices or existing devices move into groups managed by the configuration.
daily - Approximately every 24 hours
weekly - Approximately every week
monthly - Approximately every month

If the value is ‘manual’ or any other value, devices are scanned by the system under these conditions:

The user selects the ‘Scan Now’ option for a device in the UI or uses the scan_now API
A device is first connected identified in a group managed by a configuration
A device is moved to a new group managed by a different configuration than the original

If the value is ‘daily’, ‘weekly’, or ‘monthly’, devices are also scanned by the system under these conditions:

By the configurations schedule.
The device transitions from in-service into maintenance mode
The device transitions from debug mode to not in debug mode
The devices name changes and there are site-specific settings associated with the new or old name

scan_python

Boolean that indicates if python is not installed on the Digi Accelerated Linux (DAL) device that the default python for the target firmware version should be installed and made available.

scan_settings

Boolean that indicates that the configuration should scan device settings for compliance

type

Device type for devices that are managed by configuration.

vendor_id

Unique vendor ID for devices that are managed by a configuration.

xbee_profile

This value is only valid if the configuration applies to XBee devices, more specifically, devices with the XBee vendor ID (0xFE000006).

The name of the fileset used by the configuration to load the XBee profile(s) on devices that support XBee profiles. See the Files API for more information about creating, uploading and removing files from filesets. The XBee profile is snapshot of a specific radio firmware configuration, including firmware, setting values, file system and other configuration information.

Images Fields

The images field in the configuration is a list of Digi Accelerated Linux (DAL) images that describe Digi containers that should be scanned on the device.

For example:

{
  "images": [
    {
      "name": "digi-iot-dal",
      "version": "1.0.0"
    }
  ]
}

name

The name of the Digi Containers image to use.

version

The optional version of the Digi Containers image to use.

Modem Firmware Fields

The list that describes which firmware should be installed for modems on the target devices. Some modem’s require firmware specific to the carrier, other modems support generic firmware across carriers. You can use the Remote Manager firmware UI or API to get a list of supported firmware for a modem.

For example:

{
  "modem_firmware_versions": [
    {
      "model": "EG25_G",
      "name": "modem",
      "versions": [
        {
          "version": "EG25GGBR07A07M2G_01.001.01.001"
        }
      ]
    }
  ]
}

{
  "modem_firmware_versions": [
    {
      "model": "EM7411",
      "name": "wwan1",
      "versions": [
        {
          "carrier": "GENERIC",
          "version": "01.14.13.00_GENERIC_002.048_000"
        },
        {
          "carrier": "ATT",
          "version": "01.14.13.00_ATT_002.062_000"
        }
      ]
    },
    {
      "model": "EM7411",
      "name": "wwan2",
      "versions": [
        {
          "carrier": "GENERIC",
          "version": "01.14.13.00_GENERIC_002.048_000"
        },
        {
          "carrier": "ATT",
          "version": "01.14.13.00_ATT_002.062_000"
        }
      ]
    }
  ]
}

name

The name of the modem to apply the modem firmware on

model

The model of the modem matching the firmware to apply

versions

The list of objects with version field and optional carrier field of the firmware(s) to apply to the target modem.

On Remediate Action Fields

At the end of a configuration scan that detects a device that is not in compliance and makes it compliant you can reboot the device or run an automation. This step occurs before any On Success actions.

automation_name

The automation to run at the end of the scan that remediated the device. The scan waits for the automation to complete. If the automation fails the scan fails as well. The automation for the remediate action is run after the device is rebooted, if the reboot field is true.

reboot

Boolean that indicates if the device should be rebooted after the scan that remediated the device. The reboot occurs before any On Success actions. Note that a firmware update may also reboot the device, by specifying this field you can reboot again, later in the scan. For example, after the firmware update occurs, and the device reconnects, some configuration changes or installing applications or containers may require a reboot to take effect. The reboot occurs before any automation specified in the remediate action

On Scan Action Fields

At the start of a configuration scan you can run an automation. The automation could, for example, run a CLI command on the device to flash the LEDs so that you can identify the device in a rack or set a tag on the device to indicate an update is in progress.

automation_name

The automation to run at the beginning of the scan. The scan waits for the automation to complete. If the automation fails the scan fails as well.

On Successful Scan Action Fields

At the successful completion of a configuration scan you can run an automation. The automation could, for example, run a CLI command on the device to turn off the flasshing LEDs or set a tag on the device to indicate an update was completed. Successful completion occurs if the device is already in compliance or if the scan successfully makes the device compliant. This step occurs after any On Remediate actions.

automation_name

The automation to run at the successful completion of the scan. The scan waits for the automation to complete. If the automation fails the scan fails as well.

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.

Site specific settings

The Settings section described how to manage common settings for a configuration and how individual settings are marked as site-specific by setting the @scope property to mixed or matched

In the example below, we see that there are 3 settings marked as site-specific settings.

/system/1/contact - A required setting that must be present in the device’s site-specific settings
/system/1/location - An optional setting that can be present in the device’s site-specific settings. If not present the value Rochester, MN is used.
/system/1/description - An optional setting that can be present in the device’s site-specific settings. If not present the value used is empty

{
    "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...

GET Site-specific settings

Retrieve site-specific settings for a device in one of two formats.

In the following example there are 2 devices that have site-specific settings specified.

The first device is identified by device_id 00000000-00000000-0040FFFF-FF8001B0 and sets the contact and description settings to Fred and Store Router respectively. Only that device receives those settings, the location setting is unset and therefore the common value of Rochester, MN is used.

The second device is identified by the device name. When the configuration scan encounters a device named Bus23, the contact, description, and location settings are set to Bob, Home Router, and Hopkins, MN respectively.

JSON Format

Retrieve site-specific settings for all devices that have site-specific settings in either JSON format using the GET method of the /ws/v1/configs/inventory/6415/settings/device API.

{
    "count": 2,
    "list": [
        {
            "customer_id": 57639,
            "id": 6415,
            "key_type": "device_id",
            "key_value": "00000000-00000000-0040FFFF-FF8001B0",
            "settings": {
                "system/1/contact": "Fred",
                "system/1/description": "Store Router"
            }
        },
        {
            "customer_id": 57639,
            "id": 6415,
            "key_type": "device_name",
            "key_value": "Bus23",
            "settings": {
                "system/1/contact": "Bob",
                "system/1/description": "Home Router",
                "system/1/location": "Hopkins, MN"
            }
        }
    ],
    "size": 1000
}

CSV Format

Retrieve site-specific settings for all devices that have site-specific settings in either CSV format using the /ws/v1/configs/inventory/6415/settings/device/bulk API.

key_type,key_value,system/1/contact,system/1/description,system/1/location
device_id,"00000000-00000000-0040FFFF-FF8001B0",Fred,"Store Router",
device_name,Bus23,Bob,"Home Router","Hopkins, MN"

GET Site-specific settings for a specific device

Retrieve site-specific settings for a specific device using the GET method and specifying either the device_name or the device_id parameter. If there are no site-specific settings currently set for the device, the result is an HTTP 404 error.

For example the result of the GET method of the /ws/v1/configs/inventory/6415/settings/device?device_id=00000000-00000000-0040FFFF-FF8001B0 API results in the following json.

{
    "customer_id": 57639,
    "id": 6415,
    "key_type": "device_id",
    "key_value": "00000000-00000000-0040FFFF-FF8001B0",
    "settings": {
        "system/1/contact": "Fred",
        "system/1/description": "Store Router"
    }
}

The result of the GET method of the /ws/v1/configs/inventory/6415/settings/device?device_name=Bus23 API results in the following json.

{
    "customer_id": 57639,
    "id": 6415,
    "key_type": "device_name",
    "key_value": "Bus23",
    "settings": {
        "system/1/contact": "Bob",
        "system/1/description": "Home Router",
        "system/1/location": "Hopkins, MN"
    }
}

Put site-specific settings

To update site specific settings for all devices, POST a multipart/form payload with a CSV file to the /ws/v1/configs/inventory/6415/settings/device/bulk API.

This payload replaced all existing site-specific settings for all devices with the settings for those devices specified in the CSV file. Devices that are not in the new settings file have their site-specific settings removed.

key_type,key_value,system/1/contact,system/1/description,system/1/location
device_id,"00000000-00000000-0040FFFF-FF8001B0",Fred,"Store Router",
device_name,Bus23,Bob,"Home Router","Hopkins, MN"
device_name,Bus42,Bill,"Shop Router","Byron, MN"
device_name,Bus99,Chris,"Store Router","Lewiston, MN"

Put site-specific settings for a specific device

To update site specific settings for a specific device, PUT a json payload to the /ws/v1/configs/inventory/6415/settings/device API using a device_id or device_name parameter.

This payload replaces all existing site-specific settings for the specified device with the settings specified in the payload. For example, POST the following payload to /ws/v1/configs/inventory/6415/settings/device?device_name=Bus99 will replace all site-specific settings for the Bus99 device.

{
    "settings": {
        "system/1/contact": "Chris",
        "system/1/description": "Store Router",
        "system/1/location": "Lewiston, MN"
    }
}

Delete site-specific settings for a specific device

To delete site specific settings for a specific device, DELETE to the /ws/v1/configs/inventory/6415/settings/device API using a device_id or device_name parameter.

For example, DELETE to /ws/v1/configs/inventory/6415/settings/device?device_name=Bus99 will delete all site-specific settings for the Bus99 device.