Documentation

Task

A Task is the executable unit in Polysync. It is a configured instance of a Job that captures:

  • The Job (and therefore the Platform) it runs against.
  • Parameter values — overrides for the Job's parameter schema.
  • Schedules — zero or more cron expressions describing when the Task should run automatically.
  • Dependencies — other Tasks that must succeed first, optionally with parent-output → child-input attribute mappings.
  • Retry policy — automatic retries on failure with configurable backoff.
  • Priority — execution ordering relative to other queued Tasks.
  • Contention profiles — concurrency / rate-limit profiles that gate dispatch.

Editor tabs

Tab What you configure
General Task name, Platform, Job Type, Job (locked after save).
Settings Parameter values inherited from the Job's schema. Supports literals, vault references, and parent-output mappings.
Dependencies Upstream Tasks that must succeed before this Task runs. Includes a visual dependency diagram with split/stacked view.
Scheduling Zero or more cron expressions that trigger automatic runs.
Runtime Settings Priority, retry configuration, execution timeout, and per-task concurrency cap.

Lifecycle of a run

  1. Schedule fires, dependency completes, manual Run Once is invoked, or a retry is queued.
  2. A TaskRun is created in the Queued state.
  3. The Dispatcher claims the run subject to any linked contention profiles.
  4. The run transitions through Running → Succeeded / Failed / Cancelled, with a status-history record at each transition.
  5. On failure, automatic retries are queued up to the Task's retry limit.

Run Once (manual execution)

The Run Once action queues a single immediate execution of a Task with trigger type Manual. Useful to:

  • Validate a freshly-created or freshly-modified Task before its schedule fires.
  • Re-run an ad-hoc workload.
  • Smoke-test a platform connection through a real artefact.

The AI Copilot exposes this via the run_task_once tool — it requires only the Task name and returns the new TaskRun id.

Parameter mapping

Task parameter values (Settings tab) can be:

  • Literals — pinned at task-edit time.
  • Vault references — vault://<vault>/<secret> resolved at runtime.
  • Parent outputs — set per dependency, copying a named output of a parent run into a named input of this Task.

Dependencies and visualisation

The Dependencies tab shows an editable list of upstream Tasks alongside an interactive diagram. Use the Split / Stacked toggle to view the list and diagram side-by-side or one above the other. Clicking a node in the diagram opens that Task in the editor.

Runtime Settings

Task Priority

Sets the dispatch order when multiple Tasks are queued simultaneously. Higher-priority Tasks are claimed by the Dispatcher before lower-priority ones.

Retry Configuration

Field Description
Retry Enabled Toggle automatic retry on failure.
Max Retry Attempts How many times to retry before marking the run Failed.
Backoff Strategy Fixed — same delay each time. Linear — delay × attempt number. Exponential — delay doubles each attempt.
Initial Retry Delay (seconds) Base delay before the first retry (and the multiplier for Linear/Exponential).
Max Retry Delay (seconds) Cap on how large the calculated delay can grow.

Execution & Concurrency

Field Description
Execution Timeout (seconds) Maximum wall-clock time a single run may take before being terminated. Leave empty for no timeout.
Max Concurrent Runs Maximum simultaneous active runs of this specific Task. Use 1 to enforce sequential execution. Leave empty for unlimited. This is independent of any linked Contention Profiles.

Best practices

  • Always Run Once a new Task before scheduling it.
  • Keep Max Retry Attempts conservative (1–3); use contention profiles to absorb platform quota spikes instead of unbounded retries.
  • Use Exponential backoff for platform calls that may be transiently throttled; use Fixed for predictable downstream services.
  • Set Max Concurrent Runs = 1 for Tasks that write to a shared resource that does not tolerate parallel writes.
  • Use dependencies + parent-output mapping rather than embedding values from upstream tasks into Task parameters.