Table Of Contents

Device Group Management Functions

addDevicesToGroup

createDeviceGroup

deleteDeviceGroup

listAllGroups

removeDevicesFromGroup

renameDeviceGroup

Device Group Management Functions

---

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

•addDevicesToGroup

•createDeviceGroup

•deleteDeviceGroup

•listAllGroups

•removeDevicesFromGroup

•renameDeviceGroup

addDevicesToGroup

Synopsis

IDStatus addDevicesToGroup(UserToken token, String[] dev_ids, String group) throws 
RemoteException; 

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 removeDevicesFromGroup() 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 an IDStatus object. If the operation is successful, ClmErrors.SUCCESS is returned in the error code and the IDStatus object contains IDStatusItem[]. 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 the IDStatus object with the error code and error message.

createDeviceGroup

Synopsis

Status createDeviceGroup(UserToken token, String group) throws RemoteException;

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 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 the IDStatus object with the error code and error message.

deleteDeviceGroup

Synopsis

Status deleteDeviceGroup(UserToken token, String group) throws RemoteException;

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 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 the IDStatus object with the error code and error message.

listAllGroups

Synopsis

String[] listAllGroups(UserToken token) throws RemoteException;

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 name of the device group.

Error and Exception

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

When an error occurs, this function returns null.

removeDevicesFromGroup

Synopsis

IDStatus removeDevicesFromGroup(UserToken token, String[] dev_ids, String group) throws 
RemoteException;

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 deleteDevices() 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 an IDStatus object. If the operation is successful, ClmErrors.SUCCESS is returned in the error code, and the IDStatus object contains IDStatusItem[]. 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 the IDStatus object with the error code and error message.

renameDeviceGroup

Synopsis

Status renameDeviceGroup(UserToken token, String group, String new_name) throws 
RemoteException;

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 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 the IDStatus object with the error code and error message.