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

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: API Methods
   5 title: "pipeline_templates"
   6
   7 ...
   8 {% comment %}
   9 Copyright (C) The Arvados Authors. All rights reserved.
  10
  11 SPDX-License-Identifier: CC-BY-SA-3.0
  12 {% endcomment %}
  13
  14 p=. *Legacy.  This endpoint is read-only and disabled by default in new installations.*
  15
  16 API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/pipeline_templates@
  17
  18 Object type: @p5p6p@
  19
  20 Example UUID: @zzzzz-p5p6p-0123456789abcde@
  21
  22 h2. Resource
  23
  24 Deprecated.  A pipeline template is a collection of jobs that can be instantiated as a pipeline_instance.
  25
  26 Each PipelineTemplate has, in addition to the "Common resource fields":{{site.baseurl}}/api/resources.html:
  27
  28 table(table table-bordered table-condensed).
  29 |_. Attribute|_. Type|_. Description|_. Example|
  30 |name|string|||
  31 |components|hash|||
  32
  33 The pipeline template consists of "name" and "components".
  34
  35 table(table table-bordered table-condensed).
  36 |_. Attribute    |_. Type |_. Accepted values                           |_. Required|_. Description|
  37 |name            |string  |any                                          |yes        |The human-readable name of the pipeline template.|
  38 |components      |object  |JSON object containing job submission objects|yes        |The component jobs that make up the pipeline, with the component name as the key. |
  39
  40 h3. Components
  41
  42 The components field of the pipeline template is a JSON object which describes the individual steps that make up the pipeline.  Each component is an Arvados job submission.  "Parameters for job submissions are described on the job method page.":{{site.baseurl}}/api/methods/jobs.html#create  In addition, a component can have the following parameters:
  43
  44 table(table table-bordered table-condensed).
  45 |_. Attribute    |_. Type          |_. Accepted values |_. Required|_. Description|
  46 |output_name     |string or boolean|string or false    |no         |If a string is provided, use this name for the output collection of this component.  If the value is false, do not create a permanent output collection (an temporary intermediate collection will still be created).  If not provided, a default name will be assigned to the output.|
  47
  48 h3. Script parameters
  49
  50 When used in a pipeline, each parameter in the 'script_parameters' attribute of a component job can specify that the input parameter must be supplied by the user, or the input parameter should be linked to the output of another component.  To do this, the value of the parameter should be JSON object containing one of the following attributes:
  51
  52 table(table table-bordered table-condensed).
  53 |_. Attribute    |_. Type |_. Accepted values                               |_. Description|
  54 |default         |any     |any                                              |The default value for this parameter.|
  55 |required        |boolean |true or false                                    |Specifies whether the parameter is required to have a value or not.|
  56 |dataclass       |string  |One of 'Collection', 'File' [1], 'number', or 'text' |Data type of this parameter.|
  57 |search_for      |string  |any string                                       |Substring to use as a default search string when choosing inputs.|
  58 |output_of       |string  |the name of another component in the pipeline    |Specifies that the value of this parameter should be set to the 'output' attribute of the job that corresponds to the specified component.|
  59 |title           |string  |any string                                       |User friendly title to display when choosing parameter values|
  60 |description     |string  |any string                                       |Extended text description for describing expected/valid values for the script parameter|
  61 |link_name       |string  |any string                                       |User friendly name to display for the parameter value instead of the actual parameter value|
  62
  63 The 'output_of' parameter is especially important, as this is how components are actually linked together to form a pipeline.  Component jobs that depend on the output of other components do not run until the parent job completes and has produced output.  If the parent job fails, the entire pipeline fails.
  64
  65 fn1. The 'File' type refers to a specific file within a Keep collection in the form 'collection_hash/filename', for example '887cd41e9c613463eab2f0d885c6dd96+83/bob.txt'.
  66
  67 The 'search_for' parameter is meaningful only when input dataclass of type Collection or File is used. If a value is provided, this will be preloaded into the input data chooser dialog in Workbench. For example, if your input dataclass is a File and you are interested in a certain filename extention, you can preconfigure it in this attribute.
  68
  69 h3. Examples
  70
  71 This is a pipeline named "Filter MD5 hash values" with two components, "do_hash" and "filter".  The "input" script parameter of the "do_hash" component is required to be filled in by the user, and the expected data type is "Collection".  This also specifies that the "input" script parameter of the "filter" component is the output of "do_hash", so "filter" will not run until "do_hash" completes successfully.  When the pipeline runs, past jobs that meet the criteria described above may be substituted for either or both components to avoid redundant computation.
  72
  73 <notextile><pre>
  74 {
  75   "name": "Filter MD5 hash values",
  76   "components": {
  77     "do_hash": {
  78       "script": "hash.py",
  79       "repository": "<b>you</b>/<b>you</b>",
  80       "script_version": "main",
  81       "script_parameters": {
  82         "input": {
  83           "required": true,
  84           "dataclass": "Collection",
  85           "search_for": ".fastq.gz",
  86           "title":"Please select a fastq file"
  87         }
  88       },
  89     },
  90     "filter": {
  91       "script": "0-filter.py",
  92       "repository": "<b>you</b>/<b>you</b>",
  93       "script_version": "main",
  94       "script_parameters": {
  95         "input": {
  96           "output_of": "do_hash"
  97         }
  98       },
  99     }
 100   }
 101 }
 102 </pre></notextile>
 103
 104 This pipeline consists of three components.  The components "thing1" and "thing2" both depend on "cat_in_the_hat".  Once the "cat_in_the_hat" job is complete, both "thing1" and "thing2" can run in parallel, because they do not depend on each other.
 105
 106 <notextile><pre>
 107 {
 108   "name": "Wreck the house",
 109   "components": {
 110     "cat_in_the_hat": {
 111       "script": "cat.py",
 112       "repository": "<b>you</b>/<b>you</b>",
 113       "script_version": "main",
 114       "script_parameters": { }
 115     },
 116     "thing1": {
 117       "script": "thing1.py",
 118       "repository": "<b>you</b>/<b>you</b>",
 119       "script_version": "main",
 120       "script_parameters": {
 121         "input": {
 122           "output_of": "cat_in_the_hat"
 123         }
 124       },
 125     },
 126     "thing2": {
 127       "script": "thing2.py",
 128       "repository": "<b>you</b>/<b>you</b>",
 129       "script_version": "main",
 130       "script_parameters": {
 131         "input": {
 132           "output_of": "cat_in_the_hat"
 133         }
 134       },
 135     },
 136   }
 137 }
 138 </pre></notextile>
 139
 140 This pipeline consists of three components.  The component "cleanup" depends on "thing1" and "thing2".  Both "thing1" and "thing2" are started immediately and can run in parallel, because they do not depend on each other, but "cleanup" cannot begin until both "thing1" and "thing2" have completed.
 141
 142 <notextile><pre>
 143 {
 144   "name": "Clean the house",
 145   "components": {
 146     "thing1": {
 147       "script": "thing1.py",
 148       "repository": "<b>you</b>/<b>you</b>",
 149       "script_version": "main",
 150       "script_parameters": { }
 151     },
 152     "thing2": {
 153       "script": "thing2.py",
 154       "repository": "<b>you</b>/<b>you</b>",
 155       "script_version": "main",
 156       "script_parameters": { }
 157     },
 158     "cleanup": {
 159       "script": "cleanup.py",
 160       "repository": "<b>you</b>/<b>you</b>",
 161       "script_version": "main",
 162       "script_parameters": {
 163         "mess1": {
 164           "output_of": "thing1"
 165         },
 166         "mess2": {
 167           "output_of": "thing2"
 168         }
 169       }
 170     }
 171   }
 172 }
 173 </pre></notextile>
 174
 175 h2. Methods
 176
 177 See "Common resource methods":{{site.baseurl}}/api/methods.html for more information about @create@, @delete@, @get@, @list@, and @update@.
 178
 179 Required arguments are displayed in %{background:#ccffcc}green%.
 180
 181 h3. create
 182
 183 Create a new PipelineTemplate.
 184
 185 Arguments:
 186
 187 table(table table-bordered table-condensed).
 188 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 189 |pipeline_template|object||query||
 190
 191 h3. delete
 192
 193 Delete an existing PipelineTemplate.
 194
 195 Arguments:
 196
 197 table(table table-bordered table-condensed).
 198 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 199 {background:#ccffcc}.|uuid|string|The UUID of the PipelineTemplate in question.|path||
 200
 201 h3. get
 202
 203 Gets a PipelineTemplate's metadata by UUID.
 204
 205 Arguments:
 206
 207 table(table table-bordered table-condensed).
 208 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 209 {background:#ccffcc}.|uuid|string|The UUID of the PipelineTemplate in question.|path||
 210
 211 h3. list
 212
 213 List pipeline_templates.
 214
 215 See "common resource list method.":{{site.baseurl}}/api/methods.html#index
 216
 217 h3. update
 218
 219 Update attributes of an existing PipelineTemplate.
 220
 221 Arguments:
 222
 223 table(table table-bordered table-condensed).
 224 |_. Argument |_. Type |_. Description |_. Location |_. Example |
 225 {background:#ccffcc}.|uuid|string|The UUID of the PipelineTemplate in question.|path||
 226 |pipeline_template|object||query||