Jobs: recurrence settings
Set the default recurrence form
/a/JobRecurrence_setForm
Choose the default form for generated jobs, optionally discarding future children for regeneration.
When to use this endpoint
Use the Form cell in the recurring-jobs table; choose whether existing future children should be reset.
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 uses the prior job's form. Positive IDs must identify non-archived type-0 Job forms. |
reset | Integer flag | Yes | Exactly 0 changes settings only; 1 removes eligible future children from now for regeneration. |
Example request
$result = FM_api('JobRecurrence_setForm', ['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":"invalid parameter: id"} | ID missing or nonpositive. |
{"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 parameter: reset"} | Reset choice omitted. |
{"error":"Invalid target job form"} | Selected positive form is missing, archived or not a Job form. |
{"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
- Validates the form before writing. Does not migrate existing answers or interpret them against a different form.
- With reset=0, current jobs are unchanged and no priority bump occurs. Nonzero reset preserves the first valid anchor and completed/deleted jobs, then removes incomplete active children strictly after now.
- Per-occurrence schedule forms can override the default. Cleanup errors/busy generation yield saved warnings.
- 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, change the Form cell and answer the reset confirmation. The 'copy previous job' option sends val=0.
CRM2
In the recurring-jobs module, edit Form and confirm whether to reset future jobs. Filter for JobRecurrence_setForm; the editor sends numeric val and reset.
Related endpoints
JobRecurrence_setSchedulecan override forms per occurrence.JobRecurrence_getreloads the default form.