Let a server function continue in the background while the original workflow returns a job ID. This is useful for work such as preparing a report or processing a batch of records.
A function or endpoint is not automatically a background job. A job is created only when a workflow calls a published server function with Run in background selected. Opening that function and running its own test runs it normally; it does not queue a job.
To test background execution, run the endpoint, function or event that contains the Run in background call. The caller returns a job_id you can find in Background jobs.
Publish the server function you want to run.
Add that function to an endpoint, server function or event workflow.
Click the Custom Function command row under Commands to open its editor. Click the command row itself; the linked function name opens the function definition instead.
At the top of that sidebar, change Execution from Wait for result to Run in background.
Supply its inputs using the usual variable controls.
Set the maximum run time and, optionally, a delay and an idempotency key.
Choose Return as to name the job details returned to the calling workflow.
The caller receives job_id, state, created_at and queue_deadline_at. It does not wait for the background function's result. Leave Execution as Wait for result when later commands need that result immediately.
The function receives a copy of its inputs. The original customer's login and uploaded files do not follow it into the background. Design it to work with explicitly supplied, permitted record IDs and values. Background execution is available to server workflows, not page workflows.
An optional Idempotency key identifies one logical request. Reusing the same key for that request returns the existing job instead of creating another one. Use a different key for a deliberately new action. Do not put passwords or customer tokens in keys.
Leave Automatic retries as No automatic retries for the existing behavior. Review failed, timed-out or interrupted work before deliberately starting another job. A job may have completed some actions before it stopped.
In the Run in background command, choose Up to 1 retry or Up to 2 retries under Automatic retries, then select Allow these pre-execution retries and save the command.
Only a confirmed temporary failure before the workflow starts can retry automatically. For example, Twidget may temporarily be unable to prepare a job's usage record. The workflow has not run in that attempt. It waits briefly before trying again; at most three attempts are possible when you allow two retries.
An error after workflow execution begins, a timeout, cancellation or interrupted execution is never automatically repeated. Checking the box does not make emails, payments or record updates safe to repeat. Each attempt uses your normal request and processing limits; retries do not reset them or increase your available capacity.
Select a job in Background jobs to see its attempt history. Retry scheduled means it is waiting before an allowed startup retry. The history shows whether an attempt reached the workflow and its recorded outcome. You can cancel a job while it is waiting; cancellation prevents its next attempt.
When Retry job is available for a finished job, it creates a new linked job using the same saved function version and copied inputs. Current workspace settings and secrets still apply. It does not substitute a newer published function or carry over another automatic-retry allowance.
Read the confirmation carefully: some work may already have completed, and running the job again can repeat record changes or external actions. Choose I understand, retry job only after checking those effects. The original job remains in history; Job chain and Retried from help you follow the new job and its source.
Retry is unavailable while related work is active or its earlier outcome cannot safely be confirmed. Read the explanation in job details. Retrying still uses normal queue, processing and related-job limits.
If the connection drops during the request, use Check retry outcome. This checks the same retry request instead of deliberately creating another job. Do not start a different retry merely because its first response was lost.
Open Background jobs in the sidebar. Choose Live jobs or Test jobs, then filter by state, function ID or created date. Click a date heading to change the order. Click anywhere on a job row to expand its details directly underneath. Click the same row again, or use the close button, to collapse them. You can also focus a row and press Enter or Space.
Editor tests create Test jobs, even when Use live data is enabled. The page initially shows Live jobs, so choose Test jobs to see calls queued by editor tests. Changing the environment loads its jobs immediately. Returning to the page refreshes its history; use Refresh to check again while staying on the page.
Use the Help button at the top of the page to choose a related guide. The guide opens beside your work, so you can keep your place in the job list.
A job can be queued, running, succeeded, failed, timed out, cancellation requested, cancelled or interrupted. Interrupted means execution stopped unexpectedly and its effects may be uncertain. Check what happened before running it again.
Details distinguish its scheduled time, queue deadline and retention end. The queue deadline is the latest time it can begin; retention end is when its finished history is cleared. Select Load result in the bordered Result panel to see saved output. If no output was saved, the panel explains this instead of remaining blank. A failed job can have error details without a saved result. A saved null, false, zero or empty text is still a valid result.
If the result cannot be retrieved, the panel shows a message and you can try again. Reload result fetches the output again without closing the job details.
You can also follow and cancel a job from another server workflow. In Add command, open Background jobs:
Get Background Job: supply the job_id returned by the background call. Turn on include_result when you need the finished function's result. Save the output with Return as, then use its state to decide what happens next. A result is available only after it has been stored.
Cancel Background Job: supply the same job_id to request cancellation. Read the returned state; a running job may first show CANCEL_REQUESTED before it stops.
These commands look up jobs in the current workspace and environment. Editor tests look up test jobs; live workflows look up live jobs. They do not pause until a job finishes. For example, a status endpoint can receive a job ID, use Get Background Job, and return its current state to your app.
Choose Cancel on a queued or running job and confirm. Cancellation is a request to stop further work; it cannot reverse completed emails, external calls, file changes or record changes. Refresh to see the resulting state.
Test jobs use test data. A background job has its own test data context; it does not continue an endpoint test's private record changes. Use self-contained inputs and starting data for background tests.
Operational limits on queued and concurrent work keep workloads responsive. Each job has a maximum run time of up to five minutes. Finished job history is retained for 30 days. Keep lasting business results in your own tables rather than relying on job history.
Output
Each function also has an optional output where you can return an output variable. To simplify the use of functions, you can define an output schema. The output schema acts as an internal documentation detailing what the output of the function will look like. This makes it easier to understand and u...
Data Types
Twidget supports six main data types to facilitate interactions within the platform. These data types are essential for defining inputs, outputs, and table fields, helping users understand the nature of the data being handled. The available data types in Twidget are as follows: Text. - Description: ...
Test suites
Test a customer journey across several endpoints in a single ordered run. For example: sign in, create an order, retrieve it, then check its status. Every run shares its own isolated database across its steps. Your workspace records are not changed by those database actions. This version supports is...
Workflow templates
Keep reusable workflows in a private library within your workspace. Save a useful endpoint, function, middleware or event, then install independent draft copies when you need the same starting point again. Related workflows are included automatically where supported. Open Workflow templates from the...
Functions
In Twidget, you can build custom reusable functions. These functions can be utilized across various sections including endpoints, events, and other functions. Instead of creating the same commands repeatedly, you can create a function once and reuse it wherever necessary, making your workflow more e...
