On this page, we provide detailed information about Broadsign Control API's protocols, operations, libraries and WSDL files.
Digital Signage Control Protocol (DSCP) is an XML-based protocol for communication between Broadsign Server and the rest of Broadsign Control, including Broadsign Control Administrator. This section describes the structure and elements of the protocol.
Description
The requests to be sent to Broadsign Server consist of an HTTP header followed by a DSCP message wrapped in a SOAP envelope. When the request is received, the HTTP header and SOAP envelope are processed. The DSCP request is then extracted and passed to Broadsign Server to be executed. Broadsign Server generates a DSCP response which is wrapped in a SOAP envelope and returned to the requesting party.
Each DSCP request is specified by a WSDL file and a template of the expected response is included in the text files installed with the SDK. They can be found in [install path]/etc/sdk/doc/operations/.
Request Header Elements
| Header Element | Description |
|---|---|
| not_modified_since | This value controls the age of listed resource. This element uses the ISO 8601 combined time and date formatting: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]. The earliest supported value is Unix Time, or 1970-01-01T00:00:00. Defined in the request_base_type of the WSDL. |
| token | The token is an internal parameter that should not be modified. Defined in the request_base type of the WSDL. |
| requestid | This parameter is used for tracking requests. The response to this request is guaranteed to use the same requestid. It is recommended that applications increment the requestid with each request, making it easy to identify the corresponding response. The requestid is defined in the request_base type of the WSDL. |
| version | This value is the version number of the operation and must match the value given in the operation’s name. This is a fixed value for any given operation. Defined in the request_header type of the WSDL. |
| name | This is the name of the operation and must match the name given in the WSDL file. The version of the operation must not be inlcuded. This is a fixed value for any given operation. Defined in the request_header type of the WSDL. |
Request Body Elements
| Body Element | Description |
|---|---|
| request_body type | The DSCP body always begins with the request_body type as found in the WSDL. In the above example, the type is category. |
| request_body attributes | Each operation can have very different body attributes. The WSDL file contains the required elements under request_body. |
Response Elements
| Response Element | Description |
|---|---|
| status | An internal parameter subject to change. |
| version | The version of the operation as given by the request. |
| resource_type | An internal parameter subject to change. |
| ns | An internal parameter subject to change. |
| op_type | An internal parameter subject to change. |
| requestid | The requestid as given by the request. |
| name | The name as given by the request. |
| not_modified_since | The parameter returned by Broadsign Server is formatted as ISO 8601. The value returned is the time provided by Broadsign Server for subsequent requests that will return the latest information. |
Broadsign Control API contains nearly all of the functionality of Broadsign Control Administrator condensed into a group of operation files.
Ensure that the following aspects of Broadsign Control API's implementation specifics are taken into consideration while using the provided operations.
SOAP
XML namespace processing has not been implemented. Other than the request element itself, all sub-elements in a DSCP request cannot have a namespace prefix, that is, no colons. All attributes of the request element and all sub-elements that have a namespace prefix will be ignored.
All sub-elements without attributes, after namespace prefixed attributes have been removed, will be ignored. The SOAP response will always be of the same form; it is not possible to control any aspect of the response by changing any element of the request.
UTF-16
All requests and responses are made using UTF-16, even if the request or response does not contain any characters that require the use of UTF-16 encoding. The SOAP envelope must also be UTF-16.
Port 10803
The port to be used for making requests to Broadsign Server is 10803. This port is open for parties wishing to send requests. This port may not be used for communication via Broadsign Control Administrator.
list_many operations
The list_many operation returns the details of many resources as specified in the request by id. While a list operation will list the details for all matching resources in the domain, a list_many operation will return only information on the resources specified by id in the request.
The list:ResourceId type used in list_many operations comes from the types.xsd file (.../etc/sdk/api/). It is important to note that the list: prefix indicates that the type is a list of what comes after the colon, in this case ResourceId. This list is always encoded as comma-separated values (or CSV), e.g, “1,2,3,5,8”.
Configuration Section
/* Global Configuration Section */
global $sdk_root, $ca_cert, $local_cert, $bss_host, $api_root;
$bss_host = 'https://bssopen-sandbox.broadsign.com:10803';
$sdk_root = '/opt/broadsign/suite/sdk';
$api_root = $sdk_root . '/api';
$ca_cert = $sdk_root . '/certs/ca_cert.pem';
$local_cert = '/home/jon/certs/merged_cert.pem';
$print_requests= 1;
$print_responses = 1;
| Element | Description |
|---|---|
| bss_host | This is the hostname to connect to. Broadsign Server only accepts SOAP connections on port 10803. Along with your SDK access, you were provided with a sandbox server on which to test and develop your application. Once your application is ready to be deployed to production, this hostname should change to: https://bssopen.broadsign.com:10803. |
| sdk_root | This is the SDK root installation path, which defaults to /opt/broadsign/suite/sdk. |
| api_root | This is the path to the WSDL files used by soaplib. |
| ca_cert | This is the path to the certificate used to authenticate the identity of the server. It is included in the SDK. |
| local_cert | This is the path to your local certificate that will allow Broadsign Server to authenticate you. soaplib requires a merged key and certificate file. Concatenate both your private key and the signed cert provided by Broadsign Services: cat sdk_key.pem sdk_cert.pem > merged_cert.pem |
| print_requests | This is a debugging tool that will print to stdout all the XML requests sent to the server. To disable the printing of requests, set print_requests to “0”. |
| print_responses | This is a debugging tool that will print to stdout all the XML responses received from the server. To disable the printing of responses, set print_responses to “0”. |
Classes and Functions
The soaplib.php library is not intended to be a comprehensive implementation that meets all possible client application needs. Rather, it is a collection of base classes and functions that show how to perform the internal processing needed to send requests and handle responses.
More complex operations will most likely need extra methods and parameters according to the application’s needs. For example, if you need to perform a list operation with a not_modified_since value that is not epoch, these functions would need to be modified.
Here is a quick overview of the classes and functions provided:
| Class/Function | Description |
|---|---|
| SoapAdapter | This class inherits from the native PHP SoapClient and automatically handles the conversion to and from UTF-8 and UTF-16. |
| CreateOperation | This function creates a SoapAdapter instance by setting the mutual authentication properties of the SSL context and constructing the path to the WSDL file. |
| CreateSimpleRequest | This function builds the body of a simple request. |
| PerformSimpleOperation | This function ties it all together by creating an operation and a request, performing the operation and returning the response object. |
Web Services Description Language (WSDL) describes the format of each operation in XML. Broadsign Control API includes a WSDL file for each operation available to the user.
Usage
Each WSDL file represents one operation. Each operation has three messages: request, response and error. Message names are of the form [operation name] ""_" [message type]_v" [version] (for example, user_mgr_list_v9_request).
Each message has a response type. The simplest is error which has the element type of “string” from the xml standard, contained within an “error” element. The request type for any operation is always wsdl_request and the response type is wsdl_response.
wsdl_request
wsdl_request is the type for the request message of the Operation. This consists of a DSCP request header and a request body. For the rest of this section, be careful to distinguish between "request" and "dscp request”. The wsdl_request type extends the request_header, while the request_header extends the request_base_type.
The request_header specifies the name and version attributes which are required elements of the request.
Within each wsdl_request is a request_body, which contains a list of all attributes needed for the request. The request_body is different for each operation and can vary greatly. For an operation to work properly, every attribute of the request_body must be specified.
wsdl_response
The wsdl_response is the type for the response message. This consists of a DSCP response header and a response body. The wsdl_response extends the response_type and contains the full description of elements in the response_body. This response_body can also vary greatly depending on the operation. A typical response_body for a list operation (for example, criteria_mgr_list) will contain values for all the attributes of each Criteria resource listed.
After exploring Broadsign Control API's protocols, operations, libraries and WSDLs, you are ready to send more advanced calls to our API. See Use Cases (SOAP).