Jobs: scheduling and lifecycle
Change one job's lifecycle status
/a/Job_setStatus
Apply a status transition, with completion, recurrence, quote and outsourcing follow-ups.
When to use this endpoint
Use for one persisted lifecycle transition, not the separate user_status field. Complete (1) invokes the completion workflow; use Job_setStatusToComplete directly only when its action-mask contract is required.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Legacy edit-restriction bit 128 is enforced; client administrators retain the existing admin exception.
The primary job selection is tenant-scoped. There is no automatic schedule-conflict or assignee-ownership check. Cross-tenant follow-ups use persisted outsourcing context.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive active job ID. |
value | Integer string | Yes | Status index after integer coercion. 0 Incomplete, 1 Complete, 2 Processed, 4 Authorised and 5 Cancelled are special in the implementation; other statuses must exist in the tenant status configuration. The parameter must be present; a nonnumeric present string coerces to 0. |
Example request
$result = FM_api('Job_setStatus', ['id' => '1042', 'value' => '0']);Example response
{"ok":1}An unchanged status returns {"ok":1,"warning":"job already has that status"}, skipping all later work. Completion response fields are not forwarded by this wrapper.
Errors and unusual responses
| Response | Condition |
|---|---|
{"error":"not logged in"} | No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs. |
{"error":"missing or invalid parameter: value"} | Missing/null value. |
{"error":"job does not exist"} | Missing/deleted job. |
{"error":"no such status"} | A non-completion index is not configured. |
{"error":"You cannot change a job from Incomplete to Processed without first marking it Complete"} | 0→2 is blocked unless allow-job-status-change-incomplete-to-processed is enabled. |
{"error":"ONCOMPLETE not set"} | Completing a non-Workflow tenant with no service configuration. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Enforces the legacy edit restriction with the client-admin exception. Value 1 delegates to Job_setStatusToComplete; other changes use Job_statusChange.
- Configured default_user changes current_user_id, not assigned user_id. With features2.workflow enabled, an eligible bound Workflow run can accompany the status write; absent bindings/already-run statuses do not create a new run. Later quote/remote/cache effects are not atomic with it.
- Reopening to 0 refreshes customer job counters and removes the global/current-assignee mobile removal markers, preserving former-assignee markers. The legacy counter query does not distinguish customer versus asset IDs.
- After a real change, updates recurrence next state and flags linked contract customer caches dirty. Cancelled (5) sets one active linked quote to status 3; there is no ordering or all-quotes loop.
- Statuses 0/1/5 are also written to the stored outsourced copy. The shared helper can mirror the other direction for eligible outsourced context. No schedule availability or batch pagination applies.
Side effects
- Status/history/edit metadata, optional current user change, Workflow run, mobile removal/reopen markers and customer counters.
- Completion can run form rules, asset changes and emails. Non-completion status helper may call configured job exports. The wrapper additionally updates recurrence/contract caches, a linked quote on cancellation and outsourced status.
See it in Fieldmotion
CRM1
Edit Status on Jobs, Customer Jobs or Job detail. The Jobs list sends Jobs_emailCancelled separately after value=5; the Job detail re-complete dialog reopens first.
CRM2
Job detail re-complete uses this to reopen. The main Jobs module normally uses mapped Job_updateData for status, then a separate cancellation-email call.
Related endpoints
Job_setStatusToCompleteruns the dedicated completion workflow.Jobs_statusSetcollects per-job transition errors.Jobs_emailCancelledqueues cancellation mail separately.