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.