Task Index — Find the Right Section Fast
How to use this repo without drowning in it: the numbered docs are the deep manual — most are over 1,000 lines. Don't read a whole doc for one task. Find your task below and open only the linked section. If you're an AI assistant: read
CLAUDE.md, then this index, then just the sections your task needs.
Every task assumes you already have a token and (for Transaction/Interactive) the UI server URL — see Getting a token below.
Doing, not studying? The recipes cookbook has self-contained copy-and-run pages (complete payload + full script + gotchas) for the most common tasks — start there and fall back to the manual sections for depth.
First call of any session
| Task | Where |
|---|---|
| Get a bearer token (v2, credentials in body) | 00 § Method 1: User Credentials |
| Authenticate with a consumer key | 00 § Method 2: Consumer Key |
| Get the UI server URL (Transaction/Interactive base) — 307 redirect gotcha | 00 § UI Server URL |
| Token TTL / reuse across APIs | 00 § Token Lifetime and Reuse |
| Fix "not authorized" (P21 user permissions) | 00 § P21 Permissions |
| Pick which API to use for a task | 01 API Selection Guide (short — read whole) |
Read data (OData)
| Task | Where |
|---|---|
| Query a table or view | 02 § Query Parameters |
| Filter syntax, operators, string functions | 02 § Filter Expressions |
Only active rows (row_status_flag eq 704) |
02 § Active Record Filter |
Traverse relationships (no joins — chain by _uid) |
02 § No Joins |
| Page through large result sets (no nextLink) | 02 § Pagination Helper · 02 § Page Size Guidance |
Date filters (now() is unsupported) |
02 § now() Not Supported |
| New table/column missing from OData | 02 § OData Schema Refresh |
| Table reads fine but is empty/inert (undeployed feature, e.g. zip→rep) | 02 § Undeployed / Unlicensed Windows |
Create / update records (Transaction API)
| Task | Where |
|---|---|
| Payload anatomy (TransactionSet / DataElements / Edits) | 03 § Request Structure |
| Payload rejected / values not landing (shape & type mistakes) | 03 § Payload Anatomy |
| Validate a payload offline before posting (JSON or XML) | scripts/validate_payload.py · 03 § Payload Anatomy |
| Copy-ready payload files (JSON and XML, validator-verified) | examples/payloads/ |
| Send/receive XML instead of JSON | 03 § XML Payloads |
| Get a service's schema, template, defaults | 03 § Endpoints · committed full-field JSON in definitions/ |
Update an existing record (Status "New" + keys; "Existing" is broken) |
03 § Updating an Existing Contract |
| Insert new keyed rows (upsert) + one-tx-per-POST rule | 03 § Upsert Semantics |
Write through disabled columns/tabs (IgnoreDisabled) |
03 § IgnoreDisabled |
| Field order silently changing values | 03 § Field Order Matters |
Labels vs code_no (UseCodeValues, code_p21) |
03 § UseCodeValues |
| Check success properly (HTTP 200 lies; per-tx pass/fail) | 03 § Response Format · 06 § Transaction API Errors |
| Read a record back / verify a write | 03 § Endpoints — /transaction/get |
| Long-running / async transactions | 03 § Async Operations |
| DynaChange rules & popup suppression for the API user | 03 § DynaChange and Popup Handling |
| Run a stored procedure via API | 03 § Stored Procedure Executor |
By record type
| Task | Recipe | Manual |
|---|---|---|
| Create a sales order + gotchas (source_loc_id, dates, DynaChange) | create-sales-order | 03 § Create Order · 03 § Order Service Gotchas |
| Order with an assembly line (explode / spawn prod order) | order-with-assembly | 04 § Sales Order Entry with Assembly Lines |
| Job contract: create, lines, breaks | — | 03 § JobContractPricing Service |
| Job contract: update / add lines / commission costs | update-contract-lines | 03 § Updating an Existing Contract · 03 § Upsert Semantics · 03 § Commission Costs |
| Job contract: bin quantities | edit-contract-bins | 03 § Editing Bin Quantities (Interactive fallback: 04 § Tab Unlock Sequences) |
| Assembly / BOM definition | — | 03 § Assembly Service |
| Item: primary bin / primary supplier at a location | set-primary-bin-supplier | 03 § Item Service |
| Create warehouse bins | create-bins | 03 § BinLocation Service |
| Sales price pages (codes, breaks, field order) | — | 08 SalesPricePage Codes |
| Create a customer (salesrep_id + default_branch gotchas, no zip→rep cascade) | create-customer | 03 § Common Services |
Create a requisition PO (po_type 'R'; disabled po_hdr_po_type; vendor vs supplier) |
create-requisition-po | 03 § Purchase Order Types |
| GL dimensions via API (voucher services carry them; POs don't) | — | 03 § GL Dimensions in the API |
| Customers / vendors / contacts / addresses (simple CRUD) | — | 05 § CRUD Operations |
Read/create sales orders via REST (/api/sales/orders) |
— | 05 § Other REST Endpoint Families |
| Inventory items: read / create / update locations | — | 11 § Reading Items · 11 § Minimum Create Payload · 11 § Updating Existing Location Fields |
| Customer-specific price + availability lookup | — | 11 § Pricing Endpoints |
| User-defined tables (UDT) rows | — | 13 § Insert · 13 § Update · 13 § Delete — update/delete need a row_uid column; 2026.1-created UDTs don't have one |
| UDT delete "succeeds" but nothing is deleted | — | 06 § [0] rows deleted · 14 § entry 7 |
| Bulk-load a UDT from CSV (2026.1+) | — | 13 § Bulk Data API — CSV upload; headerless file silently inserts nothing |
Drive a window (Interactive API)
| Task | Where |
|---|---|
| Session → window → change → save lifecycle | 04 § Session Lifecycle |
| v2 payload shapes (save body is the bare GUID, etc.) | 04 § v1 vs v2 API Differences |
| Find field / tab / datawindow names | 04 § Finding Field Names · 04 § Window Discovery |
Open a window (use ServiceName — Name/Title can 400) · map window→service |
04 § Open Window · 04 § Window→Service Discovery |
| Handle popups / response windows (Status 3, windowopened) | 04 § Response Windows · 04 § Response Window Types |
| Answer a rule-callback dialog ("Item Issues Detected") | 04 § Worked Example |
Fill fields in a popup (TabName: null) |
04 § Response Window Handling (Tabless) |
Buttons / tools (?windowId=, not ?id=) |
04 § Running Tools |
| Unlock a disabled tab | 04 § Tab Unlock Sequences |
| Row selection traps (sync bug, detail-form rebind, row 0) | 04 § Known Issues and Workarounds |
| Key field silently swallowing later edits | 04 § Key Fields Commit the Cursor |
| Verify a save actually persisted | 04 § Verifying Writes |
| PO notepad notes (header vs line) | 04 § PurchaseOrder Notepad Writes |
| Bulk/batch interactive work (session reuse, error recovery) | 09 Batch Processing Patterns |
| Intermittent "Unexpected Response Window" in production | 07 Session Pool Troubleshooting |
Production & manufacturing
| Task | Where |
|---|---|
| Service catalog & schemas (ProductionOrder, TimeEntry, …) | 12 § Available Services |
| Assembly behavior flags (prod-order vs kit vs build-to-stock) | 12 § Assembly Behavior Flags |
| Full runbook: create → print → confirm → complete → ship | recipe: production-order-runbook · 12 § Production Order Lifecycle |
| Pick ticket won't generate (make loc vs stock loc) | 12 § Printing the Pick Ticket · 03 § m_picktickets example |
| Confirm a pick (shell-confirm trap — use Interactive) | 12 § Confirming the Pick |
| Complete / production receipt (+ per-component cost override) | 12 § Completing the Production Order |
| Record labor hours | recipe: record-labor-time · 12 § Recording Labor Hours · 12 § Time Entry Against a Production Order |
| Ship + invoice | 12 § Shipping and Invoicing |
| Inventory write-off / adjustment | recipe: inventory-adjustment · 12 § Inventory Adjustment |
| Why COGS doesn't match the receipt | 12 § Cost Model |
Documents & reports (PDF)
| Task | Where |
|---|---|
Generate any m_* report as PDF |
recipe: generate-pick-ticket-pdf · 03 § PDF Report Generation |
| Discover callable report names (hidden from /services) | 03 § PDF Report Generation (Discovery note) |
| Production pick ticket at a specific location | 03 § m_picktickets example |
| PDFs from print flags on a normal transaction | 03 § PDFs from the /transaction endpoint |
When something breaks
| Task | Where |
|---|---|
| Upgrading P21? What breaks between versions | 14 Breaking Changes — 2026.1 (Accept-header 500, ghost sessions, non-atomic batched changes) · 25.2 (DatawindowName) |
| Which middleware build am I on? | 14 § Reading the middleware version — no version endpoint; it rides the session-create response |
| Error catalog by API | 06 Error Handling (per-API sections) |
| Quick symptom → cause table | 06 § Common Issues Quick Reference |
| Auth failures | 06 § Authentication Errors |
| Intermittent interactive failures under load | 07 Session Pool Troubleshooting |
| What changed in these docs recently | 10 Changelog |
Doc inventory (what each file is)
| Doc | Scope | Size |
|---|---|---|
| 00-Authentication | Tokens (v2/consumer key), permissions, UI server URL | large |
| 01-API-Selection-Guide | Which API for which job | small — read whole |
| 02-OData-API | Read-only queries | large |
| 03-Transaction-API | Stateless create/update + service reference + PDF reports | very large — use anchors |
| 04-Interactive-API | Stateful window driving, popups, traps | very large — use anchors |
| 05-Entity-API | REST CRUD on 4 entities | medium |
| 06-Error-Handling | Errors across all APIs | large |
| 07-Session-Pool-Troubleshooting | One deep-dive: session pool contamination | medium — single topic |
| 08-SalesPricePage-Codes | SalesPricePage field codes/order | medium — single service |
| 09-Batch-Processing-Patterns | Interactive bulk patterns + async client | very large |
| 10-Changelog | Doc change history | small |
| 11-Inventory-REST-API | /api/inventory/parts read/append/update |
large |
| 12-Production-Labor-API | Production services + end-to-end lifecycle | large |
| 13-UDT-Service-API | User-defined table CRUD | large |
| 14-Breaking-Changes | P21 version breaking-change registry (check before upgrading) | small — read whole |
definitions/ |
Full-field service definition JSONs (every DataElement, field, key, label + payload template) | load one file per service |