Using Batch Provisioning

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.

Batch provisioning enables you to upload and provision multiple assets at once using an XML manifest file and Brightcove's FTP server. You can use batch provisioning to automatically generate assets, titles and lineups, which will appear in your Brightcove Console once the upload process is complete.

The Brightcove Console and Publishpod were designed to let you work in your account on a relatively small scale. The batch provisioning feature makes it easier to upload large numbers of assets or make multiple edits quickly. However, the batch provisioning feature requires you to specify your upload with a high degree of precision in an XML document, rather than working with a graphical user interface.

Main steps

To use Brightcove's batch provisioning feature, follow these main steps, each of which is described in more detail later.

  1. Read Before you begin and understand the XML principles and the software that you will need to use.
  2. Prepare your assets for upload.
  3. Create your XML manifest. This XML document provides Brightcove with all the information the service needs to handle the assets, titles, and lineups you upload.
  4. Upload your files to Brightcove's FTP server.
  5. Upload your XML manifest to Brightcove's FTP server.

After your upload is complete, you can receive an email notification confirming that your files have been successfully received by Brightcove, or notifying you of any problems encountered during the transfer. See Troubleshooting for information that can help you identify any problems you run into.

In addition to this document, Brightcove provides the following documentation to help you understand and use the Brightcove batch provisioning feature:

Before you begin

What you need to know

To use Brightcove's batch provisioning system, you should have a basic knowledge of XML principles and experience creating XML documents. If you need a primer on XML, here are a few basic resources:

Tools

To use Brightcove's batch provisioning system, you'll need a few basic software tools:

  • An MD5 checksum of each file you want to upload (you can use MD5summer or a similar application to create this)
  • An XML editor to create the manifest that you upload after you upload the files. Two free XML editors are XML Marker and XRay; two other popular XML editors are Altova XMLSpy and Stylus Studio.
  • A utility to check that your XML is valid and well-formed. Most XML editors validate your XML. You could also use a utility such as W3C’s web based validation service.
  • FTP client software to upload your files and the XML manifest to Brightcove's server. Some FTP clients are WSFTP, AceFTP, and CuteFTP. There is also an FTP client built into Windows Explorer.

Preparing your assets

Gather your assets you want to upload in a location or system convenient for working with them and uploading them. Make sure that each asset is compatible with Brightcove's requirements for assets of that type.

To ensure compatibility with the automated systems that process uploaded assets, you should ensure your assets do not contain any illegal characters that might interfere with the processing of your files. In general, your file names should consist of English alphanumeric characters only (1-9, A-Z, a-z). Replace any spaces with underscores. Here is a short list of illegal characters you should avoid in file names:

  • Non-English and/or high-ASCII characters, such as: é ñ ą
  • Non-printable characters like spaces and tabs
  • Certain punctuation characters such as: @ ! ‘ “ * & # (hyphens and underscores are allowed)

Asset information

For each file you upload, you will need the following information, which needs to be include in the XML manifest:

Computing checksums

For each file you upload, you must include an MD5 checksum (sometimes called a hash) as part of the XML manifest. The MD5 checksum is a unique code that allows Brightcove to validate that the file was transferred successfully. To create an MD5 checksum for a file, you can use MD5summer or a similar application. Your MD5 checksum application will generate for each file a string like this, d689386b367ac0f6db424f6e47ea1c06, which you must include in your XML manifest.


Preparing your XML manifest

The XML manifest provides Brightcove with all the information we need to process your upload and make it available on Brightcove’s servers. You can download a sample XML manifest and use it as a starting point for your own manifest. The details of the tags and attributes you use to create the XML manifest are described in the Reference for the XML Manifest document.

Note: If an asset, title, or lineup with a particular reference ID already exists in your account, whether you added it using the Console or a previous batch upload, it will be updated with the information in the XML manifest.

It is very important to ensure that your XML manifest is free of invalid or illegal characters which need to be escaped. If uncaught, 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 &apos; and &quot;

Your XML manifest can include assets, titles, lineups, or any combination. Each asset, title, or lineup is specified in a separate XML element in the manifest.

Assets in the XML Manifest

For each asset you are uploading, the XML manifest requires you to specify the following:

  • display-name: how the file will appear in the console
  • filename: the name of the file on disk
  • file-size: the size of the file on disk in bytes
  • hash-code: the hash of the file size to ensure a successful transfer
  • type: the type of asset (FLV Full, FLV Preview, Thumbnail, etc)
  • refid: a unique id you assign to the file

The refid (reference ID) attribute allows you to reference the asset in lineup and title definitions later in the manifest. These titles and lineups will appear in the Console as well once your upload has finished processing.

For specific details and examples of how you specify lineups in the XML manifest, see Identify assets for upload.

Titles in the XML Manifest

For each title you want to specify in your XML manifest, you need to provide:

  • a name for the title
  • refid: a unique id you assign to the title
  • the refid of all assets you want to include in the title
  • a short description of the title

For specific details and examples of how you specify titles in the XML manifest, see Creating or updating titles.

Lineups in the XML Manifest

You can create either manual lineups or automatic lineups in your XML manifest. For each manual lineup, you need to provide:

  • a name
  • refid: a unique id you assign to the lineup
  • the refid of all titles you want to include in the lineup

For each automatic lineup, you need to provide:

  • a name
  • refid: a unique id you assign to the lineup

For specific details and examples of how you specify lineups in the XML manifest, see Creating or updating lineups.

Final checks

When you have finished preparing your XML manifest, perform one final check to make sure you are ready to begin uploading. Use this checklist as a guide:

  • Are my assets properly named, without spaces or illegal characters?
  • Is my manifest well-formed and valid XML, free of any illegal characters? Be sure to run your manifest file through an XML validation utility.
  • Are my MD5 hash codes and filenames correctly specified in my XML manifest, and do they match the assets I’m about to upload?
  • Does the number of assets on disk match the number of assets in my XML manifest?

Uploading

After you have prepared your assets, created the XML manifest that describes the assets, and checked everything over, you are ready to begin your upload.

  1. Log on to Brightcove's FTP server, using an FTP client and the URL, username, and password that was provided to you by your Brightcove representative.
  2. Upload all of the asset files listed in your manifest. As your upload progresses, you will notice your files disappear from the FTP server upload directory soon after they are uploaded. This is normal — files are secured to a staging area until the manifest is uploaded. Do not upload the XML manifest yet.
  3. After all of your files have been transferred successfully, upload your XML manifest. It is important to upload all of your asset files before you upload your XML manifest; otherwise, Brightcove's server will begin to process your XML manifest and generate errors when it can't locate asset files that are referenced in the manifest, but not yet uploaded to Brightcove. You have 48 hours to upload the XML manifest after assets have completed uploading.
  4. When Brightcove finishes processing your manifest, you will receive an email confirming that the files detailed in the manifest have been successfully received by Brightcove, or notifying you of any problems encountered during the transfer. You can also receive a notification callback posted to a URL you provide in your XML manifest. Note: you will receive an email confirming success only if you set the report-success="true" attribute in your XML manifest. For information about the possible causes of problems or error messages, see Batch Provisioning: Troubleshooting.

Once your files have been transferred successfully, you can sign into the Brightcove Console and edit assets, titles and lineups normally. However, you should allow up to 1 hour for assets to fully propagate on the network before they are available for preview.

Batch provisioning and the Console

You can use the Brightcove Console to work with assets, titles, and lineups that you added with batch provisioning. However, bear in mind the following:

  • If you make any changes to an asset, title, or lineup using batch provisioning, you will overwrite any information you have made earlier using the Brightcove Console, even if you didn't change all the information. For example, suppose you have a title already in your account with all attributes already set. If you use batch provisioning to modify the title's short description, but don't supply any other information about the title, the other attributes of the title will be blanked out and unset. Therefore, if you use batch provisioning to modify existing assets, titles, and lineups, be sure to provide all the information about them, not just the attributes you want to change.
  • If you set schedule information using batch provisioning, you need to provide start and end times using Pacific time. When you view schedule information in the Console, these times are automatically translated to Eastern time.

Changing existing titles

If you use batch provisioning to modify titles that already exist in your Media Library, whether they were added using the Brightcove Console or using batch provisioning, you need to be aware of how the batch provisioning system overwrites exisiting data. Suppose you have a title in your Media Library with the following information:

  • name: My Title
  • refid: myTitle
  • active: true
  • flash-full-refid: "asset2"
  • short-description: "This is my short description"
  • long-description: "This is my long description. See? Look how much longer it is!"

The long-description field is optional; it could have been set when the title was created or it could have been added in the Console afterwards.

Now suppose you want to change this title's name. You included this tag in your XML manifest:

<title name="My New Title Name" refid="myTitle" active="TRUE" flash-full-refid="asset2">
  <short-description>My short description.</short-description>
</title>

However, this does more than just change the title’s name. The batch provisioning system takes all the information in the title tag and overwrites the existing information about the title. Because you didn’t include a long-description field, that optional information was overwritten and lost.

To get around this, you can do one of two things:

  • Include all of the existing information for the title from your records so nothing is lost. Set every attribute and sub-element, even the ones you aren’t changing.
  • Use the overlay-update attribute in the title tag. Setting overlay-update to true tells the batch provisioning system to update the information only the information you explicitly include and keep the information you did not change.

Here is an example of a title tag using the overlay-update attribute:

<title name="My New Title Name" refid="myTitle" active="TRUE" 
       flash-full-refid="asset2" overlay-update="TRUE">
  <short-description>My short description.</short-description>
</title>

With overlay-update="TRUE", your long description is preserved. Only the information you explicitly include is used to overwrite the existing record.