Table Of Contents

Device Group Management Functions

add_devices_to_group

create_device_group

delete_device_group

list_all_groups

remove_devices_from_group

rename_device_group

Device Group Management Functions

---

This chapter provides information about the following device group management functions:

•add_devices_to_group

•create_device_group

•delete_device_group

•list_all_groups

•remove_devices_from_group

•rename_device_group

add_devices_to_group

Synopsis

add_devices_to_group($token, [@dev_ids], $group) 

Description

This function adds devices to the specified device group. You can add devices to more than one group.

---

Note If you want to keep a device in a single group, you should remove the device from any other group by calling the remove_devices_from_group 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.
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 to be added to the group.
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.

Return

This function returns a Cisco::CLM::Common::IDStatus object. If the operation is successful, the IDStatus object contains an IDStatusItem array. Each IDStatusItem contains the ID of the device that is being added to the group. If the device is added successfully to the group, the error code in the IDStatusItem returns ClmErrors.SUCCESS.

Error and Exception

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

When an error occurs, this function returns false.

create_device_group

Synopsis

create_device_group($token, $group) 

Description

This function creates a new device group with the given name.

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	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The name of the group.

Return

This function returns a Cisco::CLM::Common::Status object. If the operation is successful, ClmErrors.SUCCESS is returned in the error code.

Error and Exception

When an error occurs, this function returns a Status object with the error code and error messages.

When an error occurs, this function returns false.

delete_device_group

Synopsis

delete_device_group($token, $group) 

Description

This function deletes a device group from the system. Devices under this group are not deleted, but they become ungrouped.

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	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::Status object. If the operation is successful, ClmErrors.SUCCESS is returned in the error code.

Error and Exception

When an error occurs, this function returns a Status object with the error code and error messages.

When an error occurs, this function returns false.

list_all_groups

Synopsis

list_all_groups($token) 

Description

This function returns a list of all device groups in the system.

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 representing the names of all device groups.

Error and Exception

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

When an error occurs, this function returns null.

remove_devices_from_group

Synopsis

remove_devices_from_group($token, [@dev_ids], $group)

Description

This function removes devices from the specified device group. The devices become ungrouped but remain in the device inventory. To delete the devices from the inventory, use the delete_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.
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 to be removed to the group.
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.

Return

This function returns a Cisco::CLM::Common::IDStatus object. If the operation is successful, the IDStatus object contains an IDStatusItem array. Each IDStatusItem contains the ID of the device that is being removed from the group. If the device is removed successfully from the group, the error code in the IDStatusItem returns ClmErrors.SUCCESS.

Error and Exception

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

When an error occurs, this function returns IDStatus with the error code and error message.

rename_device_group

Synopsis

rename_device_group($token, $group, $new_name)

Description

This function renames a given device group. All devices contained by the group remain unchanged.

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	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The current name of the device group.
new_name	String, mandatory	Name is a string containing up to 64 ASCII characters in the range from x21 to x7A	The new name for the device group.

Return

This function returns a Cisco::CLM::Common::Status object. If the operation is successful, ClmErrors.SUCCESS is returned in the error code.

Error and Exception

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

When an error occurs, this function returns Status with the error code and error message.