Updating object retention with sweeps

You can update object retention by creating a job sweep.

By using a retention update sweep, you can change the retention period of an object based on the class of an object or the state of its properties. There are two ways to specify a new retention date:
  • Specify a date directly, by using the SpecificRetentionDate property, or
  • Cause a date to be calculated, by specifying three things:
    1. The name of a base date property on the Sweep Target class. This name is specified by the BaseDatePropertyName property, which must identify a valid property on the sweep target class, and that property must have a data type of DateTime.
    2. An offset. The offset is specified by the RetentionDuration property.
    3. The units that the offset is expressed in. The units are specified by the RetentionPeriodUnits property.

You cannot both specify a date and cause a date to be calculated, so if a value is provided by the SpecificRetentionDate property, then both the RetentionDuration property and the BaseDatePropertyName property must be set to a null value. Similarly, if the SpecificRetentionDate property is null, then both the RetentionDuration property and the BaseDatePropertyName property must be set to valid values.

Access control

Retention updates sweeps execute with the access rights of the security principal specified as the owner of the sweep.

The following table defines the minimum access rights that are required to create an instance of a retention update sweep:
Table 1. Access rights required to create a retention update sweep
Access right Granting object
Create instance Class definition for retention update sweep
Create new objects Object store
Connect to store Object store
Modify retention Object store
Retention update sweeps are supported in two modes: RetentionReductionAllow and RetentionReductionPrevent, controlled by the AllowRetentionReduction property. When the mode is set to RetentionReductionAllow, then the sweep updates the retention on all affected items, even if doing so results in the retention period being reduced. When the mode is RetentionReductionPrevent, then the sweep does not update the retention on any objects for which the update would result in reducing the retention period. The AllowRetentionReduction property is read-only, which means that the only way to change the value is to update the default value given in its property definition. The default value can be changed by modifying the PropertyDefaultBoolean property on the Property Definition for the AllowRetentionReduction property.
Table 2. Access rights required to modify the AllowRetentionReduction property
Access right Granting object
View all properties Class definition for the retention update sweep
Modify all properties Class definition for the retention update sweep
Modify existing object Object store
Connect to store Object store
Modify retention Object store