[Doc] Add user documentation for trash/delete lifecycle
We need a user-oriented description of the lifecycle for collections which are trashed, expiring, deleted, etc.
Design docs which can be used as a basis:
#4 Updated by Radhika Chippada over 4 years ago
Branch 11823-collection-lifecycle-doc @ 5bace39d3a7054663ff8b8e79c5ca2a4c3502300
- Please suggest better phrasing for “Crunch-dispatch will “expire” intermediary collections during the running of a process”
- Since we do not have a delete option in the /collections page in workbench, I used the phrase project’s Data collections for this purpose
- Since we implemented an untrash action instead of supporting update_attributes to untrash, this is what is listed in the doc
#5 Updated by Peter Amstutz over 4 years ago
- Keep data lifecycle
Keep collection lifecycle
- During it's lifetime
During its lifetime
- In addition to the two obvious states "persisted" and "permanently deleted", it can also be in "expiring" or "trashed" states.
These states are "persisted", "expiring", "trashed" and "permanently deleted".
- A trashed collection has it's is_trashed attribute set to true. It's trash_at time is set to "current_time", the time at which it is marked as trash, either by the user calling a delete operation on the collection or by the system marking an expiring collection as trash. In addition, it's delete_at time is set to current_time plus the blobSignatureTTL. It is no longer readable through normal data access APIs. However, it is still recoverable until it is permanently deleted at it's delete_at time.
A collection is expiring when it has a trash_at time in the future. An expiring collection can be accessed as normal, but is scheduled to be trashed automatically at the trash_at time.
A collection is trashed when it has a trash_at time in the past. The is_trashed attribute will also be "true". The delete operation immediately puts the collection in the trash by setting the trash_at time to "now". Once trashed, the collection is no longer readable through normal data access APIs. The collection will have delete_at set to some time in the future. The trashed collection is recoverable until the delete_at time passes, at which point the collection is permanently deleted.
- Trashing a collection using workbench (in the Recovering trashed collections section)
Un-trashing a collection using workbench
- You can then delete a particular collection using arv using it's uuid.
You can then untrash a particular collection by uuid using arv
In the example for listing trashed collections, perhaps we want a filter to limit it to just trashed collections?
arv collection list --include_trash=true --filters '[["is_trashed", "=", "true"]]'
#7 Updated by Peter Amstutz over 4 years ago
A two small comments:
The first line 'These states are “persisted”, “expiring”, “trashed” and “permanently deleted”.' should be in bold for consistency with the next paragraph: 'These states are persisted, expiring, trashed and permanently deleted.'
The Collection lifecycle attributes table, under the "collection state" column, should say "persisted collection" instead of "normal collection" for consistency.
LGTM with those tweaks.