Playlists Endpoints (2017/01)

ON THIS PAGE

Use this endpoint to manage Dynamic Playlists on the network.

/playlists/dynamic/

GET

Retrieves a list of Dynamic Playlists on the network.

Parameters

marker: A value specifying which page to retrieve. This value is useful if the isTruncated entry in the response body of the previous GET call indicates that the number of DynamicPlaylist instances exceeds the pageSize.
pageSize: The maximum number of DynamicPlaylist instances that can be contained in the response body
filter: An expression for filtering search results.
sort: An expression for sorting the search results. The sort expression specifies the entry used for sorting and the ascending/descending (ASC/DESC) sorting order (e.g. "[dynamicPlaylist].[creationDate] ASC")

Response Body

[int] totalItemCount: The total number of DynamicPlaylist instances relevant to the query
[int] pageSize: The maximum number of DynamicPlaylist instances that can be returned in a single response
[bool] isTruncated: A flag indicating whether the totalItemCount exceeds the pageSize
[string] nextMarker: A value that can be included with a subsequent GET call to return additional results that have been truncated
[string] sortExpression: The sort expression specified in the URL
[string] filterExpression: The filter expression specified in the URL
[DynamicPlaylist[]]items: An array of DynamicPlaylist object instances. Each DynamicPlaylist instance can have the following entries:
- [int] id: A unique identifier for the DynamicPlaylist instance. This value is generated by the server when the Dynamic Playlist is created.
- [string] name: The name of the Dynamic Playlist
- [string] physicalPath: The location of the feed XML file in the server directory
- [int] fileSize: The size of the feed XML file (in bytes)
- [string] fileHash: The hash algorithm and the value that results from performing the hash algorithm on the file. The string is formatted as "{algorithm}:{value}" (e.g. "SHA1:6DB465879088280AAC52DC22B07ED0AD493A99D4").
- [string] creationDate: A UTC timestamp indicating when the Dynamic Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
- [bool] supportsAudio: A flag indicating whether the Dynamic Playlist supports audio files
- [bool] supportsVideo: A flag indicating whether the Dynamic Playlist supports video files
- [bool] supportsImages: A flag indicating whether the Dynamic Playlist supports image files
- [Content[]]content: An array of Content object instances representing content files in the Dynamic Playlist. The server currently returns a null value for this parameter.
- [Presentation[]]presentations: An array of Presentation object instances representing presentations that use the Dynamic Playlist. Each Presentation instance can have the following values:
  - [int] id: A unique identifier for the Presentation instance
  - [string] name: The presentation name
  - [string] type: The presentation type
- [Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

POST

Adds a new Dynamic Playlist to the network.

Request Body

[string] name: The name of the DynamicPlaylist
[bool] supportsAudio: A flag indicating whether the Dynamic Playlist supports audio files
[bool] supportsVideo: A flag indicating whether the Dynamic Playlist supports video files
[bool] supportsImages: A flag indicating whether the Dynamic Playlist supports image files
[Content[]]content: An array of Content object instances representing content files in the Dynamic Playlist

Response Body

[int] id: A unique identifier for the DynamicPlaylist instance. This value is generated by the server when the Dynamic Playlist is created.
[string] name: The name of the DynamicPlaylist
[string] physicalPath: The location of the feed XML file in the server directory
[int] fileSize: The size of the feed XML file (in bytes)
[string] fileHash: The hash algorithm and the value that results from performing the hash algorithm on the file. The string is formatted as "{algorithm}:{value}" (e.g. "SHA1:6DB465879088280AAC52DC22B07ED0AD493A99D4").
[string] creationDate: A UTC timestamp indicating when the Dynamic Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
[bool] supportsAudio: A flag indicating whether the Dynamic Playlist supports audio files
[bool] supportsVideo: A flag indicating whether the Dynamic Playlist supports video files
[bool] supportsImages: A flag indicating whether the Dynamic Playlist supports image files
[Content[]]content: An array of Content object instances representing content files in the Dynamic Playlist
[Presentation[]]presentations: An array of Presentation object instances representing presentations that use the Dynamic Playlist. Each Presentation instance can have the following values:
- [int] id: A unique identifier for the Presentation instance
- [string] name: The presentation name
- [string] type: The presentation type
[Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

/playlists/dynamic/count/

GET

Retrieves the number of Dynamic Playlists on the network that match the specified filter criteria. If no filter is included, this call returns the total number of Dynamic Playlists on the network.

Parameters

filter: An expression for filtering search results.

Response Body

The number of Dynamic Playlists is returned as an integer value.

/playlists/dynamic/operations/

GET

Returns Business Operations for Dynamic Playlists.

Response Body

[string] uid: A unique identifier for the DynamicPlaylist instance.
[string] singularName: The name of the operation in singular form. This value is useful for displaying in entity properties dialogs.
[string] pluralName: The name of the operation in plural form. This value is useful for displaying in User and Role properties dialogs.
[string] fullName: The name of the current operation along with its parent operations (if any). Since many operation names aren't unique, this value is useful for differentiating similar business operations.
[string] targetEntity: The object type affected by the operation (in this case, "DynamicPlaylist")
[Operation{}] parent: An Operation instance indicating the operation from which permissions are inherited. This value will be Null if there is no parent operation.
[Operations[]]descendants: An array of Operation instances that inherit permissions from this operation. This value is Null if there are no descendant operations.
[Permissions[] permissions: An array of Permission instances indicating permissions associated with this operation

/playlists/dynamic/{playlist_id||name}/

GET

Returns the DynamicPlaylist instance with the specified ID or name.

Response Body

[int] id: A unique identifier for the DynamicPlaylist instance. This value is generated by the server when the Dynamic Playlist is created.
[string] name: The name of the DynamicPlaylist
[string] physicalPath: The location of the feed XML file in the server directory
[int] fileSize: The size of the feed XML file (in bytes)
[string] fileHash: The hash algorithm and the value that results from performing the hash algorithm on the file. The string is formatted as "{algorithm}:{value}" (e.g. "SHA1:6DB465879088280AAC52DC22B07ED0AD493A99D4").
[string] creationDate: A UTC timestamp indicating when the Dynamic Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
[bool] supportsAudio: A flag indicating whether the Dynamic Playlist supports audio files
[bool] supportsVideo: A flag indicating whether the Dynamic Playlist supports video files
[bool] supportsImages: A flag indicating whether the Dynamic Playlist supports image files
[Content[]]content: An array of Content object instances representing content files in the Dynamic Playlist
[Presentation[]]presentations: An array of Presentation object instances representing presentations that use the Dynamic Playlist. Each Presentation instance can have the following values:
- [int] id: A unique identifier for the Presentation instance
- [string] name: The presentation name
- [string] type: The presentation type
[Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

PUT

Modifies the specified DynamicPlaylist instance using the entries in the request body.

Request Body

[string] name: The name of the DynamicPlaylist
[bool] supportsAudio: A flag indicating whether the Dynamic Playlist supports audio files
[bool] supportsVideo: A flag indicating whether the Dynamic Playlist supports video files
[bool] supportsImages: A flag indicating whether the Dynamic Playlist supports image files
[Content[]]content: An array of Content object instances representing content files in the Dynamic Playlist

Response Body

The server returns code 204 upon success.

DELETE

Removes the specified DynamicPlaylist instance from the network.

/playlists/tagged/

GET

Retrieves a list of Tagged Playlists on the network.

Parameters

marker: A value specifying which page to retrieve. This value is useful if the isTruncated entry in the response body of the previous GET call indicates that the number of TaggedPlaylist instances exceeds the pageSize.
pageSize: The maximum number of TaggedPlaylist instances that can be contained in the response body
filter: An expression for filtering search results.
sort: An expression for sorting the search results. The sort expression specifies the entry used for sorting and the ascending/descending (ASC/DESC) sorting order (e.g. "[taggedPlaylist].[creationDate] ASC")

Response Body

[int] totalItemCount: The total number of TaggedPlaylist instances relevant to the query
[int] pageSize: The maximum number of TaggedPlaylist instances that can be returned in a single response
[bool] isTruncated: A flag indicating whether the totalItemCount exceeds the pageSize
[string] nextMarker: A value that can be included with a subsequent GET call to return additional results that have been truncated
[string] sortExpression: The sort expression specified in the URL
[string] filterExpression: The filter expression specified in the URL
[TaggedPlaylist[]]items: An array of TaggedPlaylist object instances. Each TaggedPlaylist instance can have the following entries:
- [int] id: A unique identifier for the TaggedPlaylist instance. This value is generated by the server when the Tagged Playlist is created.
- [string] name: The name of the Tagged Playlist
- [string] physicalPath: The location of the file in the server directory
- [string] contentsVirtualPath: The virtual directory location of files in the Tagged Playlist. Tagged Playlists can only use files contained in this directory.
- [string] rule: A set of tagging conditions that determines tagged media to include in the playlist. The conditions list is formatted as follows: "<tag_name> condition tag_value [AND/OR] <tag_name> condition tag_value [...]". A complete list of accepted conditions can be found here. Note that values can have quotes around them (if string values) or not (if Boolean or integer values).
```
"rule": "<City> IS 'Los Gatos' OR <California> IS True"
```
- [bool] waitingForApprove: A flag that determines whether recent changes to media tags have been approved for the Tagged Playlist. By default, changing media tags will not automatically add or remove media from a Tagged Playlist. A user with the "Update Tagged Playlist" permission (Administrators, Creators, General Managers) will need to set this flag to false for changes to go into effect.
- [string] creationDate: A UTC timestamp indicating when the Tagged Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
- [Content[]]content: An array of Content object instances representing content files in the Tagged Playlist. The server currently returns a null value for this parameter.
- [Presentation[]]presentaitons: An array of Presentation object instances representing presentations that use the Tagged Playlist. Each Presentation instance can have the following values:
  - [int] id: A unique identifier for the Presentation instance
  - [string] name: The presentation name
  - [string] type: The presentation type
- [Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

Tip

A <tag_value> can be either a media tag, which has a value assigned by a user, or a media attribute, which is a system-determined value. Media attributes include the following: "ContentType", "FileLastModifiedDate", "FileName", "FileSize", and "UploadDate".

POST

Adds a new Tagged Playlist to the network.

Request Body

[string] name: The name of the tagged playlist
[string] rule: A set of tagging conditions that determines tagged media to include in the playlist. The conditions list is formatted as follows: "<tag_name> condition tag_value [AND/OR] <tag_name> condition tag_value [...]". A complete list of accepted conditions can be found here. Note that values can have quotes around them (if string values) or not (if Boolean or integer values).
```
"rule": "<City> IS 'Los Gatos' OR <California> IS True"
```
[string] ttl: The frequency with which players will query BSN servers to determine if there is any new tagged media to include/exclude in the Tagged Playlist. The time interval is specified as "hh:mm:ss".
[string] orderTag: The order of media files in the tagged playlist (ascending or descending). The order is formatted as follows: "<tag_name> [ASC/DESC]".
```
"<FileName> ASC"
```

Tip

A <tag_value> can be either a media tag, which has a value assigned by a user, or a media attribute, which is a system-determined value. Media attributes include the following: "ContentType", "FileLastModifiedDate", "FileName", "FileSize", and "UploadDate".

Response Body

[int] id: A unique identifier for the TaggedPlaylist instance. This value is generated by the server when the Tagged Playlist is created.
[string] name: The name of the tagged playlist
[string] physicalPath: The location of the file in the server directory
[string] contentsVirtualPath: The virtual directory location of files in the Tagged Playlist. Tagged Playlists can only use files contained in this directory.
[string] rule: A set of tagging conditions that determines tagged media to include in the playlist. The conditions list is formatted as follows: "<tag_name> condition tag_value [AND/OR] <tag_name> condition tag_value [...]". A complete list of accepted conditions can be found here. Note that values can have quotes around them (if string values) or not (if Boolean or integer values).
[string] ttl: The frequency with which players will query BSN servers to determine if there is any new tagged media to include/exclude in the Tagged Playlist. The time interval is specified as "hh:mm:ss"
[string] orderTag: The order of media files in the tagged playlist (ascending or descending). The order is formatted as follows: "<tag_name> [ASC/DESC]".
[bool] waitingForApprove: A flag that determines whether recent changes to media tags have been approved for the Tagged Playlist. This flag defaults to false when the Tagged Playlist is created.
[string] creationDate: A UTC timestamp indicating when the Tagged Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
[Content[]]content: An array of Content object instances representing content files in the Tagged Playlist:
- [int] contentId: A unique identifier for the Content instance
- [string] fileName: The name of the content file
- [string] displayDuration: The amount of time that an image will be displayed. This value is null for audio and video files.
- [bool] state: A flag that determines whether the content file has been approved for use in the Tagged Playlist. This value defaults to false for all Content instances when the Tagged Playlist is created. When subsequent changes to the rule of the Tagged Playlist populates new Content instances in the list, their state will default to true.
[Presentation[]]presentaitons: An array of Presentation object instances representing presentations that use the Tagged Playlist. This value will be null when the Tagged Playlist is created.
[Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

/playlists/tagged/count/

GET

Retrieves the number of Tagged Playlists on the network that match the specified filter criteria. If no filter is included, this call returns the total number of Tagged Playlists on the network.

Parameters

filter: An expression for filtering search results.

Response Body

The number of Tagged Playlists is returned as an integer value.

/playlists/tagged/operations/

GET

Returns Business Operations for Tagged Playlists.

Response Body

[string] uid: A unique identifier for the TaggedPlaylist instance.
[string] singularName: The name of the operation in singular form. This value is useful for displaying in entity properties dialogs.
[string] pluralName: The name of the operation in plural form. This value is useful for displaying in User and Role properties dialogs.
[string] fullName: The name of the current operation along with its parent operations (if any). Since many operation names aren't unique, this value is useful for differentiating similar business operations.
[string] targetEntity: The object type affected by the operation (in this case, "TaggedPlaylist")
[Operation{}] parent: An Operation instance indicating the operation from which permissions are inherited. This value will be Null if there is no parent operation.
[Operations[]]descendants: An array of Operation instances that inherit permissions from this operation. This value is Null if there are no descendant operations.
[Permissions[] permissions: An array of Permission instances indicating permissions associated with this operation

/playlists/tagged/{playlist_id||name}/

GET

Returns the TaggedPlaylist instance with the specified ID or name.

Response Body

[int] id: A unique identifier for the TaggedPlaylist instance. This value is generated by the server when the Tagged Playlist is created.
[string] name: The name of the tagged playlist
[string] physicalPath: The location of the file in the server directory
[string] contentsVirtualPath: The virtual directory location of files in the Tagged Playlist. Tagged Playlists can only use files contained in this directory.
[string] rule: A set of tagging conditions that determines tagged media to include in the playlist. The conditions list is formatted as follows: "<tag_name> condition tag_value [AND/OR] <tag_name> condition tag_value [...]". A complete list of accepted conditions can be found here. Note that values can have quotes around them (if string values) or not (if Boolean or integer values).
[string] ttl: The frequency with which players will query BSN servers to determine if there is any new tagged media to include/exclude in the Tagged Playlist. The time interval is specified as "hh:mm:ss"
[string] orderTag: The order of media files in the tagged playlist (ascending or descending). The order is formatted as follows: "<tag_name> [ASC/DESC]".
[bool] waitingForApprove: A flag that determines whether recent changes to media tags have been approved for the Tagged Playlist. By default, changing media tags will not automatically add or remove media from a Tagged Playlist. A user with the "Update Tagged Playlist" permission (Administrators, Creators, General Managers) will need to set this flag to false for changes to go into effect.
[string] creationDate: A UTC timestamp indicating when the Tagged Playlist was created on BSN. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.
[Content[]]content: An array of Content object instances representing content files in the Tagged Playlist:
- [int] contentId: A unique identifier for the Content instance
- [string] fileName: The name of the content file
- [string] displayDuration: The amount of time that an image will be displayed. This value is null for audio and video files.
- [bool] state: A flag that determines whether the content file has been approved for use in the Tagged Playlist. This value defaults to false for all Content instances when the Tagged Playlist is created. When subsequent changes to the rule of the Tagged Playlist populates new Content instances in the list, their state will default to true.
[Presentation[]]presentaitons: An array of Presentation object instances representing presentations that use the Tagged Playlist. Each Presentation instance can have the following values:
- [int] id: A unique identifier for the Presentation instance
- [string] name: The presentation name
- [string] type: The presentation type
[Permission[]]permissions: An array of Permission object instances representing permissions rules assigned to the playlist

PUT

Modifies the specified TaggedPlaylist instance using the entries in the request body.

Request Body

[string] name: The name of the tagged playlist
[string] rule: A set of tagging conditions that determines tagged media to include in the playlist. The conditions list is formatted as follows: "<tag_name> condition tag_value [AND/OR] <tag_name> condition tag_value [...]". A complete list of accepted conditions can be found here. Note that values can have quotes around them (if string values) or not (if Boolean or integer values).
```
"rule": "<City> IS 'Los Gatos' OR <California> IS True"
```
[string] ttl: The frequency with which players will query BSN servers to determine if there is any new tagged media to include/exclude in the Tagged Playlist. The time interval is specified as "hh:mm:ss"
[string] orderTag: The order of media files in the tagged playlist (ascending or descending). The order is formatted as follows: "<tag_name> [ASC/DESC]".
```
"<FileName> ASC"
```

Tip

A <tag_value> can be either a media tag, which has a value assigned by a user, or a media attribute, which is a system-determined value. Media attributes include the following: "ContentType", "FileLastModifiedDate", "FileName", "FileSize", and "UploadDate".

Response Body

The server returns code 204 upon success.

DELETE

Removes the specified DynamicPlaylist instance from the network.