Requisition orders
Update mapped requisition fields
/a/RequisitionOrder_updateData
Update selected mapped header values while preserving omitted fields.
When to use this endpoint
Use mapped CRM2 names and native picker objects. For a full header plus spreadsheet replacement, use Layout_setValue; independent API calls are independent transactions.
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.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Positive integer | Yes | Creation ignores supplied IDs. UpdateData accepts one existing header; updateField accepts an explicit nonempty selection and saves the whole batch atomically. |
description, attention, instructions, deliveryAddress, notes | Strings | No | Stored text; blank clears. Omitted/null values are skipped. notes is stored text, not a server-authored note action. |
userID / user | Integer / native object | No | Requester ID or {id}. Positive IDs must be active users; -1/0 retain the legacy unassigned convention. Creation defaults to the actor. |
targetID, targetType / target | Integers / native object | No | Type 0 No Link requires ID 0. Types 1 Contract, 2 Customer, 3 Quote, 4 Job, 5 Department, 6 Work Area, 7 User, 8 Vehicle and 9 Asset require an existing permitted target. Scoped roles can use only target families supported by their record policy. Generic linking does not allocate stock. |
status | Integer 0–4 | No | 0 Open, 1 Approved, 2 Processed, 3 Received, 4 Cancelled. Creation requires 0. Approval transitions require Open, respect Disable RO Approve and stamp actor/time. An exact status no-op retains approval metadata. |
deliveryDate | YYYY-MM-DD | No | Exact real ISO date. Blank/invalid dates fail; omitted/null is skipped. |
deliveryNet, deliveryTax | Amounts | No | Finite nonnegative amount up to 99,999,999.99, rounded to two decimal places. The tax amount is explicit; the server does not derive it from a text tax code. |
deliveryTaxcodeID / deliveryTaxcode | String / native object | No | Code label or {id}; blank label allowed. No rate lookup. |
meta, customValues, metaLink | Native JSON value or JSON text / string | No | meta/customValues must decode to an array/object. customValues defaults {} on creation. metaLink writes meta.link. Existing server Workflow metadata is preserved. |
grandTotalNet, grandTotalTax, cDate, lastEdited | Server-calculated/read-only | No | Submitted values are ignored. Header totals come from line aggregates; delivery is separate. Timestamps come from the server. |
approvedByID / approvedBy, dateApproved, poIDs, deleted | Read-only | No | Cannot change these through ordinary mapped writes. Unchanged/null compatibility values may be echoed; approval and lifecycle operations own their metadata. |
noRecord, noRecordCustom | Native or JSON array | No | Optional named history-redaction controls. They hide values rather than eliminating the audit. |
widgetSpreadSheet | Legacy layout metadata | No | Ignored by a direct header update; it does not delete containers or save lines. Layout_setValue owns atomic header/line replacement. |
Example request
$result = FM_api('RequisitionOrder_updateData', [
'id' => '1042',
'description' => 'Updated materials request',
]);Example response
{
"ok": 1,
"oldData": {
"description": "Materials for north site"
}
}Creation returns {ok:1,id:
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. |
Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.
Behaviour and edge cases
- Aliases expand to typed stored fields; native pickers are required, and JSON strings are accepted only for the documented JSON fields/ID lists. Unknown fields are ignored. Omitted/null values do not clear fields; send blank text or the explicit No Link pair where supported.
- New headers are Open with zero line totals, server creation/edit timestamps and the actor as default requester. New IDs are not idempotent. Processed header material edits are rejected. Other ordinary edits preserve existing approval.
- Approval uses the same validation as RequisitionOrder_approve. Eligible status transitions enqueue Workflow in the same transaction when features2.workflow is enabled. The helper does not start a second status transaction that can commit earlier header edits.
- 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.
- Follow-up notifications and mentions run after the owning commit. If a follow-up fails after persistence, the response includes saved=1 and a warning; read the saved object before retrying and do not replay creation.
Side effects
- Writes checked header changes, line-only aggregates, last_edited and history. Status transitions may queue Workflow; notifications, mentions and cache invalidation follow the owning commit. Layout_setValue atomically includes all replacement lines and allocation reconciliation.
See it in Fieldmotion
CRM1
No direct caller was found in CRM1 source. Its requisition screen uses the legacy header/line endpoints instead.
CRM2
Open a Requisition Order in CRM2 and save its configured layout. The browser calls Layout_setValue; that dispatcher invokes this mapped endpoint internally. Filter Network for Layout_setValue and inspect its requisitionOrder fields. A direct endpoint request may therefore be absent from Network.
Related endpoints
RequisitionOrder_getRequestedDetails— Read current mapped values.RequisitionOrder_approve— Stamp actual approval identity/date.RequisitionOrderEntry_createData— Create a mapped line separately.