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.

You can also manipulate the Metadata in your process via scripts using the Metadata API. See Metadata API Reference.

Applications or plugins created in PlanetPress Suite 6 and using Metadata will need to be updated for use in version 2022.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.

Note: 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 affects the output.

Metadata Attributes and Fields

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. 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. (See also: Metadata Attributes reference.)
  • 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.

When the Metadata file is viewed through the Data Selector in Workflow, attributes are listed under Production information; fields are listed under User defined information (see Metadata tab).

In addition to attributes and fields, each Metadata node has a number of properties and methods. The Boolean property selected 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 Run Script task via the Metadata API.

Metadata Tools in PlanetPress Design

PlanetPress Suite 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 Design user guide: PlanetPress Design 7.6 User Guide.