registerDevices

POST public/registerDevices

Registers unregistered devices at a location by using a device template. The template sets each device's name, policy, segment, error status, and device type. Use getDeviceTemplateMatches first to see which devices the template matches, and then submit the matches you want to register.

Request syntax

curl https://apiv2.acumera.net/public/registerDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>" \
  --data-urlencode "template=<template_name>" \
  --data-urlencode 'devices=<json_array_of_devices>'

All parameters are required. The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Put the devices value in single quotes so that the shell doesn't change the double quotes inside the JSON.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required
`location_id`	Integer	The ID of the location. To find location IDs, use getCompanyInfo with `include_sites=1`.	Yes
`template`	String	The name of the device template to register the devices with. Letters, numbers, underscores (`_`), and hyphens (`-`) only. To list your templates, use getDeviceTemplates.	Yes
`devices`	String (JSON array)	The devices to register, as a JSON array of device objects. Each object must be one of the matches that getDeviceTemplateMatches returns for the same location and template, without its `errors` and `matched` fields. See Device objects.	Yes

Device objects

Each object in devices has the following fields. Copy the values exactly as getDeviceTemplateMatches returns them.

Field	Type	Description
`name`	String	The name to register the device with.
`mac`	String	The device's MAC address.
`ip`	String	The device's IP address.
`policy`	String	The firewall policy to assign. See Firewall policies.
`handle`	String	The error status: the status the device raises for the site if it stops responding, for example `CRITICAL`.
`segment`	String	The network segment the device is on.
`device_type`	String	The device type, for example `ATG`.

SC//AcuVigil registers a submitted device only if it exactly matches a current template match with no errors. A device whose fields or values differ, or that has errors in getDeviceTemplateMatches, is skipped without an error. To see which devices were registered, check registered_devices in the response.

Response syntax

{
    "success": "string",
    "data": {
        "registered_devices": [
            {
                "name": "string",
                "mac": "string",
                "ip": "string",
                "policy": "string",
                "handle": "string",
                "segment": "string",
                "device_type": "string"
            }
        ]
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned. All values are strings.

Field	Description
`registered_devices`	The devices that were registered. Submitted devices that didn't match the template aren't included.
`registered_devices[].name`	The name the device was registered with.
`registered_devices[].mac`	The device's MAC address.
`registered_devices[].ip`	The device's IP address.
`registered_devices[].policy`	The firewall policy assigned to the device.
`registered_devices[].handle`	The device's error status.
`registered_devices[].segment`	The network segment the device is on.
`registered_devices[].device_type`	The device type.

To confirm the registration, use getRegisteredDevices.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`NO_LOCATION_SELECTED`	No location was selected or the location does not exist.	`location_id` is missing or isn't a number.
`LOCATION_NOT_FOUND`	The location was not found.	No location has that ID.
`MISSING_DEVICE_REGISTRATION_TEMPLATE`	The Device Template was not supplied.	`template` is missing or empty.
`DEVICE_REGISTRATION_TEMPLATE_NOT_FOUND`	The requested Device Template was not found.	`template` contains characters other than letters, numbers, `_`, and `-`, or the company has no device template with that name.
`NO_DEVICES_SUBMITTED_FOR_REGISTRATION`	No devices were selected for registration.	`devices` is missing or empty.
`AUTH_FAILED_FUNC_NOT_ALLOWED`	Authorization failed because you are not permitted to access the requested function.	Your account isn't allowed to register devices, or doesn't have access to the location.
`SITE_NOT_ACTIVE`	The location is not active.	The location isn't active.
`MG_TYPE_HARDWARE_NOT_FOUND`	No MG-type hardware is present at this location.	The location has no ESD.
`INVALID_TEMPLATE_JSON`	The template contains invalid data.	The device template can't be read. Contact Scale Computing Support. For more information, see Getting support.
`INVALID_DEVICE_LIST_SUBMITTED_FOR_REGISTRATION`	The submitted list of devices is in an invalid format	`devices` isn't valid JSON.
`NO_VALID_DEVICES_SUBMITTED_FOR_REGISTRATION`	No valid devices were submitted for registration.	None of the submitted devices exactly matches a current template match with no errors.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Find and register devices that match a template

This example registers the devices that the Fuel-ATG template matches at location 4510.

First, list the devices the template matches:

curl https://apiv2.acumera.net/public/getDeviceTemplateMatches \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "template=Fuel-ATG"

Response:

{
    "success": "1",
    "data": {
        "available_devices": [
            {
                "name": "Tank gauge",
                "mac": "00:00:5E:00:53:30",
                "ip": "10.169.10.20",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Fuel",
                "device_type": "ATG",
                "errors": [],
                "matched": "1"
            }
        ]
    }
}

Then submit the match, without its errors and matched fields:

curl https://apiv2.acumera.net/public/registerDevices \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "template=Fuel-ATG" \
  --data-urlencode 'devices=[{"name":"Tank gauge","mac":"00:00:5E:00:53:30","ip":"10.169.10.20","policy":"Local","handle":"CRITICAL","segment":"Fuel","device_type":"ATG"}]'

Response:

{
    "success": "1",
    "data": {
        "registered_devices": [
            {
                "name": "Tank gauge",
                "mac": "00:00:5E:00:53:30",
                "ip": "10.169.10.20",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Fuel",
                "device_type": "ATG"
            }
        ]
    }
}

Example: Submit devices that don't match the template

If none of the submitted devices exactly matches a current template match, nothing is registered and the call fails. This happens, for example, when a field value was changed, or when the device has errors in getDeviceTemplateMatches.

{
    "success": "0",
    "returnCode": "NO_VALID_DEVICES_SUBMITTED_FOR_REGISTRATION",
    "returnMessage": "No valid devices were submitted for registration."
}

Example: Submit a device list that isn't valid JSON

{
    "success": "0",
    "returnCode": "INVALID_DEVICE_LIST_SUBMITTED_FOR_REGISTRATION",
    "returnMessage": "The submitted list of devices is in an invalid format"
}