本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 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 工作流程。我们建议您不要使用固定的亚马逊 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 替换为亚马逊 EC URIs R。
+ 确保在主工作流程中将所有工作流文件声明为输入，并且所有变量都已明确定义。
+ 确保所有 JavaScript 代码都是严格模式投诉。

## 使用选择退出任务重试 `omicsRetryOn5xx`
<a name="workflow-cwl-retry-5xx"></a>

HealthOmics 如果任务由于服务错误而失败（5XX HTTP 状态代码），则支持任务重试。默认情况下，最多 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: []
```