doc/api/methods/workflows.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "workflows"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/workflows@
  14
  15 Object type: @7fd4e@
  16
  17 Example UUID: @zzzzz-7fd4e-0123456789abcde@
  18
  19 h2. Resource
  20
  21 Stores a "Common Workflow Language":http://commonwl.org (CWL) computational workflow that can be searched for, browsed and executed (submitted to Crunch) from the workbench.
  22
  23 Each Workflow offers the following optional attributes, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  24
  25 table(table table-bordered table-condensed).
  26 |_. Attribute|_. Type|_. Description|_. Example|
  27 |name|string|If not specified, will be set to any "name" from the "definition" attribute.||
  28 |description|string|If not specified, will be set to any "description" from the "definition" attribute.||
  29 |definition|string|A "Common Workflow Language" document.|Visit "Common Workflow Language":http://www.commonwl.org/ for details.|
  30 |collection_uuid|string|If non-null, a linked workflow definition stored in a Collection.  See below.|
  31
  32 h2. Workflows linked to Collections
  33
  34 If @collection_uuid@ is set, this significantly changes the behavior of the workflow record.
  35
  36 The linked Collection must have the following properties.  These are extracted from and must be synchronized with the workflow in @arv:workflowMain@. They are copied into the workflow collection's @properties@ for ease of processing by client tools such as Workbench.
  37
  38 table(table table-bordered table-condensed).
  39 |_. Attribute|_. Type|_. Description|
  40 |type|string|Value must be 'workflow'|
  41 |arv:workflowMain|string|The file path within the collection that is the top-level workflow that will be launched.|
  42 |arv:cwl_inputs|array of object|Array of "workflow input parameters":https://www.commonwl.org/v1.2/Workflow.html#WorkflowInputParameter in "fully expanded form":https://www.commonwl.org/v1.2/SchemaSalad.html#Document_preprocessing |
  43 |arv:cwl_outputs|array of object|Array of "workflow output parameters":https://www.commonwl.org/v1.2/Workflow.html#WorkflowOutputParameter in "fully expanded form":https://www.commonwl.org/v1.2/SchemaSalad.html#Document_preprocessing |
  44 |arv:cwl_requirements|array of object|Array of "workflow process requirements":https://www.commonwl.org/v1.2/Workflow.html#Workflow in "fully expanded form":https://www.commonwl.org/v1.2/SchemaSalad.html#Document_preprocessing (in particular, this must list requirements that affect initial launching of the workflow such as "WorkflowRunnerResources":{{site.baseurl}}/user/cwl/cwl-extensions.html ).|
  45 |arv:cwl_hints|array of object|Array of "workflow process hints":https://www.commonwl.org/v1.2/Workflow.html#Workflow in "fully expanded form":https://www.commonwl.org/v1.2/SchemaSalad.html#Document_preprocessing (in particular, this must list hints that affect initial launching of the workflow such as "WorkflowRunnerResources":{{site.baseurl}}/user/cwl/cwl-extensions.html ).|
  46
  47 When @collection_uuid@ is set, the workflow record @name@, @description@, @definition@ and @owner_uuid@ are all set from the linked collection.  The workflow record can no longer be updated directly, but changes to the linked collection will be reflected in the workflow record.  Trashing the linked collection will cause the workflow record to become trashed and eventually deleted as well.  The workflow record cannot be un-linked from a collection, only deleted and re-created.
  48
  49 When a workflow is linked to a collection, the collection can be queried and fetched together with the workflow.  The @filters@ argument can filter on attributes of the collection referenced by @collection_uuid@. For example, @[["collection.properties.category", "=", "WGS"]]@ will match workflow definitions linked to collections that have a "category" property with the value "WGS".  When using the "group contents":groups.html#contents API to fetch workflow records, in addition the previously-described filters, you can use @include=["collection_uuid"]@ to include the collection records corresponding to the @collection_uuid@ of the workflow records in the response.
  50
  51 h2. Methods
  52
  53 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
  54
  55 Required arguments are displayed in %{background:#ccffcc}green%.
  56
  57 Supports federated @create@, @delete@, @get@, @list@, and @update@.
  58
  59 h3. create
  60
  61 Create a new Workflow.
  62
  63 Arguments:
  64
  65 table(table table-bordered table-condensed).
  66 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  67 {background:#ccffcc}.|workflow|object|Workflow resource|request body||
  68
  69 h3. delete
  70
  71 Delete an existing Workflow.
  72
  73 Arguments:
  74
  75 table(table table-bordered table-condensed).
  76 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  77 {background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path||
  78
  79 h3. get
  80
  81 Get a Workflow's metadata by UUID.
  82
  83 Arguments:
  84
  85 table(table table-bordered table-condensed).
  86 |_. Argument |_. Type |_. Description |_. Location |_. Example |
  87 {background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path||
  88
  89 h3. list
  90
  91 List workflows.
  92
  93 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
  94
  95 The @filters@ argument can filter on attributes of the collection referenced by @collection_uuid@. For example, @[["collection.properties.category", "=", "WGS"]]@ will match workflow definitions linked to collections that have a "category" property with the value "WGS".
  96
  97 h3. update
  98
  99 Update attributes of an existing Workflow.
 100
 101 Arguments:
 102
 103 table(table table-bordered table-condensed).
 104 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 105 {background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path||
 106 |workflow|object||query||