Skip to content

Federal award management

Federal awards are the long-term disability and settlement awards administered under federal jurisdiction. This operation retrieves them either for a single claim or across every claim belonging to an injured worker, attaches each award's benefit payments so callers can reason about the award and its money together, and writes status and amount changes back to the federal award table. The award object itself is update-only: federal awards are created elsewhere and can never be inserted or deleted through this library.

Field Value
Operation ID OP-BC-04
Trigger clsFederalAwardStatusCollection.GetFederalAwardStatusCollection, GetFederalAwardsForWorker, or GetFederalAwardsForClaimWithTypes, followed by Save()
Inputs ClaimID or WorkerID; an award status code; an optional list of benefit type codes used when hydrating payments
Outputs A collection of federal award objects, each carrying an award benefit payment collection; updated CL_FEDERAL_AWARD rows; error message UpdateError
Primary components clsFederalAwardStatusCollection.BeforeRetrieve, clsFederalAwardStatusCollection.AfterRetrieve, clsFederalAwardStatus.BeforeUpdate, clsFederalAwardStatus.AfterUpdate, clsFederalAwardStatus.SaveBenefitPayment
Entry point Business\SAIF.Business.Claim\clsFederalAwardStatusCollection.vb

Steps

  1. Choose the retrieval scope. BeforeRetrieve inspects the criteria: a worker identifier greater than zero selects the worker-scoped statement, otherwise the claim-scoped statement is used.
  2. Claim-scoped retrieval. The claim path selects the federal award columns for a claim identifier and an award status code, binding the status code as a five-character parameter (SQL-021, CL_FEDERAL_AWARD).
  3. Worker-scoped retrieval. The worker path joins the federal award table to the injury claim table so awards can be gathered across every claim for the worker, binding the award status code as a single character and the worker identifier (CL_FEDERAL_AWARD). The joined injury claim table is owned by another claim library and this statement is not represented in this library's SQL catalog.*
  4. Hydrate each award. AfterRetrieve walks the reader, constructing one clsFederalAwardStatus per row and loading its columns — award number, claim, status code, award and paid amounts, dates, and update number.
  5. Attach the award's benefit payments. For every award created in step 4, the collection assigns an award benefit payment collection retrieved for that award number, passing through the caller's benefit type codes when supplied (SQL-016, CL_BENEFIT_PAYMENT). When no codes are supplied the payment retrieval falls back to the federal benefit types (BR-012).
  6. Edit and save. Saving the collection walks each award; a dirty award runs its update path.
  7. Update the award. BeforeUpdate writes the award's mutable columns together with SYSDATE, an incremented update number, and the acting user, keyed on the award number and the prior update number (SQL-035, CL_FEDERAL_AWARD).
  8. If exactly one row is not affected: add UpdateError carrying the framework database contention message and stop; the award's payments are not saved (BR-008).
  9. Cascade the save to the payments. Only after a successful award update, SaveBenefitPayment saves the attached payment collection when it exists, is dirty, is valid, and carries no error messages; the award is then marked old (CL_BENEFIT_PAYMENT).
  10. Create, insert, delete, and retrieve are refused on the item. The award object's Criteria raises an application exception from its create, insert, delete, and retrieve SQL properties, so an award can only ever be reached through the collection.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller requests federal awards]) --> Scope{Worker id supplied?}
    Scope -->|Yes| ByWorker[Select awards joined to<br>the worker's injury claims]
    Scope -->|No| ByClaim[Select awards for the claim<br>and award status code]
    ByWorker --> Hydrate[Build one award object<br>per reader row]
    ByClaim --> Hydrate
    Hydrate --> Attach[Attach the award benefit<br>payment collection per award]
    Attach --> Edit[Caller edits award fields]
    Edit --> Save{Save requested?}
    Save -->|No| Idle([Collection returned unchanged])
    Save -->|Yes| Upd[Update the award keyed on<br>award number and update number]
    Upd --> Rows{Rows affected = 1?}
    Rows -->|No| Err([Add UpdateError;<br>payments not saved])
    Rows -->|Yes| Child{Payment collection dirty,<br>valid and error free?}
    Child -->|No| Done([Award marked old])
    Child -->|Yes| SavePay[Save the payment collection]
    SavePay --> Done

Failure and edge-case behavior

  • The award update and the payment collection save are sequential and unguarded by a transaction in this object, so a payment failure can leave the award updated without its payments.
  • The award status code is bound with different lengths on the two retrieval paths — one character for the worker path and five for the claim path — so a multi-character status code behaves differently depending on which entry point the caller uses.*
  • The award object's factory for a single award cannot succeed because its retrieve SQL raises an application exception; only the collection path is usable.
  • The collection's check for deleted awards by award number always reports false, so callers cannot rely on it to detect removals from the collection.*
  • One collection factory accepts a benefit-type argument that it never forwards to the retrieval, so the requested filter is silently discarded on that overload.*
  • The award object registers no business rules; award status transitions are validated by the caller, not here.
  • When a claim has no matching awards the collection is returned empty with no error, so callers must distinguish "none" from "not asked".

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\clsFederalAwardStatus.vb
  • Business\SAIF.Business.Claim\clsFederalAwardStatusCollection.vb
  • Business\SAIF.Business.Claim\clsAwardBenefitPaymentCollection.vb