Fieldmotion API Getting started

Jobs: lookups and details

Sum a named job-table column

POST /a/Job_getTableColumnSum

Evaluate a main-form sum(TableField.ColumnField) calculation against the job’s saved table rows.

When to use this endpoint

Evaluate a main-form sum(TableField.ColumnField) calculation against the job’s saved table rows.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. These calls use the authenticated account’s data; the handler has no additional job-page, department, assignee or client-admin permission check unless stated below.

Parameters

ParameterTypeRequiredDescription
idInteger stringYesJob ID, converted with intval; the result must be positive. This selects a physical job ID, not an app ID or job reference.
nameStringYesMain-form field name, a dot, then table-column field name. Use field names, not the table form’s display name. The regex only checks for text around a dot; splitting uses the first two segments.

Example request

$sum = FM_api('Job_getTableColumnSum', ['id' => '1042', 'name' => 'Parts.Quantity']);

Example response

{"tableName":"Parts","columnName":"Quantity","sum":3.5}

Errors and unusual responses

ResponseCondition
{"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"}Invalid ID; checked before login.
{"error":"missing or invalid parameter: name"}name is absent or does not contain text on both sides of a dot.
{"error":"job does not exist: 1042"}No active job matches.
{"error":"job form does not exist: 12"}The main form cannot be loaded.
{"error":"Could not find table for field entry \"Parts\"\nIn the Form config, please make sure the calculation uses the Field Name, not the Table Name"}No matching main-form field supplies a table ID through extras.values.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • Finds the table form through the matching main-form field’s extras.values. Matching is exact/case-sensitive in PHP; duplicate field names can leave the last matched table ID.
  • Sums floatval of each present positional cell under columns with the requested name. Missing cells are skipped; nonnumeric strings coerce to zero, and numeric prefixes follow PHP conversion.
  • A missing table definition, missing saved table rows or unknown column returns sum=0, not a not-found error. Zero may encode absence as well as a genuine total.
  • Reads stored values only: it does not evaluate per-cell expressions, update calculated fields or paginate.

See it in Fieldmotion

CRM1

Open a job’s Form containing a calculation with sum(Parts.Quantity). pageJobForm.js sends the extracted field/column pair to Job_getTableColumnSum and caches the returned sum during recalculation.

CRM2

The job Form calculation paths in pageJobForm.js also call Job_getTableColumnSum. Inspect id/name in the request when diagnosing a table calculation.

Related endpoints