Metadata projections¶
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:
<?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¶
New in version 4.2.
XSL Transformations version 2.0 are supported. Remember to specify the correct version in the stylesheet.
Job Information¶
New in version 4.2.
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:
<?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:
<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:
<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.
<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. Vidispine is using Rhino as the 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¶
The helper object contains some convenient functions for generating a new metadata object.
- helper.createMetadata()¶
Returns a new MetadataType.
- helper.createMetadataTimespan(start, end)¶
Returns a new MetadataType.Timespan.
Arguments: - start (string) – The start timecode.
- end (string) – The end timecode.
- helper.createMetadataGroup(name)¶
Returns a new MetadataGroupValueType.
Arguments: - name (string) – The name of the group.
- helper.generateMetadataField(name, value)¶
Returns a new MetadataFieldValueType.
Arguments: - name (string) – The name of the field.
- value (string) – The field value.
- helper.metadataToStr(metadata)¶
Translate a metadata object to a string.
Arguments: - metadata – MetadataType
- helper.log(obj)¶
Write the value of obj.toString() to the server log.
The following example script
var metadata = helper.createMetadata();
var timespan = helper.createMetadataTimespan("0", "100");
var group = helper.createMetadataGroup("mrk_marker");
var field1 = helper.createMetadataField("mrk_color", "red");
group.getField().add(field1);
timespan.getGroup().add(group);
metadata.getTimespan().add(timespan);
will generate a metadata object like this:
<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<timespan start="0" end="100">
<group>
<name>mrk_marker</name>
<field>
<name>mrk_color</name>
<value>red</value>
</field>
</group>
</timespan>
</MetadataDocument>
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:
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:
<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>