Generic SOAP interface for encoder control v1.0.1

Overview

This document describes the basis of the Nagra Encoder SOAP interface used in third party encoder integrations for VOD projects.

You can download the WDSL file for validating and typing the SOAP message here:

EncoderControl.wsdl

Audience

Nagra CMS product and engineering departments are the internal audience.

Third-party encoders’ engineering departments that are integrating with OpenTV Video Platform are the external audience.

Document change policy

Versioning of this document is defined based on three parts that are incremented as follows:

• The first part is incremented when non-backward-compatible changes are performed.
• The second part is incremented when the changes impact one of the schemas.
• The third part is incremented when the changes impact only the documentation (for example, a correction in an explanation or of a typo).

Conventions used

When the document references an XML element within the text, this element is written in a monospace font and is denoted by the use of angle brackets (e.g., <Content>).

Other references to the same word may refer to the Nagra CMS interpretation of this word, for this example, where the word is written in normal text font “Content” describes all the editorial and eventually technical information of a movie itself.

In the same way, attribute names and filenames are also written in a monospace font.

SOAP mechanism

The EncoderControl.wsdl is provided so you can validate (and type) the SOAP message.

For every SOAP method, a sample request and a sample response are provided. Any errors that the encoder returns are managed as SOAP Faults. SOAP Fault has a common schema for all SOAP methods.

NAGRA CMS does not send any SOAP headers or namespaces in the request.

Fault management

The fault schema only allows the “detail” part of the fault message to be validated.

The “Fault” sections of this document list error messages that must at least be managed.

The encoder vendor can specify additional error messages. The only constraint is that they must be human-readable.

Fault messages should be returned with an HTTP error response code. For example, 400, 500, etc.

Below is a snippet of the ExceptionWS element definition from the WSDL:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="wfm:EncoderControlAPI/v1/schemas" targetNamespace="wfm:EncoderControlAPI/v1/schemas" elementFormDefault="qualified"
      attributeFormDefault="unqualified">
       <xs:element name="ExceptionWS">
              <xs:complexType>
                     <xs:sequence>
                           <xs:element name="message" type="xs:string"/>
                     </xs:sequence>
              </xs:complexType>
       </xs:element>
</xs:schema>

Sample Fault message:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
      <soap:Fault>
         <faultcode>env:Server</faultcode>
         <faultstring>Internal error (Database Error)</faultstring>
         <detail>
                <ExceptionWS xmlns="nmcms4.nagra.com">
                       <message>Internal error (Database Error)</message>
                </ExceptionWS>
         </detail>
     </soap:Fault>
  </soap:Body>
</soap:Envelope>

Sequence diagram illustrating API use

Nominal case

Encoding job state diagram

Interface specification

The interfaces are explained in the following sub-pages: