Available in: Project application development and Site production. Production Jobs run in the Site’s release context. Chat, Agent, and Project schedules are a separate mechanism for starting conversational work.
Jobs perform application work that should continue outside a visitor's request, such as processing a batch, preparing an export, or synchronizing records. Application code defines the behavior; the execution scope determines its data, credentials, and funding.
Set up an export Job
Enable Storage for the export. Ask the Project to queue a Job from the backend with POST /jobs at PLAYBOOKS_JOBS_URL, using PLAYBOOKS_JOBS_KEY as its Bearer credential. Save the returned job ID with the export request. Have its handler accept signed deliveries at POST /_playbooks/jobs/:handler, write the export to private Storage, and record completion against the export ID. A repeated delivery should reuse that export.
Open the web app in the Project’s Browser view. Create two sample records and request one export. Open Jobs in the Project and find the run for that job ID. Once it completes, download the CSV through the application and check both rows. If the backend received no job ID, inspect the enqueue response first. Jobs are created by Project code. The Jobs view shows their execution history.
Distinguish Jobs from schedules
| Mechanism | Use |
|---|---|
| Agent schedule | Start a fresh conversation for the Agent |
| Application Job | Execute application background behavior against its environment |
| Chat schedule | Start a fresh Chat conversation for the creator in the Workspace |
| Project schedule | Start a fresh conversation in the Project |
A recurring report can use either approach depending on whether it is conversational work or part of an application's backend. See Schedules for conversational automation.
Design a recoverable operation
Give a Job a bounded responsibility and a way to identify work already completed. For a batch import, record which items were accepted so a retry does not create duplicates. For external actions, preserve the service's confirmation before deciding whether another attempt is safe.
- Define the inputs and expected output.
- Use the development scope to verify behavior.
- Review runtime, credentials, and data requirements for production.
- Release compatible application code before enabling production work.
- Inspect the recorded outcome and relevant Logs.
Review failures before retrying
A timeout does not prove that nothing happened. Check the Job history, application state, and external receipts. Retry only after distinguishing a failed action from an action that completed without a response.
Production Jobs belong to the Site and its release context. A rollback can change available code without undoing prior job effects, so verify compatibility before changing releases. Execution and downstream services follow the owning Workspace's Usage and Budgets.
Example: prepare a large export
Let an application Job assemble an export outside the visitor’s request. Record enough progress to distinguish queued work, completed output, and failure, and make retry behavior account for work already performed.
Store the output in the intended Storage scope and inspect Logs when it fails. For a recurring Operator-written report instead, use Schedules.
Describe the completion condition
For an export, completion means the intended file exists, the requesting user can access it, and another retry will not produce an unintended duplicate. Have the application distinguish waiting, running, failed, and completed work in its own interface. Use Project development to review that user experience before release.