Jobs: recurrence settings
Set a default recurrence assignee
/a/JobRecurrence_setUser
Choose the default numeric user for future generated jobs, optionally resetting future children.
When to use this endpoint
Use the User cell in recurring jobs. For resets, inspect the existing children before confirming the destructive option.
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. |
val | Integer string | Yes | 0 removes the positive default and permits copy_user fallback. Positive values must be active tenant users; negative/invalid values are rejected. |
reset | Integer flag | No | Exactly 0 (default) leaves children unchanged; 1 requests explicit reset of eligible future children from now. |
Example request
$result = FM_api('JobRecurrence_setUser', ['id'=>'1042', 'val'=>'0', 'reset'=>'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":"missing or invalid parameter: id"} | ID missing, invalid or not positive. |
{"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":"Invalid saved recurrence metadata"} | The saved metadata cannot be decoded as an array/object; it is not silently erased. |
{"error":"invalid parameter: val"} | The value is missing when required, has an unsupported type, or fails the operation-specific range/shape/date rules. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Changes numeric user_id, not user_type; a positive default takes precedence over copy_user.
- With reset=0, current child assignees remain unchanged and no priority bump occurs. With reset nonzero, settings save first, then cleanup preserves the first valid anchor and removes active incomplete children strictly after now.
- A failed/busy cleanup is exposed as a saved warning. Removal is for regeneration, not an in-place assignment change.
- A priority bump does not synchronously generate jobs: it backdates global last_run by seven days. Missing active registration is created using recurrence-days. Inactive sequences have their registration removed without being regenerated; an active sequence with blank on_arr yields a saved warning instead of a misleading rolled-back error.
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 and change the User cell. The reset confirmation sends reset=1 for Yes or 0 for No. User and customer recurring-job screens also call this route.
CRM2
Open the recurring-jobs module and change User; filter for JobRecurrence_setUser. The confirmation sends reset=1/0. The user-move-recurrence widget also uses the setter.
Related endpoints
JobRecurrence_setCopyUsersets the no-default-user fallback.JobRecurrence_getreloads the configured user.