The basic idea for the usage of tags is to describe the state of an object within a process chain. They basically consist of a name and a state value and can be assigned to any object.

Introduction

In document lifecycle management, multi-stage and asynchronous processes are not uncommon—quite the contrary. The first process steps are carried out with the highest priority. More complex and currently not absolutely essential process steps are carried out asynchronously with a lower priority. This saves time, and carrying out operations in parallel lets you distribute resources more evenly. To resume a process chain, additional information about the current state of the process is necessary. In order to not mix an object's metadata with its state data, there is the possibility to tag objects. Pure tagging operations do not trigger the creation of new object versions.

Objects can be searched by tags and selected for the next process step. All tagging activities are recorded by the yuuvis® system in the object history (Audit Trail). Thanks to this, you can always retrace who has done what and when. Trouble shooting, reporting on the process state or general issues are made easy by this centrally stored history.

Characteristics of Tags

Difference between metadata and tags:

Tags do NOT belong to the metadata and thus do not need to be defined in the schema.
Tags are stored together with the object as value for the system:tags property similar to metadata.
Pure tag operations do NOT lead to the creation of a new object version.
Tags can only be attached to the current version of an object, whereas previous versions cannot have tags.
For version-specific information, metadata provide the suitable options. They have to be defined in the schema.

State information:

Tags describe the state of an object in a process chain. The state information is specified via an integer value.

Tracing information:

Tags are provided with a process identification that allows to retrace tag operations and tune the update or deletion permissions for the tag.

Assignment:

Tags can be added to any object during object creation, during metadata updates or completely independent via a tagging endpoint.
Multiple tags can be added to one object.
The number of tags assigned to one object is limited to 50.

Querying on tags:

The properties of tags are included in the searchable data.
Tags are queried similar to table properties.

Behavior during POST metadata updates:

If the system:tags property is specified in the request body,
- all included tags are assigned to the new object version with the given name and state. The same value as system:lastModificationDate and system:traceId will be set automatically for creationDate and traceId respectively for all of them.
- each tag that is not included is deleted. The new object version will not have that tag.
If the property system:tags is NOT specified in the request body or is set to null, all tags will be deleted. The new object version will not have any tag.

Behavior during PATCH metadata updates:

If the system:tags property is specified in the request body,
- all included tags are assigned to the new object version.
- each tag that is not included is deleted. The new object version will not have that tag.
If the system:tags property is NOT specified in the request body, all tags are transferred to the new object version. Their state, creationDate and traceId remain unchanged.
If the system:tags property is set to null, all tags will be deleted. The new object version will not have any tag.

Behavior during POST updates of the binary content file:

If the tag name ends with the suffix :resistant, the tag is transferred to the new object version. Its state remains unchanged.
If the tag name does NOT end with the suffix :resistant, the tag is deleted. It will not be assigned to the new object version.

Behavior during POST restoring actions of an old version (as of 2022 Spring):

If the tag name ends with the suffix :resistant, the tag is transferred to the new object version. Its state remains unchanged.
If the tag name does NOT end with the suffix :resistant, the tag is deleted. It will not be assigned to the new object version.

Any tag operation is documented in the object audit trail.

Tag Properties

Tags are defined by the following properties:

Property	Type	Description	In a request
`name`	String	Name of the tag for identification. It has to be unique for the corresponding object. The tag names are validated during a tag creation or update process. To pass the validation, they have to match the regular expression [a-z](:?[a-z][a-z0-9]) and must not be longer than 32 characters (as of 2022 Spring, no longer than 128 characters). As of version 2021 Summer, the suffix `:resistant` triggers a specific behavior of the tag. If a tag name matches the expression *[a-z](:?[a-z][a-z0-9]):resistant*, the tag will behave like a resistant tag as described below.	required
`state`	Integer	Represents the status of the corresponding object in a process chain.	required
`creationDate`	String	Date and time of the last modification of the tag. It is set automatically by the system.	optional, only available in search queries
`traceId`	Hexadecimal lowercase string with maximum length 16	Process identification of any tag operation. If not specified in the request, a random String value will be set after the tag operation. In a tag update or delete request, the request parameter `traceIdMustMatch` can be set to `true`. The operation will be done only if the `traceId` of the call matches the current `traceId` of the requested tag. After such update processes, the `traceId` of the updated tag will be the same as before. Per default, `traceIdMustMatch` is set to `false`.	optional, specified by means of the HTTP header `X-B3-TraceId`

In a request, the corresponding properties are included directly in the URL for the call of the endpoint. In contrast, if tags are displayed in a response body, their properties are listed as a part of a JSON structure in the value of the system:tags property.

Tagging Endpoints

The following endpoints for pure tag operations do not trigger a new version of the corresponding object, but only a new entry in the audit trail:

Retrieve object tags by ID – GET /api/dms/objects/{objectId}/tags
Add object tag by ID – POST /api/dms/objects/{objectId}/tags/{name}/state/{state}
Update object tag by ID – POST /api/dms/objects/{objectId}/tags/{name}/state/{state}?overwrite=true
Delete object tag by ID – DELETE /api/dms/objects/{objectId}/tags/{name}
Add/update object tag by search query – POST /api/dms/objects/tags/{name}/state/{state}?query=<SQL>

Resistant Tags

As of version 2021 Autumn, it is possible to assign resistant tags that are automatically transferred to the new version of an object created during an update of the binary content file.
>> POST /api/dms/objects/{objectId}/contents/file

The resistant tags will be removed from the old object version and assigned to the new object version. As usual, the previous object version will not have any tags afterwards. However, the new version will have all the resistant tags assigned to it that were originally assigned to the previous version. Conventional non-resistant tags will not be reassigned to the new object version.

Resistant tags are identified by the suffix :resistant at the end of the tag name.

Note: The tag name including the suffix must not exceed the length limit of 128 characters.

Summary

This article gave an introduction into the handling of tags as a feature of the lifecycle management of objects in yuuvis® Momentum. In the "Tagging Objects for Processing" tutorial, an exemplary use case is explained.

Read on

Tagging Objects for Processing

Based on tags, you set up complex stateful processing chains. This tutorial describes how tags can be added, displayed, and updated in an example context. For this purpose, a typical application will be discussed: An import management system, which is an example for a processing chain, where tags are a helpful tool to describe the current status of each object. Keep reading

Schema - Defining Object Types

Define properties and reference them in object type definitions for the entire system, for individual tenants or for a specific app. Keep reading

Changing Schema Structures ("Schema Flow")

This tutorial shows how to change your basic schema for individual instances of an object type during the entire lifecycle of a document. Classify objects at a later point in time, add or remove property groups at runtime by defining and referencing "floating" secondary object types. Keep reading

Table of Contents