Skip to content

Tax ID history management

Tax ID history management loads all history rows for one claim person, lets the caller add or edit individual rows with collection-level primary-selection checks, and persists child-row inserts, updates, and deletes against the person tax ID history table. The operation also runs duplicate and primary-tax-ID validation queries before save.

Field Value
Operation ID OP-PER-04
Trigger Caller retrieves tax ID history for a person, changes one or more rows, and calls Save() on the collection
Inputs PersonID; optional PrimaryFlag for a new row; row fields TaxID, PrimaryFlag, VoidFlag; acting user from DataPortalInfo.UserID
Outputs In-memory collection of tax ID history rows; persisted inserts, updates, or deletes in CL_PERSON_TAX_ID_HISTORY; broken rules, warnings, and DB-contention messages
Primary components clsPersonTaxIDHistoryCollection.GetPersonTaxIDHistoryCollection, clsPersonTaxIDHistoryCollection.NewPersonTaxIDHistory, clsPersonTaxIDHistory.BeforeInsert, clsPersonTaxIDHistory.BeforeUpdate, clsPersonTaxIDHistory.BeforeDelete
Entry point Business\SAIF.Business.Claim.Person\clsPersonTaxIDHistoryCollection.vb

Steps

  1. Retrieve the person's full tax ID history. GetPersonTaxIDHistoryCollection issues the collection read query, loads each row into clsPersonTaxIDHistory, and tracks the highest PRIMARY_KEY_SEQ_NUM for later child creation (SQL-013, CL_PERSON_TAX_ID_HISTORY).
  2. Create a new history row when requested. NewPersonTaxIDHistory increments the cached maximum sequence number, creates a child row for the current PersonID, copies the optional primary flag into the child criteria, and initializes the new row with a blank tax ID and VoidFlag = "N".
  3. Validate tax ID format and flag values on each dirty row. clsPersonTaxIDHistory.AddBusinessRules enforces a nine-digit tax ID, a PrimaryFlag of Y or N, and a VoidFlag of Y or N (BR-PER-003, BR-PER-004, BR-PER-005).
  4. Validate primary and duplicate-tax-ID behavior.
  5. If the row is marked primary and the tax ID has nine digits, query for another worker-person row with the same tax ID and a primary flag; any match blocks save (BR-PER-006, SQL-011, CL_PERSON_TAX_ID_HISTORY, CL_CLAIM_PERSON).
  6. If the tax ID has nine digits, query for any other person using the same value; primary rows check only active non-primary rows, while non-primary rows check all other rows. A match adds a warning rather than a blocking error (BR-PER-007, SQL-010, SQL-012, CL_PERSON_TAX_ID_HISTORY).
  7. If a row is both primary and void, validation fails (BR-PER-009).
  8. Validate the collection-wide primary selection. Before save, the collection-level rule counts primary rows across the managed list and rejects the change when more than one row is primary (BR-PER-008).
  9. Persist each child-row insert, update, or delete through BOF save processing. clsPersonTaxIDHistoryCollection.Save calls ApplyEdit() and then delegates to the managed child objects, which execute the matching row-level SQL for new, edited, and deleted items (BR-PER-001, SQL-003, SQL-019, SQL-022, CL_PERSON_TAX_ID_HISTORY).
  10. Translate rows-affected mismatches into contention errors. After each insert, update, or delete, the child object checks the returned row count and adds the standard DB-contention message when the operation does not affect exactly one row (BR-PER-001).

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Load tax ID history for one person]) --> Read[Retrieve history rows]
    Read --> Change{Add, edit, or delete a row?}
    Change -->|Add| NewRow[Assign next sequence<br>and initialize defaults]
    Change -->|Edit| Validate[Validate row and collection]
    Change -->|Delete| DeleteRow[Queue child delete]
    NewRow --> Validate
    Validate --> Valid{Validation passes?}
    Valid -->|No| Fail([Broken rules or warnings returned])
    Valid -->|Yes| Save[Run managed child save]
    DeleteRow --> Save
    Save --> Rows{Rows affected = 1?}
    Rows -->|No| Contention([Add DB-contention message])
    Rows -->|Yes| Done([Save completes])

Failure and edge-case behavior

  • Duplicate-tax-ID checks are asymmetric by design: primary rows query active non-primary duplicates, while non-primary rows query all other rows.
  • Duplicate matches from SSNInUse are warnings, so they do not block save by themselves.
  • The collection-level single-primary rule only runs when the collection is dirty, so untouched collections are not revalidated.
  • A primary tax ID cannot be voided, even if every other field is valid.
  • The class exposes UpdateClaimPersonSQL, but this operation does not call it anywhere in the tax-ID-history save path.

Sources

  • Business\SAIF.Business.Claim.Person\clsPersonTaxIDHistory.vb
  • Business\SAIF.Business.Claim.Person\clsPersonTaxIDHistoryCollection.vb