Skip to content

Award benefit payment management

Benefit payments are the individual disbursement rows that hang off a SAIF award. This operation covers the single-payment object and its collection: reading an approved payment for a claim, reading all payments of selected benefit types for an award number, editing amounts and dates, and deleting a payment. The collection is the hydration source used when federal awards are loaded, so its default benefit-type filter determines which payments a federal award appears to carry.

Field Value
Operation ID OP-BC-03
Trigger clsAwardBenefitPayment.GetAwardBenefitPayment, GetAwardBenefitPaymentBySeq, or NewAwardBenefitPayment; clsAwardBenefitPaymentCollection.GetAwardBenefitPaymentCollection; followed by Save() for changes
Inputs ClaimID; AwardNum; BenefitPaymentSeqNum; an optional list of benefit type codes for the collection; payment fields such as issue date, amounts, and status codes; UpdateNum
Outputs A populated payment object or collection; updated or deleted CL_BENEFIT_PAYMENT rows; error messages UpdateError and DeleteError
Primary components clsAwardBenefitPayment (BeforeRetrieve, BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete), clsAwardBenefitPaymentCollection (BeforeRetrieve, AfterRetrieve, Save)
Entry point Business\SAIF.Business.Claim\clsAwardBenefitPayment.vb

Steps

  1. Retrieve one approved payment for a claim. GetAwardBenefitPayment runs the single-row select against the benefit payment table filtered by claim identifier and a benefit status code of 2, meaning the payment is approved (SQL-015, CL_BENEFIT_PAYMENT).
  2. GetAwardBenefitPaymentBySeq uses the same statement family keyed on the claim identifier and benefit payment sequence number instead.*
  3. Retrieve a collection for an award. clsAwardBenefitPaymentCollection.BeforeRetrieve starts from a select over the benefit payment table keyed on the SAIF award number whose predicate list is deliberately left incomplete, then appends a benefit type code list built from the supplied array (SQL-016, CL_BENEFIT_PAYMENT).
  4. Sub-step: each supplied benefit type code is added as its own bind parameter and appended to an IN list, so the statement text varies with the number of codes requested.
  5. Sub-step: when the caller supplies no codes, the collection falls back to the federal benefit types 4, 5, and 6 (BR-012).
  6. Hydrate the collection items. AfterRetrieve reads the data reader row by row, building a clsAwardBenefitPayment for each row through the item-level load entry point and adding it to the collection.
  7. Edit and save. The collection's Save() applies the pending edit level and then delegates to the framework collection save, which walks each dirty item through its own update or delete path.
  8. Update a payment. BeforeUpdate writes the payment's mutable columns together with SYSDATE, an incremented update number, and the acting user, keyed on the SAIF award number and the prior update number so a concurrent change is detected (SQL-030, CL_BENEFIT_PAYMENT).
  9. If exactly one row is not affected: add UpdateError carrying the framework database contention message (BR-008).
  10. Delete a payment. BeforeDelete removes the row by claim identifier and benefit payment sequence number (SQL-041, CL_BENEFIT_PAYMENT).
  11. If the affected row count is 0: add DeleteError carrying the framework database contention message (BR-008).
  12. Create and insert are refused. Both the item and the collection Criteria raise an application exception from their create and insert SQL properties, and the collection additionally refuses delete and update; payments are originated elsewhere and only maintained here.

Process flow

The following diagram visualizes the retrieve and save paths.

flowchart TD
    Start([Caller requests a payment<br>or a payment collection]) --> Which{Single item<br>or collection?}
    Which -->|Single| One[Select the approved payment<br>for the claim]
    Which -->|Collection| Codes{Benefit type codes<br>supplied?}
    Codes -->|No| Defaults[Use federal defaults 4, 5, 6]
    Codes -->|Yes| Build[Append one bind parameter<br>per supplied code]
    Defaults --> Build
    Build --> Many[Select payments for the award<br>with the code list]
    Many --> Hydrate[Build one payment object<br>per reader row]
    One --> Edit
    Hydrate --> Edit[Caller edits payment fields]
    Edit --> Save{Save requested?}
    Save -->|Update| Upd[Update keyed on award number<br>and prior update number]
    Save -->|Delete| Del[Delete keyed on claim and<br>payment sequence number]
    Upd --> URows{Rows affected = 1?}
    Del --> DRows{Rows affected = 0?}
    URows -->|No| UErr([Add UpdateError])
    URows -->|Yes| Done([Payment persisted])
    DRows -->|Yes| DErr([Add DeleteError])
    DRows -->|No| Done

Failure and edge-case behavior

  • The collection retrieve statement is only valid once the benefit type clause has been appended; invoking the criteria's retrieve SQL without going through BeforeRetrieve produces a syntactically incomplete statement.
  • A caller that supplies an empty benefit type list silently receives federal payments only, which is easy to mistake for "no payments exist" on a state claim.
  • The single-item retrieve is filtered to approved payments, so payments in any other status are invisible through that entry point even though they exist for the claim.
  • The update binds the issue date parameter twice; the redundant bind is harmless with named parameters but signals that the parameter list and the statement text have drifted.*
  • The item Save() override returns True unconditionally, so callers must inspect the error collection rather than the return value.*
  • Neither the item nor the collection registers any business rules, so field-level validity is entirely the caller's responsibility.
  • Delete failure is detected only when zero rows are affected; a statement that somehow affected more than one row would be reported as success.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Business\SAIF.Business.Claim\clsAwardBenefitPayment.vb
  • Business\SAIF.Business.Claim\clsAwardBenefitPaymentCollection.vb