eduKateSG · Why Science?
Send one carefully described workflow to different authorised compute environments—and keep every run, state and output traceable
Choose the closest route, then return to the full index whenever you need the wider evidence chain.
Science learning becomes powerful when students can tell a measured pattern from a model, a statistical decision from a mechanism, and a useful lead from a finished conclusion. The GA4GH Workflow Execution Service, or WES, is an API for submitting and managing portable workflows against an execution backend. GA4GH lists WES as a current product and v1.1 as the last approved version, approved on 14 September 2023. A request can carry workflow parameters, workflow type and version, engine information, a workflow URL or attachments, and tags. WES then exposes a run identifier, state, logs and cancellation operations. It standardises the service boundary; it does not make an unpinned workflow reproducible, grant data access, prove scientific validity or guarantee identical results across every backend. This guide supports Primary Science, PSLE Science, Secondary Science, O-Level Science and STEM education as a longform evidence-reading route; it is not medical advice, a laboratory protocol, an admission promise or a career guarantee.
Related eduKate reading: GA4GH Data Repository Service and portable access; htsget and secure genomic streaming; Crypt4GH and encrypted genomic files; Science Learning Hub; Education Hub; STEM Education; Careers by Subject Capability.
Primary and official sources checked on 12 October 2026: Official GA4GH Workflow Execution Service product page, current WES v1.1; Official GA4GH WES v1.1 API documentation; Official GA4GH WES specification repository; 2026 Singapore–Cambridge O-Level Biology syllabus; MOE G2/G3 Lower Secondary Science teaching and learning syllabus; 2026 MOE G2 Computing syllabus. Standards, service interfaces and recommendations can change, so preserve the dated documentation and versions used.
A deeper reading route
A useful way to picture WES is as the reception desk for a governed compute centre. The desk accepts a carefully described workflow request, checks what the service supports, issues a run identifier and lets the caller ask what happened. The desk does not write the scientific method, choose the correct cohort or decide whether a result is biologically persuasive. That separation is healthy: it allows one client to communicate with several execution backends while keeping scientific responsibility with the people who designed and reviewed the analysis.
Portability therefore has layers. The API can be portable while the workflow language is not supported everywhere. The workflow definition can be portable while an engine-specific option changes behaviour. Containers can pin software while processor architecture, reference files or numerical libraries still differ. A strong report identifies each layer and the test used there: service-info for advertised capability, immutable workflow and container references for identity, a small conformance fixture for execution, and scientific controls for interpretation.
Run states are also evidence, not mere interface decoration. QUEUED and INITIALIZING describe preparation; RUNNING describes active execution; COMPLETE says executors finished and outputs uploaded under the service contract. EXECUTOR_ERROR, SYSTEM_ERROR and PREEMPTED point toward different fault domains. Preserving those distinctions helps a team avoid the dangerous habit of repeatedly pressing retry without learning whether the command, infrastructure or resource policy is responsible.
For students, WES turns an abstract lesson about reproducibility into a visible chain: instructions, parameters, allowed materials, a named run, observations, failures and products. For researchers, the same chain supports audit across institutions. In both cases, the happiest outcome is not simply a green completion label. It is a result whose route can be reconstructed, whose permissions were respected and whose scientific limits remain clear.
The practical checkpoint is simple: before a large run, ask whether another authorised person could identify the exact workflow, the exact inputs, the exact parameters and the exact service capabilities from the record alone. If any answer depends on memory, a mutable branch or a private message, the workflow is not yet ready to carry an important scientific claim across environments.
| Stage | Question | Evidence | Responsible output |
|---|---|---|---|
| Describe | Which workflow and parameters should run? | Workflow URL or attachments, type, version, parameters and tags | A reviewable run request |
| Authorise | May this caller use the workflow, data and compute? | Identity, bearer token, permissions and policy | A permitted submission context |
| Execute | How does the backend manage the run? | Run ID, engine, state transitions and resources | A traceable workflow execution |
| Verify | Can another team understand and repeat it? | Logs, outputs, checksums, versions and provenance | A bounded reproducibility record |
Inside this guide
1–12 · Foundations and design
- 1. Start with the scientific question
- 2. Understand the approved service
- 3. Know what WES standardises
- 4. Bring algorithms to governed data
- 5. Treat portability as a tested claim
- 6. Discover service capabilities
- 7. Authenticate the caller
- 8. Build the multipart request
- 9. Pin the workflow definition
- 10. Name workflow type and version
- 11. Validate workflow parameters
- 12. Handle attachments safely
13–24 · Models and estimation
- 13. Use tags as searchable context
- 14. Choose engine parameters deliberately
- 15. Capture the run ID
- 16. Read run states precisely
- 17. Keep UNKNOWN genuinely unknown
- 18. Separate executor and system errors
- 19. Treat preemption separately
- 20. Cancel with care
- 21. List runs with pagination
- 22. Read logs as evidence
- 23. Verify outputs independently
- 24. Connect WES to TRS
25–36 · Diagnostics and interpretation
- 25. Connect WES to TES
- 26. Connect WES to DRS
- 27. Protect data and secrets
- 28. Connect to Primary Science
- 29. Connect to Secondary Science
- 30. Connect to mathematics
- 31. Connect to computing
- 32. Connect to pathways
- 33. Did you know?
- 34. Write a reader-ready run report
- 35. Build a validation ladder
- 36. Finish with a reproducible bundle
Section 1 of 36
1. Start with the scientific question
A portable workflow is useful only when the inputs, comparison and intended outputs answer a clear scientific question. Moving code between platforms cannot rescue a vague design.
Working checkpoint — Workflow Execution Service: Write the claim, independent sample and expected evidence before preparing the WES request. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 2 of 36
2. Understand the approved service
GA4GH describes WES as a standard protocol for running genomic analyses in different environments and lists v1.1 as current and approved.
Working checkpoint — workflow run: Record WES v1.1 and the exact implementation release rather than saying only “the cloud”. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 3 of 36
3. Know what WES standardises
WES standardises submission, status, logs, cancellation and service information around a workflow run. The backend may still use different engines, schedulers and storage.
Working checkpoint — workflow parameters: Separate the portable API contract from implementation-specific behaviour. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 4 of 36
4. Bring algorithms to governed data
A WES endpoint can let an authorised workflow run near data that should not be copied elsewhere. This supports federation, but policy and credentials remain separate controls.
Working checkpoint — run state: Confirm where inputs, temporary files and outputs are allowed to reside. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 5 of 36
5. Treat portability as a tested claim
The same workflow definition can be submitted to different WES implementations, yet containers, engines, hardware and defaults can still change results.
Working checkpoint — execution log: Run a small conformance fixture on every intended backend. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 6 of 36
6. Discover service capabilities
The service-info endpoint can describe supported workflow types, versions, engine parameters and authentication instructions. Clients should discover rather than assume.
Working checkpoint — reproducible analysis: Save service-info with the run record and compare it before resubmission. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 7 of 36
7. Authenticate the caller
The official documentation recommends OAuth 2 bearer tokens while allowing implementations to choose suitable mechanisms. Authentication identifies a caller; authorisation decides permitted actions.
Working checkpoint — Workflow Execution Service: Use short-lived scoped credentials and never embed them in workflow attachments. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 8 of 36
8. Build the multipart request
A WES run request is multipart form data containing fields such as workflow parameters, workflow type, type version, tags, engine settings, workflow URL and attachments.
Working checkpoint — workflow run: Validate every field against the target service before submission. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 9 of 36
9. Pin the workflow definition
A mutable branch or unversioned URL can point to different code later. Portability requires a stable revision and preferably a content digest.
Working checkpoint — workflow parameters: Store the registry version, commit or immutable descriptor checksum. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 10 of 36
10. Name workflow type and version
CWL, WDL, Nextflow, Galaxy or Snakemake workflows use different languages and version conventions. WES does not erase those semantics.
Working checkpoint — run state: Match the declared type and version to service capabilities and actual source. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 11 of 36
11. Validate workflow parameters
Parameters connect the abstract workflow to concrete samples, references, thresholds and outputs. A syntactically valid JSON object can still be scientifically wrong.
Working checkpoint — execution log: Schema-check parameters and independently review sensitive sample mappings. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 12 of 36
12. Handle attachments safely
Attachments can bundle workflow files and dependencies, but filenames, paths and duplicate names can create ambiguity or security risks.
Working checkpoint — reproducible analysis: Use a manifest, reject path traversal and verify every attached digest. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 13 of 36
13. Use tags as searchable context
Tags can help group runs by study, purpose or environment. They are labels, not a substitute for full provenance or access policy.
Working checkpoint — Workflow Execution Service: Define a small governed tag vocabulary and avoid personal data. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 14 of 36
14. Choose engine parameters deliberately
Engine-specific options may be needed, but they can reduce portability by introducing backend-only behaviour.
Working checkpoint — workflow run: Document each non-portable option and test a standards-only baseline. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 15 of 36
15. Capture the run ID
A successful submission returns a run identifier that anchors later status, log and cancellation requests. The ID is service-scoped unless documented otherwise.
Working checkpoint — workflow parameters: Store endpoint and run ID together immediately. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 16 of 36
16. Read run states precisely
WES v1.1 defines states including UNKNOWN, QUEUED, INITIALIZING, RUNNING, PAUSED, COMPLETE, EXECUTOR_ERROR, SYSTEM_ERROR, CANCELED, CANCELING and PREEMPTED.
Working checkpoint — run state: Do not collapse every non-complete state into one generic failure. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 17 of 36
17. Keep UNKNOWN genuinely unknown
UNKNOWN is a safe default when state information is absent; it must not be interpreted as queued, failed or complete.
Working checkpoint — execution log: Investigate service reachability and run identity before retrying. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 18 of 36
18. Separate executor and system errors
An executor error usually points to a workflow process, while a system error can arise from infrastructure such as storage or disk failure. Recovery decisions differ.
Working checkpoint — reproducible analysis: Preserve structured logs and classify the failure before resubmission. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 19 of 36
19. Treat preemption separately
PREEMPTED means the system reclaimed compute capacity. It is not the same as user cancellation or a biological-analysis failure.
Working checkpoint — Workflow Execution Service: Check retry policy, checkpoint support and duplicate-output risks. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 20 of 36
20. Cancel with care
Cancellation is a request and can pass through CANCELING before CANCELED. External jobs or uploads may take time to stop.
Working checkpoint — workflow run: Poll to a terminal state and inventory partial outputs. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 21 of 36
21. List runs with pagination
Run lists can be paginated and may reflect service retention limits. Absence from one page is not proof that a run never existed.
Working checkpoint — workflow parameters: Save next-page tokens and maintain an independent audit index. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 22 of 36
22. Read logs as evidence
Run logs can expose the original request, state, start and end information, task logs and outputs. Logs may also contain sensitive paths or environment details.
Working checkpoint — run state: Redact secrets while preserving diagnostic meaning and hashes. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 23 of 36
23. Verify outputs independently
COMPLETE indicates execution and upload succeeded under the service definition; it does not prove that the scientific result is correct.
Working checkpoint — execution log: Check output schema, counts, checksums and planned quality controls. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 24 of 36
24. Connect WES to TRS
A Tool Registry Service can identify a workflow version and descriptors, while WES executes the selected definition. Discovery and execution remain different steps.
Working checkpoint — reproducible analysis: Resolve the immutable workflow version before creating the WES request. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 25 of 36
25. Connect WES to TES
A workflow engine behind WES may break a workflow into lower-level tasks submitted through TES. WES manages the workflow boundary; TES manages task descriptions.
Working checkpoint — Workflow Execution Service: Keep workflow-run and task IDs linked without treating them as interchangeable. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 26 of 36
26. Connect WES to DRS
DRS can provide portable object identifiers and access methods for inputs or outputs. WES still needs authorised credentials and correct parameter mapping.
Working checkpoint — workflow run: Record the DRS IDs and verified checksums used by each run. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 27 of 36
27. Protect data and secrets
Workflow runs can touch controlled genomic data, credentials and logs. Secure transport, least privilege, encrypted storage and audit remain essential.
Working checkpoint — workflow parameters: Threat-model submission, staging, execution, logging and output delivery. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 28 of 36
28. Connect to Primary Science
A recipe card sent to two supervised stations can model a portable procedure: the instructions should be the same even when the workbench differs.
Working checkpoint — run state: Use safe classroom materials and compare recorded outcomes. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 29 of 36
29. Connect to Secondary Science
Fair tests require controlled variables, repeated observations and transparent methods. WES makes those ideas visible in computational experiments.
Working checkpoint — execution log: Identify which platform differences could act like uncontrolled variables. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 30 of 36
30. Connect to mathematics
State machines, resource estimates and runtime distributions connect workflow execution to logic, probability and quantitative planning.
Working checkpoint — reproducible analysis: Plot runtime and failure categories without hiding unsuccessful runs. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 31 of 36
31. Connect to computing
REST APIs, multipart requests, state transitions, containers, authentication and logs show how software architecture becomes scientific apparatus.
Working checkpoint — Workflow Execution Service: Test malformed requests, expired credentials and partial failures. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Section 32 of 36
32. Connect to pathways
Portable workflows join biology, data engineering, cloud computing, security and research governance and can illuminate STEM pathways.
Working checkpoint — workflow run: Check current official course and professional requirements separately. Read every run state beside timestamps, engine logs, data-access context and the exact submitted request.
For future study, connect workflows to biology, cloud computing and security while checking official pathways separately.
Section 33 of 36
33. Did you know?
WES distinguishes EXECUTOR_ERROR from SYSTEM_ERROR, helping teams decide whether to inspect workflow commands or the surrounding infrastructure first.
Working checkpoint — workflow parameters: Use the state as a starting signal, then verify the detailed logs. Preserve canceled, preempted and failed attempts; a complete run is not the complete execution history.
For scientific writing, cite WES, workflow, engine and data-object versions.
Section 34 of 36
34. Write a reader-ready run report
Name the WES and implementation versions, endpoint, run ID, workflow digest, engine, parameters, authorised data references, states, logs and output checksums.
Working checkpoint — run state: Keep credentials and sensitive paths out of the published report. Separate API conformance and computational completion from scientific validity and reproducibility.
For students, ask which instructions were fixed and which parts the compute environment supplied.
Section 35 of 36
35. Build a validation ladder
Validate the workflow and parameters locally, inspect service capabilities, submit a small fixture, verify states and outputs, then scale to the full governed analysis.
Working checkpoint — execution log: Fix the earliest failing layer before increasing compute. Treat workflow, engine, reference and data identifiers as scientific inputs: a silent mismatch can change the result.
For parents, ask what data move, what computation moves and who is authorised at each boundary.
Section 36 of 36
36. Finish with a reproducible bundle
Deliver immutable workflow references, parameter files, service-info, run and task identifiers, logs, outputs, checksums, environment details, permissions record and validation results.
Working checkpoint — reproducible analysis: Make every claim traceable from question to submitted workflow to verified output. Keep the workflow digest, parameters, service-info, endpoint, run ID, states and output checksums together.
For a classroom model, send the same safe recipe to two stations and compare records.
Contents · Previous section · Continue to the Science Learning Hub