15422: Add provenance and used_by to collection API doc

Arvados-DCO-1.1-Signed-off-by: Peter Amstutz <pamstutz@veritasgenetics.com>

diff --git a/apps/workbench/app/helpers/provenance_helper.rb b/apps/workbench/app/helpers/provenance_helper.rb
index 8a8337fe12ccf45b4d28d208031127a4d38babe0..cef5cc7ee816db5e906537e6da643b33223466f7 100644 (file)
--- a/apps/workbench/app/helpers/provenance_helper.rb
+++ b/apps/workbench/app/helpers/provenance_helper.rb
@@ -151,61 +151,6 @@ module ProvenanceHelper
       gr
     end
 
-    # def cr_edges cr, edge_opts={}
-    #   gr = ""
-
-    #   gr += describe_node(cr[:uuid], {href: {controller: 'container_requests',
-    #                                          id: cr[:uuid]},
-    #                                   label: cr[:name],
-    #                                   shape: 'oval'})
-    #   # Connect child CRs
-    #   children = @opts[:cr_children_of].andand[cr[:uuid]]
-    #   if children
-    #     children.each do |child|
-    #       gr += edge(child[:uuid], cr[:uuid], {label: 'child'})
-    #     end
-    #   end
-    #   # Output collection node
-    #   if cr[:output_uuid] and @opts[:output_collections][cr[:output_uuid]]
-    #     c = @opts[:output_collections][cr[:output_uuid]]
-    #     gr += describe_node(c[:portable_data_hash],
-    #                         {
-    #                           label: c[:name],
-    #                           col_uuid: c[:uuid],
-    #                         })
-    #     gr += edge(cr[:uuid],
-    #                c[:portable_data_hash],
-    #                {label: 'output'})
-    #   end
-    #   # Input collection nodes
-    #   output_pdhs = @opts[:output_collections].values.collect{|oc|
-    #     oc[:portable_data_hash]}
-    #   ProvenanceHelper::cr_input_pdhs(cr).each do |pdh|
-    #     if not output_pdhs.include?(pdh)
-    #       # Search for collections on the same project first
-    #       cols = @opts[:input_collections][pdh].andand.select{|ic|
-    #         ic[:owner_uuid] == cr[:owner_uuid]}
-    #       if not cols or cols.empty?
-    #         # Search for any collection with this PDH
-    #         cols = @opts[:input_collections][pdh]
-    #       end
-    #       if cols
-    #         names = cols.collect{|x| x[:name]}.uniq
-    #       else
-    #         names = ['(collection not found)']
-    #       end
-    #       input_name = names.first
-    #       if names.length > 1
-    #         input_name += " + #{names.length - 1} more"
-    #       end
-    #       gr += describe_node(pdh, {label: input_name})
-    #     end
-    #     gr += edge(pdh, cr[:uuid], {label: 'input'})
-    #   end
-
-    #   gr
-    # end
-
     def cr_edges cont, edge_opts={}
       uuid = cont[:uuid]
       gr = ""

diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid
index d611c5b1613ce4ba93c48039c6c335457c5584e4..a62600e34d5651166251dea3952039ff572e28fb 100644 (file)
--- a/doc/api/methods/collections.html.textile.liquid
+++ b/doc/api/methods/collections.html.textile.liquid
@@ -124,3 +124,36 @@ table(table table-bordered table-condensed).
 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 {background:#ccffcc}.|uuid|string|The UUID of the Collection to untrash.|path||
 |ensure_unique_name|boolean (default false)|Rename collection uniquely if untrashing it would fail with a unique name conflict.|query||
+
+
+h3. provenance
+
+Returns a list of objects in the database that directly or indirectly contributed to producing this collection, such as the container request that produced this collection as output.
+
+The general algorithm is:
+
+# Visit the container request that produced this collection (via "output_uuid" or "log_uuid")
+# Visit the input collections to that container request (via "mounts", or "container_image")
+# Iterate until there are no more objects to visit
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the Collection to get provenance.|path||
+
+h3. used_by
+
+Returns a list of objects in the database this collection directly or indirectly contributed to, such as containers that takes this collection as input.
+
+The general algorithm is:
+
+# Visit containers that take this collection as input (via "mounts", or "container_image")
+# Visit collections produced by those containers (via "output" or "log")
+# Iterate until there are no more objects to visit
+
+Arguments:
+
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+{background:#ccffcc}.|uuid|string|The UUID of the Collection to get usage.|path||

diff --git a/services/api/app/controllers/arvados/v1/collections_controller.rb b/services/api/app/controllers/arvados/v1/collections_controller.rb
index ede6fbd899a2a1e2ce81772e40b753ede98f6e79..99e635b20a3bd5fe6dcffa8ce03c278c668bc65e 100644 (file)
--- a/services/api/app/controllers/arvados/v1/collections_controller.rb
+++ b/services/api/app/controllers/arvados/v1/collections_controller.rb
@@ -215,13 +215,13 @@ class Arvados::V1::CollectionsController < ApplicationController
           visited[uuid] = c.as_api_response
           if direction == :search_up
             # Follow upstream collections referenced in the script parameters
-            find_collections(visited, c) do |hash, col_uuid|
+            find_collections(visited, c, ignore_columns=["log", "output"]) do |hash, col_uuid|
               search_edges(visited, hash, :search_up) if hash
               search_edges(visited, col_uuid, :search_up) if col_uuid
             end
           elsif direction == :search_down
             # Follow downstream job output
-            search_edges(visited, c.output, direction)
+            search_edges(visited, c.output, :search_down)
           end
         end
       elsif rsc == ContainerRequest
@@ -230,13 +230,13 @@ class Arvados::V1::CollectionsController < ApplicationController
           visited[uuid] = c.as_api_response
           if direction == :search_up
             # Follow upstream collections
-            find_collections(visited, c, ignore_columns=["log_uuid"]) do |hash, col_uuid|
+            find_collections(visited, c, ignore_columns=["log_uuid", "output_uuid"]) do |hash, col_uuid|
               search_edges(visited, hash, :search_up) if hash
               search_edges(visited, col_uuid, :search_up) if col_uuid
             end
           elsif direction == :search_down
             # Follow downstream job output
-            search_edges(visited, c.output_uuid, direction)
+            search_edges(visited, c.output_uuid, :search_down)
           end
         end
       elsif rsc == Collection
@@ -253,7 +253,7 @@ class Arvados::V1::CollectionsController < ApplicationController
               search_edges(visited, cr.uuid, :search_up)
             end
           elsif direction == :search_down
-            search_edges(visited, c.portable_data_hash, direction)
+            search_edges(visited, c.portable_data_hash, :search_down)
           end
         end
       elsif rsc != nil