Table Of Contents

Device Management Functions

create_devices_by_ip_addr

create_devices_by_udi

delete_devices

discover_devices

list_all_devices_in_group

list_all_groups_by_device

list_device_ids_by_filter

poll_device_license_info

re_create_devices

read_devices

write_devices

Device Management Functions

---

This chapter provides information about the following device management functions:

•create_devices_by_ip_addr

•create_devices_by_udi

•delete_devices

•discover_devices

•list_all_devices_in_group

•list_all_groups_by_device

•list_device_ids_by_filter

•poll_device_license_info

•re_create_devices

•read_devices

•write_devices

create_devices_by_ip_addr

Synopsis

create_devices_by_ip_addr($token, [@ips],$group,[@dev_auth_info], [@transports]) 

Description

This function creates device objects in the inventory using a given IP address and associates devices with the specified group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
ips	Array of string, mandatory	IP address	An array of IP addresses. Each address is used for creating a device object.
group	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the group.
dev_auth_info	Array of DeviceAuthentication, mandatory	—	An array of DeviceAuthentication to be used when communicating with discovered devices to get license information Each entry in the array is used to the mapping IP address in the IP array. DeviceAuthentication contains username, password, and enable password.
transports	Cisco::CLM::Common::Device::TransportMethod array, mandatory	HTTP, Telnet, ssh	This parameter specifies which connection transport method is used for each IP entry. Cisco License Manager assumes the caller knows the connection method used for each device.

Return

This function returns a Cisco::CLM::Common::DeviceStatus object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

create_devices_by_udi

Synopsis

create_devices_by_udi($token, [@udis],[$group]) 

create_devices_by_udi($token, [@udis])

Description

This function creates device objects in the inventory using a given unique device identifier (UDI).

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
udis	Array of string, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	An array of UDIs. Each UDI is used for creating a device object.
group	String, optional	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the device group.

Return

This function returns a Cisco::CLM::Common::DeviceStatus object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

delete_devices

Synopsis

delete_devices($token, [@dev_ids]) 

Description

This function deletes device objects from the inventory using the given device IDs. If a device that is being deleted belongs to a group, it is removed from the group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns Cisco::CLM::Common::IDSTATUS object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.

discover_devices

Synopsis

discover_devices ($token, $subnet, $subnet_mask, $group, $dev_auth_info, [@transports]) 

Description

This function generates an inventory of devices that are discovered in the given subnet and adds the devices to the specified device group.

The Cisco License Manager currently supports Cisco IOS Telnet and secure shell (ssh) for non-agent-enabled device discovery, thus prolonging the discovery time. If the network devices are configured the same way, you can provide the transport method (such as HTTP, Telnet, or ssh), which speeds up the discovery and reduces the discovery process time. If a null or empty string array is passed in, Cisco License Manager uses all supported methods to discover the devices.

This function blocks until the call completes. It returns a Cisco::CLM::Common::IDStatus object containing the staus of the operation.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
subnet	String, mandatory	Network address	The subnet to conduct the auto-discovery.
subnet_mask	String, mandatory	—	The subnet mask.
group	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The group to which the discovered devices should be added.
dev_auth_info	DiscoveryAuthInfo, mandatory	—	A DiscoveryAuthInfo is used when communicating with discovered devices to retrieve license information. If no authentication is needed for the devices in the network, this parameter can be set to null. DiscoveryAuthInfo contains an array of username and password pairs and an array of enable passwords. When Cisco License Manager tries to communicate with the device, the instances of DiscoveryAuthInfo are tried one at a time until they can be authenticated by the device. If Telnet is used, there are only three tries.
transport	TransportMethod array, mandatory	HTTP, Telnet, ssh	If the devices in a subnet are set up with the same device discovery method, the device discovery process is speeded up because Cisco License Manager uses only the specified method to quickly determine if the device license is supported. This parameter specifies which connection transport is used. Cisco License Manager uses the specified transports by entry order. If null or zero length is entered, Cisco License Manager uses all available methods to discover the device.

Return

This function returns a request ID to the caller.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

list_all_devices_in_group

Synopsis

list_all_devices_in_group ($token, $group)

Description

This function returns an array of device IDs that belong to the given device group. If the group is null, this function returns an array of device IDs that do not belong to any device group.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
group	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The name of the device group, or null if the function is looking for ungrouped devices.

Return

This function returns an array of device IDs if the group is valid. Otherwise, if the group is invalid or empty, an array of size zero is returned.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

list_all_groups_by_device

Synopsis

list_all_groups_by_device ($token, $dev_id) 

Description

This function returns an array of groups to which the given device belongs.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_id	String, mandatory	Up to 64 ASCII characters in the range from x21 to x7A	The device ID.

Return

This function returns an array of groups if the device is valid. If the device is invalid or belongs to no group, a size zero is returned.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null.

list_device_ids_by_filter

Synopsis

list_device_ids_by_filter($token, $device_type, $device_model, [@features]) 

Description

This function returns a list of device IDs that contains the device_type, device_model, and license feature.

Each filter can be set to null for no filtering. If all the filters are set to null, the operation is treated as an error and null will be returned.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
device_type	String, optional	—	String that represents device type.
device_model	String, optional	—	String that represents device model.
features	Array of string, optional	—	Array of string that represent the license feature names.

Return

This function returns an array of string. Each string is a device ID.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs, this function returns null. An array length of zero means that no device is found.

poll_device_license_info

Synopsis

poll_device_license_info ($token, [@dev_ids]) 

Description

This function communicates with the given devices, retrieving license information from them and storing the information in the inventory.

This function blocks until the call completes. It returns a Cisco::CLM::Common::IDStatus object containing the status of the operation.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns a request ID to the caller.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

re_create_devices

Synopsis

re_create_devices ($token,[@devs],$group, [@dev_auth_info], [@transports]) 

Description

This function recreates device objects in the inventory due to an authentication or transport method change. It reconnects to the device and updates the device access information.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
devs	Array of Device, mandatory	Device objects	An array of device objects that already exist in the inventory. If the device object does not exist in the inventory, it is created and placed in the inventory.
group	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the device group.
dev_auth_info	Array of DeviceAuthentication, mandatory	—	An array of DeviceAuthentication to be used when communicating with discovered devices to get license information Each entry in the array is used to the mapping IP address in the IP array. DeviceAuthentication contains username, password and enable password.
transports	Cisco::CLM::Common::Device::TransportMethod array, mandatory	HTTP, Telnet, ssh	This parameter specifies which connection transport method is used for each IP entry. CLM assumes the caller knows the connection method used for each device.

Return

This function returns a Cisco::CLM::Common::DeviceStatus object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

read_devices

Synopsis

read_devices ($token, [@dev_ids])

Description

This function uses the given device ID to retrieve an array of device objects from the inventory.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
dev_ids	Array of string, mandatory	ID is a string containing up to 64 ASCII characters in the range from x21 to x7A	An array of device IDs.

Return

This function returns a Cisco::CLM::Common::DeviceStatus object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an operation error occurs, a DeviceStatus object is returned with information about the error. To inspect the individual element status, you must traverse the DeviceStatusItem array within DeviceStatus. Each DeviceStatusItem contains the Device object, the error code, and the error message.

write_devices

Synopsis

write_devices ($token, [@devices]) 

Description

This function writes the given device objects into the inventory. The input device objects can be new instances of devices returned by the create_devices function or existing ones retrieved from the inventory by the read_devices function.

Input Parameters

Parameter	Type	Value	Description
token	UserToken, mandatory	—	A token that represents your authorization pass, which is obtained after you invoke the login function and are authenticated by the back-end server.
devices	Array of device, mandatory	—	An array of device objects, which can be new instances of a device class or existing ones retrieved from the inventory by the readDevice() function.

Return

This function returns a Cisco::CLM::Common::IDStatus object.

Error and Exception

If a system error prevents the operation from completing, a RemoteException is thrown.

When an error occurs on an element in the input array, a status object is returned with information about the error.