navigate-subworkflows

Navigating Subworkflows

This skill teaches you how to work with nested WDL subworkflows in Terra. When a WDL workflow calls another workflow (a subworkflow), each subworkflow gets its own workflow ID and can be inspected independently.

Understanding Subworkflows

In WDL, a workflow can call other workflows as tasks. When this happens:

1. Parent workflow: Has its own workflow ID and metadata
2. Subworkflow: Gets a separate workflow ID, visible in parent metadata
3. Each subworkflow: Can be queried independently using Terra tools

Finding Subworkflow IDs

Subworkflow IDs are stored in the parent workflow's metadata under:

calls.<subworkflow_name>[*].subWorkflowId

Step 1: Get Parent Workflow Metadata

get_job_metadata(
    workspace_namespace, workspace_name, submission_id, workflow_id,
    mode="extract",
    field_path="calls.*.subWorkflowId"
)

This returns subworkflow IDs for all task calls that are subworkflows.

Step 2: Identify Which Tasks Are Subworkflows

Not all tasks are subworkflows. To check:

get_job_metadata(
    workspace_namespace, workspace_name, submission_id, workflow_id,
    mode="summary"
)

In the summary, subworkflow tasks will have execution entries with subWorkflowId fields.

Alternative: Extract Specific Subworkflow ID

If you know the subworkflow task name:

get_job_metadata(
    workspace_namespace, workspace_name, submission_id, workflow_id,
    mode="extract",
    task_name="my_subworkflow_call",
    field_path="subWorkflowId"
)

Debugging Subworkflows

Once you have a subworkflow ID, use it directly with any workflow tool:

Get Subworkflow Summary

get_job_metadata(
    workspace_namespace, workspace_name, submission_id,
    workflow_id="<subworkflow-id>",  # Use subworkflow ID here
    mode="summary"
)

Get Subworkflow Logs

get_workflow_logs(
    workspace_namespace, workspace_name, submission_id,
    workflow_id="<subworkflow-id>",
    fetch_content=True
)