Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions aws-healthomics/steering/migration-guide-for-wdl.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ AWS HealthOmics requires:

**Done WHEN**:
- All tasks have `docker` (or `container` for WDL 1.1), `cpu`, and `memory` runtime attributes.
- All resources meet HealthOmics minimums (≥2 vCPU, ≥4 GB).
- All resources meet HealthOmics minimums (≥2 vCPU, ≥4 GiB).

### Phase 3: WDL Version Compatibility

Expand Down Expand Up @@ -132,13 +132,15 @@ AWS HealthOmics requires:
- Obtain and upload `http(s)://` and `ftp://` resources to S3.
- Set appropriate S3 storage class (Intelligent-Tiering).
- Validate checksums after upload.
4. Create `healthomics.inputs.json` with S3 URIs for all File inputs.
4. Create `healthomics.inputs.json` with S3 URIs for all File inputs. Keys MUST be bare parameter names, NOT namespaced with the workflow name — see [Workflow Development SOP](./workflow-development.md). Cromwell inputs files namespace every key (`WorkflowName.input`), so ENSURE the namespace is stripped when porting one.
- DO NOT rely on `StartRun` to reject a namespaced key. IF the workflow declares a default for that parameter, the key MAY be accepted silently and **the default runs instead of the value you supplied** — the run reports COMPLETED with results that do not reflect the submitted inputs. A namespaced key fails loudly only where the bare parameter is required.
5. Update any hardcoded paths in command sections to use input variables.

**Done WHEN**:
- Reference inventory CSV lists all files and sizes.
- All reference files accessible from S3.
- `healthomics.inputs.json` uses S3 URIs exclusively.
- No key in `healthomics.inputs.json` is namespaced with the workflow name.
- No hardcoded file paths in command sections.

### Phase 5: Output Collection Strategy
Expand Down Expand Up @@ -204,7 +206,7 @@ runtime {
runtime {
docker: "<account-id>.dkr.ecr.<region>.amazonaws.com/workflow-name/bwa:0.7.17--h5bf99c6_8"
cpu: 4
memory: "8 GB"
memory: "8 GiB"
}
```

Expand All @@ -230,12 +232,15 @@ workflow MyWorkflow {
```

### S3 Input (Before/After)

The path MUST become an S3 URI, and the workflow namespace MUST be removed from the key.

```json
// Before
// Before (Cromwell)
{ "WorkflowName.reference_fasta": "/path/to/reference.fasta" }

// After
{ "WorkflowName.reference_fasta": "s3://bucket/references/Homo_sapiens/GATK/GRCh38/Sequence/reference.fasta" }
// After (HealthOmics)
{ "reference_fasta": "s3://bucket/references/Homo_sapiens/GATK/GRCh38/Sequence/reference.fasta" }
```

## WDL-Specific Considerations
Expand Down
6 changes: 5 additions & 1 deletion aws-healthomics/steering/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ This SOP defines how you, the agent, diagnose and resolve common HealthOmics wor

## Workflow Creation Failure

IF a workflow fails to reach `CREATED` status, check these causes in order:
Workflow creation is asynchronous. `CreateAHOWorkflow` returns HTTP 200 with status `CREATING`; the workflow then transitions to `ACTIVE` or `FAILED`. A 200 response is NOT evidence of a valid workflow — you MUST poll `GetAHOWorkflow` until the status leaves `CREATING`. Invalid definitions are accepted at submission time and reported only as the later `FAILED` status, with the parser error in `statusMessage`.

ALSO read `statusMessage` on an `ACTIVE` workflow. It carries warnings that do not block creation but change how the workflow is interpreted — for example `MissingVersion, document should declare WDL version; draft-2 assumed`, or a report that no input parameters were found.

IF a workflow fails to reach `ACTIVE` status, check these causes in order:

1. The workflow zip package is corrupted or missing.
2. The workflow zip package has multiple workflow definition files at the top level. There MUST be only one `main.wdl`, `main.nf`, etc. at the top level — dependencies MUST be in sub-directories.
Expand Down
1 change: 1 addition & 0 deletions aws-healthomics/steering/workflow-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ This SOP defines how you, the agent, create and deploy genomics workflows for AW
- You MUST reference the package created in Step 1 as the workflow `definition_source`.
- You MUST reference the package as a file path or S3 URI.
- Call `GetAHOWorkflow` to verify the workflow was created successfully.
- Creation is asynchronous: `CreateAHOWorkflow` returns status `CREATING`, so you MUST poll until the status becomes `ACTIVE`. DO NOT treat the create response itself as success — an invalid definition is accepted at submission time and reported as `FAILED` only on a subsequent `GetAHOWorkflow`. See the [Troubleshooting SOP](./troubleshooting.md) for creation failure causes.

### Step 3. Run the Workflow
- Follow the [Running a Workflow SOP](./running-a-workflow.md) to execute the deployed workflow.