From 882be2b6f0e2b45e282cf584cf14e5dccc4b5b9a Mon Sep 17 00:00:00 2001 From: radhika Date: Mon, 12 Sep 2016 13:49:35 -0400 Subject: [PATCH] 9836: Add workflow to api documentation. --- doc/_config.yml | 2 + doc/api/methods/workflows.html.textile.liquid | 67 +++++++ doc/api/schema/Workflow.html.textile.liquid | 176 ++++++++++++++++++ 3 files changed, 245 insertions(+) create mode 100644 doc/api/methods/workflows.html.textile.liquid create mode 100644 doc/api/schema/Workflow.html.textile.liquid diff --git a/doc/_config.yml b/doc/_config.yml index 96b8a52ef6..fd9bf7ce85 100644 --- a/doc/_config.yml +++ b/doc/_config.yml @@ -123,6 +123,7 @@ navbar: - api/methods/traits.html.textile.liquid - api/methods/users.html.textile.liquid - api/methods/virtual_machines.html.textile.liquid + - api/methods/workflows.html.textile.liquid - Schema: - api/schema/ApiClientAuthorization.html.textile.liquid - api/schema/ApiClient.html.textile.liquid @@ -144,6 +145,7 @@ navbar: - api/schema/Trait.html.textile.liquid - api/schema/User.html.textile.liquid - api/schema/VirtualMachine.html.textile.liquid + - api/schema/Workflow.html.textile.liquid installguide: - Overview: - install/index.html.textile.liquid diff --git a/doc/api/methods/workflows.html.textile.liquid b/doc/api/methods/workflows.html.textile.liquid new file mode 100644 index 0000000000..c1b6c3cfe7 --- /dev/null +++ b/doc/api/methods/workflows.html.textile.liquid @@ -0,0 +1,67 @@ +--- +layout: default +navsection: api +navmenu: API Methods +title: "workflows" + +... + +See "REST methods for working with Arvados resources":{{site.baseurl}}/api/methods.html + +API endpoint base: @https://{{ site.arvados_api_host }}/arvados/v1/workflows@ + +Required arguments are displayed in %{background:#ccffcc}green%. + + +h2. create + +Create a new Workflow. + +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location |_. Example | +|workflow|object||query|| + +h2. delete + +Delete an existing Workflow. + +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location |_. Example | +{background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path|| + +h2. get + +Get a Workflow's metadata by UUID. + +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location |_. Example | +{background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path|| + +h2. list + +List workflows. + +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location |_. Example | +|limit|integer (default 100)|Maximum number of workflows to return.|query|| +|order|string|Order in which to return matching workflows.|query|| +|filters|array|Conditions for filtering workflows.|query|| + +h2. update + +Update attributes of an existing Workflow. + +Arguments: + +table(table table-bordered table-condensed). +|_. Argument |_. Type |_. Description |_. Location |_. Example | +{background:#ccffcc}.|uuid|string|The UUID of the Workflow in question.|path|| +|workflow|object||query|| diff --git a/doc/api/schema/Workflow.html.textile.liquid b/doc/api/schema/Workflow.html.textile.liquid new file mode 100644 index 0000000000..bd95a336ca --- /dev/null +++ b/doc/api/schema/Workflow.html.textile.liquid @@ -0,0 +1,176 @@ +--- +layout: default +navsection: api +navmenu: Schema +title: Workflow + +... + +A *Workflow* is a definition of work to be performed by a Crunch2 process. It defines the steps and inputs for the process. + +h2. Methods + +See "workflows":{{site.baseurl}}/api/methods/workflows.html + +h2. Resource + +Each Workflow offers the following optional attributes, in addition to the usual "attributes of Arvados resources":{{site.baseurl}}/api/resources.html: + +table(table table-bordered table-condensed). +|_. Attribute|_. Type|_. Description|_. Example| +|name|string|If not specified, will be set to any 'name' from the 'definition' attribute.|| +|description|string|If not specified, will be set to any 'description' from the 'definition' attribute.|| +|definition|string|A definition yaml that defines the steps in the workflow.|See "Workflow definition":#workflow_definition below for details.| + +h2(#workflow_definition). Workflow definition + +The workflow definition is a string dump of the yaml document that describes the steps to be executed by any container_request created using it. It is expected to be a valid cwl document that specifies the steps and inputs to be used by the process. An example workflow with explanation follow: + +h3. Example workflow + +
{
+    "$graph": [
+        {
+            "class": "Workflow",
+            "id": "#main",
+            "inputs": [
+                {
+                    "default": {
+                        "basename": "blorp.txt",
+                        "class": "File",
+                        "location": "keep:99999999999999999999999999999991+99/input/blorp.txt"
+                    },
+                    "id": "#main/x",
+                    "type": "File"
+                }
+            ],
+            "steps": [
+                {
+                    "id": "#main/step1",
+                    "in": [
+                        {
+                            "id": "#main/step1/x",
+                            "source": "#main/x"
+                        }
+                    ],
+                    "out": [],
+                    "run": "#submit_tool.cwl"
+                }
+            ]
+        }
+        . . .
+    ],
+    "cwlVersion": "v1.0"
+}
+ +h3. Explanation + +In the above example, the class @workflow@ in @$graph@ contains an element with the id @#main@ with @inputs@ and @steps@. In addition, information such as cwlVersion, name, description can be provided as well. + +table(table table-bordered table-condensed). +|_. Element Id|_. Description|_. Notes| +|@#main@|Specifies the steps and inputs of the workflow.|| +|@inputs@|Specifies the inputs for the workflow. The inputs can be required or optional. +In this example, there is one input of type @File@ with id @#main/x@ with a @default@ value. +See "Supported input types":#workflow_inputs below for the supported input types.|
{
+  "default": {
+    "basename": "blorp.txt",
+    "class": "File",
+    "location": "keep:99999999999999999999999999999991+99/input/blorp.txt"
+  },
+  "id": "#main/x",
+  "type": "File"
+}
| +|@steps@|Specifies the steps to be executed by this workflow. In this example, there is one step with id @#main/step1/x@.|| + +h3(#workflow_inputs). Supported input types + +Currently, input types @boolean@, @double@, @float@, @integer@, @long@, @string@, @Directory@, @File@, and @enum@ are supported. Each can be specified as required or optional. + +table(table table-bordered table-condensed). +|_. Input type|_. Example|_. Notes| +|@boolean@ - required|
{
+  "type": "boolean",
+  "id": "a_required_boolean_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|*Note:* The @id@ needs to be unique among all specified inputs. +e.g., @a_required_boolean_input@| +|@boolean@ - optional|
{
+  "type": ["null", "boolean"],
+  "id": "a_optional_boolean_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "boolean"]@| +|@double@|
{
+  "type": "double",
+  "id": "a_double_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "double"]@| +|@float@|
{
+  "type": "float",
+  "id": "a_float_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "float"]@| +|@int@|
{
+  "type": "int",
+  "id": "an_int_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "int"]@| +|@long@|
{
+  "type": "long",
+  "id": "a_long_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "long"]@| +|@string@|
{
+  "type": "string",
+  "id": "a_string_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "string"]@| +|@Directory@|
{
+  "type": "Directory",
+  "id": "a_directory_input",
+  "label": "an optional label for this input directory / collection",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "Directory"]@| +|@File@|
{
+  "type": "File",
+  "id": "a_file_input",
+  "label": "an optional label for this input  file in a collection",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +@"type": ["null", "File"]@| +|@enum@ - required|
{
+  "type": {
+    "type": "enum",
+    "symbols": ["a", "b", "c"]
+  },
+  "id": "a_required_enum_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|The @symbols@ are the items in this enum.| +|@enum@ - optional|
{
+  "type":  ["null", {
+    "type": "enum",
+    "symbols": ["a", "b", "c"]
+  }],
+  "id": "a_required_enum_input",
+  "label": "an optional label for this input",
+  "inputBinding": {"position": 1}
+}
|Include @null@ in @type@ definition to mark it as optional. +
"type":  ["null", {
+    "type": "enum",
+    "symbols": [. . .]
+  }]
| -- 2.30.2