Stock items and catalogue maintenance
Read the legacy stock grid
/a/Stock_getDT
Return positional cells and DataTables counts for the CRM1 catalogue grid.
When to use this endpoint
Use the legacy grid’s filter names; select Stocks_getDataTable for named camelCase projections.
Authentication and permissions
Authenticate with a signed API key or a logged-in CRM session on the account’s routed host. API keys act as their owner; session calls require dispatcher CSRF protection where configured. IDs address the authenticated tenant.
These stock handlers do not add a Stock page-action or CRM2 role check, and the dispatcher has no Stock/Stocks TeamAccess object mapping. CRM2 screen controls are separate from this shared API contract; their roles must not be assumed to apply to CRM1.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
draw / start / length / order | DataTables values | Yes | All four must be present (order may be an empty native array). start/length integer-convert directly; no handler page-size maximum or negative-range normalization. |
order[0][column] / dir | Native sort controls | No | Sort indices: 0 ID,1 name,2 code,3 description,7 supplier,8 cost,9 price,10 nominal,11 tax,12 in_stock. Others sort name. Only dir exactly asc is ascending; every other value chooses descending. |
search[value] | Text | No | Global substring across name,id,supplier,categories,description,meta,code. |
fId / fCategory | Integer-compatible | No | Truthy item ID exact match; nonzero category ID tests the encoded category_ids string. |
fName / fDescription / fNotes / fCode / fSupplier / fLocation | Text | No | Trimmed/lowercased contains filters; location matches whole stock.meta text, not only location tags. |
fIsTriggered | Integer-compatible | No | Nonzero filters in_stock against the numeric threshold before the |email separator in amt_trigger. |
fIsArchived | Integer-compatible | No | Zero/omission selects unarchived; nonzero selects archived. Both exclude deleted stock. |
Example request
$result = FM_api('Stock_getDT', ['draw'=>'1', 'start'=>'0', 'length'=>'25', 'order'=>[['column'=>'1','dir'=>'asc']], 'fIsArchived'=>'0']);
Example response
{
"draw": 1,
"recordsTotal": 1,
"recordsFiltered": 1,
"data": [
[
18,
"Valve",
"VALVE-1",
"Replacement valve",
"",
[
0,
null
],
12.5,
20,
"4000",
20,
8,
2.5,
"5|stock@example.test",
0,
[
"Heating",
{
"Heating": {
"name": "Heating"
}
}
],
"Cabinet A",
""
]
]
}
Application errors can use HTTP 200. Inspect error/warning fields; database numeric values can be strings unless this handler explicitly converts them.
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: draw"} | Required DataTables control is absent/null. |
{"error":"missing or invalid parameter: length"} | Required DataTables control is absent/null. |
{"error":"missing or invalid parameter: order"} | Required DataTables control is absent/null. |
{"error":"missing or invalid parameter: start"} | Required DataTables control is absent/null. |
{"error":"invalid stored location tags"} | A selected item has an unsupported saved tag shape. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- data rows contain 17 cells, in order: ID,name,code,description,notes,[supplierID,supplierName],average_cost,price,nominal_code,tax_rate,in_stock,allocated,amt_trigger,is_archived,[saved categories,category rows keyed by category name],location tags,empty action cell.
- ID/supplierID/archive are integer-converted; cost/price/tax/warehouse/allocated are float-converted. Supplier is a left join to undeleted suppliers. Allocated is SUM(amt) over every container type, including outbound types.
- recordsTotal counts all undeleted stock including archives. recordsFiltered includes filters and the selected archive state. Category rows come from undeleted category IDs and are keyed by name, for example {Heating:{name:Heating}}; duplicate category names collapse to one keyed entry and order is unspecified. No categories produces an empty list.
- Location tags accept saved string or legacy list (presented as newline text), with invalid shapes returning an error. This display conversion does not write metadata.
- Sort-column indices reflect legacy table controls and do not match the packed response-cell indices for later columns. Use the explicit mapping above rather than assuming array index equals sort index.
- The triggered filter compares in_stock against the numeric threshold before the |email separator. Existing archive selection, float balances, sort-index mapping and legacy unbounded paging contract are otherwise retained.
Side effects
- Reads only; unlike Stock_get, does not repair category data.
See it in Fieldmotion
CRM1
Open Stock in CRM1. The legacy grid is Stock_getDT and its editor/inline actions use legacy Stock routes. Inspect the exact function name in the browser Network panel. Open Stock and apply archive/category/minimum-level filters. The browser sends the f-prefixed controls and expects 17 positional cells.
CRM2
The CRM2 main catalogue uses Stocks_getDataTable; no direct current CRM2 Stock_getDT caller was found.
Related endpoints
Stocks_getDataTable— Return named stock rows with mapped filters, paging and optional supplier/allocation summaries.Stock_get— Read the full saved stock row, with selected manufacturing metadata flattened for the legacy editor.Stock_getRequestedDetails— Return projected stock rows with optional supplier and allocation summaries.