Jobs: recurrence settings
Replace per-occurrence recurrence overrides
/a/JobRecurrence_setSchedule
Replace the structured form, stock, rate and job-type overrides used when generating future jobs.
When to use this endpoint
Use when a client already owns the recurrence editor's complete override structure. Read get first so replacing the document does not discard other override groups.
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 | JSON string | Yes | Complete JSON-object text. Recognized occurrence maps must decode to arrays with positive numeric keys; nested form/stock/rate entries must decode to arrays. Native request arrays and malformed shapes are rejected. |
skip-run | Legacy truthy flag | No | Default false. A truthy value suppresses only the scheduler-priority bump. It does not suppress the settings save, explicit cleanup, expiry registration updates or reminder reconciliation. |
Example request
$result = FM_api('JobRecurrence_setSchedule', [
'id'=>'1042',
'val'=>json_encode(['stock'=>1, 'stock_items'=>['2'=>json_encode([['id'=>81,'num'=>3,'price'=>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":"missing or 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
- Whole-document replacement, not a merge. Read get first and preserve other override groups.
- Worker keys include form/formfield_items, allform_values, stock/stock_items, sor/sor_items, jobtype_items and duedateoffset/duedateoffset_items. Numbered occurrence maps use recurrence_no; the next generated job normally starts at 2.
- Non-loop stock_items values are JSON strings of {id,num,price}; loop stock entries use richer rows including amt. formfield_items contains formID and optional formValue.formValues/subFormValues; allform_values is keyed by form ID.
- Looping maps repeat independently by highest occurrence key. Empty maps are safe no-ops, not a modulo-by-zero failure; do not assume sparse maps provide values for every occurrence.
- No independent child reset occurs.
- 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.
- The surrounding Job_save recurrence editor invokes this setter internally. Its wider generation-setting save separately requests reset-from-now and now propagates failures/saved warnings. Direct endpoint effects above do not describe the whole editor save.
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.
- 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.
See it in Fieldmotion
CRM1
No direct production CRM1 caller to this focused endpoint was found. The recurrence configuration dialog instead saves settings with JobRecurrence_set or as part of Job_save.
CRM2
No direct production CRM2 caller to this focused endpoint was found. The job recurrence editor carries configuration through Job_save; the recurring-jobs module also uses JobRecurrence_set and mapped updates. The shared job recurrence editor also reaches this setter indirectly through Job_save; observe Job_save in the Network panel rather than expecting a separate request to this focused route.
Related endpoints
JobRecurrence_setLoopRecurrencechooses whether override maps repeat.JobRecurrence_setCopyFormValuescontrols available answer copying.JobRecurrence_getreturns the existing schedule as encoded JSON.