Metadata Projection


A "metadata projection" is a directional XSLT transformation.

  • An "incoming projection" is used to transform a thirty-party xml file arriving at the metadata update endpoint to a "MetadataDocument". This is equivalent to something like:

xsltproc projection.xml input.xml | curl -X PUT -uadmin:admin -d@- -Hcontent-type:application/xml http://localhost:8080/API/item/VX-1683/metadata

  • An "outgoing projection" can be used to transform item metadata to a third-party xml format when the item is exported.

Incoming projection example

Create an incoming projection called p1

PUT /API/projection/p1/incoming @projection-in.xml

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:template match="/">
    <MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
      <timespan start="-INF" end="+INF">
        <xsl:for-each select="catalog/cd">
          <group>
            <name>cd_catalog</name>
            <field>
              <name>title_field</name>
              <value>
                <xsl:value-of select="title"/>
              </value>
            </field>
            <field>
              <name>artist_field</name>
              <value>
                <xsl:value-of select="artist"/>
              </value>
            </field>
          </group>
        </xsl:for-each>
      </timespan>
    </MetadataDocument>
  </xsl:template>
</xsl:stylesheet>
CODE

And then update item metadata using

PUT /API/item/VX-1631/metadata?projection=p1 @input.xml

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
  <cd>
    <title>Empire Burlesque</title>
    <artist>Bob Dylan</artist>
    <country>USA</country>
    <company>Columbia</company>
    <price>10.90</price>
    <year>1985</year>
  </cd>
</catalog>
CODE

The result metadata will contain something like:

<?xml version="1.0"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="-INF" end="+INF">
    <group>
      <name>cd_catalog</name>
      <field>
        <name>title_field</name>
        <value>Empire Burlesque</value>
      </field>
      <field>
        <name>artist_field</name>
        <value>Bob Dylan</value>
      </field>
    </group>
  </timespan>
</MetadataDocument>
CODE

Outgoing projection example

Create an outgoing projection:

PUT /API/projection/p2/outgoing @projection-out.xml

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
                xmlns:vs="http://xml.vidispine.com/schema/vidispine"
                exclude-result-prefixes="vs">
  <xsl:template match="/vs:MetadataListDocument">
    <catelog>
        <xsl:for-each select="vs:item/vs:metadata/vs:timespan/vs:group[vs:name='cd_catalog']">
          <cd>
            <title><xsl:value-of select="vs:field[vs:name='title_field']/vs:value"/></title>
            <artist><xsl:value-of select="vs:field[vs:name='artist_field']/vs:value"/></artist>
          </cd>
        </xsl:for-each>
    </catelog>
  </xsl:template>
</xsl:stylesheet>
CODE

Create an export location for the item export:

PUT /API/export-location/location1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ExportLocationDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>file:///tmp/loc1/</uri>
</ExportLocationDocument>
CODE

And then export the item using:

POST /API/item/VX-1631/export?locationName=location1&metadata=true&projection=p2

The item metadata in the Incoming projection example above will be transformed back to:

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
  <cd>
    <title>Empire Burlesque</title>
    <artist>Bob Dylan</artist>
    <country>USA</country>
    <company>Columbia</company>
    <price>10.90</price>
    <year>1985</year>
  </cd>
</catalog>
CODE

Auto-projection (Calculated Fields)

Metadata auto-projection is a way to update item metadata automatically when there is an API request updating the metadata, bulky metadata or shape metadata of the target item. The final metadata applied to the item is calculated by the defined script. The configuration is managed by the Auto-projection rule endpoints

Example:

Below is an example of AutoProjectionRuleDocument:

<AutoProjectionRuleDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <step>
    <order>1</order>
    <description>step description1</description>
    <script>
​
var metadata = wrapper.getMetadata();
var timespans = metadata.getTimespan();
var timespanSize = timespans.size();
var value1, value2, value3;
var shapetag = wrapper.shape.get(0).getTag()
for (var i = 0; i &lt; timespanSize; ++i) {
    var timespan = timespans.get(i);
    var metadataFields = timespan.getField();
    var fieldSize = metadataFields.size();
    for (var j = 0; j &lt; fieldSize; ++j) {
        var metadataField = metadataFields.get(j);
        if (metadataField.getName() == "asset_url"){
            value1 = metadataField.getValue().get(0).getValue();
            
        }
        if (metadataField.getName() == "asset_company") {
            value2 = metadataField.getValue().get(0).getValue();
            
        }
    }
    value3 = value1 + "_" + value2 + "_" shapeTag;
    var newField = helper.createMetadataField("asset_info", value3);
    metadataFields.add(newField);
}
​
    </script>
  </step>
  <name>rule-name</name>
  <description>rule description</description>
  <inputFilters>
    <inputFilter>oldMetadata</inputFilter>
    <inputFilter>shapeDocument</inputFilter>
    <bulkyMetadataKeysRegex>.*</bulkyMetadataKeysRegex>
  </inputFilters>
  <triggers>
    <trigger>itemMetadata</trigger>
    <trigger>shapeMetadata</trigger>
  </triggers>
</AutoProjectionRuleDocument>
CODE

The <triggers/> element defines which API request would trigger this script. In this case, an item metadata or shape metadata update request would trigger this script.

The <inputFilters/>section defines how the different attributes in the wrapper object will be constructed. In this case:

  • wrapper.oldMetadatawill contain the current metadata, because there is an oldMetadatainput filter.

  • wrapper.shape will contain the current item shape document, because of the shapeDocumentfilter.

  • wrapper.metadatawill contain the incoming item metadata, if this is triggered by an item metadata update.

The <script/> section contains the actual script that will be run during the projection.

Assuming an item metadata update request like blow, and the tag of the first shape is mp4:

PUT /API/item/VX-1/metadata
​
<?xml version="1.0" encoding="UTF-8"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="10@PAL" end="20@PAL">
      <field>
        <name>asset_url</name>
        <value>example.com</value>
      </field>
      <field>
        <name>asset_company</name>
        <value>Arvato</value>
      </field>
  </timespan>
</MetadataDocument>
​
CODE

The resulting metadata on the item would be:

<?xml version="1.0" encoding="UTF-8"?>
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="10@PAL" end="20@PAL">
      <field>
        <name>asset_url</name>
        <value>example.com</value>
      </field>
      <field>
        <name>asset_company</name>
        <value>Arvato</value>
      </field>
      <field>
        <name>asset_info</name>
        <value>example.com_Arvato_mp4</value>
      </field>
  </timespan>
</MetadataDocument>
CODE

Note the "calculated" field asset_info in the final result.