# Retentions

todo

Data Retentions is a feature that we use for Clients who want to have their Materials available only for a fixed, defined period, after they were created.

This is also to our benefit, as we can save some storage space by deleting old Materials - and the cascading of it -, as well as to higher our data security a bit.

# How It Works

We have a Command/Job, named scp:material:check-retention (CheckMaterialDataRetentionCommand), that currently runs every night.

When the Command/Job is triggered, all Client Configurations are checked for available configurations. If they have at least one configuration set, the cleanup will start.

There are currently three periods that can be set:

reminder_for_soft_delete_after_months

This period should be set to a certain amount of time before the soft deletion or hard deletion period.

It is advised to have an incremental approach here, (pseudo) notification => 34, soft => 35, hard => 36.

The user has therefore still enough time to copy their Material, before it is deleted.

soft_delete_after_months

This configures the amount of months, after which a Material was created, for it to be soft deleted.

hard_delete_after_months

This configures the amount of months, after which a Material was created, for it to be completely deleted. This is irreversible.

Periods and Mails

Do not forget that you are still able to define your own wording for the Notification Emails that are sent and the amount of months for the data retention periods, within the Client Configuration.

You can also just leave it as null/don't define it within your Client Configuration to keep it disabled, as this is the default.

# The Emails

# The Notification

Filling the reminder_for_soft_delete_after_months configuration triggers a Notification Email after the amount of months specified, about the data retention period starting.

# On Soft Delete

Filling the soft_delete_after_months configuration triggers a Notification Email after the amount of months specified, about the deletion of the Material.

For the user, at this point, the material is no longer accessible. However, it is “just” soft deleted, which means we still have all the data available. So in an urgent case, the user could ask us to rescue the Material.

If you save your Material it will only be available for a maximum of 24 hours, till the cleanup does run next.

They therefore do not get any mail on hard delete.

# On Hard Delete

Just to be sure: Like said above, on a hard delete there will be no Notification Email.

# How To Use

First, there is a fallback defined, here shown as the default example:

<?php

// default example

return [

  // ...

  /**
   * This defines after what period of time (Carbon; in days) Materials
   * should face their retention.
   * @note Pay attention to the ordering (DESC; which means, default has to go last)
   */
  'material_retentions' => null,

  // ...

];

As you can see the default is null, therefore no action will be taken by default, for any Client.

Things are different though, if you want to set it (selectively) within an Client Configuration.

You can also use the benefits of our Filter approach we use all over SCP, as you can see below:

<?php

// default

return [

  // ...

  /**
   * This defines after what period of time (Carbon; in days) Materials
   * should face their retention.
   * @note Pay attention to the ordering (DESC; which means, default has to go last)
   */

  /**
   * This defines after what period of time (Carbon; in days) Materials
   * should face their retention.
   * @note Pay attention to the ordering (DESC; which means, default has to go last)
   */
  'material_retentions' => [
    [
      'filter' => [
        'opu' => 'usa'
      ],
      'values' => [
        'reminder_for_soft_delete_after_months' => null,
        'soft_delete_after_months'              => null,
        'hard_delete_after_months'              => null
      ]
    ],
    [
      'filter' => [],
      'values' => [
        'reminder_for_soft_delete_after_months' => 34,
        'soft_delete_after_months'              => 35,
        'hard_delete_after_months'              => null
      ]
    ]
  ],

  // ...

];

Using our Filters you can define differing configurations, depending for example on defined OPUs and/or Material Types within a Client.

In this Client's example we can see the implementation of two differing configurations.

One of the definitions is usa-only, which basically disables the whole usage, and therefore needs to go first.
The other one is the default for every other OPU.

Remember, you can also define other properties for the Filter, depending on how you want to use it.

Filters & Ordering

If you have forgotten how to use Filters, please read up about them again.

It is also always helpful to refresh such basics.

On another note, please also pay attention to the order in which you define your differing configurations within the the material_retentions array.

The order is DESC, so the most important should go to the top.

← Actions Roles →