Brightsign Network Web API Reference Manual v.3.8 User Manual

API REFERENCE MANUAL BrightSign Network Version 3.8 BrightSign, LLC. 16795 Lark Ave., Suite 200 Los Gatos, CA 95032 | 408-852-9263 | www.bright

Group ... 94 Group En

88 Required Permissions None Parameters • [DeviceModel] deviceModel: A DeviceModel enumeration indicating the model of BrightSign player to evaluat

89 Note that when using this method to check whether a Presentation instance can be deleted, a False status may change in the time between calling t

90 o The resolution in the ScreenSettings structure is not compatible with the specified device model (see the Output Resolutions FAQ for more deta

91 device model of a passed presentation entity. The instance must also have a Zones list property containing PresentationContent and DynamicPlaylis

92 Required Permissions Presentation: Update Presentation Parameters • [int] presentationId: The identifier and primary key of the Presentation ins

93 • [PresentationZone] entity: A PresentationZone structure with an initialized [int] Id and an updated set of properties, including a new Content

94 GROUP Group Entity The Group entity has the following properties: • [int] Id:(Read Only) The identifier and primary key of the Group instance. •

95 Group Management Web Methods • PagedList<Group> GetGroups(string marker, int pageSize) • List<Group> GetSpecifiedGroups(int[] group

96 List<Group> GetSpecifiedGroups(int[] presentationIds) Description Retrieves a list of Group instances matching the specified identifiers. T

97 not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to

Device Entity ...

98 Group CreateGroup(Group entity) Description Creates a new Group instance with the specified name and settings. If successful, this method will re

99 deletion is reserved (i.e. the default “Unassigned” Group instance) or if the [int] Id value is positive and does not correspond to an existing G

100 SCHEDULE ScheduledPresentation Entity-Relation The ScheduledPresentation entity-relation represents the relationship between a Presentation and

101 Note: A presentation scheduled for “all day, every day” can be created with the following property settings: StartTime as “00:00:00”, EndTime as

102 Parameters • [int] groupID: The identifier of the Group instance that is associated with the schedule. If a Group instance with the specified i

103 o The specified Group[int] Id or Group [string] Name does not correspond to an existing Group instance. o The [TimeSpan] StartTime value of th

104 the method will immediately return Null without an Error. A descriptive error will be returned if any of the following conditions occur: o The

105 Parameters • [int] groupId: The identifier of the Group instance to modify. If the Group [int] Id does not correspond to an existing Group inst

106 Required Permissions Schedule: Update Schedule, Remove Presentation – Presentation Unassign Presentation Parameters • [int] ScheduledPresentati

107 DEVICE Device Entity The Device entity has the following properties: • [int] Id:(Read Only) The identifier and primary key of the Device instan

PagedList<DeviceDownload> GetDeviceDownloads(int deviceId, string marker, int pageSize) ...

108 • [string] CardSize:(Read Only) The total size of the device storage. This information is displayed in the format “{0} MiB” or “{0:F2} GiB” (wh

109 • [DateTime] LastSyncSpecProcessedTime • [DateTime] LastContentDownloadStartTime:(Read Only) A UTC timestamp indicating when the device last b

110 • [int] AccountId:(Read Only) The identifier of the BrightSign Network account that owns the DeviceSubscription instance. • [int] DeviceId:(Re

111 • [DateTime] EndDate:(Read Only) A UTC timestamp that represents the end of the time range covered by the DeviceLogReport instance. • [DateTim

112 • Active: The normal operational status of a subscription. • Suspending: An intermediate status between “Active” and “Suspended”, indicating t

113 • [int] WiredConnection Priority: A number that defines the priority of a wired connection for the device. • [int] WirelessConnectionPriority:

114 • [string] SubnetMask: A user-defined IPv4 subnetwork mask for the device wireless connection. • [string] DefaultGateway: A user-defined IPv4

115 DeviceError Structure The DeviceError structure has the following values. • [DateTime] Timestamp:(Read Only) A UTC timestamp indicating the mos

116 • bool RenameDevice(int deviceId, string newName, string newDescription) • bool UpdateDeviceLogsSettings(int deviceId, DeviceLogsSettings sett

117 not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to

1 INTRODUCTION The BrightSign Network API exposes a large set of WebUI functionality using a standardized set of entities, methods, and properties.

118 • [int] pageSize: The maximum number of objects returned by the method. If the list of objects that match the search criteria exceeds the [int]

119 PagedList<DeviceError> GetDeviceErrors(int deviceId, string marker, int pageSize) Description Retrieves the next page of the DeviceError l

120 • [string] marker: The timestamp of the last DeviceDownload instance on the previous page. If the value is Null, then the method will retrieve

121 Required Permissions Device: Update Device Parameters • [int] DeviceId: The identifier and primary key of the Device instance to be updated. If

122 bool ForceDevicesReboot(int[] deviceIds) Description Enables the flags indicating that the specified device(s) should reboot during the next che

123 bool ForceDevicesRecovery(int[] deviceIds, bool reformat) Description Enables the flags indicating that the specified device(s) should download

124 an existing Device instance will also result in an error. Passing an empty array will lead to an immediate False response without an error. bool

125 Parameters • [int[]] deviceIds: An array of identifiers corresponding to the Device instance(s) that should be affected. The number of passed i

126 not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to

2 Methods The BSN Web API provides different methods to perform similar operations. It is possible, for example, to retrieve/update either all or a

3 Find{EntityName(s)} Methods of this type allow you to search for entities using a [string] Name pattern (including wildcards). This method type on

4 Specific Update Methods: e.g. UpdateGroupsAutorun These methods receive Entity IDs and one or more values for updating logically related propertie

5 Once you find such a tool/library for your platform, you will be able to create a service reference for the web service and work with it using fam

6 User Authentication Credentials Both BSN endpoints use simple username-password authentication; the username has the following format: {AccountNam

7 CONTENT Content Entity The Content entity has the following properties: • [int] Id:(Read only) The identifier and primary key of the Content enti

TABLE OF CONTENTS Introduction ...

8 ContentFolder Entity The ContentFolder entity has the following properties: • [int] Id:(Read only) The identifier and primary key of the ContentF

9 • WipeFromLeft • WipeFromRight • ExplodeFromCenter • ExplodeFromTopLeft • ExplodeFromTopRight • ExplodeFromBottomLeft • ExplodeFromBottomRi

10 • [DateTime] ValidityStartDate: A value that determines the validity start date for the associated content item (i.e. the point at which the con

11 • [ContentType] ContentType: A ContentType enumeration that allows a system to distinguish between a media file and a Dynamic Playlist. DynamicP

12 • bool DeleteContent(int[] contentIds) Note: Content update and creation operations can only be performed by the File Upload Service. PagedList&

13 Parameters • [string] virtualPath: The virtual path of the parent ContentFolder entity containing the requested subfolders. The root virtual pat

14 Parameters • [Int[]] contentIds: An array of [int] Id values for the Content instances being requested. The maximum number of items is limited t

15 Required Permissions Content: View Content Parameters • [int] contentId: The identifier and primary key of the associated Content instance. Cont

16 Required Permissions Content: Update Content Parameters • [int[]] contentIds: An array of [int] Id values for the Content and/or ContentFolder i

17 bool DeleteContent(int[] contentIds) Description Deletes the specified Content and ContentFolder instances, as well as any associated files, in b

ContentType Enumeration ...

18 CONTENT UPLOAD Overview Content Upload methods use a separate SOAP endpoint from all other Web API methods. To upload a file, the client must fir

19 a. Call StartFileUpload() using parameters for the asset file, as well as the session token and asset upload token from the WebPageUploadStatus

20 i. Call AppendChunk() for the number of times needed to complete the asset file upload. Use the session token and asset upload token from the We

21 ContentUploadStatus StartFileUpload(string uploadToken, string sessionToken, string filename, long filesize, int chunksCount, enum ContentType, d

22 • [enum: Auto, Image, Video, Audio, Webpage] contentType: The type of the content file. The default type is “Image”. • [DateTime] fileLastModif

23 Parameters • [string] uploadToken: The token of the upload that was initialized by the StartFileUpload() or StartWebPageUpload() method. A descr

24 o This string is empty. o The string has more than 128 characters. o The file name is not valid. • [long] filesize: The size of the video fil

25 WebPageUploadStatus StartWebPageUploadSession(array webpageAssets[], string uploadToken, string sessionToken, string filename, long filesize, int

26 o [string] virtualPath: The path in the BSN Library to which the file should be uploaded. If the path does not exist, it will be created. It mus

27 • [string] sha1Hash: The SHA1 hash of the webpage file. The server performs verification of the uploaded file using the specified hash. A descri

Web Page Update Work Flow ...

28 o [int] chunksCount: The number of chunks the file consists of (starting at 1). The optimal chunk size is 256KiB. Files that are larger than thi

29 • [enum: Auto, Image, Video, Audio, Webpage] contentType: The type of the content file, which should be specified as “Webpage”. • [string] virt

30 Required Permissions None Parameters [string] sessionToken: The token of the upload session initialized by the StartFileUpload() method. If the s

31 DYNAMIC PLAYLIST ImageVideoDynamicPlaylist Entity The ImageVideoDynamicPlaylist entity represents a Dynamic Playlist containing image or video fi

32 • [string] PhysicalPath:(Read Only) The external URL of the Dynamic Playlist MRSS file in persistent storage. • [long] FileSize:(Read Only) The

33 • bool CheckDynamicPlaylistUsageByName(string name) • DynamicPlaylist CreateDynamicPlaylist(DynamicPlaylist entity) • bool UpdateDynamicPlayli

34 PagedList<ImageVideoDynamicPlaylist> GetImageVideoDynamicPlaylists(string marker, int pageSize) Description Retrieves the next page of the

35 Parameters • [string] marker: The [string] Name of the last AudioDynamicPlaylist instance on the previous page. If the value is Null, then the m

36 method retrieves both ImageVideoDynamicPlaylist and AudioDynamicPlaylist instances; these instances can be differentiated by data type. Required

37 Parameters • [string] namePattern: The exact [string] Name of the ImageVideoDynamicPlaylist instance (or its wildcard-based pattern). Supported

PagedList<AudioDynamicPlaylist> GetAudioDynamicPlaylists(string marker, int pageSize) ...

38 truncated. If the integer is not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects

39 • [bool] loadContent: A flag that specifies whether the method should also initialize and return a list of all Content instances in use by the r

40 Required Permissions Dynamic Playlist: View Dynamic Playlists Parameters • [int] dynamicPlaylistId: The identifier and primary key of the ImageV

41 Required Permissions Dynamic Playlist: Create Dynamic Playlist – Content: Assign Content Parameters • [DynamicPlaylist] entity: An ImageVideoDyn

42 o The passed string is more than 50 characters. o The passed string does not match a preexisting Dynamic Playlist. o The [int] DisplayDuration

43 Parameters • [int[]] dynamicPlaylistIds: An array of [int] Id values for the instances to be deleted. The number of items that can be deleted is

44 LIVE TEXT FEED LiveTextFeed Entity The LiveTextFeed entity has the following properties: • [int] Id:(Read Only) The identifier and primary key o

45 • [DateTime] ValidityEndDate: A value that determines the validity end date for the associated item (i.e. the point at which the item will no lo

46 Parameters • [string] marker: The [string] Name of the last LiveTextFeed instance on the previous page. If the value is Null, then the method wi

47 Required Permissions Live Text Feed: View Live Text Feeds Parameters • [string] namePattern: The exact [string] Name of the LiveTextFeed instanc

List<LiveTextFeed> GetSpecifiedLiveTextFeeds(int[] liveTextFeedIds) ...

48 LiveTextFeed GetLiveTextFeedByName(string name, bool loadContent) Description Retrieves the LiveTextFeed instance with the specified [string] Nam

49 bool CheckLiveTextFeedUsage(int liveTextFeedId) Description Determines whether the LiveTextFeed instance (specified by its primary key) is refere

50 LiveTextFeed CreateLiveTextFeed(LiveTextFeed entity) Description Creates a new LiveTextFeed instance and related RSS file with the specified [str

51 Parameters • [string] feedUrl: An external URL of a publicly available RSS feed. The RSS Title will be used as the LiveTextFeed instance name an

52 bool RenameLiveTextFeed(int liveTextFeedId, string newName) Description Updates the [string] Name of the specified LiveTextFeed instance. This me

53 LIVE MEDIA FEED LiveMediaFeed Entity The LiveMediaFeed entity has the following properties: • [int] Id:(Read Only) The identifier and primary ke

54 • [string] Description: The value (i.e. MRSS item description) of the associated media item in the related Live Media Feed. • [TimeSpan] Displa

55 PagedList<LiveMediaFeed> GetLiveMediaFeeds(string marker, int pageSize) Description Retrieves the next page of the LiveMediaFeed list, sort

56 PagedList<LiveMediaFeed> FindLiveMediaFeeds(string namePattern, string marker, int pageSize) Description Retrieves the next page of a LiveM

57 • [bool] loadAssets: A flag specifying whether the method should also initialize and return a list of all content files currently being used by

LiveMediaFeed GetLiveMediaFeed(int liveMediaFeedId, bool loadContent) ...

58 Parameters • [string] name: The Live Media Feed [string] Name value to be evaluated. LiveMediaFeed CreateLiveMediaFeed(LiveMediaFeed entity) Des

59 o One or more custom field names contain a string that is reserved for the MRSS feed: "title", "description", "link&quo

60 bool RenameLiveMediaFeed(int liveMediaFeedId, string newName) Description Updates the [string] Name of the specified LiveMediaFeed instance. This

61 o An empty array is passed to the server.

62 WEB PAGE WebPage Entity The WebPage entity has the following properties: • [int] Id:(Read Only) The identifier and primary key of the WebPage in

63 • [long] FileSize:(Read Only) The size (in bytes) of the associated asset file. PresentationContent Entity-Relation The PresentationContent enti

64 PagedList<WebPage> GetWebPages(string marker, int pageSize) Description Retrieves the next page of the WebPage list, sorted by [string] Nam

65 PagedList<WebPage> FindWebPages(string namePattern, string marker, int pageSize) Description Retrieves the next page of a WebPage list cont

66 • [bool] loadAssets: A flag specifying whether the method should also initialize and return a list of all assets currently being used by the Web

67 Parameters • [string] name: The Web Page Name value to be evaluated. bool CheckWebPageUsage(int liveTextFeedId) Description Determines whether t

bool CheckWebPageUsageByName(string name) ...

68 Parameters • [string] name: The user-defined name of the WebPage instance to evaluate. If a WebPage instance with the specified [string] Name do

69 cause an error. Passing Web Page identifiers that don’t exist will also result in an error return. Passing an empty array will lead to an immedia

70 DEVICE WEB PAGE DeviceWebPage Entity The DeviceWebPage entity has the following properties: • [int] Id:(Read Only) The identifier and primary ke

71 • bool CheckDeviceWebPageUsage(int deviceWebPageId) • bool CheckDeviceWebPageUsageByName(string name) • bool RenameDeviceWebPage(int deviceWeb

72 Parameters • [int[]] deviceWebPageIds: An array of [int] Id values for the DeviceWebPage instances being requested. The number of items is limit

73 Required Permissions Web Page: View Web Pages Parameters • [int] deviceWebPageId: The identifier and primary key of the DeviceWebPage instance t

74 Required Permissions None Parameters • [string] name: The Device Web Page Name value to be evaluated. bool CheckDeviceWebPageUsage(int liveTextF

75 Required Permissions None Parameters • [string] name: The user-defined name of the DeviceWebPage instance to evaluate. If a DeviceWebPage instan

76 Parameters • [int[]] deviceWebPageIds: An array of [int] Id values for the DeviceWebPage instances to be deleted. The number of items is limited

77 PRESENTATION Presentation Entity The Presentation entities has the following properties: • [int] Id:(Read Only) The identifier and primary key o

PresentationLanguage Enumeration ...

78 DeviceModel Enumeration The DeviceModel enumeration can contain the following values: • Unknown: This value is used by the server for presentati

79 Note: This enumeration is set to Null for presentations created in BrightAuthor. o 1920x1080x60p o 1920x1080x59.94p o 1920x1080x50p o 1920x10

80 o 800x600x60p o 720x576x50p o 720x480x60p o 720x480x59.94p o 640x480x60p o SECAM o NTSC-COMPONENT o PAL-COMPONENT o NTSC-M o NTSC-M-JPN

81 o OverscanActionSafeArea o OverscanTitleSafeArea PresentationZone Structure The PresentationZone structure has the following properties: • [in

82 • [AnalogOutputMode] AnalogOutput: An AnalogOutputMode enumeration, which can contain the following values: o None o PCM • [HDMIOutputMode] H

83 o None o PCM o PassThrough • [SPDIFOutputMode] SPDIFOutput: A SPDIFOutputMode enumeration, which can contain the following values: o None o

84 • ScreenResolution[] GetSupportedScreenResolutions(DeviceModel deviceModel, ConnectorType connectorType) • bool CheckPresentationName(string na

85 not positive, then the method will return the maximum allowed number of objects. Attempting to request more objects than is allowed will lead to

86 Note: This method will not be able to initialize the DeviceModel enumeration, PresentationLanguage enumeration, or ScreenSettings structure if a

87 Parameters • [int] presentationId: The identifier and primary key of the Presentation instance to be retrieved. • [bool] loadContent: A flag sp