Requisition orders
Link requisition materials to a Job
/a/RequisitionOrder_setLinkToJob
Attach requisition material rows to Job stock and its live allocation state.
When to use this endpoint
Use CRM2’s specialised linkage after saving header/lines. A plain target assignment does not transfer materials; this route rewrites Job stock and can have partial effects.
Authentication and permissions
Authenticate with signed API-key fields or a logged-in CRM session. API keys use their owner’s tenant; session dispatch applies CSRF checks. Office requisition access requires View and Edit on Requisition Order or Requisition Orders. A visible UI control is not sufficient authorization.
Tenant and TeamAccess/legacy department scope apply to headers and to the parent of each line. Deleted parents hide their lines. Scoped users can see their own unlinked requisitions; the legacy department-only rule retains its target-based visibility. There is no additional Requisition feature-entitlement check.
The destination also requires its own View and Edit permission and record scope, checked before material or allocation writes.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive integer | Yes | Existing, non-deleted requisition ID in the authenticated tenant and your record scope. |
jobID | Integer-compatible | Yes | Positive existing non-deleted Job in the caller’s scope, with Job View and Edit permission. |
Example request
$result = FM_api('RequisitionOrder_setLinkToJob', [
'id' => '1042',
'jobID' => '501',
]);Example response
{"ok":1}An exact no-op header setter may include warning:"No Change.". Committed follow-up failures include saved=1 and a warning; inspect saved state before retrying.
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":"permission denied"} | Required office page/action access is absent. |
{"error":"requisition order does not exist"} | The header is missing, deleted or outside the caller’s scope. |
{"error":"Processed requisitions are read-only"} | A material/header edit targets status 2. |
{"error":"Unable to save requisition. Check the saved state before retrying."} | A checked database/audit operation failed; verify saved state before replaying an uncertain request. |
{"error":"Insufficient requisition stock for destination"} | Requested material exceeds available initial and matching destination allocations. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Validates both records and target permissions before writing. Standard requisition lines become Job type 0 and miscellaneous lines type 1 with source "15_
". Blank unfinished lines are ignored. Each line has its own stable linkID, so equal miscellaneous descriptions stay distinct. - Replaces only Job rows from this exact requisition source, preserving unrelated/source-less stock and miscellaneous rows. Resolves current customer-adjusted prices for new standard rows and sums every resulting row into Job stock_cost/price. Miscellaneous unit price follows unit cost.
- Initial requisition containers move to Job container type 7 as awaiting stock; no physical inventory is dispatched. Exact repeated links retain allocation quantities instead of duplicating them. Other destinations, insufficient material or already-dispatched rows tied through oldSource fail before a successful relink.
- autoupdate-job-substatus blank/1 sets Awaiting Stock when requisition material is linked. An explicit disabled setting leaves the existing substatus. Stock-tracking entitlement does not dispatch awaiting material.
- The header target/type/timestamp and Job stock/totals/containers/audit commit together. After commit, Job_syncStockUsedForm(option=1) updates mapped Form stock; a later failure is reported as saved=1 with a warning.
- The header/line changes, aggregate totals and audit are checked in one tenant transaction. A failed write or audit rolls back the operation. Existing caller transactions use savepoints; the caller owns final commit. No request key deduplicates creation.
Side effects
- Atomically writes Job stock/cost/price/substatus, requisition target/timestamp, container allocations and history. After commit invalidates caches and synchronizes mapped Form stock. No physical inventory dispatch.
See it in Fieldmotion
CRM1
No direct caller was found in CRM1 source. Its requisition screen uses the legacy header/line endpoints instead.
CRM2
In CRM2 Requisition details link to Job and Save, or link a requisition from the Job stock widget. Filter for RequisitionOrder_setLinkToJob after Layout_setValue; the widget supplies the selected Job ID.
Related endpoints
RequisitionOrder_setLink— Save only a target reference.RequisitionOrderEntry_save— Save legacy line contents before linking.RequisitionOrderEntry_createData— Create mapped entries/initial containers.