Java Developers

Step 1: Download and Install the Broadsign Control API SDK

As a Java developer, to integrate with Broadsign Control API, you need to download and install the SDK. Also, you will need to install the Apache Axis2 library.

Supported Ubuntu Versions

Broadsign Control's SOAP SDK is compatible with the following 64-bit Ubuntu versions:

Supported Linux Versions

Ubuntu Desktop 22.04 LTS (Minimum Install)
Ubuntu Desktop 20.04 LTS (Minimum Install)
Ubuntu Desktop 18.04 LTS (Minimum Install)

Tip: See Ubuntu Release Cycle for official supported Ubuntu versions.

Ubuntu 22.04 Hardware Acceleration Differences

With the support of Ubuntu 22, the Broadsign Control hardware acceleration performance undergoes notable changes compared to Ubuntu 20 and earlier versions. The key differences are as follows:

Supported Hardware:
- Hardware acceleration is now supported on Comet/Ice/Amber Lake (NUC10) and subsequent models in Ubuntu 22. This is a significant enhancement compared to Ubuntu 20 and earlier versions.
Performance Issues on Ubuntu 22:
- Using hardware acceleration with 60 FPS video on older hardware, such as Comet/Ice/Amber Lake (NUC10) and earlier, may result in performance issues. Broadsign recommends to either disable hardware acceleration or opt for 30 FPS video playback.
- On Kaby/Appollo Lake (NUC7) and earlier, Broadsign recommends to set the environment variable LIBVA_DRIVER_NAME=i965, which will force Broadsign Control Player to use the Intel i965 driver.
- For Coffee/Amber/Whiskey Lake (NUC7) and earlier, hardware acceleration is not functional for H265/HEVC video with high-depth color profiles, such as 10bit/channel 422.

The hardware acceleration issues mentioned above do not apply when hardware acceleration is disabled in the player's configuration, which is the default setting.

To download and install Broadsign Control's SOAP SDK:

Below, we provide instructions for Ubuntu Linux users:

Install Broadsign Control's SDK.

Copy

sudo dpkg -i bssdk-13_0_0-xxx-i386.deb

Download the Apache Axis2 binary distribution from http://axis.apache.org/axis2/java/core/download.cgi.
Unpack the library to a known folder (henceforth ~/bssdk/), using the following terminal command (change, as necessary, based on the proper version):
Copy
```
unzip axis2-1.6.2-bin.zip
```

Note: If you are installing Apache Axis2 on Windows, you will need some extra configuration to get HTTPS support; otherwise, you will receive this error message: "SSL support is not available in this build".

Step 2: Authenticate your Broadsign Control API User

When integrating with Broadsign Control API in production, we recommend a cryptographic certificate and key.

You must install them on the client machine that is associated with a user — with proper privileges — in Broadsign Control Administrator. For auditing and security reasons, it is best to create a new user solely for use with Broadsign Control API. Add a user through Broadsign Control Administrator, choose an arbitrary password and assign the proper privileges.

Then, you must generate a private key and submit a Certificate Signing Request (CSR) to Broadsign. Broadsign will respond with a signed certificate and a public key fingerprint:

The signed certificate and your private key are your authentication tokens.
The public key fingerprint is assigned to the user you created, thereby allowing Broadsign Server to authenticate the user and assign the correct security context.

To authenticate your Broadsign Control API user:

Run the following terminal command:

Copy

sudo keytool -importcert -trustcacerts -alias broadsign_ca -file /opt/broadsign/suite/sdk/certs/ca_cert.pem -keystore ~/bssdk/keys/trusted.keystore

Generate a unique key to identify your SDK user.
Copy
```
sudo keytool -genkey -alias soap -keyalg RSA -validity 265 -keystore ~/bssdk/keys/soap.keystore
```
- Fill out the fields accurately.
- DO NOT specify any of the following extra attributes:
  - a challenge password
  - an optional company name

Create a Certificate Signing Request (CSR) by running the following terminal command:

Copy

sudo keytool -certreq -alias soap -file ~/bssdk/keys/soap.csr -keystore ~/bssdk/keys/soap.keystore

Send the Certificate Signing Request (CSR) to Broadsign. Include the following information:
- To: services@broadsign.com
- Subject: SDK CSR
- Attachment: [soap.csr]
- Body: Please find attached the API Certificate Signing Request for [your company's name].
  
  Warning: Do not send your private key. Keep it secure at all times. Anyone with access to your private key could make unapproved changes to your domain.
  
  Note: If the email address from which you send the request is unregistered at Broadsign, you will receive a bounce-back email. You will need to have a registered contact from your organization contact us to register the email.
Receive the signed certificate and the public key fingerprint from Broadsign.
Assign the public key fingerprint to your designated Broadsign Control API user:
1. In Broadsign Control Administrator, from the resource tabs on the left, select Users. See Edit User Properties.
2. Find and double-click your Broadsign Control API user.
3. In the User Properties, go to the Credentials tab.
4. In the Public Key Fingerprint section, paste your fingerprint.
  - The user making the requests must have a valid fingerprint value that matches the certificate being used on the client side of the mutually-authenticated SSL connection.
  - The fingerprint is a series of hexadecimal characters, 20 pairs separated by colons.

Step 3: Add your Signed Certificate to the Keystore

The local certificate allows Broadsign Server to authenticate you.

To add your signed certificate to the keystore:

Put the sdk_cert.pem file into your ~/bssdk/keys directory.

Run the following commands:

Copy

sudo keytool -trustcacerts -importcert -alias broadsign_client_ca -file /opt/broadsign/suite/sdk/certs/java/soap_ca_cert.pem -keystore ~/bssdk/keys/soap.keystore
sudo keytool -importcert -alias soap -file ~/bssdk/keys/sdk_cert.pem -keystore ~/bssdk/keys/soap.keystore

Step 4: Configure your Installation

Configuring your Java installation involves the following general steps:

Select the Server
Generate the Stubs
Patch the Stubs
Compile the Stubs

Select the Server

To select a server, edit the api/bsapi_merged.wsdl file and at the bottom, you will see this section:

Copy

<service name="bsapi" >
    <port binding="tns:bsapi_binding" name="bsapi_port" >
        <soap:address location="https://bssopen.broadsign.com:10803" />
    </port>
</service>

Change the “location” attribute to reflect the correct server. The addresses of the servers are:

Sandbox – https://bssopen-sandbox.broadsign.com:10803
Production – https://bssopen.broadsign.com:10803

Generate the Stubs

The next step is the generation of the stub classes. These classes expose the Broadsign operations as methods. Axis2 includes a tool — wsdl2java.sh — that generates stubs automatically. The following command will create a stub for all the possible Broadsign operations.

Copy

wsdl2java.sh -o stubs -s -d xmlbeans -uri api/bsapi_merged.wsdl

It is important to dissect this command to understand how it works:

Part	Description
-o operation	This is the name of the directory where `wsdl2java.sh` will store the stubs.
-s	This tells Axis2 to generate synchronous (not asynchronous) code.
-d xmlbeans	This is the most important option, as it specifies the data-binding to use in the stub. Broadsign recommends `xmlbeans` over the default `adb`. We have found `xmlbeans` easier to work with and less error-prone than `adb`. None of the other data-binding options are supported by Broadsign.
-uri	This tells Axis2 which WSDL to find the operations in. Every operation in the file will be included in the generated stubs. Please note that if you receive an error about illegal characters when generating the stubs, this is often caused by spaces in the path. To work around this issue, modify the path to not contain any spaces.

Patch the Stubs

Axis2 unfortunately has a databinding bug that you will need to be patch. This bug should be fixed as of Axis2 1.6; however, as of this writing, version 1.5.1 is the latest version available. More information on this bug can be found here: https://issues.apache.org/jira/browse/AXIS2-4374.

Broadsign has included a tool in the bin directory of the SDK that will automate the patching process for you. Run the tool on your stubs directory:

Copy

binjava_axis2_fix.exe stubs

Compile the Stubs

Next you must compile the stubs. This is done using the ant command. There is a build.xml file in the stubs directory that was generated by Axis2 for use with the ant build tool. It requires that the AXIS2_HOME environment variable has been set. This should be set to the installed location of the Axis2 toolkit, for example: /home/sdk/axis2-1.6.2

From within the stubs directory, execute the ant build command like so:

Copy

AXIS2_HOME=/home/sdk/axis2-1.6.2
    cd stubs
    ant

Step 5: Test your Installation

To test your Java installation requires the following general steps:

Compile the Samples
Set up the Keystore
Create the Stub
Use the Stubs

Choose a Java development environment that is familiar to carry out these steps. This sample will need to use some Java libraries. It is up to the developer to include the proper libraries in their project.

The included Java sample does two things: it creates a display unit and it reserves a campaign from a media package. The implementation of the factory classes shows how to use the stub classes to perform operations.

Note: A good starting point to familiarize yourself with the SDK is to create a simple method that lists a simple resource like criteria or categories. Further investigation into the source code of the samples is left as an exercise to the reader; however, we will explain some basics below.

Set up the Keystore

First, Axis2 needs to be setup to communicate through mutual authentication, using the keystore setup previously. In the samples, this is in Main.Java::setupKeystore().

Copy

private static void setupKeystore()
{
System.setProperty("javax.net.ssl.keyStoreType", "jks");
System.setProperty("javax.net.ssl.keyStore", "c:\test\certs\soap.keystore");
System.setProperty("javax.net.ssl.keyStorePassword", "123123");
System.setProperty("javax.net.ssl.trustStoreType", "jks");
System.setProperty("javax.net.ssl.trustStore", "c:\test\certs\trusted.keystore");
System.setProperty("javax.net.ssl.trustStorePassword", "123123");
}

The keystore setup is straightforward; however, ensure the paths match the ones you selected in Step 2: Authenticate your Broadsign Control API User.

Create the Stub

Next, Axis2 needs to instantiate the stub class. In the sample, this is done in Main.java::createStub(). Broadsign Server requires that all communication be made in UTF-16 encoding. This is done when initializing the stub.

Copy

private static void createStub()
{
try {
ConfigurationContext config = ConfigurationContextFactory.createDefaultConfigurationContext();
TransportOutDescription transport = new TransportOutDescription("https_mutual_auth");
CommonsHTTPTransportSender sender = new CommonsHTTPTransportSender();
sender.init(config, transport);
m_stub = new BsapiStub();
transport.setSender(sender);
m_stub._getServiceClient().getOptions().setProperty(Configuration.CHARACTER_SET_ENCODING, "utf-16");
m_stub._getServiceClient().getOptions().setProperty(HTTPConstants.CHUNKED, "false");
m_stub._getServiceClient().getOptions().setTransportOut(transport);
} catch (java.lang.Exception e) {
System.out.println("Error:" + e.toString());
}
}

Use the Stubs

Using the stubs correctly involves using several classes that were automatically generated from the WSDL. The basic flow of issuing a request is:

Create a request body (each operation has its own request body class that controls what is allowed as attributes in the request):
Copy
```
CriteriaMgrAddRequestBody body = CriteriaMgrAddRequestBody.Factory.newInstance();
```
Create a WSDL Request object (this is the parent object that contains the request body):
Copy
```
WsdlRequest wsdl = WsdlRequest.Factory.newInstance();
```
Create a Request Document object (this is the parent object that contains the WSDL request):
Copy
```
RequestDocument request = RequestDocument.Factory.newInstance();
```
Create a Response Document object (this is the object that will receive the response):
Copy
```
ResponseDocument response;
```
Set the attributes on the request body (the attributes you will need to set depends on the request you are performing, but typically, it requires that you set the domainId):
Copy
```
body.setDomainId(domainId);
```
Set the attributes on the WSDL request object. These attributes pertain to the type and version of the request being performed.
Copy
```
wsdl.setName("criteria_mgr_list");
wsdl.setVersion(5);
wsdl.setResourceCriteria(body)
```
Strip the “xsi:type” attribute from the request. This is an attribute that Axis2 dynamically appends that is not supported by Broadsign Server. This has been corrected in version 8.0 of Broadsign Control's SDK, if you are using this version or above, this line is not needed.
Copy
```
//  will reject xsi:types, so we must remove them.
wsdl.getResourceCriteria().getDomNode().getAttributes().removeNamedItem("xsi:type");
```

Set the request and encode it in UTF-16. Print the request so you can see what is being sent to the server.

Copy

request.setRequest(wsdl);
request.documentProperties().setEncoding("utf-16");
System.out.println(rcRequestDocument.xmlText());

Perform the operation on the stub and print out the raw response.

Copy

response = m_stub.criteria_mgr_list_v5(request);
System.out.println(response.xmlText());

Use the response for something useful. Typically, this involves parsing the response.

Copy

XmlObject rcBodies[];
rcBodies = response.getResponse().getCriteriaArray();
CriteriaMgrListResponseBody rc =
CriteriaMgrListResponseBody.Factory.parse(rcBodies[0].xmlText());
// rc.getId() <-- this is the resource Id, etc.

What's Next?

Once you have tested your installation, you could do one of the following:

Test the Sandbox – Broadsign provides developers with a sandbox as a learning environment and to test applications. See About the Sandbox (SOAP).
Record Requests to File – You can record to file all requests made from Broadsign Control Administrator and Broadsign Control Player to Broadsign Server. This valuable tool helps developers debug their code and become familiar with Broadsign Control API. See Recording Requests to File (SOAP).
Explore Common Use Cases – We provide background information and code samples for a number of common use cases. See Use Cases (SOAP).
Explore Broadsign Control Administrator and Broadsign Control Player – We encourage developers integrating with Broadsign Control API to explore our resources in the context of our other products. We created a number of video and online tutorials that provide a foundation in Broadsign Control Administrator and Broadsign Control Player. See Quick Start Tutorial and Training Videos.

v15.10	v15.9	v15.8	v15.7	v15.6	v15.5
v15.4	v15.3	v15.2	v15.1	v15.0	v14.8
v14.7	v14.6	v14.5	v14.4	v14.3	v14.2
v14.1	v14.0	v13.2	v13.1	v13.0	v12.1