AWS omics documentation change

Service: omics · 2026-01-28 · Documentation low

File: omics/latest/dev/workflow-languages-cwl.md

Summary

Added documentation for cwltool Loop requirement and Arvados OutOfMemoryRetry extension

Security assessment

The changes introduce workflow control features (loops) and fault tolerance mechanisms (OOM retries). While OOM handling improves reliability, there is no evidence of a specific security vulnerability being addressed. The retry mechanism is a resilience feature, not a security fix.

Diff

diff --git a/omics/latest/dev/workflow-languages-cwl.md b/omics/latest/dev/workflow-languages-cwl.md
index f945d94f8..7adcf1dcc 100644
--- a//omics/latest/dev/workflow-languages-cwl.md
+++ b//omics/latest/dev/workflow-languages-cwl.md
@@ -5 +5 @@
-Convert CWL workflows to use HealthOmicsOpt out of task retry using omicsRetryOn5xxExamples
+Convert CWL workflows to use HealthOmicsOpt out of task retry using omicsRetryOn5xxcwltool Loop requirementArvados OutOfMemoryRetry extensionExamples
@@ -22,0 +23,4 @@ Best practice is to define a separate CWL workflow for each container that you u
+  * cwltool Loop requirement
+
+  * Arvados OutOfMemoryRetry extension
+
@@ -103,0 +108,97 @@ The following example shows how to configure the `omicsRetryOn5xx` directive at
+## cwltool Loop requirement
+
+HealthOmics supports the `cwltool:loop` extension. You can use loops to run workflow steps repeatedly until a specified condition is met. This is useful for iterative processes where you need to repeat a task multiple times or until a certain result is achieved.
+
+**Note:** Loop functionality requires CWL version 1.2 or later. Workflows using CWL versions earlier than 1.2 do not support loop operations.
+
+To use loops in your CWL workflow, define a `cwltool:Loop` requirement.
+
+The following example shows a simple counting loop that increments a counter until it reaches a maximum value:
+    
+    
+    cwlVersion: v1.2
+    class: Workflow
+    
+    $namespaces:
+      cwltool: "http://commonwl.org/cwltool#"
+    
+    requirements:
+      InlineJavascriptRequirement: {}
+      SubworkflowFeatureRequirement: {}
+      StepInputExpressionRequirement: {}
+    
+    inputs:
+      max_count: int
+    
+    steps:
+      count:
+        run:
+          class: CommandLineTool
+          baseCommand: echo
+          inputs:
+            counter:
+              type: int
+              inputBinding:
+                position: 1
+            max:
+              type: int
+          outputs:
+            result:
+              type: int
+              outputBinding:
+                outputEval: $(inputs.counter + 1)
+          
+        in:
+          counter: 
+            default: 0
+          max: max_count
+        out: [result]
+        
+        requirements:
+          - class: cwltool:Loop
+            loopWhen: $(inputs.counter < inputs.max)
+            loop:
+              counter:
+                loopSource: result
+                valueFrom: $(self)
+            outputMethod: last
+    
+    outputs:
+      final_count:
+        type: int
+        outputSource: count/result
+
+In this example, the loop continues as long as the counter is less than the maximum count. Each iteration increments the counter by 1, and the final output is the result from the last iteration.
+
+For more information about loop functionality and advanced usage patterns, see the [cwltool loop documentation](https://cwltool.readthedocs.io/en/latest/loop.html).
+
+## Arvados OutOfMemoryRetry extension
+
+HealthOmics supports the `http://arvados.org/cwl#OutOfMemoryRetry` extension to handle out-of-memory task failures. When a task exits with code 137 (out-of-memory), HealthOmics creates a new task with increased memory allocation based on the specified multiplier.
+
+###### Note
+
+HealthOmics retries out-of-memory failures up to 3 times or until the memory allocation reaches 1.5 TiB, whichever limit is reached first.
+
+The following example shows how to configure out-of-memory retry:
+    
+    
+    hints:
+      ResourceRequirement:
+        ramMin: 4096
+      http://arvados.org/cwl#OutOfMemoryRetry:
+        memoryRetryMultiplier: 2.5
+
+When a task fails due to out-of-memory, HealthOmics calculates the retry memory allocation using the formula: `previous_run_memory × memoryRetryMultiplier`. In the example above, if the task with 4096 MB of memory fails, the retry attempt uses 4096 × 2.5 = 10,240 MB of memory.
+
+The `memoryRetryMultiplier` parameter controls how much additional memory to allocate for retry attempts:
+
+  * **Default value:** If you don't specify a value, it defaults to `2` (doubles the memory)
+
+  * **Valid range:** Must be a positive number greater than `1`. Invalid values result in a 4XX validation error
+
+  * **Minimum effective value:** Values between `1` and `1.5` are automatically increased to `1.5` to ensure meaningful memory increases and prevent excessive retry attempts
+
+
+
+