Holding an object using labeled holds

Content Platform Tenant Management Help

File Size
4269 KB
Part Number

A labeled retention hold, or labeled hold, is a named retention hold that has a unique identifier. The ability to set multiple, independent labeled holds on an object enables multiple organizations or custodians to place a hold on the same object to prevent its deletion or versioning, or metadata modification, until all holds are explicitly released. This feature is supported by both the REST API and Hitachi API for Amazon S3.

A common use of labeled holds is when an object is needed for legal discovery by multiple organizations or custodians. For example, there might be several lawsuits handled by different organizations within a company. The investigations or inquiries have different but overlapping time lines. A file relevant to all of the lawsuits must not be deleted when the first legal hold ends because the other lawsuits need the file as well.

A labeled hold can be placed on a new object at ingest time, or on an existing object in the namespace, provided the client application has write and privileged data access permissions. Similarly, the application can modify a labeled hold on an existing object.

To place a labeled hold on an object at ingest time, use the Hitachi API for Amazon S3 or REST API with the HTTP PUT object method and the X-HCP-LabelRetentionHold header.

To add or remove a labeled hold on an existing object, use the S3 compatible API with the HTTP PUT object copy method and the X-HCP-LabelRetentionHold header, or the REST API HTTP PUT method with the query parameter method to add or remove system metadata.

Retention holds and labeled retention holds on the same object

An object can have both a single hold and one or more labeled holds at the same time. These hold settings are independent of one another. All holds must be released on the object before it can be deleted or have its metadata modified, regardless of the retention setting.

Prerequisite to set privileged data access and write permissions

Before an application can place a labeled hold on an object, the application must have write and privileged data access permissions for the associated namespace.

Privileged permission can be set either programmatically by using the HCP Management API to update the dataAccessPermissions.xml file, or through the Tenant Management Console on the Users page of the Security menu.

Label limits

The following limits apply to the labeled hold feature:

Maximum label size
64 characters
Maximum number of labeled holds per object