How Tracked Execution Works

This page uses three diagrams to show how your system works together with onestep to run a long task when you apply Tracked Execution: who is responsible for what, where the data flows, and what to prepare before integrating. Deployment details for both backends are covered in MySQL Tracked Execution and PostgreSQL Tracked Execution.

Three Roles

There are three components in the application. Outside the dashed boxes everything is provided by onestep; you only write the API routes and the task handler.

Code	Provided by
HTTP routes (submit / query / cancel)	You
Task handler	You
ExecutionClient / ExecutionSource / OneStepApp	onestep
DDL for the two tables and state transitions	onestep (create tables as migration role, run with auto_create=False)

Task state is a row in the database; no message queue is involved. The API process and the worker process never talk directly — they cooperate through the same set of tables.

Lifecycle of One Task

Key points:

• Submit with an idempotency key: submitting the same key again returns the same execution instead of running it twice.
• Only four terminal states: succeeded / failed / cancelled / expired; queued / running / retrying / cancel_requested are non-terminal and the client keeps waiting.
• Cancellation is cooperative: cancel_requested is only a request; the worker converges to cancelled at the handler's next checkpoint and does not guarantee an immediate stop.

What to Prepare Before Integrating

For the full business semantics of each state, the exception mapping table, deployment steps, the go-live checklist, and rollback, see the backend pages:

• MySQL Tracked Execution
• PostgreSQL Tracked Execution