Jobs: field and bulk edits
Change selected jobs’ forms
/a/Jobs_setFormId
Replace form links on selected jobs without remapping their stored answers.
When to use this endpoint
Replace form links on selected jobs without remapping their stored answers.
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 |
|---|---|---|---|
form_id | Integer string | Yes | Converted with intval; negative values are rejected. Zero/omitted input reaches the form lookup and normally returns form does not exist. The destination must be unarchived, but its form type is not checked. |
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. A nonempty input array is required; null/empty decoded input has a dedicated error. |
Example request
$result = FM_api('Jobs_setFormId', ['form_id'=>'501', 'ids'=>json_encode(['1042','1088'])]);Example response
[1042,1088]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: form_id"} | form_id converts to a negative number. |
{"error":"ids should be a JSON-encoded array of job IDs"} | ids is missing, empty, malformed/scalar after decoding, or contains nonscalar list members. |
{"error":"form does not exist"} | The unarchived-form lookup fails or has no row, including an archived destination. |
{"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. |
{"error":"Could not read jobs. Please retry."} | The active-job batch query 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
- Returns integer IDs of jobs whose stored form_id differed, not an ok object. Missing/deleted jobs and unchanged jobs are omitted; no matches returns []. IDs are appended only after a successful primary write.
- No answer migration, clearing or validation occurs. form_type, form_num, form_values and subform_values are left as stored, so switching forms can leave incompatible historic answers.
- IDs are queried with IN; repeated IDs do not produce repeated rows. No ordering, pagination or form ownership/assignment rule is added.
- 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 a job history entry with old and new form IDs. Does not recalculate costs, send mail, mirror outsourcing or run completion/workflow actions.
See it in Fieldmotion
CRM1
In CRM1 Jobs list select several rows, open the bulk-edit menu and choose Change Form. jobsMultiEdit.js calls Jobs_setFormId; filter Network for that route. The caller sends ids as JSON.stringify(ids).
CRM2
In CRM2 Jobs list select several rows, open the bulk-edit menu and choose Change Form. lib/jobsMultiEdit.js calls Jobs_setFormId; filter Network for that route. The caller supplies a native ids list.
Related endpoints
Forms_listsupplies selectable form definitions.Job_setFormNumchanges a job’s displayed form number instead.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.