Schema

For details about each API method, see SOAP Architecture Method Reference.

Each method or operation consists of a request and response. These operations are described in the WSDL files (one operation per file) included in the SDK. The WSDL files provide XML descriptions of the functionality and parameters for each operation, including the request and response details.

The name of the operation text file -- for example, loop_policy_mgr_add_v4 -- consists of four parts:

• the targeted resource, for example, loop_policy;
• mgr;
• the operation type, for example add; and,
• the version, for example, v4. For more information about WSDL/Method versioning, see About WSDL Versioning.

Each operation is one of three basic types:

• add: The add operation type creates a new row in the database. It reserves a unique id number for the resource and assigns it to the new addition. The new entry is populated with the information given in the add operation. Example: reservation_mgr_add
• list: The list operation type is used to list entries from the database. The list operation will typically return all matching resources from the requesting user’s domain. Others might only list all resources based on some other specified criteria. It can be used to list multiple entries despite the existence of list_many, which is used to list multiple specific resources. Example: reservation_mgr_list
  • list_many: The list_many operation type lists multiple specific resources. This operation type returns the entries specified by a list of IDs given in the request. Use list_many instead of list when targeting specific resources by their ID number instead of returning all results from a domain (or other common factor). Example: reservation_mgr_list_many
• update: The update operation type is used to edit the resources in the database. This can be one element of a resource or multiple elements of the same resource. Example: reservation_mgr_update

Broadsign provides an XSD file that lists the possible values for each parameter in the API methods.

For example, let us look at the incident_threshold_mgr_add method. This method creates a new incident threshold relative to an existing incident.

Among the parameters you need to pass is warning_action. Referring to the table at incident_threshold_mgr_add method, you will see that this parameter is of the type "IncidentThresholdAction".

Refer to the types.xsd file and you will see the following:

<simpleType name="IncidentThresholdAction">
    <restriction base="string">
        <!-- IncidentThresholdAction_NEVER = 1 -->
        <enumeration value="1"/>
        <!-- IncidentThresholdAction_IMMEDIATE = 2 -->
        <enumeration value="2"/>
        <!-- IncidentThresholdAction_LATER = 3 -->
        <enumeration value="3"/>
    </restriction>
</simpleType>

This portion of the types.xsd file shows us the options available for the warning_action parameter:

• "1" = Never
• "2" = Immediate
• "3" = Later

You can find the types.xsd file at: /broadsign/suite/sdk/api

Often, if we have updated a new feature or fixed a bug, we will need to update certain WSDLs/methods. Each WSDL and, thus, each method has its own version number that increments separately from Broadsign Control Products.

When a WSDL version increments, some or all of the parameters or fields will change.

Note: If you want a new feature that impacts Broadsign Control API, you will need to upgrade. Broadsign Server is backwards compatible so previous versions will continue to work.

Each operation requires the proper privileges before Broadsign Server will execute them. Without the proper privilege, Broadsign Server will reject the request with a "Denied" error. Ensure that the user assigned to make these requests has the correct and necessary privileges for the relevant operation.

For more information, see:

• Step 2: Authenticate your Broadsign Control API User and Create your Local Certificate
• Step 2: Authenticate your Broadsign Control API User
• Edit User Group Properties

This section provides the components that make up some of our more common resources.

When building these resources using Broadsign Control Player API with SOAP, it will help to keep these structural relationships in mind.