User accounts and profiles
Configure a user’s background sync timer
/a/User_setBackgroundFunction
Save or remove one supported browser background-sync interval in user metadata.
When to use this endpoint
Use the Xero automatic-sync setting to configure the logged-in user’s browser timer. This stores a client preference; the API does not run a sync or schedule a server worker.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured; signed requests follow the API-key authentication flow.
Requires login and an owned tenant user. Ordinary self-profile edits are allowed; editing another user requires client administrator or explicit Users Edit permission. Protected membership fields require that permission even for self. Configured TeamAccess record scope and relationship checks remain in force.
The dispatcher applies configured TeamAccess user-record scope before the handler. An explicit target outside that scope returns an error; omitted targets use the current user for the scope check. Active/deleted filtering and additional target checks are described below.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | No | Defaults to the current user when omitted or integer-converted below 1. |
name | String | Yes | Trimmed alphabetic name; exactly bgFuncXeroSync or bgFuncXeroSyncFull is supported. Other alphabetic names return unsupported; punctuation/digits fail name validation. |
seconds | Integer string | Yes | Nonnegative integer seconds. Exactly 0 removes the selected timer. Missing, blank, negative, fractional, nonnumeric or nested values are rejected rather than coerced into removal. |
Example request
$result = FM_api('User_setBackgroundFunction', [
'name'=>'bgFuncXeroSync',
'seconds'=>'300',
]);Example response
{
"ok": 1
}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 parameter: name"} | Trimmed name is blank. |
{"error": "invalid parameter: name"} | Name contains nonalphabetic characters. |
{"error": "unsupported background function: Example"} | Alphabetic name is not in the two-name allowlist; the submitted name is appended. |
{"error": "user does not exist"} | Tenant user is absent. |
{"error": "user does not exist"} | No target user belongs to the authenticated account. |
{"error": "only client admins or users with Users edit permission can edit other users"} | Caller targets another user without explicit edit authority. |
{"error": "Unable to save user changes. Check the saved state before retrying."} | A checked write/transaction failed; inspect saved state before retrying, especially for separate global identity storage. |
{"error":"missing or invalid parameter: seconds"} | Interval is missing, malformed, negative or not an 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
- Only bgFuncXeroSync and bgFuncXeroSyncFull are accepted; handler availability is independent of frontend script files, including in the API-only container.
- Merges/removes the named background_functions entry independently in tenant and global metadata. Unrelated keys, other timers and nested arrays survive; an empty timer map is removed.
- If both serialized stores are unchanged, returns ok=1, msg=no update needed without edit-marker/history writes.
- Self edits update only the named timer in the current session metadata, preserving session-only keys. Editing another authorized user never replaces the caller’s session metadata.
- The handler stores a browser timer preference; it does not invoke Xero or create a server worker. The shared self/editor policy and configured TeamAccess guards apply.
- Tenant/global storage are independently checked, with tenant history in the tenant transaction. A cross-host commit uncertainty is reported without automatic replay.
Side effects
- On change, writes both metadata stores with edit markers, invalidates employees/users caches and records background_functions history. Updates current session metadata only for self. No external sync call is made.
See it in Fieldmotion
CRM1
In Settings → Finance → Xero, change Automatic sync. CRM1 calls User_setBackgroundFunction with name=bgFuncXeroSync, seconds and no id, then updates its local timer state.
CRM2
CRM2’s Xero settings use the same direct route and name, with no id. Filter User_setBackgroundFunction and compare the saved interval with local userdata.bg_funcs.
Related endpoints
User_getMeta— Read one tenant metadata value.User_setMeta— Merge one ordinary preference into both identity stores.