Stock catalog fields and lookups
Save stock location tags
/a/Stock_setLocationTags
Save stock location tags with checked history and stock synchronization metadata.
When to use this endpoint
Use for the stock tag textarea. Send newline-separated text for UI compatibility; tags are descriptive and do not relocate physical stock.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. This handler requires both a user identity and tenant context; it adds no stock-page, finance or administrator permission check.
All queries use the authenticated tenant. API signing and session CSRF checks still apply; see Getting started.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer-compatible string | Yes | Stock ID converted with intval; must be at least 1. |
val | String or native list of strings | Yes | Required non-null value. Text is preserved; native string lists are joined with newline separators. Nested arrays, numeric/object values and non-list arrays are rejected. Blank string or empty list clears to empty text. |
Example request
$result = FM_api('Stock_setLocationTags', ['id'=>'1042', 'val'=>"Cabinet A\nShelf 2"]);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 or invalid parameter: id"} | Missing/nonpositive id. |
{"error":"missing parameter: val"} | val absent/null. |
{"error":"stock catalog write failed"} | A primary write or required history insert fails; the transaction rolls back. |
{"error":"stock catalog read failed"} | A checked read fails; a normalization or write transaction is rolled back. |
{"error":"stock catalog transaction failed"} | Transaction start or commit fails; no success is returned. |
{"error":"stock catalog operation failed"} | Unexpected database/runtime failure during the transaction. |
{"error":"missing or invalid parameter: val"} | Unsupported val type or non-string list member. |
{"error":"Stock item does not exist"} | Target is missing/deleted. |
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 a non-deleted stock row and preserves unrelated keys from decoded metadata. Malformed/non-array metadata is replaced by a fresh property map; archived stock remains eligible.
- Stores UI-compatible text: strings are unchanged, native string lists are newline-joined. No sorting, trim, tag deduplication or tag-specific tenant setting.
- An unchanged stored text value returns ok without touching timestamps/history/events. Saving equivalent text over a legacy stored array converts its representation and counts as a change.
- Checked metadata write, server last_edited/edited_uuid and location_tags history commit together. Configured Stock_edit runs only after commit.
- No direct mobile caller was found in the current app JavaScript or
m/wwwintermediary. The app receives stock throughsyncDownloads, which selects non-deleted stock by edit timestamp; these calls are not the app synchronization protocol.
Side effects
- On change, writes meta, server last_edited and edited_uuid=Stock_setLocationTags, plus checked location_tags history, and invalidates stocks cache.
- Runs Stock_edit after commit. No physical stock quantities or container/location transaction; synchronize the mobile app to receive the edit.
See it in Fieldmotion
CRM1
On Stock, click the location/tags cell and change the textarea. It sends the string as val after Stock_getLocationTags loads it.
CRM2
On Stocks, click Tags and change its textarea. CRM2 sends this exact endpoint with id and newline string val; it starts from the mapped table’s meta rather than a getter call.
Related endpoints
Stock_getLocationTagsreads back the stored property and type.