Fieldmotion API Getting started

Saved views and configuration

Save one page preference

POST /a/PageSetting_update

Insert or replace one user or tenant-shared preference value.

When to use this endpoint

Use for a single preference or explicitly JSON-encoded advanced-search value. This is not a tenant business setting API; it stores UI page keys and values.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Ordinary page keys, including the literal string false, use the current user; pageLayouts and pageGlobal use tenant-shared user ID 0.

Shared reads need no additional permission. Only the account administrator (user ID equals parent account ID) can write pageLayouts. pageGlobal retains its existing shared-write access for authenticated users.

Parameters

ParameterTypeRequiredDescription
pageStringYesNonempty page key, maximum 100 characters. pageLayouts and pageGlobal are shared; other keys are current-user specific.
fieldStringYesNonempty field key, maximum 100 characters.
valueScalar or native JSON structureYesStored text, at most 65535 bytes. Native arrays/objects are JSON-encoded and booleans stored as true/false tokens. Empty string is accepted; null is rejected.

Example request

$result = FM_api('PageSetting_update', [
	'page' => 'advanceSearch',
	'field' => 'jobs',
	'value' => json_encode([['column' => 'name', 'condition' => 'contains', 'value' => 'Northwind']]),
]);

Example response

{"ok":"1"}

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: page"}Missing/invalid page; field/value have equivalent errors.
{"error":"Page cannot be updated."}Non-account-administrator writes pageLayouts.
{"error":"configuration read failed"}A required database read fails; no write is committed.
{"error":"configuration write failed"}Persistence or checked history fails; the transaction rolls back.
{"error":"configuration transaction failed"}Transaction begin or commit fails; no success is reported.

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 the supplied key is merged; unrelated keys remain unchanged. Exact stored-text equality skips the write.
  • Upserts serialize on a tenant lock to prevent new duplicate user/page/field rows. Existing duplicate rows for that key are updated together. Literal false is current-user specific.
  • Shared-page scope matches both bulk writers and readers. No feature flag changes scope.

Side effects

  • Changes page_settings with its cache marker; shared changes have checked Page settings history. All changes/history commit together.
  • No last-edited marker, notification or business-object mutation.

See it in Fieldmotion

CRM1

No direct CRM1 production caller was found. These routes underpin CRM2 server-stored display preferences; CRM1 also keeps client-side display/filter state.

CRM2

Save the CRM2 advanced-search dialog; widgetAdvanceSearch.js sends JSON text as value. Shared saveSetting also calls this route for individual preferences.

Related endpoints