Fieldmotion API Getting started

Jobs: recurrence settings

Set the recurrence frequency mode

POST /a/JobRecurrence_setEvery

Choose how the stored on_arr values are interpreted by the recurrence generator.

When to use this endpoint

Save the frequency mode together with a compatible on_arr value using setOn. This endpoint changes only the mode, so an intervening scheduler run may see mixed settings.

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

ParameterTypeRequiredDescription
idInteger stringYesPositive recurrence ID in canonical integer form; not a job ID. The record must exist.
valInteger stringNoValidated integer mode 0–6; omission defaults to 0.
skip-runLegacy truthy flagNoDefault 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_setEvery', [
	'id' => '1042',
	'val' => '1',
]);

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

ResponseCondition
{"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

  • Modes are 0 weekdays, 1 zero-based month days, 2 zero-based year days, 3 every N days, 4 every N weeks, 5 every N 30-day months, and 6 every N approximate years.
  • This focused call changes the mode only. Save a compatible selection with setOn, or use the frequency editor's combined set path to avoid mixed settings.
  • The worker uses elapsed/approximate interval arithmetic for modes 3–6, not a promise of calendar-month/year anniversary scheduling. Existing children are not independently reset by this route.
  • 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