CONTENTS

INTRODUCTION
SCOPE OF THE DOCUMENT
METADATA SIDECAR INGEST
STEPS FOR INGEST AUTOMATION WITH SIDECAR XML
VALIDATE YOUR XML
PRE-REQUISITES
SAMPLE XML
XML STRUCTURE

• 1. IDENTIFY THE XML
• 2. ROOT TAG
• 3. EMAM ASSET
  • 3.1 File name:
  • 3.2 File path:
  • 3.3 Asset id
  • 3.4 Ingest actions:
  • 3.5 File Action:
• 4. TAGS:
• 4.1 Basic Metadata
• 4.2 Custom Metadata
• 4.3 Markers
• 4.4 Subclips
• 4.5 Projects
• 4.6 Categories
• 4.7 Associate File

INGEST ACTION AND ATTRIBUTE COMBINATIONS
SAMPLE XML FILE

• A. CREATE-NEW-ASSET:
• B. CREATE-NEW-VERSION
• C. ASSOCIATE-METADATA
• D. CREATE-ASSET-PLACEHOLDER

KNOWN ISSUES
GLOSSARY
GET HELP

Introduction

eMAM has defined an XML schema (a description of the structure of xml) for creating the ingest sidecar XML files. This is a reference document for creating the ingest sidecar XML files when using the eMAM sidecar ingest option. This enables you to ingest multiple videos and associated metadata by dropping the XML files into the configured ingest watch folder. eMAM will validate the XML file against the predefined rules defined in the XML Schema Definition (XSD) and if it fails, it will be shown as validation error in eMAM ingest dashboard.

Scope of the Document

The purpose of this document is to describe the XML specifications and code samples of the required elements and the attributes that you must include in the eMAM Sidecar ingest XML file.

Metadata Sidecar Ingest

Side car files are the files that come along with the source files and hold the metadata of the source files. Based on the eMAM defined Xml schema, Xml files which follow this schema are parsed by the eMAM Ingest Manager to extract the metadata given in that xml and perform actions based on that. The metadata xml can be ingested alone or with the source files. eMAM Ingest manager parses the xml, collects the information from xml and updates the database. This automates the process of metadata association with the asset in the eMAM system.

Steps for Ingest Automation with sidecar XML

To use the Ingest automation with sidecar xml feature, follow below steps:

• Prepare your list of assets.
• Create an XML file for assets that needs to be ingested to eMAM.
• Drop the XML file to the configured ingest folder.
• Wait for processing to complete.
• If there is any validation error associated with the XML file, error message will be displayed in the eMAM dashboard.
• Fix the error in XML file and resubmit the job from the dashboard.

Validate your XML

You can validate your XML file against the XSD and to ensure that it is free of invalid or illegal characters which need to be removed. If left unfixed, these characters could cause failures during the ingest process. Here is the list of illegal characters and its representation in XML:

• & should be represented as &
• < and > should be represented as < and >
• ' and " should be represented as ' and "

A comma (,) cannot be included in a tag. The reason behind this is that tags are stored internally as comma separated lists, and unexpected commas cause issues.

Pre-requisites

Few pre-requisites for ingest automation with the Metadata Sidecar XML are:

• If a user needs to upload both source files and the metadata XML to ingest folders, an ingest profile should be created by the Super Admin with XCode Type as ‘SidecarXMLIngest’.
• There should be at least one Unit Admin user created in eMAM and associated with the Sidecar XML Ingest profile.
• A Unit Admin user key. User key can be obtained from the eMAM Admin interface or from the eMAM Director interface>Admin Tools page>Manage Users> edit user>Manage User key tab.

Sample XML

Below is a sample of a basic XML file. All the tag names and attributes used in the xml file are case sensitive and should be used as it is.

XML Structure

Users need to follow the below mentioned XML structure specified by eMAM.

1. Identify the XML

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

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

2. Root Tag

eMAM: For user authentication, provide the user key from the manage users section in the Admin Tools page. This user should be associated with at least one ingest profile with ‘SidecarXMLIngest’ option enabled in order to use the sidecar XML ingest option. Otherwise, an error will show up in the dashboard “user xyz is not associated with the ingest profile” Required- This automatic ingest-specific (eMAM user key) tag marks the beginning of the upload.

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA="> 

3. eMAM asset

For all the assets which needs to be uploaded, please specify following attributes for each asset in the Xml file.

<asset file-name="Ads1.mov" ingest-action="create-new-version" file-action="copy-file" file-path="\\102.10.0.148\shareddelvry\Videos" asset-id="30494">

Asset attributes: <asset> tag uses following attributes:

• 3.1 File name: Name of the source file.
• 3.2 File path: Source location of the asset. (File path can also be an Http URL.

e.g.: file-path="http://10.0.20.15/Highres". Http URL as file path can be used with Create new asset, create new version and associate files)

• 3.3 Asset id: Id of an asset from eMAM. Asset Id can be obtained from the version widget, API, asset state report or from the SQL report. Note: If asset id is equal to 0, it will create a placeholder for a new asset.
• 3.4 Ingest actions: Various actions that can be performed during Ingest are mentioned below:

• 3.5 File Action: Various actions that can be performed for an asset during ingest.

4. Tags:

Various tags that can be associated with assets are:

               <basic-metadata>

                     <title>Ads1</title>

                     <description>first ad-based video test description</description>

                     <author>John Garyson</author>

              </basic-metadata>

4.1 Basic Metadata:

Basic metadata details of an asset can be updated by providing title, description and author details.

4.2 Custom Metadata

After you have created the custom metadata fields and assigned them to Metadata groups and Metadata Sets in the eMAM Director Admin Tools page, you can use the metadata standard id (associated with the metadata fields) and standard set id (associated with the metadata sets) in the XML to set the custom metadata values for an asset. Both these values can be obtained from the Manage Metadata section in the eMAM Director Admin Tools page. The field values should be validated before submitting the XML. Metadata field Standard-id for custom metadata fields are mandatory attributes for each field tag however Metadata Set-standard-id is optional. Note: If Set-standard-id is not provided, you will not be able to see the associated metadata in the Director Interface, unless it is already associated. Custom metadata details of an asset can be updated with a value that matches the field-type (integer, string, list-item, float, date-time or time-code) provided the unique standard-id for that field exists in the eMAM system otherwise ingest will fail. Therefore, please ensure that the metadata standard id and set standard id exists in the eMAM system before you start with the ingest. If the standard id or set standard id do not exist in eMAM, eMAM ingest manager will ignore those metadata fields. During ingest of a new version of an asset, existing metadata values will be overwritten with the values from the XML.

             <custom-metadata set-standard-id="CUST_SET_7576">

                     <field standard-id="CUST_FLD_APPROVED_TXT_595">Approved</field>

                     <field standard-id="CUST_FLD_APPROVED_ON_TXT_595">02/12/2016</field>

              </custom-metadata>

Note: *standard-id: Unique id for each metadata field which can be obtained from eMAM Admin interface>Tools>Administrator tools>Metadata Fields OR, eMAM Director Interface>Admin Tools>Manage  Metadata>Metadata Fields>Standard Id.

*set standard-id: Unique id for each metadata set which can be obtained from eMAM Admin interface>Tools>Administrator tools> Metadata Set OR, eMAM Director interface>Admin Tools>Manage Metadata>Metadata Set>Standard Id

*Element value: Metadata value should be entered between the field opening and closing XML tags.

4.3 Markers

Markers of a video asset can be updated using the XML with name, time-code, duration and description details.

<markers>

<marker name="my_marker1" time-code="00:05:44:10" duration="00:00:00:00">The first filter for the video starts from here</marker>

<marker name="my_marker2" time-code="00:09:44:14" duration="00:00:00:00">The second filter for the video starts from here</marker>

</markers>

4.4 Subclips

Sub clips information of a video asset can be updated with subclip name, subclip type (Std or Tx), start-time and end-time details.

<subclips>

<subclip type=”std” name="sb_clp1" start-time="05:59:51:13" end-time="07:00:36:00" />

<subclip type=”tx” name ="sb_clp2" start-time="08:25:10:13" end-time="14:00:36:00" />

</subclips>

4.5 Projects

Assets can be associated with one or more Projects. Bins inside the project can be defined inside the XML with forward slash (/) after the project name. Ingested assets will be automatically assigned to the specified project or bin. Project structure will be created automatically if it does not exist in eMAM system.

<projects>

<project name="Project5/New"/>

</projects>

4.6 Categories

Assets can be associated with one or more Categories. Subcategories can be defined inside the XML with a forward-slash (/) after the category name. Ingested assets will be automatically assigned to the specified categories. Category structure will be created automatically if it does not exist in the eMAM system.

<categories>

<category name="Main/Approved_Items"/>

<category name="Videos/Ads"/>

</categories>

4.7 Associate File

Assets can be associated with the Original, Proxy and Mezzanine files. You can also attach key frames as thumbnails for videos. Note: It can be attached from http URL too.

<asset asset-id="30494" ingest-action="associate-metadata" file-name="NewVideo1.mp4" version-id="35662">

<associate file-type="original" file-action="copy" file-exist-action="replace" file-name="A013C009_160219_R0S7.mov" file-path="D:\Project A\Bin" />

       <associate file-type="platform" file-action="copy" platform-id="1" file-name="A013C009_160219_R0S7.mp4" file-path="D:\Project B\Clip" />

       <associate file-type="thumbnail" file-action="move" file-name="hd_wallpapers_forbackground_2015.jpg" file-path="G:\Test Assets\Images" />

Ingest action and Attribute Combinations

Various ingest actions and its combinations with different attributes are mentioned in the below figure:

Sample XML file

Assets ingested using XML file with various ingest actions: Using one Xml file, you can automatically ingest any no. of assets to eMAM. Details of each asset can be included like basic metadata, custom metadata, associate files, markers, subclips, projects, categories that needs to be associated with the asset. eMAM Ingest manager will process each asset based in the “ingest action” and “file action” specified in the XML. Below is a sample XML file used for automated ingest of 4 assets with different ingest actions.

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

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA=">

       <asset file-name="Heartbeat.avi" ingest-action="create-new-asset" file-action="copy-file" file-path="\\10.0.8.40\emamfolders\xmlingest">

              <basic-metadata>

                     <title>Heartbeat</title>

                     <description>Euphoria is the ninth studio album by Spanish singer-songwriter Enrique Iglesias. </description>

                     <author>John Garyson</author>

              </basic-metadata>

              <markers>

                     <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The best part of the album</marker>

              </markers>

              <subclips>

                     <subclip type=”std” name="subclip1" start-time="00:00:01:43" end- time="00:00:03:43"/>

                     <subclip type=”tx” name="subclip2" start-time="00:00:03:53" end-time="00:00:06:43"/>

              </subclips>

              <projects>

                     <project name="NewProjects/Albums"/>

                     <project name="LatestCollections/Videos"/>

              </projects>

              <categories>

                     <category name="Albums/Enrique/Euphoria"/>

              </categories>

       </asset>

       <asset asset-id="30544" file-path="\\10.0.8.40\emamfolders\xmlingest" file-action="move" ingest-action="create-new-version" file-name="Ayer1.avi">

              <basic-metadata>

                     <title>Ayer</title>

                     <description>'Ayer' by Enrique Iglesias.</description>

                     <author>Johan</author>

              </basic-metadata>

              <custom-metadata>

                     <field standard-id="CUST_FLD_TXT_DATETIME_598">02/23/2015</field>

                     <field standard-id="CUST_FLD_TST_INT_596">15</field>

                     <field standard-id="CUST_FLD_TXT_TIMECODE_599">00:02:05:29</field>

              </custom-metadata>

              <markers>

                     <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The first part of the album from here</marker>

                     <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The second part of the album from here</marker>

              </markers>

              <projects>

                     <project name="NewProjects/Album1"/>

              </projects>

             

       </asset>

       <asset asset-id="30494" ingest-action="associate-metadata" file-name="NewVideo1.mp4">

              <basic-metadata>

                     <title>NewVideo1.mp4</title>

                     <description>The All new video from the Collection</description>

                     <author>John Garyson</author>

              </basic-metadata>

              <custom-metadata>

                     <field standard-id="CUST_FLD_TST_LIST_595">VideoCategory1</field>

                     <field standard-id="CUST_FLD_TXT_DATETIME_598">02/03/2016</field>

                     <field standard-id="CUST_FLD_TXT_TIMECODE_599">00:00:25:50</field>

                     <field standard-id="CUST_FLD_TXT_FLOAT_597">29.97</field>

              </custom-metadata>

              <categories>

                     <category name="Albums/Enrique/Ayer"/>

              </categories>

       </asset>

       <asset ingest-action="create-asset-placeholder" file-name="NextAlbum.avi">

              <basic-metadata>

                     <title>NextAlbum</title>

                     <description>Place holder for Next album video </description>

                     <author>Justin</author>

              </basic-metadata>

       </asset>

</eMAM>

a. create-new-asset:

Asset 1.

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

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA=">

<asset file-name="Heartbeat.avi" ingest-action="create-new-asset" file-action="copy-file" file-path="\\10.0.8.40\emamfolders\xmlingest">

          <basic-metadata>

                 <title>Heartbeat</title>

                 <description>Euphoria is the ninth studio album by Spanish singer-songwriter Enrique Iglesias. The album is a joint-release by Universal Republic and Universal Music Latino and was released on 5 July 2010 internationally and in the US on 6 July 2010</description>

                 <author>John Garyson</author>

          </basic-metadata>

          <markers>

                 <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The best part of the album</marker>

          </markers>

          <subclips>

                 <subclip type=”std” name="subclip1" start-time="00:00:01:43" end-time="00:00:03:43"/>

                 <subclip type=”tx” name="subclip2" start-time="00:00:03:53" end-time="00:00:06:43"/>

          </subclips>

          <projects>

                 <project name="NewProjects/Albums"/>

                 <project name="LatestCollections/Videos"/>

          </projects>

          <categories>

                 <category name="Albums/Enrique/Euphoria"/>

          </categories>

  </asset>

      </eMAM>

b. create-new-version

Asset 2.

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

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA=">

<asset asset-id="30544" file-path="\\10.0.8.40\emamfolders\xmlingest" file-action="move" ingest-action="create-new-version" file-name="Ayer1.avi">

          <basic-metadata>

                 <title>Ayer</title>

                 <description>'Ayer' by Enrique Iglesias.</description>

                 <author>Johan</author>

          </basic-metadata>

          <custom-metadata>

                 <field standard-id="CUST_FLD_TXT_DATETIME_598">02/23/2015</field>

                 <field standard-id="CUST_FLD_TST_INT_596">15</field>

                 <field standard-id="CUST_FLD_TXT_TIMECODE_599">00:02:05:29</field>

          </custom-metadata>

          <markers>

                 <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The first part of the album from here</marker>

                 <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The second part of the album from here</marker>

                 <marker name="marker1" time-code="00:00:01:10" duration="00:00:00:00">The third part of the album from here</marker>

          </markers>

          <projects>

                 <project name="NewProjects/Album1"/>

          </projects>

         

   </asset>

</eMAM>

c. associate-metadata

Asset 3.

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

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA=">

<asset asset-id="30494" ingest-action="associate-metadata" file-name="NewVideo1.mp4" version-id="35662">

          <associate file-type="original" file-action="copy" file-exist-action="create-new-version" file-name="A013C009_160219_R0S7.mov" file-path="D:\Project A\Bin" />

            <associate file-type="platform" file-action="copy" platform-id="1" file-name="A013C009_160219_R0S7.mp4" file-path="D:\Project B\Clip" />

              <basic-metadata>

                 <title>NewVideo1.mp4</title>

                 <description>The All new video from the Collection</description>

                 <author>John Garyson</author>

          </basic-metadata>

          <custom-metadata>

                 <field standard-id="CUST_FLD_TST_LIST_595">VideoCategory1</field>

                 <field standard-id="CUST_FLD_TXT_DATETIME_598">02/03/2016</field>

                 <field standard-id="CUST_FLD_TXT_TIMECODE_599">00:00:25:50</field>

                 <field standard-id="CUST_FLD_TXT_FLOAT_597">29.97</field>

          </custom-metadata>

          <categories>

                 <category name="Albums/Enrique/Ayer"/>

          </categories>

   </asset>

</eMAM>

d. create-asset-placeholder

Asset 4.

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

<eMAM user-key="zlEKbVGXb0UWyOavK6yQwneL7cPxV6zy6V1/+ZTxuuA=">

<asset ingest-action="create-asset-placeholder" file-name="NextAlbum.avi">

          <basic-metadata>

                 <title>Next Album</title>

                 <description>Place holder for Next album video </description>

                 <author>Justin</author>

          </basic-metadata>

   </asset>

</eMAM>

Known Issues

If the file action is copy-file, even though there are more than one categories defined in the XML file, assets will be associated only with the first category.

Glossary

XML- Extensible Markup Language

is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. XML provides a uniform method for describing and exchanging structured data that is independent of applications or vendors.

XSD- XML Schema Definition:

XML Schema describes the structure of an XML document. Schemas are useful for enforcing structure and/or constraining the types of data that can be used validly within other XML documents. XML Schema Definition refers to the fully specified and currently recommended standard for use in authoring XML schemas.

HTML (Hyper Text Markup Language)

is the standard markup language for creating web pages and web applications.

Attributes-

An XML structural construct. A name-value pair, separated by an equal’s sign, included inside a tagged element that modifies certain features of the element. All attribute values, including things like size and width, are in fact text strings and not numbers.

Elements-

An XML structural construct. An XML element consists of a start tag, an end tag, and the information between the tags, which is often referred to as the contents. Each element has a type, identified by name, sometimes called its "generic identifier" (GI), and may have a set of attribute specifications. Each attribute specification has a name and a value. An instance of an element is declared using tags.

Schema-

A formal specification of element names that indicates which elements are allowed in an XML document, and in what combinations. It also defines the structure of the document: which elements are child elements of others, the sequence in which the child elements can appear, and the number of child elements. It defines whether an element is empty or can include text. The schema can also define default values for attributes.