NetSuite sales order lifecycle · workflow contract

0 · Visual flow 3-path branch · Finance handoff · dunning loopback

idle

1 · Trigger FIRES WHEN…

kind

email_intake

mailboxes

orders@globalfoodsolutions.co
danielle@globalfoodsolutions.co

description

Most customer orders arrive via email at orders@ or danielle@. Team reviews, enters as SO in NetSuite. Other channels (NS UI, portal, EDI 850 manual keying, phone) feed the same downstream branching.

2 · Inputs required

name	required	type / hint
`customer_id`	required	integer · NS customer internal ID
`items`	required	array · item_code, qty, rate, requested_ship_date
`shipping_requirements`	required	object · ship-to, carrier, delivery window
`special_instructions`	optional	string · notes the team must honor
`email_thread_id`	optional	string · trace back to inbound email

3 · Context loaded D1 queries run before fan-out

name

customer

tables

customers

returns

row

SELECT id, entityid, terms, credit_limit, hold_status, service_hold
  FROM customers WHERE id = ?

name

items_inventory

tables

items · inventory_balance

returns

rows

SELECT item_code, itemtype, dropship, quantityavailable, cost
  FROM items LEFT JOIN inventory_balance USING (item_code)
  WHERE item_code IN (?)

name

customer_program

tables

customer_programs

returns

rows

SELECT item_code, override_price, override_terms
  FROM customer_programs
  WHERE customer_id = ? AND status = 'active'

name

credit_limit

tables

customers · transactions

returns

row

SELECT credit_limit,
       (SELECT SUM(amount_remaining) FROM transactions
         WHERE customer=? AND type='Invoice' AND status != 'paid') AS open_ar
  FROM customers WHERE id = ?

name

hold_status

tables

customers

returns

row

SELECT hold_status, service_hold FROM customers WHERE id = ?

4 · Preconditions checked before any fan-out

check	rule	severity
`customer_exists`	`customer_id IN (SELECT id FROM customers)`	block
`all_items_priced`	every item has a resolved price via pricing_master OR customer_programs OR contracts	warn
`customer_not_on_hold`	`customer.hold_status = 'active' AND customer.service_hold = 0`	block

Mike's documented process does not explicitly show a credit gate. under_credit_limit is no longer a precondition. Confirm with Mike whether NS-side enforces this or whether it should be re-added.

5 · HITL gate

Risk level 2 < 3 — no global HITL gate. Individual fan-out steps that are HITL-gated: create_work_orders (Path 2), complete_assembly_build (Path 2), create_purchase_order (Path 3), invoice_customer (Finance), trigger_dunning email send (Finance).

6 · Fan-out targets 17 total · 3-path branching

#1`classify_path` chat_tool STUB auto REAL operator

tool

classify_so_line_paths

description

Classify each so_line into inventory / assembly / dropship. Today operator-driven; auto-classification is a STUB.

#2`fulfill_from_inventory` d1_write PATH 1 REAL

table

inventory_balance

operation

update (reserve_qty)

condition (if)

path=inventory

UPDATE inventory_balance
  SET reserved_qty = reserved_qty + ?
  WHERE item_code = ? AND location_id = ?

#3`create_work_orders` stage_proposed_action PATH 2 REAL

action_type

workorder_create_from_so

entity_type

sales_order

condition (if)

path=assembly

description

Per assembly_line: create WO with parent_so_id linking back to SO. Records linked end-to-end.

#4`complete_assembly_build` chat_tool PATH 2 REAL

tool

complete_assembly_build

condition (if)

path=assembly

description

Production crew executes build; Mike approves at /assembly-build.html. Alternate: if FG already on hand → close WO + fulfill from inventory instead.

#5`create_purchase_order` stage_proposed_action PATH 3 REAL

action_type

purchaseorder_create_from_so

entity_type

sales_order

condition (if)

path=dropship

description

Per dropship_line: create PO with parent_so_id. Records linked end-to-end.

#6`receive_item_receipt` chat_tool PATH 3 REAL

tool

post_item_receipt

condition (if)

path=dropship

description

Vendor ships; Item Receipt closes PO line.

#7`item_fulfillment_complete` d1_write REAL · CONVERGENCE

table

item_fulfillments

operation

insert

description

All 3 paths land here.

INSERT INTO item_fulfillments (so_id, status, shipped_at)
  VALUES (?, 'Shipped', datetime('now'))

#8`notify_finance` hitl_email_draft ★ KEY HANDOFF code verify

tool

propose_email_to_finance

mailbox

finance@globalfoodsolutions.co

template

itemfulfillment_to_finance_alert

description

THE KEY HANDOFF. Automation alert fires to Finance on every Item Fulfillment completion. Documented as concept; NS workflow trigger config needs code-level verification.

#9`finance_review` chat_tool FINANCE REAL

tool

finance_review_fulfillment

description

Finance checks fulfilled qty, pricing, terms, tax handling.

#10`invoice_customer` stage_proposed_action FINANCE REAL

action_type

post_customer_invoice

entity_type

sales_order

description

Finance posts CustInvc using shipped qty.

#11`monitor_payment_terms` flag FINANCE REAL

view

v_customer_ar_aging

field

bucket

description

Track invoice aging bucket (current / 30 / 60 / 90+).

#12`trigger_dunning` workflow_class_invoke FINANCE REAL

workflow_type

ar_aging_action_plan

condition (if)

invoice_overdue

description

Loops at 30 / 60 / 90+ until paid or escalated to service hold.

#13`payment_apply` d1_write FINANCE REAL

table

payment_applications

operation

insert

INSERT INTO payment_applications (payment_id, invoice_id, amount)
  VALUES (?,?,?)

#14`close_so` d1_write REAL

table

transactions

operation

update (status='Closed')

UPDATE transactions SET status='Closed'
  WHERE id=? AND type='SalesOrd'

#15`enter_vendor_bill` stage_proposed_action PATH 3 sidecar REAL

action_type

enter_vendor_bill

entity_type

purchase_order

condition (if)

path=dropship

description

Path 3 sidecar — vendor bill entered against PO.

#16`pay_vendor_bill` stage_proposed_action PATH 3 sidecar REAL

action_type

pay_vendor_bill

entity_type

vendor_bill

condition (if)

path=dropship

description

Path 3 sidecar — paid per vendor terms.

#17`reflexion_write` d1_write REAL

table

reflexion_log

7 · Post actions declared + runner-automatic

id	action	source
`runner_log_run`	INSERT into `workflow_run_log`	runner automatic
`runner_reflexion`	INSERT into `reflexion_log` (tags=`sales_order,3_path`)	runner automatic
`log_run`	INSERT workflow_run_log	declared in contract
`reflexion`	INSERT reflexion_log with tags=sales_order,3_path	declared in contract
`event_completed`	FIRE event `workflow.completed (workflow_type=sales_order_lifecycle)`	declared in contract

8 · Verify checks written to `workflow_verify_results`

name

invoice_created

when_to_run

+24h after run

expected

n >= 1

SELECT COUNT(*) AS n FROM customer_invoices
  WHERE so_id=? AND created_at > datetime('now','-24 hours')

name

ns_so_status_closed

when_to_run

+72h post-payment

expected

status='Closed'

SELECT status FROM transactions WHERE id=? AND type='SalesOrd'

name

customer_payment_applied

when_to_run

+30d (typical Net 30)

expected

n >= 1

SELECT COUNT(*) AS n FROM payment_applications pa
  JOIN customer_invoices ci ON pa.invoice_id=ci.id
  WHERE ci.so_id=?

9 · Retry policy

max_attempts

3

backoff

exponential

base_ms

1000

max_ms

30000

alert_on_final_failure

true

10 · What changes when this workflow runs aggregated side effects

system	table / resource	action	status	source
D1	`inventory_balance`	UPDATE (reserve_qty)	REAL	#2 (Path 1)
D1	`proposed_actions`	INSERT (workorder_create_from_so)	REAL	#3 (Path 2)
NS	`assemblybuild`	INSERT	REAL	#4 (Path 2)
D1	`proposed_actions`	INSERT (purchaseorder_create_from_so)	REAL	#5 (Path 3)
NS	`itemreceipt`	INSERT	REAL	#6 (Path 3)
D1	`item_fulfillments`	INSERT (Shipped)	REAL	#7 convergence
NS Workflow	`finance_alert`	fire (★ key handoff)	verify in code	#8
D1	`proposed_actions`	INSERT (post_customer_invoice)	REAL	#10 (Finance)
Workflow	`ar_aging_action_plan`	invoke (if invoice_overdue)	REAL	#12 (Finance)
D1	`payment_applications`	INSERT	REAL	#13 (Finance)
D1	`transactions (SalesOrd)`	UPDATE status='Closed'	REAL	#14
D1	`proposed_actions`	INSERT (enter_vendor_bill)	REAL	#15 (Path 3 sidecar)
D1	`proposed_actions`	INSERT (pay_vendor_bill)	REAL	#16 (Path 3 sidecar)
D1	`reflexion_log`	INSERT (tags=sales_order,3_path)	REAL	#17
D1	`workflow_run_log`	INSERT (run summary)	REAL	runner automatic
Event	`workflow.completed`	fire	REAL	runner automatic
Event	`order.closed`	fire	REAL	#14 post-close

0 · Visual flow 3-path branch · Finance handoff · dunning loopback

1 · Trigger FIRES WHEN…

2 · Inputs required

3 · Context loaded D1 queries run before fan-out

4 · Preconditions checked before any fan-out

5 · HITL gate

6 · Fan-out targets 17 total · 3-path branching

#1classify_path chat_tool STUB auto REAL operator

#2fulfill_from_inventory d1_write PATH 1 REAL

#3create_work_orders stage_proposed_action PATH 2 REAL

#4complete_assembly_build chat_tool PATH 2 REAL

#5create_purchase_order stage_proposed_action PATH 3 REAL

#6receive_item_receipt chat_tool PATH 3 REAL

#7item_fulfillment_complete d1_write REAL · CONVERGENCE

#8notify_finance hitl_email_draft ★ KEY HANDOFF code verify

#9finance_review chat_tool FINANCE REAL

#10invoice_customer stage_proposed_action FINANCE REAL

#11monitor_payment_terms flag FINANCE REAL

#12trigger_dunning workflow_class_invoke FINANCE REAL

#13payment_apply d1_write FINANCE REAL

#14close_so d1_write REAL

#15enter_vendor_bill stage_proposed_action PATH 3 sidecar REAL

#16pay_vendor_bill stage_proposed_action PATH 3 sidecar REAL

#17reflexion_write d1_write REAL

7 · Post actions declared + runner-automatic

8 · Verify checks written to workflow_verify_results

9 · Retry policy

10 · What changes when this workflow runs aggregated side effects

#1`classify_path` chat_tool STUB auto REAL operator

#2`fulfill_from_inventory` d1_write PATH 1 REAL

#3`create_work_orders` stage_proposed_action PATH 2 REAL

#4`complete_assembly_build` chat_tool PATH 2 REAL

#5`create_purchase_order` stage_proposed_action PATH 3 REAL

#6`receive_item_receipt` chat_tool PATH 3 REAL

#7`item_fulfillment_complete` d1_write REAL · CONVERGENCE

#8`notify_finance` hitl_email_draft ★ KEY HANDOFF code verify

#9`finance_review` chat_tool FINANCE REAL

#10`invoice_customer` stage_proposed_action FINANCE REAL

#11`monitor_payment_terms` flag FINANCE REAL

#12`trigger_dunning` workflow_class_invoke FINANCE REAL

#13`payment_apply` d1_write FINANCE REAL

#14`close_so` d1_write REAL

#15`enter_vendor_bill` stage_proposed_action PATH 3 sidecar REAL

#16`pay_vendor_bill` stage_proposed_action PATH 3 sidecar REAL

#17`reflexion_write` d1_write REAL

8 · Verify checks written to `workflow_verify_results`