Jobs: scheduling and lifecycle
Run the job completion workflow
/a/Job_setStatusToComplete
Complete a job using either the legacy on-complete service or the tenant's durable Workflow engine.
When to use this endpoint
Use when marking Complete or performing the legacy re-complete action selection. Re-complete callers reopen first: this endpoint is not an unconditional replay of all completion rules.
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 job ID. Omitted gives no id; nonpositive gives missing or invalid parameter: id. Workflow mode checks an active row before changes; legacy mode relies first on the service. |
actions | Integer bitmask | No | Default 0, expanded by the legacy service to 255 (all actions). Either of the low bits 1/2 enters the shared main/table asset pass; do not rely on them to isolate one asset source. Bit 4 runs on-complete rules, 8 email and 16 completion timestamp. Combine as needed. Workflow mode ignores this legacy mask. |
Example request
$result = FM_api('Job_setStatusToComplete', ['id' => '1042']);Example response
{"ok":1,"date_completed":"2026-10-13 10:00:00","date_completed_e":"1791882000"}Completion dates are reread database values, not a transport receipt. A positive legacy service acknowledgement is required before completion events/mobile removal; a nonempty error or malformed reply is not success.
Workflow mode returns an already-complete warning without replaying post-completion effects. Canonical completion-source settings can determine the effective timestamp.
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":"no id"} | Parameter entirely omitted. |
{"error":"ONCOMPLETE not set"} | Legacy mode has no configured completion-service URL. |
{"error":"job does not exist"} | Workflow branch cannot find an active job. |
{"error":"Error while contacting onComplete service. This job will be completed automatically once service is resumed."} | Legacy service returned an empty response; a retry request is recorded globally. Do not blindly resubmit. |
{"error":"Completion service response was not confirmed. Check job status and history before retrying."} | Nonempty malformed reply or no positive ok acknowledgement; no completion follow-ups. |
{"error":"Completion was acknowledged but the job is not complete. Check job status and history before retrying."} | The active job reread still has status 0 or is missing. |
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 client-admin exception and prechecks an active job. No form-required-answer or assignment-ownership check is added.
- Workflow mode locks the active job, applies the times-edited completion source and commits a checked status write with any eligible bound Workflow run. An already-1 job returns its existing dates and a warning before later side effects.
- Legacy mode decodes the signed service response. Explicit errors are propagated; malformed/missing-positive acknowledgements return an uncertainty error asking for status/history review. Only an empty transport result creates the existing global retry record.
- The legacy asset pass uses actions & 3; its inner low-bit guards do not reliably isolate main/table asset work. The office dialog sends 1/4/8/16. Workflow ignores that legacy mask and uses its bound transition actions.
- Before firing completion follow-ups, rereads an active job and rejects a still-zero status. This does not make every external rule/email atomic or guarantee each later follow-up succeeded.
Side effects
- Fires Job_markAsComplete, recounts customer open/closed jobs or updates asset last-visited/service next-date metadata. Asset frequency uses days/weeks/months/years from the current server time; CRM2 can send an asset update notification.
- Deletes existing mobile-removal markers for the job and creates a global removal marker without soft-deleting the job; logs Complete. Legacy service may update asset movements, execute form rules, email and update recurrence/costs; Workflow schedules its configured actions separately.
See it in Fieldmotion
CRM1
Job detail → re-complete opens action checkboxes, first calls Job_setStatus(value=0), then this endpoint with a bitmask. Normal completion via Job_setStatus also delegates here.
CRM2
Job detail uses the same reopen-then-complete sequence. Mobile completion uses its separate intermediary/service path; its response and flags are not this office API contract.
Related endpoints
Job_setStatusincludes the extra single-job transition follow-ups.Jobs_statusSetcollects per-job transition errors.Job_updateAssetJobsmaintains derived asset associations without erasing history.