| Status | |
|---|
| Priority | 1 |
|---|
| Note |
|
|---|
| Assignee | Inga | Andreas D. |
|---|
Ressources https://wiki.optimal-systems.de/pages/viewpage.action?pageId=57442949
Remarks- Antje: Cleaning up the Tutorial → moving things to Concepts
table entry: traceid | hexadecimal string with maximum legth 16 | Unique process number 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 |
Handling of the traceid The traceid is a unique process number that provides the possibility to retrace tag operations and tune the update or deletion permissions for the tag. In the HTTP header, the request parameter traceIdMustMatch can be changed from its default value false to true. Thus, two different scenarios are possible: - Call with
traceIdMustMatch=false (default)
traceid for the tag.
In case of a tag deletion, the endpoint removes the tag from the corresponding object without checking the current traceid of the tag to be deleted. - Call with
traceidMustMath=true
An update or deletion endpoint takes the traceid from the request and compares it to the current traceid of the requested tag. The update or deletion operation will be performed only if the values are matching. Thus, the tag can only be updated or deleted if the previous traceid is known to the caller.
In case of a tag creation, this condition would never match and should therefore not be used.
|
Tags are used to describe the status of an object within a process chain independently of the object's metadata, which means no need of definition in the schema and no triggering of new versions. |
Table of Contents
|
|
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 status of the process is necessary. In order to not mix an object's metadata with its status data, there is the possibility to tag objects.
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 status or general issues are made easy by this centrally stored history.
Characteristics of Tags
- Tags describe the status of an object in a process chain.
- Tags can be added to any object. They are stored together with the object.
- Multiple tags can be added to one object.
- The tags specify the status information via an integer value. Additionally, tags have a unique process number that can be set during the tag creation or will be randomly set after any tag operation.
- Any tag operation is documented in the object audit trail.
- Tags do not belong to the metadata and thus do not need to be defined in the schema. Moreover, tag operations do not lead to the creation of a new object version.
- Tags are always available for the current object version.
- The properties of tags are included in the searchable data.
The special feature of tags is the independence of versioning and schema definitions. The tags of an object are always attached to the current version, whereas previous versions cannot have tags. For version-specific information, metadata provide the suitable options. They have to be defined in the Schema.
Tag Management
Endpoints
Tags can be set in any object creation body in the system property system:tags. In the same way, it is also possible to set tags for the new version of an object in any POST/PATCH update call. A POST update without the explicit specification of already existing tags will remove them from the corresponding object.
Furthermore, there are endpoints for pure tag operations that do not trigger a new version of the corresponding object, but only a new entry in the 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. | 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 | String | Unique process number of any tag operation. If not specified in the request, a random String value will be set after any tag operation. If specified in an update or deletion request, the operation will be done only if the the value matches the current traceid of the requested tag. After such update processes, the traceid of the updated tag will be the same as before. | 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 property system:tags.
Handling of the traceid
The traceid is a unique process number that provides the possibility to tune the update or deletion permissions for the tag. As an optional property, the endpoints allow for two different scenarios:
- Call without
traceid
The endpoint does not check the current traceid of the tag to be updated or deleted. In case of an update, a new random traceid will be set.
- Call with
traceid
The update or deletion endpoint takes the traceid from the request and compares it to the current traceid of the requested tag. The update or deletion operation will be performed only if the values are matching. Thus, the tag can only be updated or deleted if the previous traceid is known to the caller.
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.