Read the mapped goods-return table

When to use this endpoint

Use for CRM2’s configurable goods-return table. Unlike GoodsReturned_getDT, rows are mapped objects and do not include supplier names or received/PO dates.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session CSRF and account/IP restrictions still apply. These handlers add no goods-return, finance, department, owner or page-role permission check.

Records belong to the authenticated tenant. CRM1 shows this workflow when the employer features bit 262144 is enabled; CRM2 uses features2.goodsReturnedNotes. These are UI gates, not checks performed by these handlers.

Parameters

Parameter	Type	Required	Description
`fields`	Native array	Yes	Mapped header aliases to project. id is added automatically; unknown aliases are skipped. Do not pass JSON text. Aliases: id, cDate, lastEdited, supplierID, grnID, notes, totalNet, deliveryNet, deliveryTaxCode, deliverTax, customValues.
`isTable`	Integer	No	Default table mode; intval 0 selects non-table mode.
`start / length / draw`	Integer	No	Table mode: offset 0, size 10, draw 0. Values are integer-converted without bounds checks; -1 is not a supported all-rows size.
`limit`	Integer	No	Non-table mode only: a positive number caps returned rows; zero/omitted leaves the query unbounded.
`orderBy / orderDesc`	String	No	Explicit mapped table sort when both supplied. orderDesc accepts asc/desc only, case-normalized; unknown mapped orderBy resolves the first valid projected field.
`order`	Native array	No	Table-mode first DataTables entry: column is interpreted as projected-field index minus one, clamped to 0; exact desc selects descending. Without explicit ordering, first valid projected field is ascending.
`Mapped aliases`	Scalar or native array	No	ANDed column filters. Quoted scalar values use case-insensitive substring matching; quoted arrays use exact membership. Numeric scalars use intval (even decimal aliases); arrays use typed numeric conversion. This differs from getLayoutDetails text equality.
`searchValue / searchField`	String / alias or native array	No	Lowercased trimmed substring search. searchField defaults to ["All"]; restrict it to header aliases as needed. This helper does not read search.value. No joined supplier-name search.
`referenceDate`	String	No	Mapped alias used for date/hour filtering, normally cDate or lastEdited. An unknown alias disables those filters. Non-table mode orders this field ascending; otherwise non-table results are unordered.
`dateFrom / dateTo`	Integer day offsets	No	Both required to filter: days relative to today in setting timezone, default UTC. Bounds run from 00:00:00 to 23:59:59. Not absolute date strings.
`offsetFrom / offsetTo`	Native objects	No	Each accepts hour and minute for date bounds. Hour values are negated before application; minute values are added. offsetFrom.hour also shifts the hourly filter.
`timeRangeFrom / timeRangeTo`	Integer hours	No	With referenceDate, timeRangeFrom enables the inclusive hourly range; timeRangeTo alone is ignored. Defaults 0/23, reversed values are swapped. SQL converts from GMT to the tenant timezone; this path’s fallback is Europe/London. No range validation.
`groupBy`	Native array	No	Known mapped aliases grouped in SQL. Counts still count underlying matching records, not groups. Non-aggregated projected fields can be rejected by database grouping rules.
`advanceSearch`	Native array	No	Native structured conditions: exact mapped id/column, allowlisted condition, scalar/scalar-list value, optional AND/OR andOr and ( or ) special. Raw where is rejected.

Example request

FM_api('GoodsReturned_getDataTable', ['fields'=>['id','grnID','notes','cDate'], 'start'=>0, 'length'=>25, 'draw'=>1]);

Example response

{"data":[{"id":"642","grnID":"531","notes":"Damaged packaging","cDate":"2026-10-07 10:30:00"}],"draw":1,"recordsTotal":"1","recordsFiltered":"1"}

Table mode returns data plus draw/recordsTotal/recordsFiltered. Non-table mode returns only {"data":[...]}. Header fields do not have composite sort-name lookups; database scalar/JSON-text types are retained.

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: fields"}`	fields absent.
`{"error":"error in database query"}`	The row query fails, including invalid paging, ordering or grouping.
`{"error":"unsupported raw advanced search"}`	A rule contains where instead of an allowlisted mapped structured condition.
`{"error":"missing or invalid parameter: orderDesc"}`	Direction is not asc/desc.
`{"error":"missing or invalid parameter: fields"}`	fields must be a native string 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

Total count is for all headers, filtered count applies predicates/joins but not LIMIT or GROUP BY. Missing joined supplier information must be fetched separately.
No stable ID tiebreaker or stablePages mode is enabled by this wrapper. Paging over non-unique sorts can shift rows.
No header or related-object soft-delete filter is added for this table. Data reads never recalculate stock or totals. Date-offset and hourly filters have different empty-timezone fallbacks as described above.
Native filter shapes and structured advanced-search/order controls are validated before the helper executes. Raw SQL is not supported.

Side effects

Read only; timezone lookups may populate the shared settings cache.

See it in Fieldmotion

CRM1

CRM1 uses GoodsReturned_getDT, which has a distinct tuple response and absolute-date filter syntax.

CRM2

pageGoodsReturned configures the goodReturned/GoodsReturned table pair. The shared mapped table resolves its request to GoodsReturned_getDataTable with native fields and layout-specific search/order options.