Articles in this section

See more

Asset Management (Device Inventory) - RESTful API

Avatar
Stuart Hill
  • Updated
Follow

This article details instructions for two calls:

  • api/inventory (listing assets on a server, and adding a new asset)
  • api/inventory/{deviceId} (listing details of, updating, or deleting an asset).

 

Summary:

List the inventory devices (assets) on a server, and add a new device to the inventory.

URL:

http(s)://{server hostname}/api/inventory

 

 

Summary:

List details of, update or delete an inventory device (asset).

URL:

http(s)://{server hostname}/api/inventory/{deviceId}

 

Asset management

 

Method summary

Note on the use of credential sets

GET Method - inventory

POST Method - inventory

GET Method - inventory/{deviceId}

PUT Method - inventory/{deviceId}

DELETE Method - inventory/{deviceId}

Note regarding backwards compatibility for adding a device using a local credential

 

 

Method summary

inventory:

  • GET Method - list the contents of the inventory (XML, JSON).
  • POST Method - queue a device to add to the inventory of a server (XML, JSON).

inventory/{deviceId}:

  • GET Method - list details of an inventory device (XML, JSON).
  • PUT Method - change an inventory device's details (XML, JSON).
  • DELETE Method - remove a device from the inventory.

 

 

Note on the use of credential sets

From Entuity v19.0 upwards, users can create shared credential sets that can then be bulk-applied to multiple assets. Entuity recommends that you add devices using these shared credential sets. Please see below for the attributes required to define different types of credentials (credentials can be specified or seen by the corresponding credential name):

SNMP and virtualization-type devices:

  • credentialId

Config Management:

  • cmCredentialId
  • cmCredentialName

Server or storage hardware:

  • hwConnMethod
  • hwConnPort
  • hwCredentialId
  • hwCredentialName

Server OS:

  • osConnMethod
  • osConnPort
  • osCredentialId
  • osCredentialName

User Defined REST Poller:

  • udConnMethod
  • udConnPort

 

 

GET Method - inventory

List the contents of the inventory, in either XML or JSON formats.

Response:

Name Description
Count number of devices in the inventory.
Items

list of device summary details:

  • name: Display Name
  • Id:  Unique Identifier per server
  • polledName: DNS name or IP address
  • serverId: server identifier

Examples:

INPUT
curl –u admin:admin https://localhost/api/inventory?media=json

OUTPUT
{
  "items": [
  {
    "serverId": "34564e92-3b4f-43ba-94a8-04309c0e48fe",
    "id": "2",
    "name": "A",
    "added": true,
    "polledName": "10.66.24.2"
  }
  ],
"count": 1
}

 

INPUT
curl -u admin:admin https://localhost/api/autodiscoveryResults?media=xml

OUTPUT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<items count="1">
  <item xsi:type="device" added="true" polledName="10.66.24.2" name="A" id="2" serverId="34564e92-3b4f-43ba-94a8-04309c0e48fe" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"/>
</items>

 

 

 

 

 

 

POST Method - inventory

Queue a device to add to the inventory of a server, via either XML or JSON formats.

URL parameters:

Note: URL parameters are appended to the end of the URL and are delimited from the main part of the URL using a question mark (?) character, see the example below.

Name Description

allowduplicateIps

(Pre Entuity v20.0)

allow duplicate IP addresses. By default, ENA will not manage a device that has IP addresses that have already been seen on an existing managed device. The duplicateIps flag can be used to override this behavior.

The flag will accept the values; "false", "no", "0", "true", "yes" or "1". To override ENA's default behavior, set this flag to true. For default behavior, set the flag to false or omit the flag altogether.

Request parameters:

Name Description

allowDuplicateIps

(Entuity v20.0 upwards)

allow duplicate IP addresses. 

To override the default behavior the attribute has to be set to true and included in the body of the request.

"allowDuplicateIps": "true"
cmCredentialId ID of the config management credential set.
cmCredentialName name of the config management credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).
configurationManagementLicense if Configuration Mangement is enabled ('true') or disabled ('false'), by default false.
credentialId ID of the shared credential set, used only for SNMP and virtualization assets. The credential must be a valid credential for the specified device type. credentialId is based on the credentials you have created and therefore can be any value. E.g. if credentialId = 1 is an SNMP credential, and the device requires an API Key credential, the request will then fail.
deviceType

Device type, one of:

  • Hub.
  • Token Ring Switch.
  • Ethernet Switch.
  • ATM Switch.
  • Router.
  • Blade Center.
  • User Created Node.
  • VM Platform.
  • Autonomous WAP.
  • Firewall.
  • VPN.
  • Managed Host.
  • Non-SNMP Device.
  • Unclassified (Full).
  • PoE Midspan Injector.
  • Load Balancer.
  • SSL Proxy.
  • Unclassified.
  • Wireless Controller.
  • Uninterruptible Power Supply.
  • Matrix Switch.
  • Wide Area Application Service.
  • Multiplexer.
  • SDN Controller.
  • Cloud Controller.
  • Custom Device.
hwConnMethod

connection method used to the hardware asset, which is the collector name based on the device type being added, from the following:

Server:

  • ciscoucscimcsnmp
  • dellidracrest
  • dellidracsnmp
  • dellopenmanagesnmp
  • hpinsightsnmp
  • hpilorest
  • hpilosnmp

Storage:

  • dellequallogicsnmp
  • emcdatadomainsnmp
  • emcisilonrest
  • emcisilonssh
  • emcvnxcontrolssh
  • hpnimblerest
  • naviseccli
  • netapprest
  • netappsnmp
  • uemcli
hwConnPort connection port used to the hardware asset.
hwCredentialId ID of the hardware asset credential set.
hwCredentialName name of the hardware credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).
managementLevel

management level:

  • FULL.
  • FULL_NO_PORTS.
  • BASIC.
  • PING_ONLY.
  • WEB.
name

device name.
nameUsing

device name is determined using one of the following:

  • CUSTOMNAME.
  • IPADDRESS.
  • POLLEDNAME.
  • RESOLVABLENAME.
  • RESOLVABLENAMEFQ.
  • SYSTEMNAME.
osConnMethod

connection method used to the OS, which is the collector name based on the device type being added, from the following:

  • osaixssh
  • ossolarisssh
  • oslinuxssh
  • oswinrm
osConnPort connection port used to the OS.
osCredentialId ID of the OS credential set.
osCredentialName name of the OS credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).

polledName

 DNS name or IP Address.

protocol

transport protocol: IPv4, IPv6.

snmpBulk

whether SNMPBulkGet is used ('true' or 'false', by default false).

snmpPDUSize

maximum size of SNMP PDU.

0 = system default

snmpRetry

number of SNMP retries.

0 = system default

snmpTimeout

SNMP timeout in seconds.

0 = system default

snmpType

SNMP type:

  • v1.
  • v2c.
  • v3.
  • v1/2.

snmpPort

SNMP port number (if omitted, the default value will be used).

udConnMethod

connection method used to the user defined object.

udConnPort

connection port used to the user defined object.

webURL

web URL, applicable to the following asset types:

  • Oracle VM Manager
  • VMWare vCenter or ESXi
  • Cisco APIC
  • Cisco DNA Center
  • Meraki SD Controller
  • vManage SD Controller

Response:

200 - OK (Device is queued to be added to the inventory.)

The status info message will say “Queued” or “Replaced”, depending on whether this was the first attempt to add a device, or if there was a previous failed attempt to add the device with the same polledName.

Examples:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST –H "content-type:application/json" -d \
'{
  "polledName" : "10.66.23.1",
  "managementLevel" : "FULL",
  "protocol" : "IPv4",
  "snmpType" : "v2c",
  "credentialId" : "1"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

INPUT
curl -u admin:admin https://localhost/api/inventory?media=xml -X POST –H "content-type:application/xml" -d \
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<inventoryDevice
  polledName="10.66.23.1"
  managementLevel="FULL"
  protocol="IPv4"
  snmpType="v2c"
  credentialId="1"
/>'

OUTPUT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<statusInfo>
  <message>Queued</message>
</statusInfo>

 

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST –H "content-type:application/json" -d \ 
'{ 
  "polledName" : "10.66.23.1", 
  "managementLevel" : "FULL", 
  "protocol" : "IPv4", 
  "snmpType" : "v2c", 
  "credentialId" : "1",
  "allowDuplicateIps": "true"
}'

OUTPUT
'{
"message": "Queued"
}'

 

To add a device that is not a VM Platform, Cloud Controller, SDN Controller, Ping Only, or Custom Device:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "nameUsing" : "POLLEDNAME",
  "polledName" : "10.66.33.2",
  "managementLevel" : "FULL",
  "protocol" : "IPv4",
  "snmpType" : "v2c",
  "credentialId" : "1"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

To specify a Ping Only device:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "nameUsing" : "POLLEDNAME",
  "polledName" : "10.66.33.2",
  "managementLevel" : "PING_ONLY",
  "protocol" : "IPv4"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

To specify a device type such as VM Platform, Cloud Controller, SDN Controller:

i). To add an Amazon Web Services platform:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "AWS",
  "deviceType" : "VM Platform",
  "credentialId" : "4"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

ii). To add a Meraki Cloud Controller platform:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "Meraki",
  "deviceType" : "Cloud Controller",
  "webURL" : "https://api.meraki.com/api/v0/"
  "credentialId" : "3"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

iii). To add an Azure platform:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "AZURE",
  "deviceType" : "VM Platform",
  "credentialId" : "5"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

iv). To add a Cisco APIC SDN Controller:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "APIC",
  "deviceType" : "SDN Controller",
  "webURL" : "https://myapicname.cisco.com/api",
  "credentialId" : "6"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

v). To add a VMWare Platform:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "vortex",
  "deviceType" : "VM Platform",
  "webURL" : "https://vortex/sdk",
  "credentialId" : "6"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

vi). To add a Viptela device:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "Viptela1",
  "deviceType" : "Cloud Controller",
  "webURL" : "https://api.viptela/com/api/v1",
  "credentialId" : "6"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

vii). To add a Cisco DNA Center:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "WEB",
  "polledName" : "DNAC1",
  "deviceType" : "Cisco DNA Center",
  "webURL" : "https://1.2.3.4",
  "credentialId" : "6"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

viii). To add an Cisco UCS server device:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
  "managementLevel" : "CLI",
  "polledName" : "CISCO UCS",
  "deviceType" : "Server",
  "hwConnMethod" : "ciscoucscimcsnmp",
  "hwConnPort" : "0",
  "hwCredentialId" : "9"
}'

OUTPUT
'{
  "message": "Queued"
}'

 

ix). To add a Linux OS:

INPUT
curl -u admin:admin https://localhost/api/inventory?media=json -X POST -H "content-type:application/json" -d \
'{
"managementLevel" : "FULL",
"polledName" : "LINUX UCS",
"deviceType" : "Server",
"osConnMethod" : "oslinuxssh",
"osConnPort" : "0",
"osCredentialId" : "5"
}'

OUTPUT
'{
"message": "Queued"
}'

 

 

GET Method - inventory/{deviceId}

List details of an inventory device, in either XML or JSON formats.

Response:

Name Description

capabilities

device capabilities: routing, switching, switching & routing.

certified

if device has been certified.
cmCredentialId ID of the config management credential set.
cmCredentialName name of the config management credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).
configurationManagementLicense if Configuration Mangement is enabled ('true') or disabled ('false'), by default false.
context SNMP v3 context.
credentialId ID of the shared credential set, used for SNMP and virtualization assets. The credential must be a valid credential for the specified device type. credentialId is based on the credentials you have created and therefore can be any value. E.g. if credentialId = 1 is an SNMP credential, and the device requires an API Key credential, the request will then fail.

deviceType

device type.

dsObjectId

device’s stormworks identifier.

id

device’s unique identifier.
hwConnMethod

connection method used to the hardware asset, which is the collector name based on the device type being added, from the following:

Server:

  • ciscoucscimcsnmp
  • dellidracrest
  • dellidracsnmp
  • dellopenmanagesnmp
  • hpinsightsnmp
  • hpilorest
  • hpilosnmp

Storage:

  • dellequallogicsnmp
  • emcdatadomainsnmp
  • emcisilonrest
  • emcisilonssh
  • emcvnxcontrolssh
  • hpnimblerest
  • naviseccli
  • netapprest
  • netappsnmp
  • uemcli
hwConnPort connection port used to the hardware asset.
hwCredentialId ID of the hardware asset credential set.
hwCredentialName name of the hardware credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).

managementIP

management IP address.

managementLevel

management level:

  • FULL
  • FULL_NO_PORTS
  • BASIC
  • PING_ONLY
  • WEB.

name

device name

nameUsing

device name is determined using either:

  • CUSTOMNAME
  • IPADDRESS
  • POLLEDNAME
  • RESOLVABLENAME
  • RESOLVABLENAMEFQ
  • SYSTEMNAME.
osConnMethod

connection method used to the OS, which is the collector name based on the device type being added, from the following:

  • osaixssh
  • ossolarisssh
  • oslinuxssh
  • oswinrm
osConnPort connection port used to the OS.
osCredentialId ID of the OS credential set.
osCredentialName name of the OS credential - this name will only be displayed if it is a shared credential (i.e. not a local credential).

polledName

DNS name or IP Address.

protocol

Transport protocol: IPv4 or IPv6.

serverId

server identifier.
snmpBulk

whether SNMPBulkGet is used ('true' or 'false', by default false).

snmpPDUSize

maximum size of SNMP PDU, where 0 = system default.
snmpPort SNMP port number (if omitted, the default value will be used).

snmpRetry

number of SNMP retries, where 0 = system default.

snmpTimeout

SNMP timeout in seconds, where 0 = system default.

snmpType

SNMP version: v1, v2, v3 or v1/2. For a non-SNMP device, this will be 'none'.

sysDescription

SNMP description field.

sysLocation

SNMP retrieved system Location field.

sysOid

SNMP system identifier field.
udConnMethod connection method used to the user defined object.
udConnPort connection port used to the user defined object.

username

SNMP v3 user name.

webURL

virtual platform URL (non-Amazon virtual platforms).

zoneId

the ID of a zone.

Examples:

INPUT
curl -u admin:admin https://localhost/api/inventory/2?media=json

OUTPUT
{
  "serverId" : "34564e92-3b4f-43ba-94a8-04309c0e48fe",
  "id": "2",
  "name": "10.66.23.1",
  "dsObjectId": 814,
  "snmpTimeout": 0,
  "snmpRetry": 0,
  "snmpPDUSize": 0,
  "protocol": "IPv4",
  "snmpType": "v3",
  "nameUsing": "CUSTOMNAME",
  "certified": "Yes",
  "polledName": "10.66.23.1",
  "managementIP": "10.66.23.1",
  "sysOid": ".1.3.6.1.4.1.2.3.50",
  "sysDescription": "10/100 Mbps Ethernet Switch",
  "sysLocation": "Simulator",
  "deviceType": "Ethernet Switch",
  "readCommunity": "public",
  "userName": "entuity",
  "authType": "MD5",
  "encrType": "DES",
  "managementLevel": "FULL",
  "context": "",
  "zoneId": 0,
  "cliUsername": ""
}

 

INPUT
curl -u admin:admin https://localhost/api/inventory/2?media=xml

OUTPUT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<inventoryDevice cliUsername="" zoneId="0" snmpPDUSize="0" snmpRetry="0" snmpTimeout="0" context="" encrType="NONE" authType="NONE" userName="" readCommunity="public" snmpType="v1/v2c" protocol="IPv4" certified="Yes" deviceType="Ethernet Switch" managementLevel="FULL_MGMT_PORT_ONLY" capabilities="Switch" sysLocation="Simulator" sysDescription="10/100 Mbps Ethernet Switch" sysOid=".1.3.6.1.4.1.2.3.50" managementIP="10.66.23.1" polledName="10.66.23.1" nameUsing="CUSTOMNAME" dsObjectId="922" name="10.66.23.1" id="2" serverId="34564e92-3b4f-43ba-94a8-04309c0e48fe"/>

 

 

PUT Method - inventory/{deviceId}

Change the details of an inventory device, in either XML or JSON formats. Please see this section for help and information on managing assets via the Entuity UI.

Request:

Same as for GET - inventory/{deviceId} above.

Response:

200 OK

Examples:

INPUT
curl -u admin:admin https://localhost/api/inventory/2?media=json -X PUT -H "content-type:application/json" -d \
'{
  "managementLevel" : "FULL",
  "protocol" : "IPv4",
  "snmpType" : "v3",
  "userName" : "entuity",
  "authType" : "MD5",
  "authPass" : "entuity123",
  "encrType" : "DES",
  "encrPass" : "entuity123"
}'

OUTPUT
{
  "serverId": "34564e92-3b4f-43ba-94a8-04309c0e48fe",
  "id": "2",
  "name": "10.66.23.1",
  "dsObjectId": 814,
  "snmpTimeout": 0,
  "snmpRetry": 0,
  "snmpPDUSize": 0,
  "protocol": "IPv4",
  "snmpType": "v3",
  "nameUsing": "CUSTOMNAME",
  "certified": "Yes",
  "polledName": "10.66.23.1",
  "managementIP": "10.66.23.1",
  "sysOid": ".1.3.6.1.4.1.2.3.50",
  "sysDescription": "10/100 Mbps Ethernet Switch",
  "sysLocation": "Simulator",
  "deviceType": "Ethernet Switch",
  "readCommunity": "public",
  "userName": "entuity",
  "authType": "MD5",
  "encrType": "DES",
  "managementLevel": "FULL",
  "context": "",
  "zoneId": 0,
  "cliUsername": ""
}

 

INPUT
curl -H -u admin:admin https://localhost/api/inventory/2?media=xml -X PUT -d \
'<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<inventoryDevice
  managementLevel="FULL"
  snmpType="v3"
  userName="entuity"
  authType="MD5"
  authPass="entuity123"
  encrType="DES"
  encrPass="entuity123"
/>'

OUTPUT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<inventoryDevice cliUsername="" zoneId="0" snmpPDUSize="0" snmpRetry="0" snmpTimeout="0" context="" encrType="DES" authType="MD5" userName="entuity" readCommunity="public" snmpType="v3" protocol="IPv4" certified="Yes" deviceType="Ethernet Switch" managementLevel="FULL" capabilities="Switch" sysLocation="Simulator" sysDescription="10/100 Mbps Ethernet Switch" sysOid=".1.3.6.1.4.1.2.3.50" managementIP="10.66.23.1" polledName="10.66.23.1" nameUsing="CUSTOM" dsObjectId="922" name="10.66.23.1" id="6" serverId="34564e92-3b4f-43ba-94a8-04309c0e48fe"/>

 

Changing the credentials of a Cisco UCS server device:

INPUT
curl -H -u admin:admin https://localhost/api/inventory/14?media=json -X PUT -H "content-type:application/json" -d \
'{
  "managementLevel" : "CLI",
  "polledName" : "CISCO UCS",
  "deviceType" : "Server",
  "hwConnMethod" : "ciscoucscimcsnmp",
  "hwConnPort" : "0",
  "hwCredentialId" : "6"
}'

OUTPUT
{
  "serverId": "{serverId}",
  "id": "11",
  "name": "CISCO UCS",
  "dsObjectId": 1629,
  "snmpTimeout": 0,
  "snmpRetry": 0,
  "snmpPDUSize": 0,
  "protocol": "IPv4",
  "snmpType": "None",
  "nameUsing": "POLLEDNAME",
  "certified": "",
  "polledName": "CISCO UCS",
  "managementIP": "xx.xx.xxx.xxx",
  "sysOid": "",
  "sysDescription": "",
  "sysLocation": "",
  "deviceType": "Server",
  "managementLevel": "CLI",
  "zoneId": 0,
  "snmpPort": 0,
  "snmpBulk": false,
  "hwConnMethod": "ciscoucscimcsnmp",
  "hwCredentialId": 9,
  "hwCredentialName": "snmpCreds2",
  "deviceName": "CISCO UCS",
  "configManagementLicense": false
}

 

 

DELETE Method - inventory/{deviceId}

Remove a device from the inventory.

Request:

The ID of the object that is to be deleted is sent as a part of a URL.

Response:

“OK” message if the device was removed successfully, an error message otherwise.

Examples:

INPUT
curl -u admin:admin https://localhost/api/inventory/2?media=json –X DELETE

OUTPUT
{
  "message": "OK"
}

 

INPUT
curl -u admin:admin https://localhost/api/inventory/2?media=xml –X DELETE

OUTPUT
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<statusInfo>
  <message>OK</message>
</statusInfo>

 

 

Note regarding backwards compatibility for adding a device using a local credential:

Note, for backwards compatibility, users can still add a device or devices using a local credential (via api/inventory POST or api/inventory/{deviceId} PUT), but the credential details of such devices are not accessible via GET calls. The applicable parameters are as follows:

  • authKey, authPass, authType.
  • encrKey, encrPass, encrType.
  • readCommunity, writeCommunity.
  • webAccessKey, webPassword, webPlatformType, webSecretKey, webTenantId, webUser.

Related articles

Comments

0 comments

Please sign in to leave a comment.