Jobs: field and bulk edits
Change job mileage
/a/Job_setMileage
Store a distance quantity and refresh the job’s derived cost and price fields.
When to use this endpoint
Store a distance quantity and refresh the job’s derived cost and price fields.
Read the target job first with Jobs_getSome to obtain the current values and confirm the IDs belong to the intended account.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. The request uses the authenticated account’s job IDs, not mobile app IDs.
The legacy userdata.permissions bit 128 blocks editing with No permission to edit; this handler does not exempt client administrators from that bit. It does not add an assignee/department scope.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Integer string | Yes | Physical job ID in the authenticated account, converted with intval; must be positive. |
value | Number/string | Yes | Required present value converted with floatval. Zero is allowed, and negative/nonnumeric values are not explicitly rejected. The account’s distance unit is not converted here. |
Example request
$result = FM_api('Job_setMileage', ['id'=>'1042', 'value'=>'12.3']);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"} | id is absent or converts to a nonpositive integer. |
{"error":"No permission to edit"} | The legacy edit restriction bit is set. |
{"error":"no value provided"} | value is absent or null. |
{"error":"job does not exist"} | The active ID lookup fails or finds no row. |
{"error":"Unable to save job"} | The primary database write failed. History and dependent effects are not performed for that failed save. |
{"ok":1,"warning":"Job saved, but cost recalculation failed"} | The field was saved but the cost helper returned an error. Inspect the job’s derived costs before retrying. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Requires an active job. No no-change shortcut is applied.
- Cost recalculation uses current user wage and vehicle cost_per_distance, work-day-start/end, overtime-multiplier and travel-is-labour-cost, and the configured exclusions for stock tables. It is not a distance-unit conversion or an accounting-system write.
- The primary UPDATE is checked before history and dependent effects. There is no transaction combining this field write with later cross-object effects; inspect committed-success warnings before retrying.
Side effects
- Writes last_edited and edited_uuid with the changed fields and invalidates the meetings cache.
- Records a job history entry. No mail is sent directly by this setter.
- Calls Job_updateCosts after the checked field write; a returned calculation error produces committed success with a warning. That helper can recalculate labour/overtime, mileage, stock, rate and miscellaneous costs; backfill resource costs/prices; choose the user’s default vehicle; and call Job_updatePrices. Pricing can update price_net/price and, when autoupdate-job-value=1, meta.job_value. This is broader than only the edited input.
See it in Fieldmotion
CRM1
No direct CRM1 caller was found in the canonical/legacy route search. This is a focused API setter; other edit flows need not use it.
CRM2
No direct CRM2 caller was found in the canonical/legacy route search. CRM2’s layout-driven updates are a separate contract.
Related endpoints
Job_setVehicleIdchanges the vehicle used for mileage cost calculation.Job_getTimeAndCostsreads the resulting costs and time fields.Jobs_getSomereads selected job records before editing and verifies the stored result afterward.