Metadata projections [VC 21.3 GEN]

Vidispine supports two kinds of conversion tools for automating integration with other systems.

Projection: A metadata projection is a bidirectional XSLT transformation, meant to simplify integration of the Vidispine system with several third party systems.
Auto-projection: The auto-projection is used to interact on metadata changes. For example, a change to one field may automatically trigger changes to other fields.

Projections

A projection consists of an incoming and an outgoing XSLT transformation.

The incoming projection transforms information in some format to a format supported by Vidispine.
The outgoing projection transforms information from Vidispine to a some other format.

When you use projections to transform item metadata then the outgoing projection will transform a MetadataListDocument and the incoming projection must produce a MetadataDocument.

Projection id

Projections are identified by a projection id of the regular expression form: [_A-Za-z][_A-Za-z0-9]*, maximum 32 characters. The projection is is case sensitive.

Example

This is an example of valid XSL:

HTML/XML

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vs="http://xml.vidispine.com/schema/vidispine">

<xsl:template match="/">
  <metadata>
  <item><xsl:value-of select="vs:MetadataListDocument/vs:item/@id"/></item>
    <xsl:for-each select="vs:MetadataListDocument/vs:item/vs:metadata/vs:timespan/vs:field">
      <metadataField>
        <name><xsl:value-of select="vs:name"/></name>
        <xsl:for-each select="vs:value">
          <value><xsl:value-of select="."/></value>
        </xsl:for-each>
      </metadataField>
    </xsl:for-each>
  </metadata>
</xsl:template>
</xsl:stylesheet>

XSLT 2.0

XSL Transformations version 2.0 are supported. Remember to specify the correct version in the stylesheet.

It is possible to access job information in the XSLT. This is done by adding the element <vs:vsXSLTVersion>2</vs:vsXSLTVersion> (xmlns:vs="http://xml.vidispine.com/schema/vidispine") at the global level of the XSLT. When the xsltVersion option is set, the actual input to the transformation is no longer a MetadataListDocument, but an ExportInformationDocument. The new input contains two element:

metadataList: The same as the old input to the transformation.
job: The current job, as outputted by /API/job/{jobid}?metadata=true.

Example

The following example uses both XSLT v2.0 and the job information:

HTML/XML

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vs="http://xml.vidispine.com/schema/vidispine">
    <vs:vsXSLTVersion>2</vs:vsXSLTVersion>
    <xsl:template match="/">
        <root>
            <job>
                <xsl:value-of select="vs:ExportInformationDocument/vs:job/vs:jobId/text()"/>
            </job>
            <custom>
                <xsl:for-each select="vs:ExportInformationDocument/vs:job/vs:data[vs:key='custom']/vs:value/tokenize(.,',')">
                    <data>
                        <xsl:value-of select="."/>
                    </data>
                </xsl:for-each>
            </custom>
        </root>
    </xsl:template>
</xsl:stylesheet>

Auto-projection rules

The auto projection is used to interact on metadata changes. For example, a change to one field may automatically trigger changes to other fields.

An AutoProjectionRuleDocument contains of four parts: <step>, <description>, <inputFilters> and <triggers>.

MetadataWrapperDocument

During the projection, a temporary structure called “MetadataWrapperDocument” is created for manipulation.

A MetadataWrapperDocument contains some of the fields below, depending on the values of inputFilters in AutoProjectionRuleDocument :

`metadata`	The new incoming item metadata
`oldMetadata`	The old metadata of the item
`shapeMetadata`	The new incoming shape metadata
`shape`	The shape list of the item
`bulkyMetadata`	The new incoming bulky metadata of the item or shape
`oldBulkyMetadata`	The old bulky metadata of the item

Projection steps

Multiple projection steps can be defined in different <step>, with their execution order, description, and script/XSLT respectively. Please note that <script> and <xslt> are used to hold JavaScript and XSLT respectively and each step can only contain one of them.

Example:

HTML/XML

<step>
  <order>1</order>
  <description>step1 description</description>
  <script>...</script>
</step>
<step>
  <order>2</order>
  <description>step2 description</description>
  <xslt>...</xslt>
</step>

Input filters

Input filter defines which information should goes into the MetadataWrapperDocument during the projection. There are two kinds of filters: inputFilter and bulkyMetadataKeysRegex

Legal values of inputFilter are

`oldMetadata`	Add old metadata of the item into the MetadataWrapperDocument
`shapeDocument`	Add old shape metadata of the item into the MetadataWrapperDocument

All bulky metadata of the item whose key matches the pattern defined in bulkyMetadataKeysRegex will go into MetadataWrapperDocument. Multiple filters are allowed.

Example:

HTML/XML

<inputFilters>
  <inputFilter>oldMetadata</inputFilter>
  <inputFilter>shapeDocument</inputFilter>
  <bulkyMetadataKeysRegex>.*</bulkyMetadataKeysRegex>
</inputFilters>

Rule triggers

Rule triggers defines what kinds of metadata update triggers this rule. They are:

`itemMetadata`	Rule triggered if there is an item metadata update
`shapeMetadata`	Rule triggered if there is a shape metadata update
`bulkyMetadata`	Rule triggered if there is a bulky metadata update

Multiple triggers are allowed.

HTML/XML

<triggers>
  <trigger>itemMetadata</trigger>
  <trigger>shapeMetadata</trigger>
</triggers>

Auto-projection using JavaScript

A JavaScript projection is created by including the JavaScript in the script element of AutoProjectionRuleDocument. The script will be interpreted using a JavaScript engine.

A number of global variables are defined for the script to use:

api
helper
wrapper

The api object

Please see The api object.

The helper object

Please see The metadatahelper object. In Auto-projection scripts, it is also available under the name helper.

The wrapper object

The wrapper object represents the MetadataWrapperDocument during the projection. Below are available functions:

wrapper.getMetadata()

Get the new incoming item metadata.

Returns:

MetadataType.

wrapper.getOldMetadata()

Get the old metadata of the item.

Returns:

MetadataListType.

wrapper.getShapeMetadata()

Get the new incoming shape metadata.

Returns:

SimpleMetadataType.

wrapper.getShape()

Get the shape list of the item.

Returns:

List<ShapeType>.

wrapper.getBulkyMetadata()

Get the new incoming bulky metadata of the item/shape.

Returns:

BulkyMetadataType.

wrapper.getOldBulkyMetadata()

Get the old bulky metadata of the item.

Returns:

BulkyMetadataType.

wrapper.getOldBulkyMetadata()

Get the old bulky metadata of the item.

Returns:

BulkyMetadataType.

wrapper.setMetadata(value)

Assign a new metadata to the wrapper document.

Arguments:

value – MetadataType

There are two ways to apply projection results to an item:

If the rule is triggered by an item metadata update, one should manipulate the object reference returned by wrapper.getMetadata() directly. Because Vidispine will take that object as the projection result.

If the rule is triggered by a shape metadata update or bulky metadata update, one should use the api object to update the item metadata:

JAVASCRIPT

var metadata = helper.createMetadata();
...
var xml = helper.metadataToStr(metadata);
var id = wrapper.getTargetId();
var result = api.path("item/" + id + "/metadata").input(xml, "application/xml").put();

Auto-projection using XSLT

A XSLT projection is created by including the XSL script in the xsl element of AutoProjectionRuleDocument.

The transformation result could either be a MetadataDocument or MetadataWrapperDocument. If the result is a MetadataWrapperDocument, the value of metadata element will be used as the projection result.

During a shape/bulky metadata update, one need to set up another step using the JavaScript api object to update the item metadata.

Example:

HTML/XML

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:vs="http://xml.vidispine.com/schema/vidispine">
    <xsl:template match="/">
        <MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
            <timespan start="-INF" end="+INF">
                <xsl:for-each select="vs:MetadataWrapperDocument/vs:metadata/vs:timespan/vs:field">
                    <field>
                        <name>
                            <xsl:value-of select="vs:name"/>
                        </name>
                        <value><xsl:value-of select="vs:value"/>+projection</value>
                    </field>
                </xsl:for-each>
            </timespan>
        </MetadataDocument>
    </xsl:template>
</xsl:stylesheet>