Export Templates [VC 21.3 GEN]

Developer preview

Export templates describe a structure for material exported.

Concepts

The export template is defined in an XML or JSON structure. It can be considered as a “super shape”, or “super transcoder template”, as it builds on top of the shape definitions of items.

Structure

During the execution of the export template, the XML/JSON elements are instantiated as nodes. Each node (element) in the definition represents either:

data, such as the content of a shape (component) or text content
a selection, such as a shape of an item
operations on subnodes, such as creating an archive (zip)

Some nodes are mapped 1-1 to the definition elements. Some nodes are expanded during execution, such as the shapes of the item, which are expanded to the actual number of shapes.

Dependencies

Nodes are expanded (but not executed) and subnodes are created when all dependencies are met.
Nodes cannot be executed before subnodes have executed.
Inter-node dependency can be configured by tag/dependency elements in the node definition

Common node elements

tag: A list of strings that this node defines.
dependency: A list of strings that this node depends on. Example: node 1 has tag=a, node 2 has tag=a,b, node 3 has dependency=a, node 4 has dependency=b. The node 3 can execute after node 1 and node 2 has executed. Node 4 can execute after node 2 has executed.
filter: A script that controls whether an instance of a node should be executed or not. Example, in a shape node, filter can control which shapes should be executed. If the script returns false, the node is skipped.
pre: A script that runs before a node is instantiated. Can be used to compute common values, or to set tag/dependency values.

In addition, nodes have an optional path attribute, that sets the output name of the element.

Scripts

Export templates make heavy use of ECMAScript (JavaScript) code. The scripts are used both for flow control, but also for inlining computed results. Inlining is done by writing the script inside {{ and }}.

The scripts are running in a context (scope). The context is available as variables in the script. The context is inherited to subnodes. In addition to the Common JavaScript functions, the following objects are defined:

xml: Object with two functions defined. indent(string, spaces), which reformats a XML. Default value for spaces is 2. xml(object), which takes a JAXB object (see Javadoc) and generates an XML string.
item: Represents the current item in context (if any). Four functions defined: id(), returns the item id, struct(), returns the JAXB object of ItemType, xml(), returns the XML string of the ItemDocument, json(), returns the JSON string of the ItemDocument.
metadata: Represents the metadata of current item. Can be used as metadata.field(fieldName).value().
node: The JAXB structure of the current node.
tag: The dependency tags this node defines, as an array. Can be modified.
dependency: The dependency tags this node depends on, as an array. Can be modified, but if execution has already started, the value is ignored.
global: An empty object that is shared by all nodes.
tags: Object with one function defined, get(tag) that returns the first node that has that tag defined. The object returned defines three functions, path() that returns the named output of the node, size() that returns the number of bytes outputted of the node, checksum(algorithm) that returns the checksum/hash of the output generated by the node. Examples of algorithms are MD5 and SHA-1.

Example

<text path="{{item.id()}}.txt">
    ...

Node types

`text`

Creates text content. For plain text (with {{ }} substitution), use the content element. For XML content which can embed other nodes, use the xml element.

`item`

Expands to the all items that will be exported. For item export, that is one. For collection or library export, it is all items in the collection or library. The item node does not generate any output by itself, it must contain subnodes for that to happen.

`shape`

Expands to all shapes of the current item. If the shapeTag element is present, only the shapes matching the given set of shape tags. If generate is true, the shapes are generated (transcoded) if they do not already exist. In the generated subnodes, the following objects are defined:

shape: The JAXB object of ShapeType.

`componentfile`

Expands to all files defined in the shape. In the generated subnodes, the following objects are defined:

file: The JAXB object of FileType
components: An object containing all components that uses the current file. The key is the component id, the value is the JAXB object of ComponentType.

`folder`

Modifies all generated content by subnodes by prepending a folder name.

`archive`

Puts all generated content by subnodes in an archive format (zip or tar).

`compress`

Compresses the generated content by subnodes (gz or bzip2). The subnodes may only generate one output.

`external`

Includes other content, references by URI.

`iterate`

Expands into new subnodes as specified by the value element. The value element may be specified multiple times, or it may contain comma-separated values. In the generated subnodes, the following objects are defined:

value: The current value of the subnode.

Example

<ExportTemplateDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <item>
        <archive method="TAR" path="{{item.id()}}.tar">
            <text path="metadata.xml">
                <pre>
                    providerid="vidispine.example.com";
                    var now = new Date();
                    var yyyy = now.getFullYear().toString();
                    var mm = (now.getMonth()+1).toString(); // getMonth() is zero-based
                    var dd = now.getDate().toString();
                    var creationdate=yyyy + "-" + (mm[1]?mm:"0"+mm[0]) + "-" + (dd[1]?dd:"0"+dd[0]);
                    var assetidcounter = 0;
                    function getassetid() {
                       return ""+assetidcounter++;
                    }
                    function m(field) {
                       return metadata.field(field).value();
                    }
                </pre>
                <xml indent="2">
                    <DEFINITION xmlns="http://example.com/">
                        <Metadata>
                            <Header
                                 Description="mydescription" Creation_Date="{{creationdate}}" Provider_ID="{{providerid}}"
                                 Asset_ID="{{getassetid()}}" Asset_Class="package"/>
                        </Metadata>
                        <Asset>
                            <Metadata>
                                <Header Description="" Creation_Date="{{creationdate}}"
                                     Provider_ID="{{providerid}}" Asset_ID="{{getassetid()}}" Asset_Class="title"/>
                                <App_Data Name="Title" Value="{{m('title')}}"/>
                            </Metadata>
                            <shape xmlns="http://xml.vidispine.com/schema/vidispine">
                                <pre>
                                    var content=tags.get('mp4');
                                </pre>
                                <dependency>mp4</dependency>
                                <shapeTag>__mp4</shapeTag>
                                <generate>false</generate>
                                <text>
                                    <xml indent="2">
                                        <Asset xmlns="http://example.com/">
                                            <Metadata>
                                                <Header
                                                     Provider_ID="{{providerid}}" Asset_ID="{{getassetid()}}"
                                                     Asset_Class="movie"/>
                                                <App_Data Name="Content_FileSize" Value="{{content.size()}}"/>
                                                <App_Data Name="Content_CheckSum" Value="{{content.checksum('MD5')}}"/>
                                            </Metadata>
                                            <Content Value="{{content.path()}}"/>
                                            <ExampleValue>
                                                <iterate xmlns="http://xml.vidispine.com/schema/vidispine">
                                                    <value>somevalue</value>
                                                    <pre>node.getValue().add("somevalue2");</pre>
                                                    <text>
                                                        <content>{{value}}</content>
                                                    </text>
                                                </iterate>
                                            </ExampleValue>
                                        </Asset>
                                    </xml>
                                </text>
                            </shape>
                        </Asset>
                    </DEFINITION>
                </xml>
            </text>
            <shape xmlns="http://xml.vidispine.com/schema/vidispine">
                <componentfile path="hd.mp4">
                    <tag>mp4</tag>
                </componentfile>
                <shapeTag>__mp4</shapeTag>
                <generate>true</generate>
            </shape>
        </archive>
    </item>
</ExportTemplateDocument>

item enters the scope of the exported item. If multiple items where exported, this node will expand automatically to all items.
archive generates a tar file. The name of tar file is based on the item id, using substitution.
text generates a text file inside the tarball. The pre element defines some utility functions.
The content of the text file will be xml. Inside the xml element, export template directives can be mixed with other xml content, based on the namespace. The content of the other xml is subject to {{ }} substitution.
The shape element inside of the xml element will not be executed before the shape element at the end of the document has executed, due to the tag/dependency link.
In ExampleValue, an iterate block will be generated twice, once with value=somevalue, once with value=somevalue2. The text content of ExampleValue will be somevaluesomevalue2.
The last shape element will generated a __mp4 shape tag of the item. It will also include the actual component of the shape.

The output of this export template, applied to the item VX-345, will be a tar file named VX-345.tar, containing metadata.xml and hd.mp4.