Group APIs
14 min
Group Entity
The Group entity has the following properties:
- Id int:(read only) The identifier and primary key of the Group instance.
- Name string: The user-defined name of the Group instance. This is an alternate key and must be unique within the scope of the account.
- CreationDate DateTime:(read only) A UTC timestamp indicating when the Group instance was created within the BrightSign Network.
- MinAutorunVersion string: (read only) The minimum version of device autorun required to play presentations scheduled for the Group instance.
- HD9XXFirmware string: The minimum version of device firmware required to play presentations for the HD970 model.
- HDx10Firmware string: The minimum version of device firmware required to play presentations for the following player models: HD210w, HD1010, HD1010w.
- HDx20Firmware string: The minimum version of device firmware required to play presentations for the following player models: AU320, HD220, HD1020, LS322, LS422.
- HDx22Firmware string: The minimum version of device firmware required to play presentations for the following player models: HD222, HD1022.
- XDx30Firmware string: The minimum version of device firmware required to play presentations for the following player models: XD230, XD1030, XD1230.
- XDx32Firmware string: The minimum version of device firmware required to play presentations for the following player models: XD232, XD1032, XD1132.
- 4Kx42Firmware string: The minimum version of device firmware required to play presentations for the following player models: 4K242, 4K1042, 4K1142.
- EnableSerialDebugging bool: A flag specifying whether serial debugging should be enabled for all players assigned to the Group instance.
- EnableSystemLogDebugging bool: A flag specifying whether system log debugging should be enabled for all players assigned to the Group instance.
- DevicesCount int:(read only) An integer indicating the number of players assigned to the Group instance.
- EnableStorageSpaceLimit bool: A flag specifying whether the player storage will be divided into different segments. This allows the user to allot maximum sizes to different segments to ensure that a certain type of data does not take up too much space on the storage device.
- StorageSpaceLimitUnits StorageSpaceLimitUnit: A StorageSpaceLimitUnit enumeration specifying whether the following limits are measured in percentages or megabytes.
- PublishedDataSizeLimit ushort: The maximum size allotted to all presentation and content files that are written to the storage device during the publish process. This includes audio, video, images, text, and HTML content files.
- DynamicDataSizeLimit ushort: The maximum size of all dynamic content, including Dynamic Playlists and MRSS feeds. When this segment runs out of space, dynamic content files will be deleted to create space, starting with the oldest files first.
- HtmlDataSizeLimit ushort: The maximum size of the HTML application cache.
- HtmlLocalStorageSizeLimit ushort: The maximum size of all JavaScript variables and data.
- Devices List:(read only) A list of Device entities that are assigned to the current group.
- Presentations PresentationInfo[]:(read only) An array of PresentationInfo structures denoting presentations that are currently scheduled for the Group instance.
StorageSpaceLimitUnit Enumeration
The StorageSpaceLimitUnit enumeration has the following values:
- Percentage
- Megabyte
Group Management Web Methods
PagedList<Group> GetGroups(string marker, int pageSize)
Retrieves the next page of the Group list, sorted by Name string. The returned list will contain no more items than the defined page size.
Required Permissions
Group: View Groups
Parameters
- marker string: The Name string of the last Group instance on the previous page. If the value is Null, then the method will retrieve the first page.
- pageSize int: The maximum number of objects returned by the method. If the list of objects that match the search criteria exceeds the pageSize int limit, the returned list will indicate that it is truncated. If the integer is not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to the same result, but without an error.
List<Group> GetSpecifiedGroups(int[] presentationIds)
Description
Retrieves a list of Group instances matching the specified identifiers. The list is sorted by the [string] Name of the Group instances. The identifiers of nonexistent Group instances will be ignored.
Required Permissions
Group: View Groups
Parameters
- groupIds int[]: An array of Id int values for the Group instances being requested. The number of returned items is limited to 100 by the server. Attempting to request more than the maximum allowed number of objects will cause an error, while passing an empty array will lead to an immediate empty response without an error.
PagedList<Group> FindGroups(string namePattern, string marker, int pageSize)
Retrieves the next page of a Group list containing names matched with the specified pattern. The returned list is organized by [string] Name and may not contain more items than the defined page size.
Required Permissions
Presentation: View Presentations
Parameters
- namePattern string: The exact Name string of the Group instance (or its wildcard-based pattern). Supported wildcards currently include “*”, “?”, and “[‘and’]”.
- marker string: The Name string of the last Group instance on the previous page. If the value is Null, then the method will retrieve the first page.
- pageSize int: The maximum number of objects returned by the method. If the list of objects that match the search criteria exceeds the pageSize int limit, the returned list will indicate that it is truncated. If the integer is not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to the same result, but without an error.
Group GetGroup (int groupId, bool loadDevices)
Retrieves a single Group instance with the specified Id int. This method returns Null if he Group instance with the specified identifier does not exist.
Required Permissions
Group: View Groups
Parameters
- groupId int: The identifier and primary key of the Group instance to be retrieved.
- loadDevices bool: A flag specifying whether the method should also initialize and return a list of all Device instances that are assigned to the specified Group.
Group GetGroupByName(string name, bool loadContent)
Retrieves the Group instance with the specified [string] Name. This method returns Null if the Group instance with the specified name does not exist.
Required Permissions
Group: View Groups
Parameters
- name string: The user-defined Name of the Group instance to be retrieved.
- loadDevices bool: A flag specifying whether the method should also initialize and return a list of all Device instances that are assigned to the specified Group.
Group CreateGroup(Group entity)
Creates a new Group instance with the specified name and settings. If successful, this method will return a Group instance with all initialized properties. If an error occurs, the method will return Null.
Required Permissions
Group: Create Group
Parameters
- entity Group: A Group object instance with an initialized name, device autorun version, firmware versions, and debugging settings. Other property values will be ignored. If this parameter is set to Null, the method will immediately return False without an error. A descriptive error will be returned if any of the following conditions occur:
- The length of the specified Group Name string is greater than 50 characters.
- The specified Group Name string is already in use by another Group instance within the account.
- Creating the Group instance will cause the total number of Group instances to exceed the limit set on the server.
bool UpdateGroup(Group entity)
Updates the specified Group instance using the values passed in the Group entity. This method returns True only if completely successful; otherwise, it will return False.
Required Permissions
Group: Update Group
Parameters
- entity BrightWallGroup: A Group object instance specifying the Id int of the Group instance to update, as well as other new properties for the updated instance: HD9XXFirmware string, HDX10Firmware string, HDX20Firmware string, HDX22Firmware string, XDX30Firmware string, XDX32Firmware string, 4KX42Firmware string, EnableSerialDebugging bool, EnableSystemLogDebugging bool, StorageSpaceLimitUnits StorageSpaceLimitUnit, PublishedDataSizeLimit ushort,DynamicDataSizeLimit ushort, HtmlDataSizeLimit ushort, and HtmlLocalStorageSizeLimit ushort. If this parameter is Null or Invalid, the method will immediately return Null without an error. A descriptive error will be returned if any of the following conditions occur.
- The specified Id int does not correspond to an existing Group instance.
- The Name string of the Group entity does not correspond to the original instance (i.e. Group instances cannot be renamed using this method).
- The sum of the PublishedDataSizeLimit ushort, DynamicDataSizeLimit ushort, HtmlDataSizeLimit ushort, and HtmlLocalStorageSizeLimit ushort values does not equal 100 when the StorageSpaceLimitUnits enumeration is set to Percentage.
- One of the specified model firmware versions is invalid or not supported. A firmware version value can be set to Null or left empty without error.
bool UpdateGroupsFirmware(int[] groupIds, string hd9xxFirmware, string hdx10Firmware, string hdx20Firmware, string hdx22Firmware, string xdx30Firmware, string xdx32Firmware, string 4kx42Firmware)
Updates one or more model firmware versions for devices associated with the specified Group instances. This method returns True upon success and False upon failure.
Required Parameters
Group: Update Group, Update Firmware
Parameters
- groupIds int[]: An array of Id int values specifying the Group instances to be updated. The maximum number of items is limited to 100 by the server. Attempting to request more than the maximum allowed number of objects will cause an error, while passing an empty array will lead to an immediate empty response without an error.
- hdx10Firmware string: A new value for the HDX10Firmware string property of the specified Group instance(s).
- hdx20Firmware string: A new value for the HDX20Firmware string property of the specified Group instance(s).
- hdx22Firmware string: A new value for the HDX22Firmware string property of the specified Group instance(s).
- xdx30Firmware string: A new value for the XDX30Firmware string property of the specified Group instance(s).
- xdx32Firmware string: A new value for the XDX32Firmware string property of the specified Group instance(s).
- 4kx42Firmware string: A new value for the 4KX42Firmware string property of the specified Group instance(s).
A descriptive error will be returned if any of the following conditions occur:
- One or more of the Id int values does not correspond to an existing Group instance.
- One of the specified firmware versions is invalid or not supported. A firmware version value can be set to Null or left empty without error.
bool DeleteGroup(int groupId, int reassignmentGroupId)
Deletes the specified Group instance and assigns all devices within it to another specified Group instance. This method only returns True if completely successful. Otherwise, it returns False.
Required Parameters
Group: Delete Group, Remove Device – Device: Change Target Group
Parameters
- groupId int: The identifier of the Group instance to be deleted. If the Id int value is negative, the method will immediately return False without an error. A descriptive error will be returned if the Group specified for deletion is reserved (i.e. the default “Unassigned” Group instance) or if the Id int value is positive and does not correspond to an existing Group instance.
- reassignmentGroupId int: The identifier of the Group instance to which affected devices should be reassigned. If this value is negative, the devices will be reassigned to the default “Unassigned” Group instance. If a Group instance with the specified positive Id int does not exist, the method will return a descriptive error.