Jobs: field and bulk edits
Change priorities for selected jobs
/a/Jobs_setPriority
Replace a priority code across selected jobs, returning per-ID missing/no-change messages.
When to use this endpoint
Replace a priority code across selected jobs, returning per-ID missing/no-change messages.
Read the target jobs first with Jobs_getSome to obtain the current values and confirm the IDs belong to the intended account.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Requests address physical job IDs in the authenticated account.
The legacy job-edit restriction bit 128 blocks the request with No permission to edit, including client administrators, matching the restricted focused setters. No additional assignee or department scope is applied.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
priority | Integer string | Yes | Required present value, cast to integer. Zero, negative and unknown codes are not rejected; this differs from the zero/no-write behavior of Job_setPriority. |
ids | Native array or JSON-encoded array | Yes | Job IDs converted with intval. Supply a valid list; decoded scalar/malformed JSON and nonscalar list members are rejected. No pagination or automatic chunking. |
Example request
$result = FM_api('Jobs_setPriority', ['priority'=>'2', 'ids'=>json_encode(['1042','1088'])]);Example response
{"errors":[]}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: priority"} | priority is absent or null. |
{"error":"missing or invalid parameter: ids"} | ids is absent or null. |
{"errors":["Job 1088 does not exist","Job 1042 is already the selected priority."]} | Missing/deleted/read-failed jobs and no-change IDs append messages while other IDs continue. |
{"error":"No permission to edit"} | The legacy job-edit restriction applies to this authenticated user. |
{"error":"Unable to save job","failedId":1088,"updatedIds":[1042]} | A primary write failed for failedId. updatedIds contains the earlier successfully written IDs, not a promise of an atomic batch. |
{"errors":["Job 1042 saved, but outsourced copy could not be updated"]} | The local priority write succeeded but the outsourced write failed. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Processes IDs in request order without deduplication. A repeated ID may update on its first occurrence and append an already-selected error on the next.
- No configured-priority existence check, transition validation or workflow action applies.
- Success is an errors-list object, not ok. Primary persistence is checked, while committed mirror failures are described in errors.
- Primary writes are checked. A failed write stops the batch with error, failedId and updatedIds (the successfully written prefix). Earlier writes remain committed; re-read the selected jobs before retrying.
Side effects
- For changed jobs, advances last_edited/edited_uuid and invalidates the meetings cache.
- Records job history and mirrors the converted priority to the linked outsourced job in the destination tenant. Mirror failures append a committed-save message to errors; mirror writes still have no deleted filter.
- Does not send mail or change completion/user-status fields.
See it in Fieldmotion
CRM1
In CRM1 Jobs list select several rows, open the bulk-edit menu and choose Change Priority. jobsMultiEdit.js calls Jobs_setPriority; filter Network for that route. The UI sends encoded IDs and will not submit zero even though the handler accepts it.
CRM2
In CRM2 Jobs list select several rows, open the bulk-edit menu and choose Change Priority. lib/jobsMultiEdit.js calls Jobs_setPriority; filter Network for that route. The UI also sends encoded IDs and declines zero; inspect errors in the response rather than only top-level error.
Related endpoints
Job_setPrioritychanges one job, with a zero-value no-op rather than a bulk clear.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.