Skip to content

Workflow Run API Implementation

This page documents the technical implementation of workflow run APIs and CLI integration.

Core WorkflowRun API Endpoints

From the actual WorkflowRunViewSet implementation:

Standard CRUD Operations

Endpoint Method Purpose
/api/v2/workflows/workflowruns/ GET List workflow runs
/api/v2/workflows/workflowruns/ POST Create new workflow run
/api/v2/workflows/workflowruns/{id}/ GET Get specific workflow run
/api/v2/workflows/workflowruns/{id}/ PUT Update workflow run
/api/v2/workflows/workflowruns/{id}/ DELETE Delete workflow run

WorkflowRun Model Fields

From actual model definition in workflows/models/__init__.py:

class WorkflowRun(SoftDeletable, Annotatable, Noteable, Ownable, NameableAbstractBaseModel):
    workflowversion = ForeignKey(WorkflowVersion)
    status = ChoiceField(choices=STATUS_CHOICES)  # SUCCESS, FAILED, RUNNING, etc.
    started_at = DateTimeField()
    completed_at = DateTimeField()
    run_command = TextField()
    run_environment = JSONField()
    is_imported = BooleanField()  # True for Galaxy imports

Specialized Actions

Dataset Management

Endpoint: /api/v2/workflows/workflowruns/{id}/manage_datasets/ Method: PUT

Associate datasets with a workflow run:

{
    "datasets": [{"id": "dataset-uuid-1"}, {"id": "dataset-uuid-2"}],
    "data_type": "INPUT|OUTPUT|PARAMETER"
}

Galaxy Import

Endpoint: /api/v2/workflows/workflowruns/import_from_galaxy/ Method: POST

Import workflow invocation from Galaxy:

{
    "url": "https://usegalaxy.eu/workflows/invocations/{invocation_id}",
    "create_datasets": true  # Optional, default: false
}

CLI Registration via DatasetCollection Register Endpoint

The CLI workflow run registration is handled through the existing dataset registration endpoint at /api/v2/data-management/datasetcollections/register/.

DataRegister Serializer Integration

From data_management/serializers/register.py, the DataRegister serializer includes:

class DataRegister(Serializer):
    # ... other fields ...
    workflowrun = WorkflowRunSerializer(required=False)
    datasets = DatasetSerializer(many=True)

WorkflowRun Registration in CLI Context

From the WorkflowRunSerializer for registration:

class WorkflowRunSerializer(Serializer):
    id = UUIDField(required=False)  # For existing runs
    name = CharField(required=False)
    new = BooleanField(required=False)  # True for new runs
    workflowversion = UUIDField(required=False)  # Required for new runs
    run_command = CharField(required=False)
    run_environment = CharField(required=False)
    started_at = DateTimeField(required=False)
    completed_at = DateTimeField(required=False)
    status = ChoiceField(choices=WorkflowRun.STATUS_CHOICES, required=False)

Registration Process

  1. New WorkflowRun: Set new: true and provide workflowversion UUID
  2. Existing WorkflowRun: Set new: false and provide id UUID
  3. Dataset Association: Each dataset must specify data_type field

Example CLI Registration Payload

Based on actual test cases:

{
    "input_dir": "/path/to/dropbox/user/WorkflowRun",
    "workflowrun": {
        "name": "Analysis Run 2024-01-15",
        "workflowversion": "workflow-version-uuid",
        "run_command": "snakemake --cores 8 --use-conda",
        "run_environment": "GNU/Linux 5.4.0-x86_64",
        "status": "SUCCESS",
        "started_at": "2024-01-15T10:00:00Z",
        "completed_at": "2024-01-15T12:30:00Z",
        "new": true
    },
    "collections": [
        {"id": "input-collection", "name": "Input Files"},
        {"id": "output-collection", "name": "Results"}
    ],
    "datasets": [
        {
            "collection": "input-collection",
            "id": "existing-dataset-uuid",
            "new": false,
            "data_type": "INPUT"
        },
        {
            "collection": "output-collection", 
            "name": "Final Results",
            "data_type": "OUTPUT",
            "new": true,
            "datafiles": [/* ... */]
        }
    ],
    "owned_by": "group-uuid"
}

Dataset Association Types

From workflows/utils/constants.py:

  • INPUT: Input datasets to the workflow
  • OUTPUT: Datasets produced by the workflow
  • PARAMETER: Configuration/parameter files

Automatic Association Logic

From the registration implementation:

if self.workflowrun:
    WorkflowRunDataset(
        dataset=dataset,
        workflowrun=self.workflowrun,
        data_type=dataset_data["data_type"],
        created_by=request.user,
        modified_by=request.user,
        owner=request.user,
    ).save()

RO-Crate Support

UI Functionality

The workflow run page offers an "RO-Crate" button to download an RO-crate archive representation of the workflow run:

  • Existing RO-Crate: When an RO-Crate archive was provided at import (and is stored with the workflow run), this archive is served as-is
  • Generated RO-Crate: When no RO-Crate archive was provided at import, an RO-Crate archive representing the workflow run should be generated

API Endpoints

WorkflowRunDataset Management

Dedicated Endpoints

Endpoint Purpose
/api/v2/workflows/workflowrundatasets/ Manage dataset-workflow run associations
/api/v2/workflows/workflowrundatasets/{id}/ Delete specific associations

Model Structure

class WorkflowRunDataset(Ownable, BaseModel):
    workflowrun = ForeignKey(WorkflowRun)
    dataset = ForeignKey(Dataset)
    data_type = ChoiceField(choices=DATASET_TO_WORKFLOWRUN_TYPES)