Merge pull request #43 from common-workflow-language/data-link

Define data link.  Also specify default interpretation of exit codes.

Author: mr-c

CommandLineTool.yml

@@ -77,6 +77,7 @@ $graph:
         `DockerRequirement.dockerOutputDirectory` this it possible to
         control the locations of both input and output files when
         running in containers.
+      * Specify default success/fail interpretation of exit codes when not given.
 
       See also the [CWL Workflow Description, v1.2.0-dev4 changelog](Workflow.html#Changelog).
       For other changes since CWL v1.0, see the
@@ -702,20 +703,26 @@ $graph:
       doc: |
         Exit codes that indicate the process completed successfully.
 
+        If not specified, only exit code 0 is considered success.
+
     - name: temporaryFailCodes
       type: int[]?
       doc: |
         Exit codes that indicate the process failed due to a possibly
         temporary condition, where executing the process with the same
         runtime environment and inputs may produce different results.
 
+        If not specified, no exit codes are considered temporary failure.
+
     - name: permanentFailCodes
       type: int[]?
       doc:
         Exit codes that indicate the process failed due to a permanent logic
         error, where executing the process with the same runtime environment and
         same inputs is expected to always fail.
 
+        If not specified, all exit codes except 0 are considered permanent failure.
+
 
 - type: record
   name: DockerRequirement

Workflow.yml

@@ -70,6 +70,7 @@ $graph:
         * Specify behavior when `source` is a single-item list and no
           linkMerge is set.
         * Added discussion about handling different document versions.
+        * Added definition of **data link**
 
       See also the [CWL Command Line Tool Description, v1.2.0-dev4 changelog](CommandLineTool.html#Changelog).
       For other changes since CWL v1.0, see the
@@ -660,15 +661,21 @@ $graph:
     and may execute in any order or execute concurrently.  A workflow is
     complete when all steps have been executed.
 
-    Dependencies between parameters are expressed using the `source` field on
-    [workflow step input parameters](#WorkflowStepInput) and [workflow output
+    Dependencies between parameters are expressed using the `source`
+    field on [workflow step input parameters](#WorkflowStepInput) and
+    `outputSource` field on [workflow output
     parameters](#WorkflowOutputParameter).
 
-    The `source` field expresses the dependency of one parameter on another
-    such that when a value is associated with the parameter specified by
-    `source`, that value is propagated to the destination parameter.  When all
-    data links inbound to a given step are fufilled, the step is ready to
-    execute.
+    The `source` field on each workflow step input parameter expresses
+    the data links that contribute to the value of the step input
+    parameter (the "sink").  A workflow step can only begin execution
+    when every data link connected to a step has been fulfilled.
+
+    The `outputSource` field on each workflow step input parameter
+    expresses the data links that contribute to the value of the
+    workflow output parameter (the "sink").  Workflow execution cannot
+    complete successfully until every data link connected to an output
+    parameter has been fulfilled.
 
     ## Workflow success and failure
 

concepts.md

@@ -71,11 +71,13 @@ A **process** is a basic unit of computation which accepts input data,
 performs some computation, and produces output data. Examples include
 CommandLineTools, Workflows, and ExpressionTools.
 
-An **input object** is an object describing the inputs to an invocation of
-a process.
+An **input object** is an object describing the inputs to an
+invocation of a process.  The fields of the input object are referred
+to as "input parameters".
 
-An **output object** is an object describing the output resulting from an
-invocation of a process.
+An **output object** is an object describing the output resulting from
+an invocation of a process.  The fields of the output object are
+referred to as "output parameters".
 
 An **input schema** describes the valid format (required fields, data types)
 for an input object.
@@ -389,6 +391,12 @@ the document.  The responsibilities of the workflow platform may include
 scheduling process invocation, setting up the necessary runtime environment,
 making input data available, invoking the tool process, and collecting output.
 
+A **data link** is a connection from a "Source" parameter to a "Sink"
+parameter.  A data link expresses that when a value becomes available
+for the source parameter, that value should be copied to the "sink"
+parameter.  Reflecting the direction of data flow, a data link is
+described as "outgoing" from the source and "inbound" to the sink.
+
 A workflow platform may choose to only implement the Command Line Tool
 Description part of the CWL specification.
 
@@ -412,8 +420,10 @@ of [process requirements](#Requirements_and_hints).
 
 ## Generic execution process
 
-The generic execution sequence of a CWL process (including workflows and
-command line line tools) is as follows.
+The generic execution sequence of a CWL process (including workflows
+and command line line tools) is as follows.  Processes are
+modeled as functions that consume an input object and produce an
+output object.
 
 1. Load input object.
 1. Load, process and validate a CWL document, yielding one or more process objects.