Jobs: recurrence settings
Set the recurrence department
/a/JobRecurrence_setDepartmentId
Change the department attached to a recurring-job sequence.
When to use this endpoint
Use the Department cell in the recurring-jobs table to classify the sequence itself.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Tenant context is required. The Job edit-restriction bit 128 applies, with the existing client-administrator exception.
IDs resolve inside the authenticated tenant. There is no additional department-visibility or recurrence-ownership filter.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Positive recurrence ID in canonical integer form; not a job ID. The record must exist. |
department_id | Integer string | Yes | 0 clears; positive values must identify an existing tenant department. |
Example request
$result = FM_api('JobRecurrence_setDepartmentId', ['id'=>'1042', 'department_id'=>'0']);Example response
{"ok":1}A post-save follow-up failure adds saved=1 and warning/warnings without undoing the settings. Read the warning and reload affected objects rather than blindly replaying the operation.
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 supplied"} | ID omitted. |
{"error":"job recurrence 1042 does not exist"} | No matching recurrence; numeric ID varies. |
{"error":"No permission to edit"} | The Job edit restriction applies and the caller is not a client administrator. |
{"error":"Unable to save job delivery changes"} | The checked local transaction failed; settings/history are rolled back. |
{"error":"that department does not exist"} | Positive department has no tenant row. |
{"error":"Invalid saved recurrence metadata"} | The saved metadata cannot be decoded as an array/object; it is not silently erased. |
{"error":"missing or invalid parameter: department_id"} | Department value missing, negative or not a supported integer. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Sets department_id and server-owned meta.department_override. Future generated jobs use this explicit value, including 0; existing jobs are unchanged.
- Unmarked legacy sequences keep inheriting the example job's department. No independent reset/priority bump occurs.
- The department is existence-checked, without an extra visibility filter. Same-value calls are successful no-ops after the override is established.
Side effects
- The existing recurrence is locked and changed settings, edit timestamp/operation marker and history are committed together in a checked local transaction. Failed local persistence rolls back; an unchanged value normally returns ok without a new local write.
- Cleanup, child-target changes and global scheduler/reminder reconciliation run after the local save. A failed follow-up preserves committed settings and returns ok=1, saved=1, warning/warnings. Inspect current state and any partial progress before retrying; tenant and global effects are not distributed-atomic.
See it in Fieldmotion
CRM1
Open Jobs → Recurring Jobs or a customer's recurring-jobs tab, edit Department and filter for JobRecurrence_setDepartmentId.
CRM2
No direct production CRM2 call was found. Its recurring-jobs table uses the mapped department field/update flow.
Related endpoints
JobRecurrence_getreads the saved department and sequence settings.