Task discussion notes
Edit or upsert a Task note
/a/TaskNote_updateField
Edit one mapped note or use the legacy first-note upsert path.
When to use this endpoint
Use explicit note IDs obtained from a read. Do not use id=0 as an append instruction.
Authentication and permissions
Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; normal session requests need dispatcher CSRF protection where configured. Tenant data is selected from the authenticated account.
The dispatcher’s configured TeamAccess policy recognizes TaskNote IDs and checks their owning Task scope. TaskNotes_get additionally checks task_id. TasksNotes_get is a different plural namespace and has no matching scope mapping. These existing feature/actor-dependent checks are separate from a CRM2-only role grant; this work adds no permission rules.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible | No | Positive scalar selects an existing note; absent/zero activates a first-note-by-taskID lookup. Native id lists reach the generic writer through an integer-converted wrapper branch, so prefer scalar IDs. ids does not control this wrapper’s branch selection. This is a note ID, not the Task ID. |
taskID | Integer-compatible | Conditional | For zero/missing id, selects any first note for the Task, without ordering; if none exists, inserts one. Parent existence is not checked here. For explicit id it supplies notification-link context in updateData, not verification that the note belongs to it. |
Mapped note fields | Mapped values | No | id, userID, note, lastEdited, editedUUID, taskID and cDate. userID/taskID are integers; note/editedUUID text; date aliases are SQL datetime text. These mapped writers do not protect lifecycle/author/relationship fields merely because the UI hides them. |
field / val | Mapped name / non-null value | Required on existing-note branch | The normal updateField branch requires both. On the no-existing-note creation branch, field is not used to choose the created column: val is copied to note, default empty when absent. |
Example request
$result = FM_api('TaskNote_updateField', ['id'=>'45','taskID'=>'18','field'=>'note','val'=>'Reviewed']);
Example response
{
"ok": 1,
"oldData": [
{
"id": "45",
"note": "Previous note"
}
]
}
Application errors normally remain JSON responses with HTTP 200; inspect error/warning keys. Numeric driver values can be strings.
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: field"} | Existing-note inline update lacks field. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- The current mobile app synchronizes task_notes through the mobile intermediary and caches task_notes-<Task ID>. That cache identity is a Task ID, not the CRM note-record ID accepted as id by these mapped office routes; the sync payload/selection contract is separate.
- Omitted/native-null optional mapped fields are skipped. Blank text is saved; blank date/datetime/JSON clears to SQL NULL where mapped. Numeric values integer/float-convert. Real date fields receive calendar validation, but ordinary datetime strings have no equivalent strict check. Unknown keys are ignored by the primary mapped write.
- Missing/zero id is an upsert of the first note, not an append. With multiple notes the selected existing row is unspecified; repeated calls can overwrite an older author’s note. Explicit note IDs are preferable.
- On creation sets actor userID, cDate now and editedUUID to this endpoint name; lastEdited is stamped by the shared writer. Other mapped values, including taskID and lifecycle/author fields on updates, have no route-owned validation/protection.
- Creation does not enforce field/val like the existing-note branch and always puts val into note. Updates return oldData storage-column rows; no-op updates may return ok="1",warning="no change required". It does not send mentions or notification-service events.
Side effects
- Changed mapped values stamp last_edited, invalidate the table cache and write field-change history. Primary UPDATE acknowledgement is checked; history and later service calls are not one atomic save. No automatic retry/idempotency token is provided.
- No explicit notification/mention calls or parent Task timestamp refresh.
See it in Fieldmotion
CRM1
CRM1 Task editor appends notes with TaskNote_new and reloads TaskNotes_get. The Tasks table loads several discussions with TasksNotes_get.
CRM2
CRM2 Task editor/moduleTasks preloads TaskNote_getRequestedDetails and derives mapped TaskNote update routes for the note field. These mapped notes can contain encoded structured content rather than the CRM1 plain note text.
Related endpoints
TaskNote_getRequestedDetails— Continue the related read/write workflow.TaskNotes_get— Continue the related read/write workflow.TaskNote_new— Append a plain note.