本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# CWL 工作流程定義詳細資訊
<a name="workflow-languages-cwl"></a>

以通用工作流程語言或 CWL 編寫的工作流程提供與以 WDL 和 Nextflow 編寫的工作流程類似的功能。您可以使用 Amazon S3 或 HealthOmics 儲存 URIs做為輸入參數。

如果您在子工作流程的 secondaryFile 中定義輸入，請在主要工作流程中新增相同的定義。

HealthOmics 工作流程不支援操作程序。若要進一步了解 CWL 工作流程中的操作程序，請參閱 [CWL 文件](https://www.commonwl.org/user_guide/topics/operations.html)。

最佳實務是為您使用的每個容器定義個別的 CWL 工作流程。建議您不要使用固定的 Amazon ECR URI 硬式編碼 dockerPull 項目。

**Topics**
+ [將 CWL 工作流程轉換為使用 HealthOmics](#workflow-cwl-convert)
+ [使用 選擇退出任務重試 `omicsRetryOn5xx`](#workflow-cwl-retry-5xx)
+ [循環工作流程步驟](#workflow-cwl-loop)
+ [重試記憶體增加的任務](#workflow-cwl-out-of-memory-retry)
+ [範例](#workflow-cwl-examples)

## 將 CWL 工作流程轉換為使用 HealthOmics
<a name="workflow-cwl-convert"></a>

若要將現有的 CWL 工作流程定義轉換為使用 HealthOmics，請進行下列變更：
+ 將所有 Docker 容器 URIs取代為 Amazon ECR URIs。
+ 請確保在主要工作流程中將所有工作流程檔案宣告為輸入，並明確定義所有變數。
+ 確保所有 JavaScript 程式碼都是嚴格模式投訴。

## 使用 選擇退出任務重試 `omicsRetryOn5xx`
<a name="workflow-cwl-retry-5xx"></a>

如果任務因服務錯誤 (5XX HTTP 狀態碼） 失敗，HealthOmics 支援任務重試。根據預設，HealthOmics 最多會嘗試兩次失敗任務的重試。如需 HealthOmics 中任務重試的詳細資訊，請參閱 [任務重試](monitoring-runs.md#run-status-task-retries)。

若要選擇退出任務重試服務錯誤，請在工作流程定義中設定 `omicsRetryOn5xx`指令。您可以根據要求或提示來定義此指令。我們建議您新增 指令做為可攜性的提示。

```
requirements:
  ResourceRequirement:
    omicsRetryOn5xx: false

hints:
  ResourceRequirement:
    omicsRetryOn5xx: false
```

要求覆寫提示。如果任務實作在封裝工作流程中也由需求提供的提示中提供資源需求，則以封裝需求為優先。

如果工作流程的不同層級出現相同的任務需求，HealthOmics 會使用來自 的最具體項目 `requirements`（如果 中沒有項目`hints`，則為 `requirements`)。下列清單顯示 HealthOmics 用來套用組態設定的優先順序，從最低到最高優先順序：
+ 工作流程層級
+ 步驟層級
+ 工作流程定義的任務區段

下列範例示範如何在工作流程的不同層級設定 `omicsRetryOn5xx` 指令。在此範例中，工作流程層級需求會覆寫工作流程層級提示。任務和步驟層級的要求組態會覆寫提示組態。

```
class: Workflow
# Workflow-level requirement and hint
requirements:
  ResourceRequirement:
    omicsRetryOn5xx: false

hints:
  ResourceRequirement:
    omicsRetryOn5xx: false  # The value in requirements overrides this value 

steps:
  task_step:
    # Step-level requirement
    requirements:
      ResourceRequirement:
        omicsRetryOn5xx: false
    # Step-level hint
    hints:
      ResourceRequirement:
        omicsRetryOn5xx: false
    run:
      class: CommandLineTool
      # Task-level requirement
      requirements:
        ResourceRequirement:
          omicsRetryOn5xx: false
      # Task-level hint
      hints:
        ResourceRequirement:
          omicsRetryOn5xx: false
```

## 循環工作流程步驟
<a name="workflow-cwl-loop"></a>

HealthOmics 支援循環工作流程步驟。您可以使用迴圈重複執行工作流程步驟，直到符合指定的條件為止。這對於您需要多次重複任務或直到達到特定結果的反覆程序很有用。

**注意：**迴圈功能需要 CWL 1.2 版或更新版本。使用 1.2 以前 CWL 版本的工作流程不支援迴圈操作。

若要在 CWL 工作流程中使用迴圈，請定義迴圈需求。下列範例顯示迴圈需求組態：

```
requirements:
  - class: "http://commonwl.org/cwltool#Loop"
    loopWhen: $(inputs.counter < inputs.max)
    loop:
      counter:
        loopSource: result
        valueFrom: $(self)
    outputMethod: last
```

`loopWhen` 欄位控制迴圈何時終止。在此範例中，只要計數器小於最大值，迴圈就會繼續。`loop` 欄位定義如何在反覆運算之間更新輸入參數。`loopSource` 指定來自先前反覆運算的輸出會饋送至下一個反覆運算。`outputMethod` 欄位設定為 只會`last`傳回最終反覆運算的輸出。

## 重試記憶體增加的任務
<a name="workflow-cwl-out-of-memory-retry"></a>

HealthOmics 支援記憶體out-of-memory任務失敗的自動重試。當任務以代碼 137 out-of-memory) 結束時，HealthOmics 會根據指定的乘數建立記憶體配置增加的新任務。

**注意**  
HealthOmics 會重試out-of-memory故障最多 3 次，或直到記憶體配置達到 1536 GiB，以先達到者為準。

下列範例示範如何設定out-of-memory重試：

```
hints:
  ResourceRequirement:
    ramMin: 4096
  http://arvados.org/cwl#OutOfMemoryRetry:
    memoryRetryMultiplier: 2.5
```

當任務因out-of-memory而失敗時，HealthOmics 會使用公式計算重試記憶體配置：`previous_run_memory × memoryRetryMultiplier`。在上述範例中，如果具有 4096 MB 記憶體的任務失敗，重試嘗試會使用 4096 × 2.5 = 10，240 MB 記憶體。

`memoryRetryMultiplier` 參數控制要為重試嘗試配置多少額外記憶體：
+ **預設值：**如果您未指定值，則預設為 `2`（記憶體的兩倍）
+ **有效範圍：**必須是大於 的正數`1`。無效值會導致 4XX 驗證錯誤
+ **最低有效值：** `1` 和 之間的值`1.5`會自動增加到 `1.5` ，以確保有意義的記憶體增加，並防止過度重試嘗試

## 範例
<a name="workflow-cwl-examples"></a>

以下是以 CWL 撰寫的工作流程範例。

```
cwlVersion: v1.2
class: Workflow

inputs:
in_file:
type: File
secondaryFiles: [.fai]

out_filename: string
docker_image: string


outputs:
copied_file:
type: File
outputSource: copy_step/copied_file

steps:
copy_step:
in:
  in_file: in_file
  out_filename: out_filename
  docker_image: docker_image
out: [copied_file]
run: copy.cwl
```

下列檔案定義 `copy.cwl`任務。

```
cwlVersion: v1.2
class: CommandLineTool
baseCommand: cp

inputs:
in_file:
type: File
secondaryFiles: [.fai]
inputBinding:
  position: 1

out_filename:
type: string
inputBinding:
  position: 2
docker_image:
type: string

outputs:
copied_file:
type: File
outputBinding:
    glob: $(inputs.out_filename)

requirements:
InlineJavascriptRequirement: {}
DockerRequirement:
dockerPull: "$(inputs.docker_image)"
```

以下是以 CWL 撰寫且具有 GPU 需求的工作流程範例。

```
cwlVersion: v1.2
class: CommandLineTool
baseCommand: ["/bin/bash", "docm_haplotypeCaller.sh"]
$namespaces:
cwltool: http://commonwl.org/cwltool#
requirements:
cwltool:CUDARequirement:
cudaDeviceCountMin: 1
cudaComputeCapability: "nvidia-tesla-t4" 
cudaVersionMin: "1.0"
InlineJavascriptRequirement: {}
InitialWorkDirRequirement:
listing:
- entryname: 'docm_haplotypeCaller.sh'
  entry: |
          nvidia-smi --query-gpu=gpu_name,gpu_bus_id,vbios_version --format=csv   

inputs: []
outputs: []
```