SOAP API

The BrightSign Network SOAP API exposes a large set of BSN functionality using a standardized set of entities, methods, and properties. Developers can use this API to build new interfaces that have a different look and feel from, but provide a similar feature set to, the BrightSign Network WebUI.

Entities

Identifiers

Each entity has a unique ID consisting of an incremental integer value that functions as its Primary Key. This allows for simple identification and retrieval of a particular object instance. This value is usually not revealed to end users of the UI because it is only useful for internal client/server operations.

Some entities also have Alternate Keys (the [string] Name property, for example) because the system often requires the uniqueness of an entity within a BSN account. You can retrieve an entity using any of its keys, whether primary or alternate.

Dependency

Almost all entities have “parent” and “child” entities contained within a dependency tree: For example, a Dynamic Playlist entity includes Content entities on one hand, but is referenced by Presentation entities on the other. In this case, each Content entity is the “child” of the Dynamic Playlist entity, while each Presentation entity functions as the “parent” of the Dynamic Playlist entity.

If a particular object instance has one or more parent objects, then it is considered “in use”. In most cases, this status will affect the operations that can be performed with it.

Methods

The BSN Web API provides different methods to perform similar operations. It is possible, for example, to retrieve/update either all or a specified subgroup of properties. This allows you to choose which methods suit your deployment best in terms of usability, responsiveness, etc.

Entity Retrieval Methods

Currently, there are four types of entity retrieval method:

Get{EntityName(s)}

Methods of this type retrieve all entities of the corresponding type and return paged results with initialized parent dependencies and/or usage indicators. For performance reasons, they do not return child entities. The page size is limited to a certain number depending on the method.

The BrightSign Network Web API implements a markers-based approach similar to the Amazon REST 3 API: The client specifies the marker (entity ID) of the starting element in the list, as well as the number of entities to receive. The server will indicate whether the response is truncated (i.e. there are more elements that can be retrieved by the next request) and provide the marker for the next object instance.

If a client has retrieved a first page and is in the process of retrieving the second while another client adds, updates, or removes two objects on different pages, the first client may receive an inconsistent state.

GetSpecified{EntityName(s)}

Methods of this type retrieve entities with specified keys. The results will not be paged; as a result, there is a limit on the number of entities that can be requested. This type of method will initialize only parent dependencies.

Find{EntityName(s)}

Methods of this type allow you to search for entities using a [string] Name pattern (including wildcards). This method type only exists for entities that have a Name alternate key. These methods return paged results with initialized parent dependencies and/or usage indicators.

Get{EntityName}
Get{EntityName}ByName

Methods of this type retrieve a single object instance using one of its Keys. Unlike other method types, these methods allow retrieval of child entities along with the requested entity. This behavior is useful for entity properties dialogues (e.g. a Group Properties dialogue that shows general information about a particular group) and entity management pages (e.g. a Dynamic Playlist management page that can be initialized with a single call).

Entity Update Methods

Currently, there are two types of entity update method:

General Update Methods

e.g. UpdateGroup

These methods receive a complete object in its updated state and attempt to detect and store all changes on the server side. These methods are useful in cases where a client retrieves an object first, allows the user to make changes, and then passes the new state to the server without the need to track user changes or construct call chains for applying a particular change (e.g. selecting the Edit button of a Dynamic Playlist in the BrightSign Network WebUI)—this is a use case that fits most WebUI and some BrightAuthor scenarios.

These methods can also update object relations, so the client will be able to store not only all new property values, but also, for instance, updated sets of Dynamic Playlists or presentation contents in a single transactional service call without intermediate states.

Specific Update Methods

UpdateGroupsAutorun

These methods receive Entity IDs and one or more values for updating logically related properties within that entity (for example, changing the minimum required firmware values for a group). Methods of this type don’t require the client to retrieve the object first. This may be useful for small dialogs, groups of controls (such as those in BrightAuthor), or internal client logic for sealing off certain parts of functionality from end users.

Object Permissions

Currently, all supported entities have a predetermined set of Object Permissions that cannot be changed. Customizable permissions will be implemented in the future.

SOAP Endpoints

Currently, the BrightSign Network Web API consists of two web services with nearly identical configurations: the Application Service and the Content Upload Service. Each web service has two SOAP endpoints: One is configured to use the WS-* specification and the other to use the WS-I Basic Profile.

WS-*

The WS-* endpoint is intended for rich, multifunctional server or desktop applications that support features such as sessions and transactions. The endpoint also supports its own rich security module and complex messaging format.

It would be difficult and time consuming to manually implement the required functionality for WS-*, including message serialization/de-serialization, encoding/decoding, connection management, and state management. Therefore, in order to utilize this endpoint, you will first need find a library that can create a service reference (i.e. proxy class) for your language and/or platform. Windows features built-in tools for creating service references for .NET applications, where the WS-* specification is the default web service endpoint configuration. Official or third-party tools/libraries have also been built for some, but not all, languages and platforms.

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 familiar methods in the code.

WS-I Basic

The WS-I Basic endpoint is defined for simple clients that support a small number of functions or don’t support the WS-* specification. This specification does not support sessions or transactions. It does not have its own security module, using IIS instead. As a result, the message format is much simpler. WS-I Basic is also supported by all languages and platforms; it is even possible to use it directly without a service reference (i.e. proxy class) if needed (for example, through JavaScript).

SOAP Access Point URLs

Use the following URLs to create service references:

The service-endpoint addresses are specified in the WSDLs. Most SOAP tools and libraries used to create references will find the addresses automatically. The current service endpoint URLs are as follows:

Each URL has a specified API version (e.g. “2014/04/”). API versions will rarely, if ever, change after production release, the exception being changes that will extend functionality but not affect existing clients. Older API version URLs may be removed at a later time if deemed obsolete.

User Authentication

Credentials

Both BSN endpoints use simple username-password authentication; the username has the following format: {AccountName/{UserLogin}. These credentials should be passed in the header of all SOAP requests according to the corresponding SOAP specification. The complex security rules of the WS-* endpoints are defined in the WS-Security specification. The WS-I Basic Profile, on the other hand, defines just two special elements in the message header for the username and password.

Encoding

The WS-* endpoint is configured to use message-level encoding exposed over HTTP: Each request/response is encoded by the application first, then wrapped by a service message and sent in plaintext over the Internet.

The WS-I Basic endpoint, on the other hand, is configured to use transport encoding, with message credentials exposed over HTTPS: Each request/response is sent to the web server or client in plaintext; it is then encoded and transferred over the Internet via SSL/TLS.

Development Tools

The BSN WebUI contains a simple method that can be used for configuration checks and client login dialogs:

User Authenticate()

This method validates the passed credentials and returns the corresponding User instance. Note that User credentials should be specified in all other method calls.