Addons

Functional Overview

Updated: December 5, 2024

This page details the options available from Nuxeo Web UI once the Nuxeo Retention addon is installed.

Principles

From a high-level perspective, the Retention addon requires two steps to manage records:

  1. Defining retention rules that will be applicable to your content.
  2. Applying these rules to the relevant content. A document is considered a final record as soon as a rule is applied to it.

Nuxeo Web UI provides out of the box features to apply a rule to a document individually or to a list of documents. In order to automate your governance, you can also fully leverage the automation capabilities of Nuxeo Server and apply retention rules as part of your business logic.

Irreversibility of Some Actions

In Strict Mode

If you are using the addon in strict mode, to allow compliance with the SEC 17a-4 regulation requirements regarding records preservation, most of the actions related to the retention are not reversible:

  • There is no way to roll back the application of a retention rule to a document, even as an administrator.
  • There is no way to shorten a retention duration, even as an administrator.
  • There is no way to undeclare a record.
  • There is no way to replace the main file of a document under retention or legal hold, even as an administrator and even with a direct access to the storage. This can also apply to additional document properties if they are configured to be retained as well.
  • There is no way to delete the main file of a document a document under retention or legal hold, even as an administrator and even with a direct access to the storage. This can also apply to additional document properties if they are configured to be retained as well.

In Standard Mode

In standard mode, you can differentiate records that require stricter compliance and operational records that do not require the same level of security (e.g., records for which WORM storage is not a requirement and the record can be undeclared with the appropriate permission).

General restrictions will still apply:

  • There is no way to roll back the application of a retention rule to a document, even as an administrator. A record can be undeclared in specific conditions however, allowing to attach a different rule with a different retention period.
  • There is no way to shorten a retention duration, even as an administrator. A record can be undeclared in specific conditions however, allowing to attach a different rule with a different retention period.
  • If you configured the addon to use a dedicated bucket for records that leverages Object Lock in Compliance mode:
    • There is no way to replace the main file of a document under retention or legal hold, even as an administrator and even with a direct access to the storage. This can also apply to additional document properties if they are configured to be retained as well.
    • There is no way to delete the main file of a document a document under retention or legal hold, even as an administrator and even with a direct access to the storage. This can also apply to additional document properties if they are configured to be retained as well.

As a Records Manager

As a records manager, you are responsible for the proper organization and management of the documents on the platform. You have to make sure that the retention rules are properly written, implemented and used.

Once the module is installed, different menus, sub-menus and actions are available throughout Nuxeo.

Retention Menu

A new retention menu retention-icon-main is available on the left side menu, including the following sub-menus:

Retention Actions

New actions are displayed on documents and / or results lists:

  • retention-icon-main apply a retention rule to the document.

  • retention-icon-legal-hold apply/remove a legal hold to the document.

  • retention-icon-main override the retention of a document already under retention.

  • Undeclare a record (visible on a document only)

Retention Rule Document Type

A retention rule document type is available, that can only be created under the retention rules menu.

retention-screen-rules-menu
retention-screen-rules-menu

Groups and Permissions

This addon brings additional groups and permissions:

  • A RecordManager group. Members of this group can create/edit retention rules and access the retention menu in Nuxeo Web UI for further options.
  • A Manage Record permission. Users with this permission can apply a retention rule to a document or a list of documents and extend the duration of the retention for a document already under retention.
  • A Manage Legal Hold permission. Users with this permission can apply/remove a legal hold to a document or a list of documents.
  • An Unset Retention permission. Users with this permission can undeclare a record, in specific conditions. This permission is only applicable when using the addon in standard mode.

Managing Retention Rules

Create a Retention Rule

To create a new retention rule:

  1. Go to the Retention menu.
  2. Click on Retention rules.
  3. Click on the Create button Create Button.
    The following creation popup is displayed.
    retention-screen-rule-creation
    retention-screen-rule-creation
General Information
Rule name Name of the rule displayed in the retention rules menu and when selecting a retention rule to apply to a document.
Description Description of the retention rule.
Status Select if the rule can be applied to the documents ("active") or not ("inactive").
Allow undeclaring the record Select if the rule should allow the record to be undeclared.
Rule Application
Document types Filter for which document types the retention rule is displayed when attaching it from Web UI. If left empty, the retention rule will be displayed for all document types.
Period Starting Point
Immediate The retention period will start once you apply the retention rule to the document.
More details on the Focus on the retention types section.
Based on an event The retention period will start once the defined event occurs (after the retention rule has been applied to the document).
More details on the Focus on the retention types section.
Event type Select the type of event that will trigger the retention period. The list of available event types is defined using a dedicated vocabulary.
Event field value Fill in the value related to the event (contract number, employee identifier, loan reference, etc.)
Example: If I apply a retention rule to a document on January 1st, 2020 with the event "contract terminated", a retention period of 2 years, and the contract is closed on August 10th, 2020, then the retention will expire on August 10th, 2022.
Based on a metadata The retention period will start based on a defined metadata, once you apply the retention rule to the document.
More details on the Focus on the retention types section.
Metadata The path of the metadata to use. All date metadata from all schemas are available (default and local ones).
Retention Duration
Duration You can select the duration of the retention in years, months or days. The fields are aggregated to define the total retention duration.
Post Retention Actions
Actions You can select one or several actions to be automatically executed once the retention expires.
Examples: delete the document, notify specific users, export, etc.

Focus on the Retention Types

Immediate

The retention period starts immediately when you apply the retention rule on the document.

Example: If I apply a retention rule to a document on January 1st, 2020 with a period of 2 years, then the retention will expire on January 1st, 2022.

retention-schema-immediate
retention-schema-immediate

Based on a Metadata

The starting date of the retention period is based on the value of a specific document property when you apply the retention rule to the document.

This retention type is useful when the retention period depends on a past and external event. It can typically be used when migration documents from a legacy records management system to Nuxeo.

Example: If I apply a retention rule to a document on March 15th, 2020 with the metadata "publication date", a retention period of 2 years, and the "publication date" is September 15th, 2019, then the retention will expire on September 15th, 2021.

retention-schema-metadata
retention-schema-metadata

Metadata-based retention rules are designed for past dates, not future dates.

Based on an Event

When using this retention type, the file(s) to retain are protected immediately and for an undefined period of time. The end of retention is determined when the event occurs and not when the retention rule has been applied to the document.

This retention type is useful for all cases where a document needs to be preserved from any deletion or change but the retention starting point is unknown at the beginning.

Examples: If I need to retain a contract with an employee for 7 years after they leave the company, I can use an event-based retention rule with a duration of 7 years to protect the contract immediately, and trigger the event when they leave. The contract will be retained for 7 more years after the event is triggered.

retention-schema-event
retention-schema-event

Edit a Retention Rule

You can edit an existing retention rule to change its status or settings.

The changes made on a retention rule are not retroactive. It will only affect the documents linked to the retention rule after the changes are done.
They won't be applied to the documents previously linked to the retention rule.

Once on the View tab of the retention rule:

  1. Click on the Edit button.
    A popup window is displayed.
  2. Update the rule.
  3. Click on Save button.

Delete a Retention Rule

You can delete an existing retention rule.

The deletion of a retention rule will not affect the documents previously attached to the rule. Those documents will keep their retention settings, including retention period and post-retention actions.

On the View tab of the retention rule:

  1. Click on the Delete button.
    A popup window is displayed.
  2. Click Confirm to delete the retention rule.

Put a Document Under Retention

To put a document under retention, you have to attach a retention rule to the document.
By doing so:

  • The document will be automatically declared as a record
  • The retention rule's settings will be applied to the document

This is an irreversible action, even as an administrator, meaning you can't remove the retention rule from the document and you can't shorten the retention period. Records can be undeclared in specific conditions when using the addon in standard mode however.

By default, only the main file of the document will be protected and other properties will remain editable. Should you wish to protect additional properties, please refer to our documentation on how to retain multiple files or properties.

After having attached a retention rule, the only available action is to extend the retention.

There are different ways to put a document under retention. You can attach a retention rule to a single document or to several documents at once.

From a Document View

On the View tab of your document:

  1. Click on the More button and select Attach retention rule.
    A popup window is displayed.

    retention-screen-retention-popup
    retention-screen-retention-popup

  2. Select the retention rule needed from the drop-down list and click on Attach retention rule.
    A top bar is displayed at the top of your document to notify users that the document is, or will be, under retention.

    retention-screen-retention-document
    retention-screen-retention-document

From a Result List

After having performed a search from the retention search menu, a list of documents is displayed. Then, if you click on the Without attached rule quick filter, you can click on Attach retention rule icon retention-icon-main at the top-right of the screen.

retention-screen-apply-bulk
retention-screen-apply-bulk

Select the retention rule that you want from the popup window and confirm.

The retention rule will be applied on all the documents displayed on the page.

Extend the Retention of a Document

When a document is under retention, you can lengthen the retention of the document.

This is an irreversible action: there is no way to shorten a retention period, even as an administrator. If you made a mistake and wish to adapt the retention period, note that records can be undeclared in specific conditions when using the addon in standard mode however.

On the View tab of your document:

  1. Click on the More button and select Extend retention.
    A popup window is displayed.

    retention-screen-retention-extend
    retention-screen-retention-extend

  2. Select the new expiration date (end of retention period) and confirm.
    A top bar is displayed at the top of your document to notify users of the new expiration date.

    retention-screen-retention-document
    retention-screen-retention-document

Create a Retention Event

To create a new retention event:

  1. Go to the Retention menu.
  2. Click on Retention events.
  3. Fill the fields on the Fire event section:

retention-screen-eventmenu
retention-screen-eventmenu

  1. Click on Fire event.

At this stage, the event is created on Nuxeo Platform, and the retention rules fitting with this event will trigger the retention period for the involved documents.

The retention search is a dedicated search with criteria related to the retention management.

This search contains filters on:

  • The attached retention rule.
  • The expiration date (past and future).
  • The retention status (active retention, expired, not under retention).
  • The legal hold status.
  • The full-text content.

retention-screen-search
retention-screen-search

History on a Document

On the History tab of your document, you can see all the events related to the retention, including:

  • Application of a retention rule to the document.
  • Beginning of the retention period.
  • Overriding of the retention period.
  • Application of a legal hold on the document.
  • Removing of a legal hold on the document.

General History

On the Administration > Audit page, you can see all the events related to the retention, including the retention events that have been created on the platform.

There are different ways to put a document under a legal hold. You can apply a legal hold to a single document or to several documents at once.

From a Document View

Once on the View tab of your document:

  1. Click on More and select Apply legal hold.
    A popup window is displayed.

    retention-screen-legalhold-popup
    retention-screen-legalhold-popup

  2. Fill in the description and click on Apply legal hold.
    A bar is displayed at the top of your document to notify users that the document is under a legal hold.

    retention-screen-legalhold-document
    retention-screen-legalhold-document

Applying legal hold on a document automatically enforces its retention as a record necessary for compliance, meaning that it cannot be undeclared anymore. If WORM storage is configured, it will be stored in this way for the remaining duration of its retention, even after you remove the legal hold.

From a Result List

After having performed a search from the retention search menu, a list of documents is displayed. Then, if you click on the Not Under legal hold quick filter, you can click on Apply legal hold icon retention-icon-legal-hold at the top-right of the screen.

retention-applyhold-bulk
retention-applyhold-bulk

Fill in the description field from the popup window and confirm.

The legal hold will be applied on all the documents displayed on the page.

Applying legal hold on a document automatically enforces its retention as a record necessary for compliance, meaning that it cannot be undeclared anymore. If WORM storage is configured, it will be stored in this way for the remaining duration of its retention, even after you remove the legal hold.

There are different ways to remove a legal hold. You can remove a legal hold for a single document or for several documents in a row.

From a Document View

Once on the View tab of your document:

  1. Click on More and select Remove legal hold.
    A popup window is displayed.

    retention-screen-legalhold-remove-popup
    retention-screen-legalhold-remove-popup

  2. Click on Remove legal hold.
    The top bar displayed on top of your document doesn't display the legal hold anymore.

    retention-screen-retention-document
    retention-screen-retention-document

From a Result List

After having performed a search from the retention search menu, a list of documents is displayed. Then, if you click on the Under legal hold quick filter, you can click on Remove legal hold icon retention-icon-legal-hold at the top-right of the screen.

retention-screen-removehold-bulk
retention-screen-removehold-bulk

Confirm from the popup window.

The legal hold will be removed for all the documents displayed on the page.

Visualizing Retention/Legal Hold Status

To help to easily visualize if any documents are under retention or legal hold when browsing, we added a - hidden by default - column named "flags column".
This column gives some extra details about the documents, such as if the document is a favorite, is under cold storage or if it's under retention or legal hold.

Flags Screenshot

Flags setting

Delete a Document Under Retention

Standard Mode

By default, attaching a retention rule to a document is an irreversible action, meaning you can't delete a document under retention or stop retention.

That being said, you can override this default behavior when using the addon in standard mode by using a specific role.

If the role NuxeoRecordCleaners has been created in the instance and assigned to a user with the Remove permission on a given document, the user will be able to delete the document under retention.

Rather than deleting the document, you may want to undeclare the record.

Strict Mode

There is no way to delete a document under retention when using the addon in strict mode.

As a User

Standard and Strict mode
This page describes the user experience depending on the Retention Management addon mode among standard or strict.

As a user, you will see some differences on the View tab of your documents:

  • There is an info header displaying Retention information or legal hold.
  • Some actions can be unavailable due to the nature of a document under retention or legal hold, or due to the functional limitations involved by the Nuxeo Retention Management addon.

The following tables describe the availability of document actions:

  • The action is available (depending on the user permissions) as for a standard Nuxeo instance,
  • The action is disabled for records, meaning the action is disabled only when the document is under retention or legal hold,
  • The action is disabled on instance, meaning it's disabled for all documents on the Nuxeo instance, due to some limitations coming from the Nuxeo Retention Management addon to ensure compliance.

In Standard Mode

Feature
Available Disabled for records Disabled on instance
Preview
Download
Export
Add to collection
Add to favorites
Add to clipboard
Notify me
Share
View permissions
Change permissions
View history
View publishing
Add tags
Start process
Lock
Edit metadata
✓(1)
Publish document
Replace main file
Delete main file
Delete document
✓(2)
Comments
Versioning
Add attachment

standard mode
(1): Specific metadata properties can be retained using configuration.
(2): Deleting a document is disabled on a record unless the specific role has been activated and assigned to a user.

In Strict Mode

Feature
Available Disabled for records Disabled on instance
Preview
Download
Export
Add to collection
Add to favorites
Add to clipboard
Notify me
Share
View permissions
Change permissions
View history
View publishing
Add tags
Start process
Lock
Edit metadata
Publish document
Replace main file
Delete main file
Delete document
Comments
Versioning
Add attachment