A retention can be used to ensure that a document object is not deleted and the binary content file assigned it is not deleted or changed.

Table of Contents

Introduction

This article is based on the knowledge of schema structures.

yuuvis® Momentum provides the possibility to prohibit object deletion requests as well as deletion or change requests on binary content files via an expiration date property called system:rmExpirationDate. The property is predefined in all systems and is part of the also predefined secondary object type (SOT) system:rmDestructionRetention. This SOT can be referenced in any document object type definition in any schema (global, app specific or tenant specific). Thus, an expiration date can be set for each object of such a document object type. If a document object has the system:rmExpirationDate property and if the value of this property lies in the future, it is under retention until the expiration date is reached. There is no maximum retention time. You can specify any date in the future as expiration date to ensure storage time for the sake of your archiving needs.

Since the retention is stored within the objects' metadata, the individual values can be retrieved like other object properties, e.g., via the GET /api/dms/objects/{objectId} endpoint. It is not possible to define retention periods for objects without the system:rmDestructionRetention.

Note

The retention defined in the SOT protects binary content files from beeing modified/deleted via yuuvis® Momentum API. However, objects under retention can still be modified/deleted by administrators having direct access to the used storage. To prohibit such administrative operations, some archives offer an archive-internal retention as well. In those archives, the retention specified in the individual objects' metadata is set as an individual archive-internal retention.
>> Supported Archive Drivers

Note

The metadata of objects under retention are NOT protected from changes. They remain editable. If you want to prohibit metadata updates in project-specific use cases, you can configure a suitable webhook, that is triggered before the process you want to prohibit.

'system:rmDestructionRetention' SOT

To specify a retention for an individual object, the following properties are predefined in yuuvis® Momentum.

Property Type Description

system:rmExpirationDate

datetime

Required to set a retention. Specifies the date until which the document object will be unter retention.

The value must not lie in the past at the time of specification.

If the value is null, the values for system:rmStartOfRetention and system:rmDestructionDate must be null as well.

If not specified, the default retention of the used repository will be set if defined in the corresponding archive profile. The default retention does NOT replace a retention specified via API, even if the default retention would result in a later expiration date.
>> application-storage.yml

system:rmStartOfRetention

datetime

Optional. Not considered or validated by yuuvis® Momentum core system.

Can be used to specify the start date of the retention period for documentation purposes.

system:rmDestructionDate

datetime

Optional. Has to equal or exceed the value for system:rmExpirationDate as validated by yuuvis® Momentum core system.

Can be used to specify a date to trigger an automated deletion via a custom service. The yuuvis® Momentum core system does not yet offer an endpoint for this purpose.

The following code block shows the predefined properties that are related to retention. It is not possible to edit or overwrite those definitions.

Properties of system:rmDestructionRetention

...
<propertyDateTimeDefinition>
    <id>system:rmExpirationDate</id>
    <description>contains the date until the document's content is preserved</description>
    <propertyType>datetime</propertyType>
    <cardinality>single</cardinality>
    <required>false</required>
</propertyDateTimeDefinition>
<propertyDateTimeDefinition>
    <id>system:rmStartOfRetention</id>
    <description>contains the date from which the retention time was calculated (for documentation purposes only)</description>
    <propertyType>datetime</propertyType>
    <cardinality>single</cardinality>
    <required>false</required>
</propertyDateTimeDefinition>
<propertyDateTimeDefinition>
    <id>system:rmDestructionDate</id>
    <description>holds the date when the destruction process should be triggered</description>
    <propertyType>datetime</propertyType>
    <cardinality>single</cardinality>
    <required>false</required>
</propertyDateTimeDefinition>
...

All three of those properties are referenced in the system:rmDestructionRetention SOT. The following code block shows its predefined structure. It is not possible to edit or overwrite this definition.

Definition of system:rmDestructionRetention

...
<typeSecondaryDefinition>
    <id>system:rmDestructionRetention</id>
    <localNamespace>urn:optimal-systems.de:dmscloud:system</localNamespace>
    <description>can be used to apply retentions on objects</description>
    <baseId>system:secondary</baseId>
    <propertyReference>system:rmExpirationDate</propertyReference>
    <propertyReference>system:rmStartOfRetention</propertyReference>
    <propertyReference>system:rmDestructionDate</propertyReference>
</typeSecondaryDefinition>
...

Assigning a Retention

To use retentions, your applied schema must contain a document object type that references the predefined system:rmDestructionRetention SOT. For document objects of this type, you can specify retention properties via yuuvis® Momentum API. The following code block shows an example object type definition.

Example document object type definition

...
<typeDocumentDefinition>
    <id>document</id>
    <description>a document with retention</description>
    <baseId>system:document</baseId>
    <propertyReference>name</propertyReference>
    <propertyReference>date</propertyReference>
    <contentStreamAllowed>required</contentStreamAllowed>
    <secondaryObjectTypeId>system:rmDestructionRetention</secondaryObjectTypeId>
</typeDocumentDefinition>
...

By means of yuuvis® Momentum core API, there are two ways to set an object under retention:

the object can directly be imported with an expiration date or
an expiration date can be added to a previously existing object using a metadata update.

An example data set as retrievable via GET /api/dms/objects/{objectId} is shown in the following code block.

Example metadata

{
    "objects": [{
        "properties": {
            "system:objectTypeId": {
                "value": "document"
            },
            "name": {
                "value": "exampledocument"
            },
            "system:rmStartOfRetention": {
                "value": "2018-07-20T11:52:00.000Z"
            },
            "system:rmExpirationDate": {
                "value": "2028-12-28T11:52:00.000Z"
            },
            "system:rmDestructionDate": {
                "value": "2028-12-28T11:52:00.000Z"
            }
        },
         
        ... // the content streams section is missing here
    }]
}

Effects of Retentions

If an expiration date has been set for a document object, it is not possible to change or delete its binary content file or delete the object before its expiration date. The other two properties have no particular uses provided by the system. Also, if an object is under retention, it is still possible to update its metadata; however, the expiration date cannot be removed or replaced by an earlier date.

An object under retention cannot be deleted or changed even by users that have a write or delete permissions; retentions take precedence over write or delete permissions.

Automated Retention Management

It is possible to extend the functionality of yuuvis® Momentum by configuring webhooks and adding custom microservices. Thus, you can build your own specialized solution to realize automated retention management.

One possible use case would be to calculate the required retention values based on the individual object's metadata and set them, e.g.,

during the object creation,
during a specific update of the object's metadata, or
triggered by a specific metadata update of the parent folder object (if you use system:parentId).

For the deletion of document objects with expired retention, you can introduce automated custom solutions as well. E.g., with a custom microservice in your system that automatically searches for objects with expired retention and

deletes them,
updates their state in the lifecycle via tagging, or
starts a workflow process asking assigned users to delete them (if BPM-ENGINE Service is used).

Summary

Retentions can be set for document objects via a predefined SOT that provides an expiration date property. Before this date is reached, the document object cannot be deleted and its assigned binary content file cannot be updated or deleted via yuuvis® Momentum API.

Read on

Binary Content Files

Binary content files can be imported and assigned to document objects in yuuvis® Momentum. Archiving can be managed and renditions can be retrieved. Keep reading

application-storage.yml

Configuration file containing parameters and archive profiles used by the ARCHIVE and REPOSITORY service in order to connect external archives. Keep reading

Object Representation Formats

A description of the structure in which yuuvis® Momentum expects objects to be formatted and returns objects. Keep reading

Browser not supported