Worksheets Workflow

1. Executive Summary

Purpose

The worksheets workflow is the central cash application process in Client Processing. When a buyer's payment arrives at a UTA bank account and is captured as a cash receipt, a worksheet is the working document where that cash is allocated against specific receivables (billing item details), on-account client ledger entries, and outbound payment items. Every dollar that flows through the system must pass through a worksheet before it can post to the general ledger as UTA revenue (REV) or leave the building as an outbound bank payment to the client and their party (PAY). The worksheet enforces segregation of duties through a strict multi-step lifecycle: a Cash Manager applies cash, a Cash Processor creates settlements, a Settlement Approver approves and dispatches payment items.

Scope

Covered:

Creating a worksheet from a cash receipt split
Searching for and adding receivables (billing item details) to the worksheet
Entering cash application amounts for REV and PAY detail lines
Adding deductions at the application level (tax withholding, bank charges, etc.)
Adding on-account client ledger entries when cash cannot be matched to a specific receivable
Adding passthrough and loan payout records directly
Status transitions: Draft → Applied → Settled → Approved → Returned
Reverse transitions (reject): Settled → Applied, Applied → Draft
The three-document return process (original sealed, reversal worksheet auto-created, replacement draft created)
Worksheet queue management: viewing, filtering, bulk approving, and bulk rejecting settled worksheets

Not covered (documented separately):

Settlement creation and management — see Settlements Workflow
Cash receipt and split lifecycle — see Cash Receipts Workflow
Cash matching and reference tagging — see Cash Matching Workflow
Outbound payment bank transmission — see Payments Workflow
Write-off recovery — see Write-Offs Workflow

Key Objectives

Ensure every dollar received from a buyer is explicitly allocated to UTA's revenue (REV) and/or to the client's payout (PAY) before any GL posting or bank transmission occurs.
Enforce role-based segregation of duties so that the same user cannot apply, settle, and approve a worksheet.
Provide a complete, immutable audit trail: approved worksheets are never edited in-place; corrections always produce a reversal worksheet and a new replacement draft.
Prevent premature bank transmission by only unlocking payment items for pickup after the Settlement Approver's final approval.

2. Process Overview

mermaid

flowchart TD
    A[Cash Receipt Split exists] --> B[Create Worksheet\nCash Manager]
    B --> C[Draft status - D]
    C --> D[Add Receivables\nSearch and apply REV + PAY amounts]
    D --> E[Add Deductions\nOptional tax / bank charges]
    E --> F[Add Client Ledger\nOptional on-account entries]
    F --> G[Add Payouts\nOptional passthrough / loan items]
    G --> H{Apply Worksheet\nCash Manager}
    H -->|Validation passes| I[Applied status - P\nREV staged for GL posting]
    H -->|Reject Applied| C
    I --> J[Cash Processor creates\nSettlements for PAY applications]
    J --> K{Settle Worksheet\nCash Processor}
    K -->|All PAY have settlements| L[Settled status - T]
    K -->|Reject Settled| I
    L --> M{Approve Worksheet\nSettlement Approver}
    M -->|Approved| N[Approved status - A\nPayment items created\nReady for bank]
    M -->|Reject Settled| I
    N --> O{Return Worksheet?\nSettlement Approver}
    O -->|Yes - provide reason| P[Three documents produced]
    P --> Q[Original sealed as Returned - R]
    P --> R[Reversal worksheet auto-created\nnegative entries for ALL items]
    P --> S[Replacement draft created\nonly LOCKED items pre-populated]
    S --> D
    O -->|No| T[Worksheet complete\nPayments transmit to bank]

Walkthrough

Create Worksheet — A Cash Manager opens a cash receipt split that has no active worksheet and clicks "Create Worksheet." The system validates the split, checks the parent receipt is not voided or posted, confirms no other active worksheet exists for this split, and locks the receipt to the user. A new worksheet record is created in Draft (D) status.
Add Receivables — In Draft status, the user searches for billing items using client, deal, buyer, department, or payment term reference filters. Selected billing items display their REV and PAY detail lines. The user enters the dollar amounts to apply to each detail. Tax deduction badges appear automatically when withholding or VAT is calculated for the billing item's party. The user can also trigger the Auto-Apply function to fill amounts at the billing item's outstanding balance.
Add Deductions (Optional) — For each receivable row, the user may open the Deductions dialog to record application-level deductions (US NRA withholding, UK FEU withholding, UK VAT, bank charges, discounts, direct payments, etc.). Suggested deductions are pre-populated from the tax engine when applicable.
Add Client Ledger Entries (Optional) — If cash cannot be matched to a specific receivable, the user adds an on-account entry by selecting an existing client ledger item or creating a new one. Client ledger entries post to GL at Apply time.
Add Payout Records (Optional) — The user may create passthrough (type P), loan (type L), or VAT pass-through (type V) payout records directly on the worksheet without going through the settlement process.
Apply Worksheet — The Cash Manager clicks Apply. The system checks that at least one application exists. The worksheet moves to Applied (P). posting_status_cd is set to U (Unposted) on the worksheet, marking REV applications and client ledger entries as ready for GL pickup.
Reject from Applied (if needed) — A Cash Processor can move the worksheet back to Draft (D) by clicking Reject. This clears the apply timestamps and posting status so cash applications can be corrected.
Create Settlements — In Applied status, a Cash Processor selects PAY receivable rows using checkboxes and clicks "Create Settlement." The settlement sheet opens where the processor specifies how the PAY amount is divided among the deal parties (artist, manager, lawyer, etc.). Saving a settlement auto-creates corresponding payout records of type S.
Settle Worksheet — Once all PAY applications have linked settlements, the Cash Processor clicks Settle. The worksheet moves to Settled (T). All linked settlements are also updated to Settled status. The Settle button is disabled until all PAY applications have a participant_settlement_id.
Reject from Settled (if needed) — A Settlement Approver can move the worksheet back to Applied (P) by clicking Reject from the Settled tab. Settlement statuses revert to Draft so they can be edited.
Approve Worksheet — The Settlement Approver reviews the worksheet and settlements in the Worksheet Queue. They click Approve (individually or in bulk). The worksheet moves to Approved (A). Payment items are created from all cash_receipt_payout records. do_not_send_ind is cleared on unlocked items so the bank transmission job picks them up.
Return Worksheet (if needed) — If an approved worksheet must be corrected (e.g., wrong amount, wrong party), the Settlement Approver clicks "Reopen Worksheet" and provides a return reason. Three documents are produced: the original is sealed as Returned (R), a reversal worksheet is auto-created with negative entries for all items, and a replacement draft is created with only locked (sent-to-bank) items pre-populated as read-only. Users add fresh applications manually to the replacement draft.

3. Business Rules

3.1 One Active Worksheet Per Split

Business rule: Each cash receipt split may have at most one active worksheet at any time. A worksheet is active when cash_receipt_worksheet.current_item_ind = true. If a worksheet already exists for a split, a new one cannot be created until the existing one is returned or deleted.

Foundation reference: Validation — Worksheet Creation

Workflow context: The "Create Worksheet" button on the split is hidden or disabled when a record with current_item_ind = true already exists for that split.

3.2 Receipt Must Not Be Voided or Posted

Business rule: A worksheet cannot be created for a cash receipt that has been voided (cash_receipt.posting_status_cd = 'V') or posted (cash_receipt.posting_status_cd = 'P'). Only Unposted receipts are eligible for worksheet creation.

Foundation reference: Validation — Receipt Eligibility

3.3 At Least One Application Required to Apply

Business rule: A worksheet cannot transition from Draft (D) to Applied (P) unless at least one record exists across cash_receipt_application, cash_receipt_client_ledger, or cash_receipt_payout. An empty worksheet cannot be applied.

Foundation reference: Apply Transition — D to P

Workflow context: The Apply button is disabled when the worksheet has no applications. Once any application is added, the Apply button becomes enabled for users with canApplyWorksheet = true.

3.4 Partial Application Is Allowed

Business rule: The worksheet's unapplied balance does not need to equal zero for any status transition. Cash can be applied to only a portion of a split, and the remaining balance can be transferred to another split after approval.

Foundation reference: Apply Transition — Partial Application

Workflow context: The balance display in the worksheet header always shows the remaining unallocated amount. A non-zero remaining balance does not block Apply, Settle, or Approve.

3.5 All PAY Applications Must Have Settlements Before Settling

Business rule: A worksheet cannot transition from Applied (P) to Settled (T) if any PAY-type application (where billing_item_detail.billing_item_detail_type_cd = 'PAY' and cash_receipt_application.cash_receipt_amt_applied > 0) has a null cash_receipt_application.participant_settlement_id.

Foundation reference: Settle Transition — P to T

Workflow context: The Settle button is disabled with the tooltip "Create settlements for all PAY applications before settling" when hasUnsettledPayApplications = true. The Receivables table highlights unsettled PAY rows so the user can identify which items still need settlements.

3.6 Settlement Total Must Equal PAY Applied

Business rule: The sum of all participant_settlement_item.participant_settlement_commission_amt entries for a settlement must equal the total PAY cash_receipt_application.cash_receipt_amt_applied for the associated applications, within a tolerance of 0.01.

Foundation reference: Settlement Save Validation

Workflow context: The settlement dialog shows a running total and a mismatch error message. The Save button is disabled until the settlement items sum matches the PAY amount selected.

3.7 Worksheets Never Move Backward — Corrections Require Return

Business rule: No worksheet transitions backward through the lifecycle from Approved. An Approved worksheet cannot become Draft again. Corrections to an Approved worksheet require the Return process, which seals the original, auto-creates a reversal worksheet, and creates a new replacement draft.

Foundation reference: Return/Reopen Transition — A to R

IMPORTANT

The reject actions (Settled → Applied, Applied → Draft) are pre-approval step-back operations available while the workflow is still in progress. They do not generate reversal documents and are distinct from Return. Return is only available from Approved status and always produces three documents.

3.8 Replacement Draft Contains Only Locked Items

Business rule: When a worksheet is returned, the replacement draft is pre-populated only with applications that are locked — those where the associated payment item's payment_item.payment_execution_status_cd is PROCESSING, SENT, ACKNOWLEDGED, or PAID. Unlocked applications (payments not yet sent to the bank) are not copied to the replacement draft. Users must add fresh applications manually to avoid duplicate accumulation across successive returns.

Foundation reference: Payment Item Locking Rules

Workflow context: Locked applications appear as read-only rows in the replacement draft with a lock icon and cannot be edited or removed. Unlocked applications must be re-entered from scratch.

3.9 REV Always Reversible; Locked PAY Cannot Be Reversed

Business rule: REV applications are always reversible because the money stays in UTA's accounts. PAY applications can only be reversed if the associated payment has not been sent to the bank. Once payment_item.payment_execution_status_cd is SENT or beyond, the PAY application, its settlement, and its payment are locked and cannot be reversed. The reversal worksheet auto-generated on return always contains negative entries for ALL items (including locked), but locked PAY reversals do not post to GL.

Foundation reference: What Can and Cannot Be Reversed

3.10 GL Posting Timing Differs for REV and PAY

Business rule: REV applications and client ledger entries are staged for GL posting when the worksheet moves from Draft to Applied (cash_receipt_worksheet.posting_status_cd set to 'U'). PAY applications do not post to GL at Apply time. PAY posts to GL only after the bank confirms the outbound payment (payment_item.payment_execution_status_cd = 'ACKNOWLEDGED' or 'PAID').

Foundation reference: GL Posting — Key Integration Points

3.11 Bilateral Lock Rule

Business rule: When any payment item in a settlement is locked (PROCESSING, SENT, ACKNOWLEDGED, or PAID), the entire settlement locks — all settlement items, their associated PAY applications, and the paired REV applications are locked together. A locked PAY application also locks its corresponding REV application within the same settlement.

Foundation reference: Bilateral Lock Rule

Workflow context: On a returned worksheet, locked REV rows appear alongside locked PAY rows as read-only context. Users cannot edit or delete either.

3.12 Write-Off Worksheets Cannot Be Returned

Business rule: Worksheets associated with a write-off receipt (cash_receipt.receipt_type_cd = 'WRITE_OFF') cannot be returned through the standard reopen process. Write-off recovery uses a separate workflow.

Foundation reference: Return/Reopen Preconditions

Workflow context: The "Reopen Worksheet" button is hidden for write-off worksheets (isWriteOff = true). Write-off worksheets also skip the settlement step — they are applied directly to written-off REV receivables without requiring PAY settlements.

3.13 Receipt Lock Acquired on Worksheet Creation

Business rule: When a worksheet is created, cash_receipt.locked_by_user_id is set to the creating user's ID. This prevents concurrent worksheet creation by another user. The lock is released when the worksheet is approved.

Foundation reference: Create Worksheet — Step 5

Workflow context: If another user holds the lock, the "Create Worksheet" action fails with an error identifying the user holding the lock. The lock is also released when the user navigates away from the worksheet.

3.14 Same Billing Item Detail May Appear Multiple Times on One Worksheet

Business rule: A single billing_item_detail_id can appear multiple times on the same worksheet as separate cash_receipt_application records. This supports incremental application events, adjustments, and credits. Cross-worksheet exclusivity still applies: an active application for a detail should not exist on a different active (non-Approved, non-Returned) worksheet.

Foundation reference: cash_receipt_application — Important Note

4. Data Access & Operations References

4.1 Queries Used

Operation	Foundation Doc	Purpose in This Workflow
`getWorksheetById`	Get Worksheet by ID	Retrieve the worksheet header record by primary key
`getWorksheetByIdWithReceipt`	Get Worksheet by ID with Receipt Context	Load the full worksheet context including split amount, receipt metadata, bank account, and lifecycle user display names for the Worksheet Detail screen
`getCurrentWorksheetByCashReceiptId`	Get Current Worksheet by Cash Receipt ID	Navigate from a cash receipt to its current active worksheet
`getWorksheetApplications`	Get Applications for Worksheet	Load all `cash_receipt_application` records with billing item detail and billing item context for the Receivables table
`getWorksheetApplicationsUnified`	Get Unified Applications	Load receivable applications, client ledger applications, and payment payouts together for balance calculation
`getClientLedgerApplicationsByWorksheetId`	Get Client Ledger Applications	Load all `cash_receipt_client_ledger` records for the Client Ledger section
`getPaymentItemPayoutsByWorksheetId`	Get Payment Payouts	Load all `cash_receipt_payout` records for the Payments section
`searchReceivables`	Search Receivables	Find billing item details matching user-entered search criteria (client, deal, buyer, department, payment term ref, etc.) for the Add Receivables dialog
`getWorksheetsForQueue`	Get Worksheets for Queue	Load all active worksheets by status for the Worksheet Queue, including application summaries, settlement summaries, and document counts
`getWorksheetStatusCounts`	Get Worksheet Status Counts	Populate the status tab count badges in the Worksheet Queue header
`getSettledWorksheetsWithSettlements`	Get Settled Worksheets with Settlements	Load the settlement-first hierarchical view for the Settled tab in the Worksheet Queue
`getSettlementsByWorksheetId`	Get Settlements by Worksheet ID	Load linked settlements per billing item for the settlement status indicator on the Receivables table
`getMatchReferencesForSplit`	TODO: Document in foundation/queries/cash-receipts.md	Load `cash_receipt_reference` records for the worksheet's split to pre-filter the Search Receivables dialog and populate client IDs for Client Ledger suggestions

4.2 Procedures Used

Operation	Foundation Doc	Trigger in This Workflow
`createWorksheet`	Create Worksheet	User clicks "Create Worksheet" on a cash receipt split
`getOrCreateWorksheet`	Get or Create Worksheet	User opens a cash receipt that auto-opens its current worksheet
`addApplication`	Add Receivable Application	User adds a billing item from the Add Receivables dialog or Auto-Apply
`updateApplication`	Update Receivable Application	User edits the REV or PAY amount on a saved receivable row
`removeApplication`	Remove Receivable Application	User clicks delete on a saved receivable row
`addReceivableImmediate`	Add Receivable Immediate	User confirms the Add Receivables dialog — creates REV and PAY applications atomically
`addClientLedgerApplication`	Add Client Ledger Application	User adds an existing client ledger item to the worksheet
`updateClientLedgerApplication`	Update Client Ledger Application	User edits the amount on a saved client ledger row
`deleteClientLedgerApplication`	Delete Client Ledger Application	User removes a client ledger row
`createOnAccountClientLedger`	Create On-Account Client Ledger	User fills the "Create On-Account" form — creates a new `client_ledger` (type `OA`) and a linked `cash_receipt_client_ledger` application atomically
`createPayoutOnly`	Create Payout	User adds a passthrough, loan, or VAT pass-through payout record directly
`updatePayout`	Update Payout	User edits a payout amount or toggles the Do Not Send flag
`deletePayout`	Delete Payout	User removes a payout record
`saveDeductions`	Save Application Deductions	User saves the Deductions dialog for a receivable application
`applyWorksheet`	Apply Worksheet — D to P	User clicks Apply
`settleWorksheet`	Settle Worksheet — P to T	User clicks Settle
`approveWorksheet`	Approve Worksheet — T to A	User clicks Approve (individual or bulk)
`reopenWorksheet`	Return/Reopen Worksheet — A to R	User clicks Reopen Worksheet and provides a return reason
`rejectWorksheetFromApplied`	Reject from Applied — P to D	User clicks Reject from Applied status
`rejectWorksheetFromSettled`	Reject from Settled — T to P	User clicks Reject from Settled status or bulk-rejects from the Worksheet Queue
`saveSettlement`	Save Settlement	User saves the Settlement Sheet — settlement record and payouts (type `S`) created atomically
`deleteSettlement`	Delete Settlement	User deletes a settlement — linked payouts voided, PAY application unlinked
`bulkApproveWorksheets`	Bulk Approve Worksheets	Settlement Approver selects multiple Settled worksheets and bulk approves from the Worksheet Queue
`bulkRejectWorksheets`	Bulk Reject Worksheets	Settlement Approver bulk-rejects Settled worksheets back to Applied from the Worksheet Queue

5.1 Create Worksheet

Preconditions:

User has CASH_MANAGER or IT role.
The target cash_receipt_split exists.
cash_receipt.posting_status_cd is neither 'V' (Voided) nor 'P' (Posted).
No active worksheet (current_item_ind = true) exists for the split.
cash_receipt.locked_by_user_id is null or matches the current user.

Procedure reference: Create Worksheet

Steps:

User navigates to a cash receipt's split and sees no active worksheet exists.
User clicks "Create Worksheet."
System validates all preconditions, locks the receipt, and inserts a new cash_receipt_worksheet in Draft (D) status.
User is navigated to the Worksheet Detail screen.

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'D'
cash_receipt_worksheet.current_item_ind = true
cash_receipt.locked_by_user_id = current user's ID

UI trigger: "Create Worksheet" button on the split detail. Visible when no active worksheet exists for the split. Enabled when the parent receipt is not voided.

5.2 Add Receivables (Search and Apply)

Preconditions:

Worksheet cash_receipt_worksheet_status_cd = 'D' and is not read-only.
User has CASH_MANAGER or IT role.

Procedure reference: Add Receivable Application

Steps:

User clicks "Add Receivables" to open the Add Receivables dialog, or "Search" to open the full Search Receivables sheet.
User enters search criteria (client, deal, buyer, department, payment term reference). Split-level match references from Cash Matching pre-populate the filters.
System returns matching billing items with their outstanding REV and PAY balances.
User selects one or more items and confirms. REV and PAY amounts default to the item's outstanding balance.
System creates cash_receipt_application records for each selected REV and PAY detail and adds them to the Receivables table.

Postconditions:

New cash_receipt_application records exist for each added billing item detail with cash_receipt_amt_applied set to the user-entered or default amount.

UI trigger: "Add Receivables" button in the Receivables section header. Visible when cash_receipt_worksheet_status_cd = 'D'. Enabled when worksheet is not read-only.

5.3 Edit Application Amount

Preconditions:

Worksheet is in Draft (D) or Applied (P) status.
The application is not locked (associated payment_item.payment_execution_status_cd is not PROCESSING, SENT, ACKNOWLEDGED, or PAID).

Procedure reference: Update Receivable Application

Steps:

User clicks the amount cell on a receivable row to make it editable.
User enters the new amount.
User saves (via Save All or focus loss). System updates cash_receipt_application.cash_receipt_amt_applied.

Postconditions:

cash_receipt_application.cash_receipt_amt_applied updated to the new value.
Worksheet balance recalculated in the header.

UI trigger: Inline editable number field on each receivable row in the REV and PAY amount columns. Editable when the worksheet is not read-only and the application is not locked.

5.4 Add Application Deduction

Preconditions:

Worksheet cash_receipt_worksheet_status_cd = 'D'.
A cash_receipt_application record exists for the billing item detail.

Procedure reference: Save Application Deductions

Steps:

User clicks the deduction badge or "Add Deduction" option in the row action menu.
The Deductions dialog opens, pre-populated with suggested deductions from the tax engine (US NRA withholding, UK FEU withholding, UK VAT) where applicable.
User reviews and adjusts deduction amounts and types (billing_item_deduction_type_cd).
User clicks Save. System creates or updates cash_receipt_application_deduction records linked to the application.

Postconditions:

cash_receipt_application_deduction records created with the specified billing_item_deduction_type_cd and deduction_amt_applied.
Tax badges on the receivable row reflect the saved deductions.

UI trigger: Deduction badge icon on each receivable row (visible when deductions exist). "Add Deduction" option in the row action menu. Both visible in Draft status when the row is not locked.

5.5 Add On-Account Client Ledger Entry

Preconditions:

Worksheet cash_receipt_worksheet_status_cd = 'D' and is not read-only.
Client context is available via match references (cash_receipt_reference with type_cd = 'CLIENT_ID') or from receivable applications.

Procedure reference: Create On-Account Client Ledger

Steps:

User clicks "Create On-Account" in the Client Ledger section.
User fills the form: client, optional deal/buyer/entity/department, and a descriptive name.
User clicks Save. System creates a new client_ledger (type OA, status C, client_ledger_amt = '0.00') and immediately creates a linked cash_receipt_client_ledger application.
The new row appears in the Client Ledger table with an editable amount field.
User enters the application amount and saves.

Postconditions:

client_ledger.client_ledger_type_cd = 'OA' with client_ledger_open_item_ind = true
cash_receipt_client_ledger.cash_receipt_amt_applied set to the user-entered amount
Worksheet balance includes the ledger application in the total applied

UI trigger: "Create On-Account" button in the Client Ledger section header. Visible when cash_receipt_worksheet_status_cd = 'D'. Enabled when at least one client is available from match references or receivable applications.

5.6 Add Passthrough Payout

Preconditions:

Worksheet cash_receipt_worksheet_status_cd = 'D' and is not read-only.
Deal parties are available (populated from billing items already on the worksheet).

Procedure reference: Create Payout

Steps:

User clicks "Add Payment" in the Payments section.
User fills the Create Payment dialog: party, amount, payment type (P for Passthrough or L for Loan), optional currency, bank account, and payment date.
User clicks Save. System creates a cash_receipt_payout record.

Postconditions:

New cash_receipt_payout with payment_item_type_cd = 'P' or 'L' and payout_status_cd = 'PENDING'.

UI trigger: "Add Payment" button in the Payments section header. Visible when cash_receipt_worksheet_status_cd = 'D' and not read-only.

5.7 Apply Worksheet (Draft → Applied)

Preconditions:

cash_receipt_worksheet_status_cd = 'D'
User has CASH_MANAGER or IT role (canApplyWorksheet = true).
At least one application exists across cash_receipt_application, cash_receipt_client_ledger, or cash_receipt_payout.

Procedure reference: Apply Worksheet — D to P

Steps:

User clicks Apply in the worksheet header.
System validates that the worksheet is in Draft and has at least one application.
System sets cash_receipt_worksheet_status_cd = 'P', posting_status_cd = 'U', applied_dt = now(), applied_by = userName.
Worksheet becomes read-only for editing; settlement creation becomes available to Cash Processors.

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'
cash_receipt_worksheet.posting_status_cd = 'U' (REV and client ledger entries ready for GL pickup)
cash_receipt_worksheet.applied_dt and applied_by populated

UI trigger: "Apply" button in the worksheet header. Visible when status_cd = 'D' and canApplyWorksheet = true. Disabled while application migration is in progress.

5.8 Reject from Applied (Applied → Draft)

Preconditions:

cash_receipt_worksheet_status_cd = 'P'
User has CASH_PROCESSOR or IT role (canSettleWorksheet = true).

Procedure reference: Reject from Applied — P to D

Steps:

User clicks Reject in the worksheet header when status is Applied.
System sets cash_receipt_worksheet_status_cd = 'D', clears applied_dt, applied_by, and sets posting_status_cd = null.
Worksheet returns to editable Draft state.

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'D'
cash_receipt_worksheet.posting_status_cd = null

UI trigger: "Reject" button visible when status_cd = 'P' and canSettleWorksheet = true.

5.9 Create Settlement for PAY Applications

Preconditions:

Worksheet is in Applied (P) status (also permitted from Draft D).
User has CASH_PROCESSOR or IT role (canSettleWorksheet = true).
At least one PAY application row is selected via checkbox.

Procedure reference: Save Settlement

Steps:

User selects one or more PAY receivable rows using checkboxes in the Receivables table.
"Create Settlement" button appears showing the count of selected rows.
User clicks "Create Settlement." The Settlement Sheet panel opens.
User specifies how the PAY amount is divided: selects parties and enters commission percentages or flat amounts. Settlement total must equal PAY applied for the selected applications.
User clicks Save. System creates a participant_settlement header and participant_settlement_item records per party, links the PAY applications via participant_settlement_id, and auto-creates cash_receipt_payout records (type S).

Postconditions:

participant_settlement.participant_settlement_status_cd = 'D'
cash_receipt_application.participant_settlement_id populated for linked PAY applications
cash_receipt_payout records (type S) created and linked to settlement items

UI trigger: Checkboxes appear on PAY receivable rows when canCreateSettlement = true (status D or P, user has settle permission). "Create Settlement" button appears above the table when rows are selected.

5.10 Settle Worksheet (Applied → Settled)

Preconditions:

cash_receipt_worksheet_status_cd = 'P'
User has CASH_PROCESSOR or IT role (canSettleWorksheet = true).
All PAY applications have a non-null cash_receipt_application.participant_settlement_id.

Procedure reference: Settle Worksheet — P to T

Steps:

User clicks Settle in the worksheet header.
System validates that all PAY applications have settlements.
System sets cash_receipt_worksheet_status_cd = 'T', settled_dt = now(), settled_by = userName.
All linked participant_settlement records are updated to Settled (T) status.

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'T'
All linked participant_settlement.participant_settlement_status_cd = 'T'
cash_receipt_worksheet.settled_dt and settled_by populated

UI trigger: "Settle" button visible when status_cd = 'P' and canSettleWorksheet = true. Disabled when hasUnsettledPayApplications = true.

5.11 Reject from Settled (Settled → Applied)

Preconditions:

cash_receipt_worksheet_status_cd = 'T'
User has SETTLEMENT_APPROVER or IT role (canApprove = true).

Procedure reference: Reject from Settled — T to P

Steps:

User clicks Reject in the worksheet header (when status is Settled), or bulk-rejects from the Worksheet Queue.
System sets cash_receipt_worksheet_status_cd = 'P', clears settled_dt and settled_by.
All linked settlements revert to Draft (D) status so they can be edited or recreated.

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'
All linked participant_settlement.participant_settlement_status_cd = 'D'

UI trigger: "Reject" button visible when status_cd = 'T' and canApprove = true. Also available as "Reject Selected" bulk action in the Worksheet Queue Settled tab.

5.12 Approve Worksheet (Settled → Approved)

Preconditions:

cash_receipt_worksheet_status_cd = 'T'
User has SETTLEMENT_APPROVER or IT role (canApprove = true).

Procedure reference: Approve Worksheet — T to A

Steps:

User clicks Approve in the worksheet detail header, or selects worksheets in the Worksheet Queue Settled tab and clicks Bulk Approve.
System sets cash_receipt_worksheet_status_cd = 'A', approved_dt = now(), approved_by = userName.
All linked settlements are approved.
payment_item records are created from all cash_receipt_payout entries.
cash_receipt_payout.do_not_send_ind is reset to false on unlocked payment items so the bank transmission batch picks them up.
Fully paid billing items have billing_item.open_item_ind = false.
cash_receipt.locked_by_user_id = null (lock released).

Postconditions:

cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'A'
payment_item records created with payment_execution_status_cd = 'WAITING'
billing_item.open_item_ind = false for fully paid items
cash_receipt.locked_by_user_id = null

UI trigger: "Approve" button visible when status_cd = 'T' and canApprove = true. Bulk "Approve Selected" button visible in the Worksheet Queue Settled tab when one or more worksheets are selected and canApproveWorksheet = true.

5.13 Return Worksheet (Approved → Returned + Three Documents)

Preconditions:

cash_receipt_worksheet_status_cd = 'A'
User has SETTLEMENT_APPROVER or IT role (canReopenWorksheet = true).
cash_receipt.receipt_type_cd != 'WRITE_OFF'.
cash_receipt_worksheet.cash_receipt_split_id is not null.
cash_receipt_worksheet.replaced_by_worksheet_id is null (not already returned).

Procedure reference: Return/Reopen Worksheet — A to R

Steps:

User clicks "Reopen Worksheet" in the worksheet header.
The Return Reason dialog opens. User enters a required return reason.
User confirms. System produces three documents:
- Original worksheet sealed: cash_receipt_worksheet_status_cd = 'R', current_item_ind = false, worksheet_type_cd = 'ORIGINAL'. returned_dt, returned_by, return_reason populated. replaced_by_worksheet_id points to the replacement draft.
- Reversal worksheet inserted: worksheet_type_cd = 'REVERSAL', current_item_ind = false, posting_status_cd = 'U'. Negative mirror entries for ALL applications, client ledger entries, and payouts. reversal_of_*_id fields link back to originals.
- Replacement draft inserted: worksheet_type_cd = 'REPLACEMENT', current_item_ind = true, cash_receipt_worksheet_status_cd = 'D'. Only LOCKED applications copied as read-only. previous_worksheet_id points to the original.
User is navigated to the replacement draft worksheet.

Postconditions:

Original: cash_receipt_worksheet_status_cd = 'R', current_item_ind = false, replaced_by_worksheet_id set
Reversal: new worksheet with all negative entries, current_item_ind = false, posting_status_cd = 'U'
Replacement draft: new worksheet status_cd = 'D', current_item_ind = true, locked items pre-populated read-only

UI trigger: "Reopen Worksheet" button visible when status_cd = 'A', canReopenWorksheet = true, replaced_by_worksheet_id is null, and isWriteOff = false.

5.14 Bulk Approve from Worksheet Queue

Preconditions:

One or more worksheets with cash_receipt_worksheet_status_cd = 'T' are selected in the Worksheet Queue.
User has SETTLEMENT_APPROVER or IT role (canApproveWorksheet = true).

Procedure reference: Bulk Approve Worksheets

Steps:

User selects one or more rows in the Settled tab using checkboxes.
User clicks "Approve Selected."
System processes each worksheet using the same service path as individual approval.
Results show count of approved and count of failed with error messages.

Postconditions:

All successfully approved worksheets: cash_receipt_worksheet_status_cd = 'A' with newly created payment_item records.

UI trigger: Checkboxes on rows in the Settled tab. "Approve Selected" toolbar button appears when at least one row is checked and canApproveWorksheet = true.

6. Permissions & Role-Based Access

Action	CASH_MANAGER	CASH_PROCESSOR	SETTLEMENT_APPROVER	IT
Create Worksheet	Yes	—	—	Yes
Add / Edit / Remove Receivables	Yes	—	—	Yes
Add Deductions	Yes	—	—	Yes
Add Client Ledger Entries	Yes	—	—	Yes
Add Payout Records (Passthrough / Loan)	Yes	—	—	Yes
Apply Worksheet (D → P)	Yes	—	—	Yes
Reject from Applied (P → D)	—	Yes	—	Yes
Create Settlements (Draft or Applied)	—	Yes	—	Yes
Settle Worksheet (P → T)	—	Yes	—	Yes
Reject from Settled (T → P)	—	—	Yes	Yes
Approve Worksheet (T → A)	—	—	Yes	Yes
Bulk Approve from Queue	—	—	Yes	Yes
Bulk Reject from Queue	—	—	Yes	Yes
Return Worksheet (A → R)	—	—	Yes	Yes
View Worksheet (all statuses)	Yes	Yes	Yes	Yes
View Worksheet Queue	Yes	Yes	Yes	Yes

Field-level restrictions:

Locked application rows (associated payment sent to bank) are read-only for all roles — no role can edit or remove a locked application.
Write-off worksheets (cash_receipt.receipt_type_cd = 'WRITE_OFF') cannot be returned; the "Reopen Worksheet" button is hidden for all roles.
Worksheets with replaced_by_worksheet_id set are permanently read-only for all roles (original after return).
Settled (T) status is read-only for all users unless the user has canApprove = true (Settlement Approver or IT can approve or reject from Settled).

7. Integration Points

7.1 Upstream

Source	Data Provided	Mechanism
Cash Receipts workflow	`cash_receipt_split` with `split_amt` — the parent record worksheets are attached to	FK `cash_receipt_worksheet.cash_receipt_split_id` → `cash_receipt_split`
Cash Matching workflow	`cash_receipt_reference` records (client ID, deal ID, buyer ID, payment term ref) tagging which client/deal the receipt relates to	Queried at worksheet load via `getMatchReferencesForSplit` to pre-filter receivable search and populate client ledger suggestions
Billing Items / Revenue	`billing_item_detail` REV and PAY rows — the receivables that cash is applied against; outstanding balance computed from prior applications	FK `cash_receipt_application.billing_item_detail_id` → `billing_item_detail`; balance queried at receivable search time
Tax Engine	Pre-calculated tax deductions and withholding requirements for each billing item's contracted party	Tax previews loaded at worksheet load time; suggested deductions pre-populate the Deductions dialog

7.2 Downstream

Consumer	Data Consumed	Mechanism
General Ledger (GL) posting	REV applications and client ledger entries staged for posting when `cash_receipt_worksheet.posting_status_cd = 'U'` (set at Apply transition)	GL posting batch reads records with `posting_status_cd = 'U'` and sets to `'P'` after posting
Settlements workflow	`cash_receipt_application` PAY rows — source for settlement creation. Each PAY application gets linked to a `participant_settlement` via `participant_settlement_id`	FK `cash_receipt_application.participant_settlement_id` → `participant_settlement`
Payments workflow	`cash_receipt_payout` records converted to `payment_item` records at worksheet approval; payment items enter the bank transmission queue	`createPaymentItemsFromPayouts` called at approval; `payment_item.payment_execution_status_cd` starts at `'WAITING'`
AR Aging reports	Billing item balances recalculated after applications are added or removed; `billing_item.open_item_ind` set to `false` when fully paid at approval	Billing item balance queries sum `cash_receipt_application.cash_receipt_amt_applied` across all active worksheets
Write-offs	Write-off status surfaced as a warning banner when any client on the worksheet has written-off receivables	`useWriteOffWarnings` queries `billing_item_detail.write_off_status_cd` for clients on the worksheet

7.3 External Integrations

No external integrations are triggered directly by worksheet operations. Outbound bank payments are triggered downstream when the Payments workflow transmits payment items created at worksheet approval — see Payments Workflow for bank adapter details (CNB EASI Link, JPM ISO 20022, BofA ISO 20022).

8. Functional Screen Requirements

8.1 Worksheet Queue

Route: /cash-processing/worksheets

Data loading:

getWorksheetsForQueue(['D', 'P', 'T', 'R']) — Get Worksheets for Queue (initial load; refetched when status tab changes)
getWorksheetStatusCounts — Get Worksheet Status Counts (populates tab count badges)
getSettledWorksheetsWithSettlements — Get Settled Worksheets with Settlements (Settled tab hierarchical view)
getCurrentUserPermissions — loaded server-side at page entry

Status Tabs Region

Displays count badges for each worksheet status. Clicking a tab re-filters the queue list.

Field / Column	Source	Editable?	Condition
Draft tab count	Computed: `getWorksheetStatusCounts` result for `D`	No	Always visible
Applied tab count	Computed: `getWorksheetStatusCounts` result for `P`	No	Always visible
Settled tab count	Computed: `getWorksheetStatusCounts` result for `T`	No	Always visible
Approved tab count	Computed: `getWorksheetStatusCounts` result for `A`	No	Always visible
Returned tab count	Computed: `getWorksheetStatusCounts` result for `R`	No	Always visible

Worksheet List Region

Tabular list of active worksheets (current_item_ind = true) filtered by the selected status tab.

Field / Column	Source	Editable?	Condition
Worksheet ID	`cash_receipt_worksheet.cash_receipt_worksheet_id`	No	Always visible
Status badge	`cash_receipt_worksheet.cash_receipt_worksheet_status_cd`	No	Always visible
Created date	`cash_receipt_worksheet.created_dt`	No	Always visible
Created by	Resolved from `users.first_name`, `users.last_name`	No	Always visible
Receipt ref	`cash_receipt.cash_receipt_ref`	No	Always visible
Deposit date	`cash_receipt.deposit_date`	No	Always visible
Receipt amount	`cash_receipt.net_receipt_amt` with `currency_cd`	No	Always visible
Split amount	`cash_receipt_split.split_amt`	No	Always visible
Split sequence	`cash_receipt_split.split_sequence`	No	When receipt has multiple splits
Bank account	`bank_account.bank_account_name`	No	When populated
Entry status	`cash_receipt.entry_status` (`BOOK`/`PDNG`)	No	When populated (bank-originated receipts)
REV applied total	Computed: sum of REV `cash_receipt_application.cash_receipt_amt_applied`	No	When applications exist
PAY applied total	Computed: sum of PAY `cash_receipt_application.cash_receipt_amt_applied`	No	When applications exist
Settlement count	Computed: count of distinct `participant_settlement_id` values	No	When settlements exist
Settlement total	Computed: sum of `participant_settlement_item.participant_settlement_commission_amt`	No	When settlements exist
Settlement parties	Computed: first 2–3 party display names from settlement items	No	When settlements exist
Return reason	`cash_receipt_worksheet.return_reason`	No	When `status_cd = 'R'`
Lock indicator	`cash_receipt_worksheet.locked_by_user_id` and resolved user name	No	When locked
Document count	Computed: file count for `cash_receipt_worksheet` entity	No	Always visible
Select checkbox	Client state	Yes	When `canApproveWorksheet = true` and `status_cd = 'T'` (Settled tab)

Grid features:

Sortable columns: worksheet ID, created date, receipt ref, deposit date, receipt amount, split amount
Filters: free-text search on receipt ref and bank account name; entry status filter (BOOK/PDNG)
Row selection: multi-select checkbox — used for bulk Approve and bulk Reject (Settled tab only)
Pagination: yes, default 25 per page

Conditional display:

"Approve Selected" and "Reject Selected" bulk action buttons visible when at least one row is checked and canApproveWorksheet = true
Row-level "Review" slide-out panel appears on row click — shows inline settlement detail, Approve, and Reject buttons
The Settled tab shows a settlement-first hierarchical view grouped by worksheet with expanded settlement items, instead of flat rows
Amount threshold highlighting applied to settlement totals: yellow at warning threshold, distinct at critical threshold

8.2 Worksheet Detail

Route: /worksheets/[id]

Data loading:

getWorksheetWithReceipt — Get Worksheet by ID with Receipt Context
getWorksheetApplicationsUnified — all applications (receivables, client ledger, payouts) for balance calculation and table population
getSettlementsByWorksheetId — linked settlements per billing item for settlement status indicators
getMatchReferencesForSplit — split references for pre-filtering receivable search and client ledger suggestions
getDealPartiesForWorksheet — deal parties available for payout creation dialogs
getAllDepartments, getAllEntities — global reference data for dropdown options
getCurrentUserPermissions — loaded server-side at page entry

Displays the worksheet's identity, status, receipt context, currency, source traceability, lifecycle metadata, tax summary, and action buttons.

Field / Column	Source	Editable?	Condition
Worksheet ID	`cash_receipt_worksheet.cash_receipt_worksheet_id`	No	Always visible
Status badge	`cash_receipt_worksheet.cash_receipt_worksheet_status_cd`	No	Always visible
Write-Off badge	Computed: `cash_receipt.receipt_type_cd = 'WRITE_OFF'`	No	When write-off worksheet
Receipt reference	`cash_receipt.cash_receipt_ref`	No	Always visible
Original currency	`cash_receipt.currency_cd`	No	Always visible
FX rate	`cash_receipt.fx_rate`	No	Always visible
Bank account	`bank_account.bank_account_name`	No	When populated
Filename	`cash_receipt.filename`	No	When bank-originated
Entry status	`cash_receipt.entry_status`	No	When bank-originated
Created	`cash_receipt_worksheet.created_dt` and creator display name	No	Always visible
Applied	`cash_receipt_worksheet.applied_dt` and `applied_by`	No	When `status_cd` >= `P`
Settled	`cash_receipt_worksheet.settled_dt` and `settled_by`	No	When `status_cd` >= `T`
Approved	`cash_receipt_worksheet.approved_dt` and `approved_by`	No	When `status_cd = 'A'` or `'R'`
Rejected	`cash_receipt_worksheet.rejected_dt` and `rejected_by`	No	When a reject occurred
Previous Reopened	`returned_dt` from the worksheet identified by `previous_worksheet_id`	No	When this is a replacement draft
Tax Summary bar	Computed from tax engine: total withholding, total VAT, required tax forms, receivables with tax	No	When total withholding or VAT > 0

Balance Display Region

Field / Column	Source	Editable?	Condition
Split amount	`cash_receipt_split.split_amt`	No	Always visible
REV applied	Computed: sum of REV application amounts	No	Always visible
PAY applied	Computed: sum of PAY application amounts	No	Always visible
Total applied	Computed: REV + PAY + client ledger + payouts	No	Always visible
Remaining balance	Computed: split amount – total applied	No	Always visible
On-account pending	Computed: sum of auto-populated client ledger amounts not yet saved	No	When auto-populated items exist

Action Buttons Region

Field / Column	Source	Editable?	Condition
Apply button	Calls `applyWorksheet`	Yes	`status_cd = 'D'` and `canApplyWorksheet = true` and not migrating
Settle button	Calls `settleWorksheet`	Yes	`status_cd = 'P'` and `canSettleWorksheet = true`; disabled when `hasUnsettledPayApplications = true`
Reject (Applied → Draft)	Calls `rejectWorksheetFromApplied`	Yes	`status_cd = 'P'` and `canSettleWorksheet = true`
Approve button	Calls `approveWorksheet`	Yes	`status_cd = 'T'` and `canApprove = true`
Reject (Settled → Applied)	Calls `rejectWorksheetFromSettled`	Yes	`status_cd = 'T'` and `canApprove = true`
Reopen Worksheet button	Opens Return Reason dialog	Yes	`status_cd = 'A'` and `canReopenWorksheet = true` and `replaced_by_worksheet_id` is null and not write-off
Back to Worksheets	Navigation to queue	Yes	When `status_cd` is `S`, `A`, or worksheet is read-only
Read-Only View indicator	Static text	No	When `replaced_by_worksheet_id` is set or other read-only conditions

Receivables Table Region

Displays all cash_receipt_application records grouped by billing item, with REV and PAY rows per item.

Field / Column	Source	Editable?	Condition
Select checkbox	Client state	Yes	`canCreateSettlement = true` and PAY amount > 0 and no existing settlement
Client name	`billing_item.client_id` → `party.display_name`	No	Always visible
Deal name	`billing_item.deal_id` → `deal.deal_name`	No	Always visible
Billing item name	`billing_item.billing_item_name`	No	Always visible
REV amount applied	`cash_receipt_application.cash_receipt_amt_applied` (REV detail row)	Yes	When not read-only and application not locked
PAY amount applied	`cash_receipt_application.cash_receipt_amt_applied` (PAY detail row)	Yes	When not read-only and application not locked
REV outstanding balance	Computed: `billing_item_detail.billing_item_detail_total_amt` minus sum of prior applications	No	Always visible
PAY outstanding balance	Computed: same for PAY detail	No	Always visible
Tax badge	Computed from tax engine preview for billing item	No	When tax withholding or VAT applies
Deduction badge	Derived from `cash_receipt_application_deduction` records count	No	When deductions exist
Settlement status badge	`participant_settlement.participant_settlement_status_cd` via `participant_settlement_id`	No	When settlement linked
Write-off badge	`billing_item_detail.write_off_status_cd`	No	When `write_off_status_cd != 'NOT_WRITTEN_OFF'`
Lock icon	Derived from `payment_item.payment_execution_status_cd`	No	When application is locked
Row action menu	Actions: Add Commission, Commission Adjust, Split Billing, Payment Adjust, Open Deductions, Remove	Yes	When not read-only and not locked

Grid features:

Sortable columns: client name, deal name
Filters: none (items are fixed to this worksheet's applications)
Row selection: multi-select checkbox on PAY rows for settlement creation
Pagination: no (all rows shown)

Conditional display:

"Add Receivables" button in section header visible when status_cd = 'D' and not read-only
"Create Settlement" button appears above grid when PAY rows are selected and canCreateSettlement = true
Write-Off Warning Banner appears above the table when any client on the worksheet has written-off receivables

Client Ledger Table Region

Displays all cash_receipt_client_ledger and auto-populated on-account entries.

Field / Column	Source	Editable?	Condition
Client name	`cash_receipt_client_ledger.client_id` → `party.display_name`	No	Always visible
Ledger name	`client_ledger.client_ledger_name`	No	Always visible
Deal name	`cash_receipt_client_ledger.deal_id` → `deal.deal_name`	No	When deal is set
Amount applied	`cash_receipt_client_ledger.cash_receipt_amt_applied`	Yes	When not read-only; inline editable
Auto-populated amount	Client state: `autoPopulatedAmounts` map	Yes	When auto-populated from client ledger suggestions
Remove button	Client action	Yes	When not read-only

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: no

Conditional display:

"Create On-Account" button visible when status_cd = 'D' and not read-only and clients are available
Auto-populated rows appear before being saved; styled differently to indicate pending state

Payments Table Region

Displays all cash_receipt_payout records.

Field / Column	Source	Editable?	Condition
Party name	`cash_receipt_payout.payout_party_id` → `party.display_name`	No	Always visible
Payment type	`cash_receipt_payout.payment_item_type_cd` (label: Settlement, Passthrough, Loan, VAT, Reversal)	No	Always visible
Amount	`cash_receipt_payout.payment_item_amt`	Yes	When not read-only and not locked
Currency	`cash_receipt_payout.payment_item_currency_cd`	No	Always visible
Payment date	`cash_receipt_payout.payment_date`	No	When populated
Do Not Send	`cash_receipt_payout.do_not_send_ind`	Yes	When not read-only
Payout status	`cash_receipt_payout.payout_status_cd`	No	When not `PENDING`
Remove button	Client action	Yes	When not locked and not read-only; not available for settlement-derived payouts (type `S`)

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: no

Conditional display:

"Add Payment" button visible when status_cd = 'D' and not read-only
Locked payouts from the returned worksheet displayed with lock icon and no edit controls

Documents Region

Displays files attached to the worksheet and linked settlements.

Field / Column	Source	Editable?	Condition
File name	File storage metadata	No	When files exist
File type	File storage metadata	No	When files exist
Settlement selector	Dropdown: linked `participant_settlement` records with document counts	Yes	When settlements with documents exist

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: no

Conditional display:

Upload button visible when not read-only
PDF document preview opens when a settlement document is selected

8.3 Add Receivables Dialog

Route: Modal dialog within /worksheets/[id]

Data loading:

searchReceivables — Search Receivables triggered by search criteria changes or on dialog open

Search Criteria Region

Field / Column	Source	Editable?	Condition
Client filter	User input; pre-populated from `cash_receipt_reference` match references	Yes	Always visible
Deal filter	User input; pre-populated from match references	Yes	Always visible
Buyer filter	User input	Yes	Always visible
Department filter	User input	Yes	Always visible
Payment term ref filter	User input; pre-populated from match references	Yes	Always visible
Hide zero balance toggle	Client state, default true	Yes	Always visible

Results Grid Region

Field / Column	Source	Editable?	Condition
Client name	`billing_item.client_id` → `party.display_name`	No	Always visible
Deal name	`billing_item.deal_id` → `deal.deal_name`	No	Always visible
Billing item name	`billing_item.billing_item_name`	No	Always visible
REV outstanding balance	Computed: `billing_item_detail.billing_item_detail_total_amt` – sum applied	No	Always visible
PAY outstanding balance	Computed: same for PAY detail	No	Always visible
REV amount to apply	User input, default = outstanding balance	Yes	Always visible
PAY amount to apply	User input, default = outstanding balance	Yes	Always visible
Tax badge	Tax engine preview for billing item	No	When tax applies
Select checkbox	Client state	Yes	Always visible

Grid features:

Sortable columns: client name, deal name
Filters: driven by Search Criteria Region
Row selection: multi-select checkbox
Pagination: yes

Conditional display:

"Add to Worksheet" confirm button enabled when at least one row is selected
Items already on the worksheet shown with an indicator but still selectable (multiple applications per item are allowed)

8.4 Settlement Sheet

Route: Slide-over panel within /worksheets/[id]

Data loading:

getSettlementDefaults — default party and commission data from deal configuration
getSettlementByApplicationIds — existing settlement data when editing

Settlement Form Region

Field / Column	Source	Editable?	Condition
PAY applied (display only)	Computed: sum of PAY `cash_receipt_amt_applied` for selected applications	No	Always visible
Settlement total (running)	Computed: sum of entered commission amounts	No	Always visible
Mismatch warning	Computed: settlement total ≠ PAY applied	No	When mismatch exists
Party name	`participant_settlement_item.payment_party_id` → `party.display_name`	Yes	Per row
Commission percentage	`participant_settlement_item.participant_settlment_commission_perc`	Yes	Per row (percentage-based)
Commission amount	`participant_settlement_item.participant_settlement_commission_amt`	Yes	Per row
Flat amount indicator	`participant_settlement_item.participant_settlement_commission_flat_ind`	Yes	Per row
Add party button	Client action	Yes	Always visible
Remove party button	Client action	Yes	Per row when more than one party

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: no

Conditional display:

Save button disabled when settlement total does not equal PAY applied
"Delete Settlement" button visible when editing an existing settlement that is not locked

8.5 Deductions Dialog

Route: Modal dialog within /worksheets/[id]

Data loading:

getSuggestedDeductions — from tax engine preview data already loaded at worksheet entry

Deduction Rows Region

Field / Column	Source	Editable?	Condition
Deduction type	`cash_receipt_application_deduction.billing_item_deduction_type_cd`	Yes	Per row
Amount	`cash_receipt_application_deduction.deduction_amt_applied`	Yes	Per row
Pre-populated indicator	Derived from tax engine suggestion	No	When suggestion provided
Add deduction row button	Client action	Yes	Always visible
Remove row button	Client action	Yes	Per row

Grid features:

Sortable columns: none
Filters: none
Row selection: none
Pagination: no

Conditional display:

"Apply Suggested" button visible when the tax engine has calculated deductions for the billing item
Warning displayed when total deduction amount exceeds the application amount

8.6 Return Reason Dialog

Route: Modal dialog within /worksheets/[id]

Data loading: None — captures user input only.

Dialog Region

Field / Column	Source	Editable?	Condition
Return reason text	User input, stored in `cash_receipt_worksheet.return_reason`	Yes	Always editable
Confirm button	Client action, calls `reopenWorksheet`	Yes	Enabled when reason is non-empty
Cancel button	Client action	Yes	Always visible

Grid features: None.

Conditional display:

Confirm button disabled when returnReason is empty or whitespace only.

9. Additional Diagrams

Worksheet Status State Machine

mermaid

stateDiagram-v2
    [*] --> D : Create worksheet
    D --> P : Apply\n(Cash Manager)
    P --> D : Reject\n(Cash Processor)
    P --> T : Settle\n(Cash Processor)
    T --> P : Reject\n(Settlement Approver)
    T --> A : Approve\n(Settlement Approver)
    A --> R : Return\n(Settlement Approver)
    R --> [*]

    state "Draft (D)" as D
    state "Applied (P)" as P
    state "Settled (T)" as T
    state "Approved (A)" as A
    state "Returned (R)" as R

Three-Document Return Process

mermaid

sequenceDiagram
    participant User as Settlement Approver
    participant System
    participant Original as Original Worksheet (A)
    participant Reversal as Reversal Worksheet
    participant Replacement as Replacement Draft

    User->>System: Click Reopen Worksheet
    System->>User: Prompt for return reason
    User->>System: Enter reason and confirm
    System->>Original: status = R, current_item_ind = false\nworksheet_type_cd = ORIGINAL\nreturned_dt, returned_by, return_reason set
    System->>Reversal: Insert new worksheet\nworksheet_type_cd = REVERSAL\ncurrent_item_ind = false\nposting_status_cd = U\nNegative mirror entries for ALL items
    System->>Replacement: Insert new worksheet\nworksheet_type_cd = REPLACEMENT\ncurrent_item_ind = true\nOnly LOCKED items copied as read-only
    System->>Original: replaced_by_worksheet_id = Replacement.id
    System->>Replacement: previous_worksheet_id = Original.id
    System->>User: Navigate to Replacement Draft

GL Posting Timing

mermaid

flowchart LR
    A[Apply Worksheet\nD to P] -->|posting_status_cd set to U| B[GL Batch picks up REV\nand Client Ledger entries]
    B --> C[REV posted to GL\nposting_status_cd set to P]
    D[Approve Worksheet\nT to A] --> E[Payment items created\ndo_not_send_ind reset to false]
    E --> F[Bank confirms payment\nACKNOWLEDGED or PAID]
    F --> G[PAY posted to GL]

10. Cross-References

Document	Relationship
Worksheets Data Model	Defines all tables used in this workflow: `cash_receipt_worksheet`, `cash_receipt_application`, `cash_receipt_application_deduction`, `cash_receipt_client_ledger`, `cash_receipt_payout`, `client_ledger`
Worksheets Queries	Specifies all data retrieval operations for worksheet loading, receivable search, queue display, and balance calculation
Worksheets Procedures	Specifies all data mutation operations for worksheet creation, application CRUD, status transitions, and the three-document return process
Billing Items Data Model	Defines `billing_item` and `billing_item_detail` — the receivables worksheets apply cash against. REV and PAY detail types drive the split between UTA revenue and client payout
Cash Receipts Data Model	Defines `cash_receipt` and `cash_receipt_split` — the parent records from which worksheets are created. Receipt posting status and split amount constrain worksheet creation and balance calculations
Cash Receipts Workflow	Upstream: cash receipt and split lifecycle, split status management, and the agent submission flow that precedes worksheet creation
Cash Matching Workflow	Upstream: tagging a split with client/deal/buyer references that pre-filter the receivable search dialog and trigger client ledger suggestions
Settlements Workflow	Downstream: creating and managing participant settlements for PAY applications. Settlements are initiated from within the worksheet in Applied status
Payments Workflow	Downstream: outbound payment transmission. Payment items created at worksheet approval enter the payment execution queue
Write-Offs Workflow	Related: write-off worksheets skip settlement and cannot be returned; write-off recovery produces a separate type of receipt
AR Aging Workflow	Related: billing item balances depend on worksheet applications; approved worksheets close `billing_item.open_item_ind` on fully paid items

11. Gherkin Scenarios

gherkin

Feature: Worksheets - Cash Application Lifecycle

  Scenario: Happy path - full worksheet lifecycle for a standard receipt
    Given a cash receipt with `cash_receipt.posting_status_cd = 'U'` for $10,000 USD
    And a `cash_receipt_split` with `split_amt = '10000.00'` and `split_status_cd = 'A'`
    And a billing item for client "Taylor Swift" with REV detail total $1,500.00 and PAY detail total $8,500.00
    And the current user has role CASH_MANAGER
    When the user clicks "Create Worksheet" for the split
    Then a `cash_receipt_worksheet` record exists with `cash_receipt_worksheet_status_cd = 'D'` and `current_item_ind = true`
    And `cash_receipt.locked_by_user_id` is set to the current user's ID
    When the user adds the billing item with REV amount $1,500.00 and PAY amount $8,500.00
    Then two `cash_receipt_application` records exist on the worksheet
    And the worksheet balance shows Remaining = $0.00
    When the user with role CASH_MANAGER clicks Apply
    Then `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'`
    And `cash_receipt_worksheet.posting_status_cd = 'U'`
    And `cash_receipt_worksheet.applied_dt` is populated
    When a user with role CASH_PROCESSOR selects the PAY row and creates a settlement for "Taylor Swift" at 100% for $8,500.00
    Then a `participant_settlement` exists with `participant_settlement_status_cd = 'D'`
    And `cash_receipt_application.participant_settlement_id` is populated for the PAY application
    And a `cash_receipt_payout` exists with `payment_item_type_cd = 'S'` and `payment_item_amt = '8500.00'`
    When the user with role CASH_PROCESSOR clicks Settle
    Then `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'T'`
    And `participant_settlement.participant_settlement_status_cd = 'T'`
    When a user with role SETTLEMENT_APPROVER clicks Approve
    Then `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'A'`
    And a `payment_item` exists with `payment_execution_status_cd = 'WAITING'`
    And `cash_receipt.locked_by_user_id` is null

  Scenario: Happy path - partial application leaves remaining balance
    Given a `cash_receipt_split` with `split_amt = '15000.00'`
    And a billing item for client "Ed Sheeran" with REV detail $1,200.00 and PAY detail $6,800.00
    When the user adds the billing item with REV $1,200.00 and PAY $6,800.00
    Then total applied = $8,000.00 and remaining = $7,000.00
    When the user with role CASH_MANAGER clicks Apply
    Then the Apply succeeds despite remaining > $0.00
    And `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'`

  Scenario: Happy path - on-account client ledger entry
    Given a worksheet in Draft status with a `cash_receipt_reference` tagging client "Drake" via `type_cd = 'CLIENT_ID'`
    When the user clicks "Create On-Account" and fills in name "Drake Q1 Advance" with no specific deal
    Then a `client_ledger` record exists with `client_ledger_type_cd = 'OA'` and `client_ledger_amt = '0.00'`
    And a `cash_receipt_client_ledger` record exists linked to the worksheet
    When the user enters $5,000.00 in the amount field and saves
    Then `cash_receipt_client_ledger.cash_receipt_amt_applied = '5000.00'`
    And the worksheet balance includes the $5,000.00 in total applied

  Scenario: Edge case - settlement total does not equal PAY applied
    Given a worksheet in Applied status with PAY `cash_receipt_application.cash_receipt_amt_applied = '8500.00'`
    And a user with role CASH_PROCESSOR opens the Settlement Sheet
    When the user enters settlement items summing to $8,000.00
    Then the Save button is disabled
    And a validation message shows "Settlement total (8000.00) must equal PAY Applied (8500.00)"
    When the user adjusts the items to sum to $8,500.00
    Then the Save button becomes enabled

  Scenario: Edge case - Settle button disabled when PAY application has no settlement
    Given a worksheet in Applied status with a PAY application where `participant_settlement_id` is null
    When a user with role CASH_PROCESSOR views the worksheet header
    Then the Settle button is disabled
    And a tooltip reads "Create settlements for all PAY applications before settling"
    When the user creates a settlement linking that PAY application
    Then `cash_receipt_application.participant_settlement_id` is set
    And the Settle button becomes enabled

  Scenario: Edge case - Apply rejected because no applications exist
    Given a worksheet in Draft status with zero records in `cash_receipt_application`, `cash_receipt_client_ledger`, and `cash_receipt_payout`
    When a user with role CASH_MANAGER clicks Apply
    Then the action fails with error "Cannot apply: No cash applications exist"
    And `cash_receipt_worksheet.cash_receipt_worksheet_status_cd` remains `'D'`

  Scenario: Error case - Create Worksheet blocked by concurrent lock
    Given a cash receipt with `locked_by_user_id` set to user ID 42 ("Jane Smith")
    When a different user with role CASH_MANAGER attempts to create a worksheet for the receipt's split
    Then the action fails with an error indicating the receipt is locked by "Jane Smith"

  Scenario: Error case - Return blocked for write-off worksheet
    Given a worksheet in Approved status where `cash_receipt.receipt_type_cd = 'WRITE_OFF'`
    And the current user has role SETTLEMENT_APPROVER
    When the user views the worksheet header
    Then the "Reopen Worksheet" button is not visible

  Scenario: Error case - Settlement deletion blocked by locked payment
    Given a `participant_settlement` linked to a PAY application on an approved worksheet
    And the associated `payment_item.payment_execution_status_cd = 'SENT'`
    When any user attempts to delete the settlement
    Then the action fails with error "Cannot delete settlement with locked payment items. One or more payments have been sent to the bank."

  Scenario: Return case - Three documents produced with mixed locked and unlocked items
    Given an approved worksheet with two PAY applications:
      - Application A: `payment_item.payment_execution_status_cd = 'PAID'` (locked)
      - Application B: `payment_item.payment_execution_status_cd = 'WAITING'` (unlocked)
    And the current user has role SETTLEMENT_APPROVER
    When the user clicks "Reopen Worksheet" and provides return reason "Incorrect amount on deal 2"
    Then the original worksheet has `cash_receipt_worksheet_status_cd = 'R'` and `current_item_ind = false`
    And `cash_receipt_worksheet.return_reason = 'Incorrect amount on deal 2'`
    And a reversal worksheet is created with `worksheet_type_cd = 'REVERSAL'` and `posting_status_cd = 'U'` containing negative entries for BOTH Application A and Application B
    And a replacement draft is created with `worksheet_type_cd = 'REPLACEMENT'` and `current_item_ind = true`
    And the replacement draft contains a read-only copy of Application A (locked)
    And the replacement draft does NOT contain Application B (unlocked — not pre-populated)

  Scenario: Return case - Replacement draft balance reflects locked items
    Given a replacement draft with a locked PAY application of $6,000.00 (read-only, already pre-populated)
    When the user adds a new receivable for client "Beyonce" with REV $1,000.00 and PAY $5,500.00
    Then total applied = $12,500.00 (locked $6,000.00 + new $6,500.00)
    And the new REV and PAY rows are editable
    And the locked rows remain read-only

  Scenario: Happy path - bulk approve multiple settled worksheets
    Given three worksheets with `cash_receipt_worksheet_status_cd = 'T'` (IDs 101, 102, 103)
    And the current user has role SETTLEMENT_APPROVER
    When the user selects all three worksheets in the Settled tab and clicks "Approve Selected"
    Then worksheets 101, 102, 103 all have `cash_receipt_worksheet_status_cd = 'A'`
    And `payment_item` records are created for each worksheet's `cash_receipt_payout` entries
    And the Settled tab count decreases by 3 and Approved tab count increases by 3

  Scenario: Reject workflow - Settled to Applied for settlement correction
    Given a worksheet with `cash_receipt_worksheet_status_cd = 'T'` and linked `participant_settlement.participant_settlement_status_cd = 'T'`
    And the current user has role SETTLEMENT_APPROVER
    When the user clicks Reject on the worksheet
    Then `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'P'`
    And `participant_settlement.participant_settlement_status_cd = 'D'`
    When the user edits the settlement and re-settles
    Then `cash_receipt_worksheet.cash_receipt_worksheet_status_cd = 'T'`

NOTE

PoC Artifact: The rejectWorksheetFromApplied and rejectWorksheetFromSettled server actions move the worksheet backward in status (P→D and T→P respectively) as direct database updates with no reversal document generation. These pre-approval step-back operations differ architecturally from the three-document Return process. Production implementation should consider whether these backward transitions require additional audit logging or a lightweight document trail.

NOTE

PoC Artifact: The applyWorksheet server action's validation rule comment block lists "APPLY-03: Worksheet balance must be 0 (all funds applied)" but then explicitly does not enforce it with the comment "Partial application allowed — no balance check required." The comment block was not updated after the business rule was relaxed. The correct behavior — partial application is permitted — is implemented and aligns with the CLAUDE.md domain rules. The stale comment should be removed in production code.

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Worksheets Workflow ​

1. Executive Summary ​

Purpose ​

Scope ​

Key Objectives ​

2. Process Overview ​

Walkthrough ​

3. Business Rules ​

3.1 One Active Worksheet Per Split ​

3.2 Receipt Must Not Be Voided or Posted ​

3.3 At Least One Application Required to Apply ​

3.4 Partial Application Is Allowed ​

3.5 All PAY Applications Must Have Settlements Before Settling ​

3.6 Settlement Total Must Equal PAY Applied ​

3.7 Worksheets Never Move Backward — Corrections Require Return ​

3.8 Replacement Draft Contains Only Locked Items ​

3.9 REV Always Reversible; Locked PAY Cannot Be Reversed ​

3.10 GL Posting Timing Differs for REV and PAY ​

3.11 Bilateral Lock Rule ​

3.12 Write-Off Worksheets Cannot Be Returned ​

3.13 Receipt Lock Acquired on Worksheet Creation ​

3.14 Same Billing Item Detail May Appear Multiple Times on One Worksheet ​

4. Data Access & Operations References ​

4.1 Queries Used ​

4.2 Procedures Used ​

5. Key User Actions ​

5.1 Create Worksheet ​

5.2 Add Receivables (Search and Apply) ​

5.3 Edit Application Amount ​

5.4 Add Application Deduction ​

5.5 Add On-Account Client Ledger Entry ​

5.6 Add Passthrough Payout ​

5.7 Apply Worksheet (Draft → Applied) ​

5.8 Reject from Applied (Applied → Draft) ​

5.9 Create Settlement for PAY Applications ​

5.10 Settle Worksheet (Applied → Settled) ​

5.11 Reject from Settled (Settled → Applied) ​

5.12 Approve Worksheet (Settled → Approved) ​

5.13 Return Worksheet (Approved → Returned + Three Documents) ​

5.14 Bulk Approve from Worksheet Queue ​

6. Permissions & Role-Based Access ​

7. Integration Points ​

7.1 Upstream ​

7.2 Downstream ​

7.3 External Integrations ​

8. Functional Screen Requirements ​

8.1 Worksheet Queue ​

Status Tabs Region ​

Worksheet List Region ​

8.2 Worksheet Detail ​

Header Region ​

Balance Display Region ​

Action Buttons Region ​

Receivables Table Region ​

Client Ledger Table Region ​

Payments Table Region ​

Documents Region ​

8.3 Add Receivables Dialog ​

Search Criteria Region ​

Results Grid Region ​

8.4 Settlement Sheet ​

Settlement Form Region ​

8.5 Deductions Dialog ​

Deduction Rows Region ​

8.6 Return Reason Dialog ​

Dialog Region ​

9. Additional Diagrams ​

Worksheet Status State Machine ​

Three-Document Return Process ​

GL Posting Timing ​

10. Cross-References ​

11. Gherkin Scenarios ​

Worksheets Workflow

1. Executive Summary

Purpose

Scope

Key Objectives

2. Process Overview

Walkthrough

3. Business Rules

3.1 One Active Worksheet Per Split

3.2 Receipt Must Not Be Voided or Posted

3.3 At Least One Application Required to Apply

3.4 Partial Application Is Allowed

3.5 All PAY Applications Must Have Settlements Before Settling

3.6 Settlement Total Must Equal PAY Applied

3.7 Worksheets Never Move Backward — Corrections Require Return

3.8 Replacement Draft Contains Only Locked Items

3.9 REV Always Reversible; Locked PAY Cannot Be Reversed

3.10 GL Posting Timing Differs for REV and PAY

3.11 Bilateral Lock Rule

3.12 Write-Off Worksheets Cannot Be Returned

3.13 Receipt Lock Acquired on Worksheet Creation

3.14 Same Billing Item Detail May Appear Multiple Times on One Worksheet

4. Data Access & Operations References

4.1 Queries Used

4.2 Procedures Used

5. Key User Actions

5.1 Create Worksheet

5.2 Add Receivables (Search and Apply)

5.3 Edit Application Amount

5.4 Add Application Deduction

5.5 Add On-Account Client Ledger Entry

5.6 Add Passthrough Payout

5.7 Apply Worksheet (Draft → Applied)

5.8 Reject from Applied (Applied → Draft)

5.9 Create Settlement for PAY Applications

5.10 Settle Worksheet (Applied → Settled)

5.11 Reject from Settled (Settled → Applied)

5.12 Approve Worksheet (Settled → Approved)

5.13 Return Worksheet (Approved → Returned + Three Documents)

5.14 Bulk Approve from Worksheet Queue

6. Permissions & Role-Based Access

7. Integration Points

7.1 Upstream

7.2 Downstream

7.3 External Integrations

8. Functional Screen Requirements

8.1 Worksheet Queue

Status Tabs Region

Worksheet List Region

8.2 Worksheet Detail

Header Region

Balance Display Region

Action Buttons Region

Receivables Table Region

Client Ledger Table Region

Payments Table Region

Documents Region

8.3 Add Receivables Dialog

Search Criteria Region

Results Grid Region

8.4 Settlement Sheet

Settlement Form Region

8.5 Deductions Dialog

Deduction Rows Region

8.6 Return Reason Dialog

Dialog Region

9. Additional Diagrams

Worksheet Status State Machine

Three-Document Return Process

GL Posting Timing

10. Cross-References

11. Gherkin Scenarios