Forms
Save form notes
/a/Form_setNotes
Store form-definition notes, with CRM2 mention notifications.
When to use this endpoint
Use for notes about the form design, rather than answers or notes on a particular job. Read Form_getNotes first; CRM1 sends plain text while CRM2 sends JSON-encoded note records.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The signed key acts as its associated tenant user.
Existing-definition settings writes require Forms Edit (pageForms_edit); client administrators pass the standard permission helper. Roleless/non-edit users fail closed. Temporary setup accounts retain their provisioned Forms Edit permission; the metadata marker alone does not grant that permission.
The account features2.disableFormEdits=1 setting blocks definition writes, except temporary setup users. Writes stay in the authenticated tenant; they do not modify an outsourced source definition.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible form ID | Yes | Positive integer-converted local form ID. The form must exist; it is locked during the save. |
val | String | Yes | Non-null notes text, HTML-escaped before storage in meta.notes. Empty text is accepted. CRM2 note widgets send a JSON string of note records; native arrays are not a substitute. |
Example request
$result = FM_api('Form_setNotes', ['id'=>'1042', 'val'=>'Review the checklist annually.']);Example response
{"ok":1}A normal save returns ok=1. If post-commit mention handling cannot be confirmed, the reply adds saved=1 and warning: notes are already saved, so refresh rather than repeat the save. An unchanged value returns ok=1 without sending mentions.
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 absent/null or converts below 1. |
{"error":"missing or invalid parameter: val"} | val absent/null. |
{"error":"form edits are disabled for this account"} | Account definition edits are disabled; temporary setup users bypass the feature. |
{"error":"permission denied"} | The actor lacks Forms Edit. Client administrators pass the standard permission helper; the temporary marker alone grants no access. |
{"error":"Unable to save form settings. Check the saved state before retrying."} | A read, primary write, history, undo or transaction acknowledgement failed; do not replay an uncertain save without refreshing. |
{"error":"form does not exist"} | No matching local row. |
{"error":"Form metadata is invalid. Repair it before saving."} | Existing nonempty metadata is not a JSON object/array. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Locks the existing local form, initializes legacy null/empty metadata, and preserves unrelated metadata keys. Invalid nonempty metadata is rejected without overwriting it. Changed notes update meta.notes and last_edited, with checked history and an undo snapshot in the same transaction.
- HTML entities remain stored as text. Plain text and CRM2 JSON note lists remain strings; Form_getNotes does not decode entities or nested JSON for the caller. Empty text clears notes; an identical stored value returns ok without writes or notices.
- CRM2 mention comparison uses the previously saved, decoded note list. Only mentions newly introduced relative to that list are passed through the normal notification helper after primary commit. An identical save sends nothing, and editing text while retaining the same mention does not create a new mention notification.
- Notice creation can update recipient notices_latest and queue enabled email notifications. These follow-ups are not distributed-atomic with the form save. A failed/missing helper acknowledgement returns ok=1, saved=1 and a warning; it does not roll back notes or automatically resend anything.
- When invoked inside an already-open transaction, the setting save uses a savepoint and returns a warning that caller-owned changes remain pending; it sends no mention notices before the caller commits. The caller must arrange its own post-commit notifications.
- No direct mobile app/m-service caller for this RPC was found. Mobile form definitions arrive through m’s syncDownloads channel; changed metadata now updates the form edit timestamp used there.
Side effects
- Changed notes commit the metadata, last_edited, acting-user history and after-change undo snapshot together, with forms cache invalidation. After a top-level commit, new CRM2 mentions can create notices, update recipients’ notices_latest and queue enabled notification emails. An unchanged value has none of those effects.
See it in Fieldmotion
CRM1
Form Edit → Notes opens a plain textarea; inspect Form_getNotes when opening and Form_setNotes when saving.
CRM2
Form Edit, On Complete and Report Document editors load Form_getNotes and send JSON.stringify(newData) from their notes widgets to Form_setNotes.
Related endpoints
Form_getNotesreads the stored notes value.Form_setTagschanges the separate tags metadata path.