Jobs
Start jobs, follow them live, read their details and logs, stop, kill, restart or resume them, and understand retries and dead-lettered jobs.
A job is one request to run a process with a set of inputs. A Robot claims the job and runs an attempt; a job that is retried has several attempts. Jobs live in a workspace, under Automations ▸ Jobs.
Job statuses#
| Status in the web app | Meaning | API status |
|---|---|---|
| Pending | Waiting for a robot, or for a scheduled retry. | Pending |
| Running | A robot is running it (also while it is being asked to stop). | Running, CancelRequested |
| Suspended | The workflow is waiting (for a timer, an event or a person) and was saved; no robot holds it. It continues when the wait ends or someone resumes it. | Suspended |
| Completed | Finished with its outputs. | Succeeded |
| Failed | A business fault, a failure that is not retried, or a retryable failure with no retries left (dead-lettered). | Failed, DeadLettered |
| Canceled | Stopped by a person, its time limit, maintenance, or its owner signing out. | Canceled |
Each job also shows its Source: for example Manual, Api, Trigger, QueueTrigger, Replay or Assistant.
Start a job#
Before you start, check that:
- The workspace has a process. See Packages and processes.
- A machine assigned to the workspace has an online robot with the runtime the package needs.
- For an unattended job, a robot account is assigned to the workspace. See Machines and robots.
- You hold
jobs.createin the workspace (for example Automation User).
Steps:
- Open the workspace and select Automations ▸ Jobs.
- Select Start job.
- Choose the Process and select Continue.
- Under Target robot, keep Auto-assign (first available) or pick a connected robot. The line below shows which robot accounts the job can run as.
- Under Inputs, fill in the fields. The form is generated from the entry point's input schema; required fields are marked.
- Select Start job.
You can also start a job from Automations ▸ Processes ▸ ⋮ on the process ▸ Start job, or with Ctrl+K ▸ Start a job.
The job appears on the Jobs tab as Pending, then Running, then Completed.
Start a job from code#
Start a jobHTTPCopyPOST /api/v1/tenants/{tenantId}/workspaces/{workspaceId}/jobs
Authorization: Bearer <your access token>
Idempotency-Key: 7c1d6c0e-invoice-2291
Content-Type: application/json
{
"automationId": "<process id>",
"inputs": { "InvoiceNumber": "2291" },
"priority": 50
}
With an Idempotency-Key, sending the same request again returns the existing job (200) instead of creating a second one (201). See Key endpoints.
Why a start is refused#
| Response | Cause | Fix |
|---|---|---|
422 |
The inputs do not match the entry point's input schema. The response points at the fields. | Correct the inputs. Names are case-sensitive. |
409 no_capable_runner |
No robot serving the workspace (or the robot you picked) has the runtime or capability the package needs. | Assign a machine with that runtime, or update its Robot. |
409 no_run_as_account |
No robot account is assigned to the workspace, and no Development machine may run the job as its signed-in user. | Assign a robot account to the workspace. See Machines and robots. |
404 |
The process or workspace does not exist, or you cannot see it. | Check the names and your role. |
Follow jobs#
Automations ▸ Jobs lists the workspace's jobs with process, runtime, status, start and end time, duration, source and hostname. Live means the list updates on its own.
- Search by process or job number.
- Select Filters to filter by Status, Source, Fault, Time range and Process. Fault ▸ Outcome unknown (to reconcile) finds jobs whose last attempt ended before it reported a result.
- A pending job shows why it is waiting, for example Robot account required.
Read a job's details#
Select a job row. The details show the status (with the failure reason for a failed job), process, robot, hostname, execution ID, created, started and finished times, the Parameters (inputs) and the Result (outputs). Preparation logs shows the steps before the automation ran: package download, verification, extraction, environment preparation and dependency restore.
Read logs#
- On the Jobs tab, select ⋮ on the job ▸ View logs for this job. (View logs for this process shows every run of that process.)
- Search the messages, or select Filters for time range, level, process, machine and host identity.
- Select Export CSV to download what you see.
The Logs tab under Automations searches the log lines of the whole workspace in the same way.
Reading logs needs logs.view. Logs are kept as long as the tenant's retention says; see Tenant settings.
Stop, kill, restart or resume a job#
From the job's ⋮ menu on the Jobs tab:
| Action | What happens |
|---|---|
| Stop job | The robot is asked to finish its current step and stop. The job ends as Canceled. Python automations see the request through velophex.runtime.stop_requested(). |
| Kill job | Ends a running or stopping job at once, without waiting for the robot. In-flight work may be lost. |
| Restart | Starts a new job with the same inputs and robot. If the earlier job's outcome is unknown, you are warned to check the systems it writes to first, so the work is not done twice. |
| Resume: wait name | Continues a Suspended job past that wait, on the next free robot. |
Stopping and killing need jobs.cancel. Through the API, stop is POST …/jobs/{jobId}/cancel with { "force": false } and kill is the same with { "force": true }.
Business and application faults#
How a job fails decides whether it is retried:
- Business fault: the automation decided the work cannot be done, for example an invoice that fails validation. In Python you raise
velophex.BusinessError. Business faults are final and never retried. - Application fault: anything else, such as an unexpected exception, a crashed executor, a timeout or a robot that stopped responding. These can be retried under the process's retry policy.
Retries and dead-lettered jobs#
A process's retry policy (set through the API, see Packages and processes) has these fields:
| Field | Meaning |
|---|---|
maxRetries |
How many times to retry after the first attempt. |
strategy |
Fixed, or Exponential (the base delay doubled per attempt, capped). |
baseDelaySeconds, maxDelaySeconds |
The delay before a retry, and the cap for exponential delays. |
retryOnApplicationError, retryOnTimeout, retryOnLeaseExpiry |
Which kinds of failure are retried. |
A retryable failure that cannot be retried any more is dead-lettered. The web app shows it as Failed; the API reports DeadLettered (filter with status=DeadLettered). Subscribe a webhook to com.velophex.job.dead_lettered, or add an alert rule, to hear about them. See Audit log and webhooks.
Attempts and leases#
While an attempt runs, the robot holds a lease on it and keeps renewing it. If a robot stops reporting, the Orchestrator's recovery sweep finds the expired lease and, depending on the retry policy, returns the job to Pending or ends it. A robot that lost its lease cannot post a stale result, and a result sent twice is recorded once. If a credential store is unreachable when a job needs its robot account password, the job goes back to Pending without using up a retry.
Check suspended jobs before a Robot upgrade#
Upgrade check on the Jobs tab lists suspended jobs that a given Robot version could not continue, and the robots whose version could not continue them. Run it before you change Robot versions on a fleet that has suspended jobs. See Updating the Robot.
Next steps#
Job statuses
Start a job
Start a job from code
Why a start is refused
Follow jobs
Read a job's details
Read logs
Stop, kill, restart or resume a job
Business and application faults
Retries and dead-lettered jobs
Attempts and leases
Check suspended jobs before a Robot upgrade
Next steps