Metadata
Metadata is a hierarchical structure describing a job. Simply put, Metadata is data about data or, in other words, information tagged to data. Depending on the type of job, the Metadata includes information about the job, the data file, items in the Connect database, a PlanetPress Design document, 'User defined information' (sometimes created by regular tasks) and in some cases page properties and page counts.
Some of the Action and Output tasks produce, alter, or use the Metadata. In addition to that, PlanetPress Workflow provides a whole series of plugins to create and edit Metadata during a Workflow process (see Metadata Tasks). The things that you have to know in order to use the Metadata tasks effectively are set out in another topic: Working with Metadata.
Applications or plugins created in PlanetPress Suite 6 and using Metadata will need to be updated for use in version 2018.1. No backward compatibility mode is available.
When a user-defined emulation (created in PlanetPress Design) is used with Metadata, results and behavior are unknown and unsupported. For instance, refreshing the Metadata file may cause the document to crash and/or corrupt. For this reason, it is strongly advised to create backup copies of your documents beforehand.
Metadata structure
The hierarchical structure of the Metadata is composed of a number of basic levels for adding information to a job. These levels are, from top to bottom:
- Job: A file that contains one or more groups.
- Group: A logical and ordered group of documents (ex: all invoices for a specific customer number; all documents going to the same address, etc.).
- Document: A group of one or more ordered data pages intended to the same recipient from the same source (ex: invoice).
- Data page: One atomic unit of content that produces zero, one or more pages.
- Page: One side of a physical paper sheet.
When Metadata is produced for a given job, a hierarchical (i.e. tree-like) structure is created, composed of the above elements in the following order: Job > Group(s) > Document(s) > Datapage(s) > Page(s). For example:
Any operation that modifies the data with regards to the structure (ex: remove pages, alter the data, etc.) makes the Metadata obsolete and so it must be recreated or refreshed; see Working with Metadata.
Metadata in OL Connect jobs
In PlanetPress Suite, all levels in the Metadata hold information about an actual job. In Connect, that isn't the case. The Metadata file created and maintained by OL Connect tasks looks the same, but contains less information. Only the first three levels in the Metadata hold information about the job: Job, Group and Document. A Group has information about a record set in the Connect database and a Document has information about one record in that set. This information appears under User defined information instead of under Production information. The Data Model fields are added into the Document level.
Although Data page and Page nodes are visible in the Metadata file, they don't contain any actual job related information in this case.
The Metadata related plugins (see Metadata Tasks) can be used in conjunction with OL Connect tasks nonetheless; see How Metadata will or can affect the output.
Metadata elements
Each Metadata node (i.e. Job, Group, Document, etc.) is described with a series of elements, that is, system-defined attributes or user-defined fields holding static or dynamic information about the node they are attached to. Each element has a name and a value. More specifically, here is a definition of these 2 types of elements:
- Attribute: A read-only, system-defined element which holds certain information about a certain node in the Metadata structure. This information can be static (e.g. the size of a physical page) or evaluated on-the-fly (e.g. the number of documents in a group). Attributes are non-repetitive (i.e. name is unique) and do not persist through Metadata recreation.
- Field: A read-write, user-defined element which holds custom information about a certain node in the Metadata structure. Fields are repetitive (i.e. the same field may appear multiple times) and persist through Metadata recreation.
In addition to attributes and fields, each node of type Group, Document or Datapage has a Boolean property called 'selected' that indicates whether or not to produce the pages under that node. By default, this property is set to true for all nodes. This property is not visible in the Metadata file, but it can be used in a Script task via the Metadata API.
Metadata attributes reference
The Metadata attributes are categorized as either Production, Finishing or Index/Count.
Production attributes describe the production of the job and/or Metadata (e.g. path and name of the datafile, date at which Metadata was created, etc.)
Finishing attributes describe the finishing intent (e.g. page dimensions, page orientation, duplex mode, etc.).
The presence of some finishing attributes depends on the PlanetPress Design document and target device used when producing the job.
Index/Count attributes are not part of the original Metadata file. They are evaluated live based on the content of the Metadata.
Metadata Index/Count values are one-based when viewed in the user interface: the first element in any collection has an index of 1 and the last element's index corresponds to the collection's length. However, in the API and in Metadata selections, they are zero-based: the first element in any collection has an index of 0 and the last element's index corresponds to the collection's length minus 1. This means the zero-based value has to be used when retrieving Metadata (see also: Metadata selections and Rule Interface).
In the following table, the last 5 columns indicate at which level the corresponding attribute is available. This also depends on the type of job, however.
In the Metadata file created for an OL Connect job:
- Only three levels are filled with actual data about the job: Job, Group and Document.
- Only Index and Count attributes are actually used.
| Attribute | Description | Category | Job | Group | Document | Datapage | Page |
|---|---|---|---|---|---|---|---|
| DataEncoding | (optional) Name of the character encoding. | Production | X | X | X |
|
|
| DataFile | (optional) Path and name of the data file used by the PlanetPress Design Document. | Production | X | X | X |
|
|
| Date | Date the Metadata was created in ISO format. | Production | X | X | X |
|
|
| Time | Time the Metadata was created in ISO format. | Production | X | X | X |
|
|
| Title | Title of the source document. | Production | X | X | X |
|
|
| Producer | Name of the software that created the Metadata. | Production | X | X | X |
|
|
| Creator | Name of the software that created the source of the Metadata. | Production | X | X | X |
|
|
| TargetDevice | Name of the device for which the Metadata and associated data is intended. | Production | X | X | X |
|
|
| Dimension | Two floats separated by a colon indicating the media size in typographical points (ex: 612:792). | Finishing | X | X | X | X | X |
| Orientation | "Rotate0", "Rotate90", "Rotate180" or "Rotate270", indicating respectively portrait, landscape, rotated portrait and rotated landscape. | Finishing | X | X | X | X | X |
| Side | "Front" or "Back"; indicates whether the page is on the front or the back of the paper sheet. This attribute is a "best effort" and is device-dependent. | Finishing |
|
|
|
|
X |
| Duplex | "None", "DuplexTumble" or "DuplexNoTumble"; indicates a change of the duplex status. | Finishing | X | X | X | X | X |
| InputSlot | Device-dependent identifier of the media source. | Finishing | X | X | X | X | X |
| OutputBin | Device-dependent identifier of the media destination. | Finishing | X | X | X | X | X |
| Weight | Device-dependent weight of the media. | Finishing | X | X | X | X | X |
| MediaColor | Device-depedent color of the media. | Finishing | X | X | X | X | X |
| MediaType | Device-dependent type of the media. | Finishing | X | X | X | X | X |
| Index |
|
Index/Count |
|
X | X | X | X |
| IndexInDocument | Returns the Absolute index of the node within all the nodes under the parent Document. | Index/Count |
|
|
|
X
|
X |
| IndexInGroup | Returns the Absolute index of the node within all the nodes under the parent Group. | Index/Count |
|
|
X
|
X
|
X |
| IndexInJob | Returns the Absolute index of the node within all the nodes under the parent Job. | Index/Count |
|
X
|
X
|
X
|
X |
| Count |
|
Index/Count | X | X | X | X |
|
| DocumentCount |
|
Index/Count | X |
|
|
|
|
| DatapageCount |
|
Index/Count | X | X |
|
|
|
| PageCount |
|
Index/Count | X | X | X |
|
|
| SelectedCount |
|
Index/Count | X | X | X | X |
|
| SelectedDocumentCount |
|
Index/Count | X |
|
|
|
|
| SelectedDatapageCount |
|
Index/Count | X | X |
|
|
|
| SelectedPageCount |
|
Index/Count | X | X | X |
|
|
| SelectedIndexInDocument | Returns the Absolute index of the node within all the selected nodes under the parent Document. | Index/Count |
|
|
|
X
|
X |
| SelectedIndexInGroup | Returns the Absolute index of the node within all the selected nodes under the parent Group. | Index/Count |
|
|
X
|
X
|
X |
| SelectedIndexInJob | Returns the Absolute index of the node within all the selected nodes under the parent Job. | Index/Count |
|
X
|
X
|
X
|
X |
| NumCopies | Indicates how many times the job is set to execute, as set when printing using a Windows driver. | Index/Count | X |
|
|
|
|
| Author | Name of the user who printed the job initially, as available in the spool file, and as the first job info of the Windows capture input. | Production | X |
|
|
|
|
Metadata in PlanetPress Design
PlanetPress Design includes a complete set of Metadata-related functionality, which can be referred to as Metadata Tools. These tools can be used to generate Metadata, retrieve or define Metadata elements, and build the Metadata structure of a PlanetPress Design document. For information about these tools see the user guide: PlanetPress Design 7.6 User Guide.