Metadata Manipulation API Reference

The metatdata is a hierarchical structure describing the data in a print job. It is composed of 5 basic levels, from outer to inner: Job, Group, Document, Datapage, and Page. Each level under Job can have any number of items. In addition, an item can contain any number of attributes and fields. See the metadata spec for more details.

The metadata API uses an object-oriented model to represent this structure. Each unit in the hierarchy is represented by an object called a Node. There are 5 types of Node objects, one for each level. Node objects are organized in a single-rooted tree-like structure, where each node is a collection of its lower level node type. At the top of this tree sits a single Node object named MetaJob. The MetaJob is a collection of MetaGroup objects, where each MetaGroup is a collection of one or more MetaDocument objects, and so on.

All Node objects share a number of properties and methods that are common for all Node object types. There are also properties and methods that are either unique to a specific Node object type, or shared between only a few of them.

Each Node object type is a collection of child nodes and provides methods to access its children (in other words, nodes that are located underneath that Node in the tree structure). The method's name varies to match the type of Node. For example, the child accessor method in a MetaDocument node is named Datapage. There is also a generic accessor method named Item that is common across all Node object types.

In addition, each Node object also has two properties named Attributes and Fields. These properties, respectively a MetaAttributeCollection and a MetaFieldCollection, are collection objects of metadata attributes and fields.

The metadata also defines the order in which the data is consumed by a PlanetPress Suite template. Changing the order and location of the various Node objects (except for the Page object) within the structure means that the final output will be different than the original and will follow the order dictated by the metadata instead of the order of the physical data. The Selected property is used to select whether a node is to be included in the final output or not, down to the smallest unit, the data page. If a node has it Selected property set to true, all of its child that also have their own Selected property set to true will print. If Selected is false, its child will not print, regardless of their Selected status.

All of these objects are contained in a MetaFile object. The MetaFile object is the only object that is formally published to the user. All the other objects are obtained, directly or indirectly, through methods of this object.

A standalone MetaFile object can be created using the MetadataLib.MetaFile ProgID (ex: CreateObject("MetadataLib.MetaFile") in VBScript) or the {145E89F9-C2DF-4604-821A-9BD6C4B468DA} CLSID with CoCreateInstance.

The current job's metadata file name can be obtained by calling the IWatchJob::MetadataFilename method from within IWatchPlugin::Execute when writing a plugin using the plugin SDK, or using the Watch.GetMetadataFilename method when using the Script task. Note that in this case, the exact syntax may vary according to the selected script language.

WARNING: UNDER NO CIRCUMSTANCES SHOULD ANY OTHER OBJECTS OF THIS LIBRARY BE CREATED DIRECTLY. ALWAYS USE THE PUBLISHED APIS TO CREATE NEW OBJECTS.

WARNING: The metadata objects point to an underlying persistent data store. This means that if there are live references to metadata objects and the underlying data is destroyed (e.g. a new file is loaded), the objects would point to invalid data. The effect of calling any object method in these circumstances is undefined and may result in memory corruption, crash or loss of data.