Tasks and runs

Tasks are portable Envoy pipelines. Runs are immutable execution records created from a task version, arguments, and connector mapping.

Task library

Open Tasks to search, filter, sort, and page through task definitions. Admins and superadmins can:

• create a task in the YAML editor;
• import a task file;
• clone a task;
• edit and save a new version;
• archive or restore a task;
• delete an eligible task.

Viewers can inspect task details and history but do not receive mutation controls.

Create or import a task

The editor expects Envoy task YAML. Keep connection details out of it:

name: example
description: Copy records into a database
 
connectors:
  source:
    type: csv
  destination:
    type: sqlite
 
steps:
  - name: read
    type: call_method
    config:
      connector: source
      method: read
      args:
        resource: records

Use the editor's validation before saving. Static validation checks structure, connector references, step configuration, argument schemas, and expression compilation. It does not prove a live connector call or transformation against real records.

For exact YAML, use Task structure, Step types, and JSONata.

Versions

Saving an existing task creates versioned YAML history. The task detail page shows the current definition and prior versions. Export options can download the current YAML or a package with history.

Runs preserve task provenance. Editing a task does not rewrite an earlier run.

Start a standalone run

From task detail:

1. Select Run.
2. Map every connector slot to a stored connector of the same type.
3. Enter declared arguments.
4. Confirm.

The argument form follows the task's schema. Integrated-account and Mongo record widgets can provide searchable pickers instead of raw identifiers when the YAML declares them.

Run detail

The run page shows:

• terminal or active status;
• task and version;
• trigger source;
• start, completion, and duration;
• item and step metrics;
• runtime arguments;
• captured logs and errors.

Active pages update while work is running. Use Stop for an active run. Stopping is asynchronous: wait for the terminal cancelled state.

Use Rerun to create another run rather than mutating history. Review current mappings and task content first when the environment has changed.

Logs

Run logs combine task subprocess output captured by the server. Structured connector errors can include HTTP status, response body, driver code, and expression context.

Admins may clear retained logs from a run without deleting the run record. Deleting a run is a separate destructive action and also cleans associated logs and metrics where supported.

Archive versus delete

Archive when a task should no longer be offered in normal workflows but its history remains useful. Delete only when the task is no longer referenced and retention policy permits removal.

Envoy may reject or skip destructive operations for records still in use. Do not remove a task merely to hide it.

Authoring workflow

For non-trivial tasks:

1. inspect real source shapes;
2. author one bounded path;
3. validate YAML;
4. run with a narrow query or small file;
5. inspect the destination;
6. rerun to prove idempotency;
7. scale concurrency only after correctness.

See Author a production task, Build an idempotent migration, and Curated recipes.