Async Progress and Jobs

Use asynchronous workflows for work that should not keep an HTTP request open: exports, imports, mail batches, external API polling, publishing, cleanup, and scheduled maintenance.

Sync launcher, async worker

A reliable pattern is to keep the user-facing workflow synchronous and move the heavy work into an async worker workflow.

{
    "name": "startPublishJob",
    "type": "action/run",
    "options": {
        "workflow": "PublishProject",
        "async": true,
        "scope": true,
        "input": {
            "project": "$project"
        }
    },
    "to": {
        "default": {
            "notifyQueued": ["default"]
        }
    }
}

The launcher validates input and tells the user that work started. The worker performs the long-running process.

With scope: true, the values in input become variables in the called workflow context. With scope: false, the called workflow runs in the existing context.

Progress notifications

Use cast/progress to make background work visible.

{
    "name": "publishProgress",
    "type": "cast/progress",
    "options": {
        "title": "Publishing project",
        "total": 4,
        "progress": 1,
        "statusMessage": "Preparing files",
        "send_to_user": true
    }
}

Use the same process value when multiple progress elements update one progress item.

{
    "name": "publishProgressDone",
    "type": "cast/progress",
    "options": {
        "process": "project_publish",
        "title": "Publishing project",
        "total": 4,
        "progress": 4,
        "statusMessage": "Finished",
        "send_to_user": true
    }
}

See Cast for option details.

Error paths

Connect supported error ports to logging, cleanup, or a user-facing failure notification.

{
    "name": "callExternalProvider",
    "type": "api/http",
    "set": {
        "providerError": "error:"
    },
    "to": {
        "default": {
            "saveResult": ["default"]
        },
        "error": {
            "logProviderError": ["default"]
        }
    }
}

Do not forward raw external service responses to end users. Log enough for debugging and send a neutral notification.

Cron jobs

Cron workflows should usually be async. They should be idempotent, log summary information, and avoid browser-only actions.

Good cron workflow tasks include:

• Checking for expired records.
• Sending reminders.
• Recomputing denormalized status fields.
• Importing or exporting batches.
• Retrying failed external operations.

Async checklist

• The workflow has async: true if it may take more than a few seconds.
• The UI path returns quickly.
• Long jobs emit progress or a completion notification.
• Error ports are connected where available.
• Cron jobs are idempotent and safe to retry.
• External service data is sanitized before it reaches users.