write-workflow-as-code

Import workflow, task, step, and related helpers from wmill, decorate an async main function with @workflow, and define tasks as top-level async functions decorated with @task. Never call main directly; the workflow entrypoint is dispatched by Windmill.

Run wmill script preview <script_path> with -d '<args>' to execute the local file without deploying. Use wmill script run only for scripts already deployed in the workspace, and wmill sync push only when explicitly asked to deploy.

task wraps an inline async function as a workflow step, taskScript dispatches to an existing Windmill script or relative module file, and taskFlow dispatches to an existing Windmill flow. All three run as child jobs when called inside a workflow.

The workflow body reruns after suspensions, so non-deterministic values like timestamps, random data, or API calls placed at the top level change between replays. Capture those values inside step() or move side effects into task() so results are checkpointed.

Call getResumeUrls inside step() to obtain the approval page URL, send it via a notification step, then call waitForApproval with an optional timeout. The workflow suspends until an approver resumes or cancels it.

In Python, except Exception is safe because internal suspension inherits from BaseException, and TaskError can be caught for failed child tasks. In TypeScript, avoid broad try/catch around SDK calls since catching the internal suspension error breaks workflow suspension.