Task discussion notes
Append a plain Task note
/a/TaskNote_new
Insert another discussion note under a Task and stamp the current author.
When to use this endpoint
Use for CRM1-style plain discussion notes; unlike mapped upserts this always inserts a new row.
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.
The handler itself checks only a defined tenant prefix after required parameters; it has no own page-action/private-Task check.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
task_id | Integer-compatible | Yes | Presence required, then integer-converts and must name an existing Task. The SQL existence check does not exclude deleted Tasks. |
note | Text | Yes | Trimmed; blank or PHP-falsy "0" is rejected. No length or structured-content validation beyond storage limits. Null counts as missing. |
Example request
$result = FM_api('TaskNote_new', ['task_id'=>'18','note'=>'Call the customer']);
Example response
{
"ok": 1
}
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: task_id"} | task_id missing/null. |
{"error":"missing or invalid parameter: note"} | note missing/null. |
{"error":"no such task"} | No Task row exists. |
{"error":"empty note"} | Trimmed note is blank/PHP-falsy. |
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.
- Checks required keys before checking tenant DB context. Inserts actor user_id, current server cdate/last_edited, edited_uuid=TaskNote_new and the requested task_id. It returns no new note ID.
Side effects
- Inserts a note only; no explicit field audit, mention detection, email, notifications-service call or parent Task timestamp/cache update. The direct insert does not request task_notes cache invalidation.
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
TaskNotes_get— Continue the related read/write workflow.TaskNote_updateData— Continue the related read/write workflow.