doc/user/tutorials/tutorial-keep-collection-lifecycle.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Keep collection lifecycle"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 During it's lifetime, a keep collection can be in various states. These states are *persisted*, *expiring*, *trashed*  and *permanently deleted*.
  13
  14 The nominal state is *persisted* which means the data can be can be accessed normally and will be retained indefinitely.
  15
  16 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.
  17
  18 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.
  19
  20 # "*Deleting / trashing collections*":#delete-collection
  21 # "*Recovering trashed collections*":#trash-recovery
  22 # "*Collection lifecycle attributes*":#collection_attributes
  23
  24 {% include 'tutorial_expectations' %}
  25
  26 h2(#delete-collection). Deleting / trashing collections
  27
  28 A collection can be deleted using either the arv command line tool or the workbench.
  29
  30 h3. Trashing a collection using workbench
  31
  32 To trash a collection using workbench, go to the Data collections tab in the project, and use the <i class="fa fa-fw fa-trash-o"></i> trash icon for this collection row.
  33
  34 h3. Trashing a collection using arv command line tool
  35
  36 <pre>
  37 arv collection delete --uuid=zzzzz-4zz18-xxxxxxxxxxxxxxx
  38 </pre>
  39
  40 h2(#trash-recovery). Recovering trashed collections
  41
  42 A collection can be un-trashed / recovered using either the arv command line tool or the workbench.
  43
  44 h3. Un-trashing a collection using workbench
  45
  46 To untrash a collection using workbench, go to trash page on workbench by clicking on the "Trash" icon in the top navigation in workbench and use the recycle icon or selection dropdown option.
  47
  48 !{display: block;margin-left: 25px;margin-right: auto;border:1px solid lightgray;}{{ site.baseurl }}/images/trash-button-topnav.png!
  49
  50 h3. Un-trashing a collection using arv command line tool
  51
  52 You can list the trashed collections using the list command.
  53
  54 <pre>
  55 arv collection list --include-trash=true --filters '[["is_trashed", "=", "true"]]'
  56 </pre>
  57
  58 You can then untrash a particular collection using arv using it's uuid.
  59
  60 <pre>
  61 arv collection untrash --uuid=zzzzz-4zz18-xxxxxxxxxxxxxxx
  62 </pre>
  63
  64 h2(#collection_attributes). Collection lifecycle attributes
  65
  66 As listed above the attributes that are used to manage a collection lifecycle are it's *is_trashed*, *trash_at*, and *delete_at*. The table below lists the values of these attributes and how they influence the state of a collection and it's accessibility.
  67
  68 table(table table-bordered table-condensed).
  69 |_. collection state|_. is_trashed|_. trash_at|_. delete_at|_. get|_. list|_. list?include_trash=true|_. can be modified|
  70 |persisted collection|false |null |null |yes |yes |yes |yes |
  71 |expiring collection|false |future |future |yes  |yes |yes |yes |
  72 |trashed collection|true |past |future |no |no |yes |only is_trashed, trash_at and delete_at attribtues|
  73 |deleted collection|true|past |past |no |no |no |no |