getDeviceTemplateMatches

POST public/getDeviceTemplateMatches

Compares the unregistered devices at a location with a device template, and returns the devices the template matches, with the settings the template would register them with. Use it before registerDevices to see which devices you can register.

Request syntax

curl https://apiv2.acumera.net/public/getDeviceTemplateMatches \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>" \
  --data-urlencode "template=<template_name>" \
  [--data-urlencode "show_unmatched=1"]

Optional parameters are shown in brackets. 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.

Request parameters

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

Parameter Type Description Required Default value
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 compare with. Letters, numbers, underscores (_), and hyphens (-) only. To list your templates, use getDeviceTemplates. Yes
show_unmatched Integer Set to 1 to also return the unregistered devices that the template doesn't match. No 0

Response syntax

{
    "success": "string",
    "data": {
        "available_devices": [
            {
                "name": "string",
                "mac": "string",
                "ip": "string",
                "policy": "string",
                "handle": "string",
                "segment": "string",
                "device_type": "string",
                "errors": {
                    "field": "string"
                },
                "matched": "string"
            }
        ]
    }
}

Response parameters

If the call succeeds, success is "1" and the following data is returned.

Field Description
available_devices The devices. Matched devices come first, then devices without errors, then the rest, each group in IP address order. Empty if no unregistered device matches the template.
available_devices[].name The name the template would register the device with.
available_devices[].mac The device's MAC address.
available_devices[].ip The device's IP address.
available_devices[].policy The firewall policy the template would assign.
available_devices[].handle The error status the template would assign: the status the device raises for the site if it stops responding.
available_devices[].segment The network segment.
available_devices[].device_type The device type the template would assign.
available_devices[].errors Problems that prevent registration, keyed by field name, for example ip. An empty array if there are none. Only devices with no errors can be registered.
available_devices[].matched "1" if the template matches the device. "0" for an unmatched device returned because of show_unmatched=1.

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.
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.
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.
NO_DEVICES_AVAILABLE_FOR_REGISTRATION No devices available for registration. The location has no unregistered devices.
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: Check which devices a template matches

This example compares the unregistered devices at location 4510 with the Fuel-ATG template.

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"
            },
            {
                "name": "Tank gauge 2",
                "mac": "00:00:5E:00:53:31",
                "ip": "172.222.0.2",
                "policy": "Local",
                "handle": "CRITICAL",
                "segment": "Fuel",
                "device_type": "ATG",
                "errors": {
                    "ip": "The IP address of this device (172.222.0.2) does not match the addressing of the segment specified in the template (Fuel)."
                },
                "matched": "1"
            }
        ]
    }
}

The first device can be registered. The second can't until its IP address is on the template's segment. To register the first device, see registerDevices.

Example: The template matches no devices

If the location has unregistered devices but the template matches none of them, available_devices is empty:

{
    "success": "1",
    "data": {
        "available_devices": []
    }
}

Example: The location has no unregistered devices

{
    "success": "0",
    "returnCode": "NO_DEVICES_AVAILABLE_FOR_REGISTRATION",
    "returnMessage": "No devices available for registration."
}