---
title: Award eligibility management
summary: Maintains beneficiary award-eligibility periods, validates period boundaries and overlap rules, and persists row-level CRUD changes.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business.Claim.Person
reference_type: package
operation_id: OP-PER-05
trigger: Caller loads a beneficiary's eligibility-period collection, changes one or more periods, and saves the collection.
---

# Award eligibility management

Award eligibility management loads every eligibility period for one beneficiary, derives the current period from the loaded set, validates date-boundary and overlap rules, and saves row-level inserts, updates, and deletes to the award eligibility table. The child rows are managed under the beneficiary object, so birth-date and death-date validation reads parent beneficiary state during save.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PER-05 |
| **Trigger** | Caller retrieves award eligibility for a beneficiary, edits periods, and calls `Save()` on the collection |
| **Inputs** | `PersonID`; period fields `AwardEligEffDate`, `AwardEligExpDate`, `BenefitNoteText`; beneficiary `BirthDate` and `DeathDate`; acting user from `DataPortalInfo.UserID` |
| **Outputs** | In-memory eligibility-period collection; computed current period; persisted inserts, updates, or deletes in `CL_AWARD_ELIGIBILITY`; broken rules and DB-contention messages |
| **Primary components** | `clsAwardEligibilityCollection.GetEligibilityPeriodsForBeneficiary`, `clsAwardEligibilityCollection.CurrentPeriod`, `clsAwardEligibility.BeforeInsert`, `clsAwardEligibility.BeforeUpdate`, `clsAwardEligibility.BeforeDelete` |
| **Entry point** | `Business\SAIF.Business.Claim.Person\clsAwardEligibilityCollection.vb` |

## Steps

1. **Load all eligibility periods for the beneficiary.** `GetEligibilityPeriodsForBeneficiary` runs the collection query ordered by descending effective date, creates a `clsAwardEligibility` child for each row, and adds it to the managed list ([SQL-005](../sql/sql-005-select.md), [CL_AWARD_ELIGIBILITY](../database-tables.md#cl_award_eligibility)).
2. **Resolve the current period from the loaded set.** `CurrentPeriod` first looks for a period whose effective date is on or before today and whose expiration date is blank or on or after today; if none qualifies, it falls back to the latest effective-dated period already in memory.
3. **Create a new eligibility period when requested.** `clsAwardEligibility.Create` seeds the new child with the parent `PersonID`, today's date as the effective date, an empty expiration date, an empty benefit note, and zeroed update metadata.
4. **Validate each period's date boundaries.** The child rules require an effective date, reject expiration dates before the effective date, reject periods that start before the beneficiary birth date, and reject periods that run past the beneficiary death date ([BR-PER-010](../business-rules.md#br-per-010-award-eligibility-effective-date-is-required), [BR-PER-011](../business-rules.md#br-per-011-award-eligibility-expiration-date-cannot-precede-the-effective-date), [BR-PER-012](../business-rules.md#br-per-012-award-eligibility-cannot-start-before-the-beneficiary-birth-date), [BR-PER-013](../business-rules.md#br-per-013-award-eligibility-cannot-extend-past-the-beneficiary-death-date)).
5. **Validate collection-wide overlap rules.** The collection-level rule compares each period to every other period and blocks save when any period contains, starts inside, or ends inside another period's date range ([BR-PER-014](../business-rules.md#br-per-014-award-eligibility-periods-cannot-overlap)).
6. **Persist inserts, updates, and deletes through managed child saves.** `clsAwardEligibilityCollection.Save` calls `ApplyEdit()` and delegates row persistence to the child objects, which issue insert, update, or delete SQL as needed ([BR-PER-001](../business-rules.md#br-per-001-optimistic-concurrency-applies-to-crud-operations), [SQL-001](../sql/sql-001-insert.md), [SQL-015](../sql/sql-015-update.md), [SQL-020](../sql/sql-020-delete.md), [CL_AWARD_ELIGIBILITY](../database-tables.md#cl_award_eligibility)).
7. **Convert zero-row results into contention errors.** After delete or update, the child adds a DB-contention error when the database reports zero affected rows; after insert, it requires exactly one affected row and otherwise adds the same error ([BR-PER-001](../business-rules.md#br-per-001-optimistic-concurrency-applies-to-crud-operations)).
8. **Refresh collection ordering and current-period cache.** Every add or remove re-sorts the collection by effective date descending and clears the cached `CurrentPeriod` reference so the next read re-evaluates the loaded periods.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Load beneficiary eligibility periods]) --> Read[Retrieve periods ordered by effective date]
    Read --> Change{Add, edit, or delete a period?}
    Change -->|Add| NewPeriod[Initialize default period]
    Change -->|Edit| Validate[Validate period and collection]
    Change -->|Delete| DeletePeriod[Queue child delete]
    NewPeriod --> Validate
    Validate --> Valid{Validation passes?}
    Valid -->|No| Fail([Broken rules returned])
    Valid -->|Yes| Save[Run managed child save]
    DeletePeriod --> Save
    Save --> Rows{Expected rows affected?}
    Rows -->|No| Contention([Add DB-contention message])
    Rows -->|Yes| Done([Save completes and cache resets])
```

## Failure and edge-case behavior

- `AwardEligExpDate` reads as `Date.MaxValue` when the underlying smart date is empty, so open-ended periods participate in overlap checks as far-future ranges.
- Deleted rows bypass child validation because `clsAwardEligibility.IsValid` returns `True` for deleted objects.
- If no currently effective period exists, `CurrentPeriod` falls back to the latest effective-dated row already loaded rather than returning `Nothing`.
- Insert and update operations stamp the acting user from `DataPortalInfo.UserID` immediately before the SQL request is built.

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

## Sources
- `Business\SAIF.Business.Claim.Person\clsAwardEligibility.vb`
- `Business\SAIF.Business.Claim.Person\clsAwardEligibilityCollection.vb`