Table Of Contents

Device Management Functions

create_device_by_ip_addr

delete_devices

discover_devices

get_discovery_transports

get_transport_method_by_device_platform

list_all_devices_in_group

list_all_groups_by_device

list_applicable_devices_by_sku

list_device_ids_by_filter

poll_device_license_info

read_devices

write_devices

Device Management Functions

---

This chapter provides information about the following device management functions:

•create_device_by_ip_addr

•delete_devices

•discover_devices

•get_discovery_transports

•get_transport_method_by_device_platform

•list_all_devices_in_group

•list_all_groups_by_device

•list_applicable_devices_by_sku

•list_device_ids_by_filter

•poll_device_license_info

•read_devices

•write_devices

create_device_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	Cisco::CLM::Common::DiscoveryAuthInfomandatory	—	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, HTTPS, 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.

The following example shows error codes and messages from DeviceStatus object:

# The general error code of the operation.

my $err_code = $device_status->get_error_code;

# The general error message of the operation.

my $err_msg = = $device_status->get_error_message;

# A list of status for each individual element in the

# bulk operation.

my $device_status_items = $id_status->get_device_status_items;

# Iterate through the list to get individual status.

foreach my $k (@{$device_status_items}){

# Get the individual Device object returned by the operation.

my $device = $k->get_device;

#Get the individual error code corresponding to

# the Device

my $item_err_code = $k->get_error_code;

# Get the individual error message corresponding to

# the Device.

my $item_err_msg = $k->get_error_message;

}

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, HTTPS, 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.

get_discovery_transports

Synopsis

get_discovery_transports ($token) 

Description

This function returns an array of Cisco::CLM::Common::Device::Transport Method set by admin user doing Discovery. Only user with ADMIN privilege can run this API.

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.

Return

This function returns an array of transport methods (Cisco::CLM::Common::Device::TransportMethod) available for the specified platform.

Error and Exception

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

get_transport_method_by_device_platform

Synopsis

get_transport_method_by_device_platform ($token, $platform)

Description

This function returns an array of Transport Methods available for the specified platform.

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.
platform	Cisco::CLM::Common::Device::DevicePlatform mandatory	CSL, WNBU, URLF, CISCO12K, IPS, UNKNOWN	The name of the platform can be CSL, WNBU, URLF, CISCO12K, IPS, or UNKNOWN.

Return

This function returns an array of transport methods (Cisco::CLM::Common::Device::TransportMethod) available for the specified platform.

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_applicable_devices_by_sku

Synopsis

list_applicable_devices_by_sku ($token, $sku, $group) 

Description

This function returns an array of device objects that are applicable for the given SKU.

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.
sku	SKU, mandatory	—	The SKU object.
group	String	—	Group name.

Return

The function returns an array of Cisco::CLM::Common::Device matching the platforms of a SKU in a given group. If group argument is null, matching devices in all groups will be returned.

Error and Exception

If sku is null, this API returns null. If platform in SKU is null or UNKNOWN, or no Device matches the SKU platform, this API returns an array of zero length.

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

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.

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.