The Content Engines APIs support recovery bins, allowing you to implement delete-and-recovery operations in your client applications. Such operations are typically implemented in graphical user intefaces, where end users drag and drop objects into trash bins, restore accidentally deleted objects, and empty trash bins to permanently remove objects. At the level of the Content Engine API, a container for deleted objects is a recovery bin, and deleted containees are recovery items.
A recovery bin is represented by the CmRecoveryBin class. Multiple recovery bins can be created, typically one per user. An object placed in a recovery bin is represented by the CmRecoveryItem class, with all deleted objects in the same recovery bin represented by the CmRecoveryItemSet.
The action of placing an object into a recovery bin is marking it for deletion, so called because the server flags the object for deletion but keeps it in the object store database. Objects that are marked for deletion are referred to as recoverable objects because, potentially, they can be unmarked for deletion; that is, they can be removed from the recovery bin and restored to their previous state.
The action of deleting a recovery item is a purge, which removes the item from the object store database. A purge has the same result as invoking the delete method on any IndependentlyPersistableObject object, in which the deleted object is irrecoverable.
The actions associated with this feature — marking for deletion, recovery, and purge — trigger the MarkForDeleteEvent, RecoveryEvent, and DeletionEvent, respectively. For more information, see Subscribable and AuditableEvents.
For code examples, see Working with Recovery Bins.
In this release, instances of VersionSeries and CustomObject can be explicitly marked for deletion. These classes include the markForDeletion method, so called because when the method is invoked, the server sets the object'sCMISMarkedforDeletion property to true.
The mark-for-deletion action is subject to delete-prevention mechanisms that might be applied to an object, such as a hold, retention, or a security constraint.
Marking an object for deletion that contains object-valued properties (OVPs) has a cascading impact on certain objects referenced by the OVPs, as determined by the DeletionAction property set on the OVPs. A DeletionAction property can have one of the following values:
If a VersionSeries or CustomObject is marked for deletion, and if the object contains OVPs with a DeletionAction of CASCADE, then the server sets theCMISMarkedforDeletion property on each object referenced by the OVPs. The server also creates a CmRecoveryItem object to represent the original object that was marked for deletion (VersionSeries or CustomObject), and it updates the cascade-deleted objects to point to the same CmRecoveryItem object.
When a VersionSeries or CustomObject is marked for deletion, the server executes a cascade discovery process to determine if objects referenced by OVPs are eligible for deletion marking. The following limitations apply to cascading relationships:
In addition to the deletion marking operation, cascading relationships apply to recovery and purge operations. However, for recovery, the server does not execute a cascade discovery process for objects referenced by OVPs.
If an object that is filed in a folder is marked for deletion, the server modifies the containment name in any relationship objects referenced by the object marked for deletion. This is done to prevent a collision with any new object filed into the same folder that uses the same containment name. If the object is later restored, the server attempts to change the containment names back to their original values (before the object was marked for deletion). If a naming collision is detected, the containment name of the object is automatically appended with a suffix to make the name unique. For details, see the ContainmentName property.
Like deletion of an object, marking for deletion requires the DELETE right. The user who marks an object for deletion can also purge the resulting recovery item because purge requires the DELETE right on the original object that was marked for deletion. Recovery of an item also requires the DELETE right, but on the CmRecoveryItem object, not on the original object that was marked for deletion. By default, the set of CmRecoveryItem objects in a recovery bin inherit their security from the CmRecoveryBin object that contains them. For more information, see Access rights required to take actions.
Recoverable objects are not accessible to most users outside of the context of the recovery bin. That is, users with typical access rights can only work with recovery bins and recovery items to restore or to purge recoverable objects. Unless granted special permission, users cannot retrieve or query recoverable objects. Retrieval through fetchObject or Factory methods results in an E_OBJECT_NOT_FOUND error. For queries, recoverable objects do not show up in the result.
Users who require higher-level access to recoverable objects can be granted the access right VIEW_RECOVERABLE_OBJECTS on the object store. With this special permission, a user can retrieve or query all recoverable objects, as well as modify recoverable objects, subject to the typical permissions granted to users for modifying objects. An exception to modifying recoverable objects applies to versioned documents. A user with the VIEW_RECOVERABLE_OBJECTS right cannot check out a version of a recoverable document.
One use case for granting the VIEW_RECOVERABLE_OBJECTS right is legal discovery, where a user is responsible for finding and holding all objects that apply to a litigation scenario. For example, a query for documents based on litigation criteria might result in documents that are marked for deletion. The legal discovery user would then put a hold on all documents, including the ones marked for deletion. Recoverable objects that are on hold cannot be purged. Similarly, if a user with the VIEW_RECOVERABLE_OBJECTS right applies retention or denies owners the DELETE right to recoverable objects, then those recoverable objects cannot be purged.
Documents and custom objects can act as security proxies for other objects. If a security proxy object is marked for deletion, the server continues to allow for the security proxy's permissions to be inherited by the child object. For example, if DocA is a security proxy for DocB and DocA is marked for deletion, then DocB continues to inherit its security from DocA, even though DocA cannot be queried or retrieved by users with typical access rights. Only users with the VIEW_RECOVERABLE_OBJECTS permission on the object store can access DocA.
Although objects marked for deletion are not viewable by most users, the objects exist in the object store database, and they are potentially recoverable. Therefore, the server maintains the inherited security from security proxy objects that are recoverable. This behavior can result in an inheriting object granting more permissions than would be expected from inspection by someone without VIEW_RECOVERABLE_OBJECTS permission, potentially causing confusion, or, in unusual circumstances, being counter to the intention of marking the proxy object for deletion.
To avoid these potential issues, it is recommended that objects whose primary purpose is to act as a security proxy not be marked for deletion. If the intent is to terminate the proxy relationship, a delete should be used instead.