FTP Batch Provisioning: Reference for the XML manifest

This is a reference document for the FTP Batch Provisioning XML manifest file that you must create to use the Video Cloud FTP Batch Provisioning system. This document gives detailed specifications and code samples of the required XML elements and attributes that you must include in your XML manifest file. Also included are the specifications for performing various actions with the XML manifest file, such as uploading assets, creating or updating videos, re-encoding videos, and many other options.

Before using batch provisioning, be sure to read Best Practices for Using Batch Provisioning.

This topic includes the following sections:

• Why use FTP Batch Provisioning?
• Prerequisites
  
• Validating your XML manifest file
• XML manifest document structure
  • Identifying the XML document
  • The opening tag for the XML manifest file
  • The address for the notification e-mail or HTTP callback
  • Common actions performed with the FTP Batch Provisioning XML manifest file
    • Identifying assets for upload
    • Creating or updating videos with the title element
    • Re-encoding existing videos
    • Creating or updating playlists with the lineup element
    • Creating cue points
    • Deleting assets, videos, playlists, or cue points
  • The closing tag for the XML manifest File 

Why use FTP Batch Provisioning?

Batch provisioning enables you to upload and provision multiple videos and playlists at once using an XML manifest file and the Video Cloud FTP server. Often, publishers use FTP Batch Provisioning to integrate their Content Management System (CMS) with video publishing in Video Cloud, or to perform initial ingestion of videos into the Video Cloud publishing services.

Prerequisites

Ensure that you have fulfilled the following prerequisites before proceeding:

• FTP batch provisioning is available only for Video Cloud Pro and Enterprise customers. If you are interested in upgrading your Video Cloud account, please contact Brightcove for more information.
• If you're still learning about XML, read the basic resources listed in Using FTP Batch Provisioning or watch the following demo:
  Video Tutorial: Introduction to XML
• See Using FTP Batch Provisioning for introductory information and detailed procedures. See also the related links list at the top-right side of this document. 
• Sample FTP Batch Provisioning XML manifest file. Download this simple example to see how to upload video using the XML manifest file. Open this file and review it as you read this article. If you choose to use this file, you will need to modify the file so that it works with your particular account and environment settings.

Validating your XML manifest file

You can validate your XML manifest file against the FTP Batch Provisioning Document Type Definition (DTD). Download the Batch provisioning Document Type Definition (DTD). 

Before validating your XML manifest file, it is very important to ensure that it is free of invalid or illegal characters, which need to be escaped. If left unfixed, these characters could cause failures in your upload process and lead to stranded or unavailable assets. A utility that checks for well-formed XML should catch these errors should they exist. The following shows how illegal characters in XML should be represented correctly in your XML manifest:

• & should be represented as &
• < and > should be represented as &lt; and &gt;
• ' and " should be represented as &#39; and &quot;

These restrictions apply to the values of XML attributes in the manifest; in the body of XML elements that permit CDATA, you can represent these characters directly. For example, compare how the phrase "Réné & moi" is represented in the <title name > attribute and in the CDATA within the <short-description> element:

<title name="R&#233;n&#233; &amp; Moi" refid="myVideo" active="TRUE" video-full-refid="asset2">
<short-description>
<![CDATA[
Réné et moi remarquons qu'il est tellement romantique,
de manière énigmatique, de se tenir debout sur la terrasse
à Chichen Itza et d'observer la montée de la lune gibbeuse!
]]>
</short-description>
</title>

XML manifest document structure

The following sections describe the structure of the XML manifest file, explaining required syntax and optional actions you can perform with the file and the FTP Batch Provisioning system.

Identifying the XML document

Required. This first tag identifies the XML document type and always looks exactly like the following:

<?xml version="1.0" encoding="utf-8"?>

The opening tag for the XML manifest file

Required. This Video Cloud-specific tag marks the beginning of the upload manifest.

Example

<publisher-upload-manifest publisher-id="101" preparer="3rd Street Video" report-success="true">

The publisher-upload-manifest  tag uses the following attributes.

The publisher-upload-manifest tag can include one or more of the following tags, each of which is described in detail in this document:

The address for the notification e-mail or HTTP callback

Optional. The notify tag identifies where Brightcove will send the e-mail notification of success or failure. While this tag is not required, it is best practice to ensure that someone in your organization is notified if there are errors. You will receive notification only of failures, not successes, unless you have set the attribute report-success="true" in the publisher-upload-manifest tag. To send notification to multiple addresses, use a separate instance of this tag for each e-mail address. The e-mail notification will come from the address donotreply@brightcove.com; make sure that e-mails from that address can make it through your spam filter.

Example

<notify email="you@example.com"/>
<notify email="me@example.com"/>

The notify tag uses the following attribute:

notify attribute

In addition to receiving notifications by e-mail, you can also use the callback tag to send upload notifications to a web page. The notification is sent in a POST to the URL you provide in the entity-url attribute of the callback tag. The POST includes:

referenceId=<the reference id provided in the manifest> 
id=<the id of the title, playlist, or asset in the database> 
entity=<VIDEO, LINEUP, or ASSET> 
action=<CREATE, DELETE, or UPDATE> 
status=<FAILED,SUCCESS> 
error=<an error message>

The status is always included in the callback post. In the event of a FAILED status, the other information may or may not be included in the callback post, depending on whether the information is available at the point of failure. See this example of how to use the HTTP callback feature in the FTP batch provisioning system, using PHP to create a log file from the data generated by FTP batch provisioning.

Example

<callback entity-url="http://example.com/batch-callback.php"/>

callback attribute

Common actions performed with the FTP Batch Provisioning XML manifest file

The following sections describe various actions that you might perform with your FTP Batch Provisioning XML manifest file. Within a single XML manifest file, you might perform several of the actions or simply one of the actions, depending on your content needs.

Identifying assets for upload

Optional. The asset tag describes a file that is being uploaded via the XML manifest file. Include a separate asset tag for each file being uploaded.

Example

<asset filename="MyVideo.flv"
       refid="asset1"
       size="188812"
       hash-code="a4ade1e2b09d517ff7360f91527639b3"
       display-name="My Video (FLV)"
       type="VIDEO_FULL"/>

The asset tag uses the following attributes:

Asset attributes

If you are using remote assets, use the remote-asset tag instead of the asset tag to identify your assets. See Creating videos with remote video files for details about using remote assets and the remote-asset tag's attributes.

Creating or updating videos with the title element

Optional. The title tag describes the videos you want to create or update. Use a separate title tag for each video that you want to include in your upload in your XML manifest.

Example

<title name="My Title"
       refid="title1"
       active="TRUE"
       start-date="01/01/2007 12:00 AM"
       end-date="01/01/2007 12:00 AM"
       video-full-refid="asset2"
       thumbnail-refid="asset4"
       video-still-refid="asset5"
       flash-prebumper-refid="asset6"
       shared="true"
       economic-type="AD"
       ad-keys=";key=value;key=value" >
    <short-description>My short description.</short-description>
    <long-description>My long description.</long-description>
    <related-link-url>http://your-company.com/</related-link-url>
    <related-link-text>Come learn about us!</related-link-text>
    <tag>funny</tag>
    <tag>entertaining</tag>
    <logo-overlay
         asset-refid="12345" 
         click-thru="http://www.example.com" 
         tooltip="Go to Example" alignment="bottom right" />
</title>

Title tags include a mix of attributes and child tags, which map closely to the fields found in the Media module's Edit Video dialog. Note, however, that you can set a video to always make an ad request by editing a video in the Video Cloud Studio, but you cannot do so using FTP batch provisioning.

Title attributes

Title sub-element tags

A title tag can contain the following child element tags.

Logo-overlay attributes

Optional. You can use the XML manifest file to specify an image that will be positioned over the video window for branding and to drive traffic to a specified location, through the  logo-overlay tag. Read more about logo overlays. The logo-overlay tag uses the following attributes:

Re-encoding existing videos

Optional. You can use the XML manifest file to direct Video Cloud to re-encode the video files for a video, while retaining all of the video's metadata. Use the reencode-from-existing-source element as a child of the top level publisher-upload-manifest element if you want to use the existing source file in your Video Cloud Media Library as the source for re-encoding; use the reencode-from-new-source element if you are supplying a new (possibly higher quality) source file with the XML manifest. Read complete information about re-encoding existing videos.

The reencode-from-existing-source attributes

<manual-lineup
    name="My Manual Lineup"
    refid="lineup1"
    thumbnail-refid="asset4"> <title-refid>title1</title-refid>
  <title-refid>title3</title-refid>
  <title-refid>title137</title-refid>
</manual-lineup>

<automatic-lineup name="My Automatic Lineup"
    refid="lineup2"
    type="NEWEST_TO_OLDEST"
    tag-filter="AND"
    title-limit="50"
    thumbnail-refid="asset4">
  <title-tag>sporty</title-tag>
</automatic-lineup>

<cuepoint name="My Cue" type="CODE" time="500000" video-refid="video001" />
<cuepoint name="My Other Cue" type="AD" time="50000" video-refid="video001" />
<cuepoint name="My Third Cue" type="AD" time="120000" video-refid="video001">
  <metadata>Something interesting about this cue point.</metadata>
</cuepoint>
<cuepoint name="My Fourth Cue" type="AD" time="270000" video-refid="video055">
  <metadata>
    <![CDATA[
      This is a multi-line
      Set of metadata
    ]]>
  </metadata>
</cuepoint>

<delete-asset refid="RandomAssetsRefID"/>
<delete-title refid="RandomTitlesRefID"/>
<delete-lineup refid="RandomLineupsRefID"/>
<delete-cuepoint video-refid="video0001" id="0123456789"/>

</publisher-upload-manifest>