Batch Provisioning: Reference for the XML Manifest

Batch provisioning is available only for Premium customers at this time. If you are interested in upgrading your Brightcove account to a Premium account please contact Brightcove for more information.

About this document

This document is a reference for the XML manifest you need to create in order to use the Brightcove batch provisioning system. See Using Batch Provisioning for more information, including prerequisites and detailed procedures. In addition, the following files can help you create your XML manifest:

• A sample XML manifest for Brightcove. You can copy this sample as a starting point and edit it to suit your needs.
• Batch provisioning DTD. Download the DTD that defines the technical requirements for a valid XML manifest

Explanation of tags used in a Brightcove XML manifest

It may be helpful to view a sample Brightcove XML manifest as you review these explanations.

• Identify XML Document
• The opening tag for the manifest
• Address for notification email or HTTP callback
• Identifying assets for upload
• Creating or updating titles
• Creating or updating lineups
• Deleting assets, titles, or lineups
• The closing tag for the manifest

Identify XML Document

Example

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

The opening tag for the manifest

This Brightcove-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:

Address for notification email or HTTP callback

The notify tag identifies where Brightcove will send the email notification of success or failure. 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 email address.

Example

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

The notify tag uses the following attribute:

notify attributes

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, PLAYLIST, 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.

Example

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

callback attribute

Identify assets for upload

The asset tag describes a file that is being uploaded. You need to include a separate asset tag for each file being uploaded.

Example

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

The asset tag uses the following attributes:

Asset attributes

Creating or updating titles

The title tag describes the titles you want to create or update. Use a separate tag for each title you want to include in your upload.

Example

<title name="My Title"
       refid="title1"
       active="TRUE"
       allow-brightcove-distribution="TRUE"
       start-date="01/01/2007 12:00 AM"
       end-date="01/01/2007 12:00 AM"
       flash-preview-refid="asset1"
       flash-full-refid="asset2"
       wmv-full-refid="asset3"
       thumbnail-refid="asset4"
       video-still-refid="asset5"
       flash-prebumper-refid="asset6"
       color="TRUE"
       language="English"
       rating="TV-Y7"
       release-date="10/5/2005"
       genre1="3575"
       genre2="3576"
       economic-type="AD"
       ad-keys="; key=value; key=value"
       rental-price="1.99"
       rental-period="3"
       purchase-price="25.00">
  <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>
  <award>Two Thumbs Award</award>
  <award>Frank's Award</award>
  <tag>funny</tag>
  <tag>entertaining</tag>
  <logo-overlay
       asset-refid="12345" 
       click-thru="http://www.brightcove.com" 
       tooltip="Go to Brightcove" 
       alignment="bottom right" />
</title>

Title tags include a mix of attributes and sub-element tags which map closely to the fields found in the Brightcove Console 's Title creation form. Note, however, that there are three title attributes that you can set in the Brightcove Console, but which you cannot set using batch provisioning:

• Enable Viral Sharing
• Force Ad Policy
• Cue Points

Title attributes

Title sub-element tags

Logo-overlay attributes

The logo-array tag uses the following attributes to define an image that will be positioned over the video window for branding and to drive traffic to a specified location.

Creating or updating lineups

There are two types of lineup : manual and automatic.

• Manual Lineups - You determine the position of titles in the lineup by creating a list of all titles to include in the lineup. Use the manual-lineup tag.
• Automatic Lineups - All titles in the publisher account are automatically included in the lineup. You specify the method by which the titles are ordered, whether oldest to newest, newest to oldest, or alphabetical. Use the automatic-lineup tag.

You do not need to create any lineups using batch provisioning; you can instead use batch provisioning just to upload assets, or assets and titles, and create your lineups using the Brightcove Console.

Manual Lineups

For a manual lineup, use the manual-lineup tag. Within the manual-lineup tag, use a series of title-refid tags to list each title that is to be included in the lineup.

Example

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

The manual-lineup tag uses a mix of attributes and sub-element tags which map closely to the fields found in the Brightcove Console's Lineup creation form.

manual-lineup attributes

Sub-element tag for the manual-lineup tag

Automatic Lineups

For automatic lineups, use the automatic-lineup tag. You do not explicitly reference titles, but instead specify how to order the titles, using the type attribute. You can also filter titles using the tag-filter attribute and the title-tag sub-element.

Example

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

Automatic lineups have a mix of attributes and sub-element tags which map closely to the fields found in the Brightcove Console's Lineup creation form.

automatic-lineup Attributes

Sub-element tag for the automatic-lineup tag

Deleting assets, titles, or lineups

You can also use the batch provisioning system to delete assets, titles, or lineups from your account. Warning: An asset cannot be deleted if it is referenced by a title, and a title can not be deleted if it is referenced by a lineup.

Example

<delete-asset refid="RandomAssetsRefID">
<delete-title refid="RandomTitlesRefID">
<delete-lineup refid="RandomLineupsRefID">

Use the following tags, setting the refid attribute to the refid of the asset, title, or lineup that you want to delete.

The closing tag for the manifest

The last tag marks the end of the manifest, indicating that the entire manifest is present.

</publisher-upload-manifest>