---
title: Federal award management
summary: Retrieves federal awards for a claim or a worker, hydrates each award with its benefit payments, and persists status changes back to the federal award table.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim
reference_type: package
operation_id: OP-BC-04
trigger: A caller requests federal awards by claim or by worker, edits an award, and saves the collection
---

# 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](../sql/SQL-021-saif-business-claim.md), [CL_FEDERAL_AWARD](../database-tables.md#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](../database-tables.md#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](../sql/SQL-016-saif-business-claim.md), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)). When no codes are supplied the payment retrieval falls back to the federal benefit types ([BR-012](../business-rules.md#br-012-award-benefit-payment-collections-default-to-federal-benefit-types)).
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](../sql/SQL-035-saif-business-claim.md), [CL_FEDERAL_AWARD](../database-tables.md#cl_federal_award)).
   - 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](../business-rules.md#br-008-updatedelete-row-count-must-equal-1)).
8. **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](../database-tables.md#cl_benefit_payment)).
9. **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.

```mermaid
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".

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [SQL catalog](../sql/index.md)
- [Database tables](../database-tables.md)

> **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`