Skip to content

Claim-person name management

Claim-person name management loads the full name-history collection for a claim person, lets the caller add a new name row or edit an existing one, generates a phonetic name code for search indexing before every insert, and validates required fields and flag consistency before persisting inserts, updates, and deletes. The collection also enforces that exactly one name row is marked primary.

Field Value
Operation ID OP-PER-02
Trigger Caller retrieves name history for a person, edits one or more name rows, and calls Save() on the collection
Inputs PersonID; row fields FirstName, LastName, MiddleName, NameExtensionCode, PrimaryFlag, VoidFlag; acting user from DataPortalInfo.UserID
Outputs In-memory clsClaimPersonNameCollection; persisted inserts, updates, or deletes in CL_CLAIM_PERSON_NAME_HISTORY; broken rules and DB-contention messages
Primary components clsClaimPersonNameCollection.GetClaimPersonNameCol, clsClaimPersonNameCollection.NewClaimPersonName, clsClaimPersonName.BeforeInsert, clsClaimPersonName.BeforeUpdate, clsClaimPersonName.BeforeDelete, clsClaimPersonName.GetPhoneticNameCode
Entry point Business\SAIF.Business.Claim.Person\clsClaimPersonNameCollection.vb

Steps

  1. Retrieve the person's full name history. GetClaimPersonNameCol issues the collection read query for the given PersonID, loads each row into clsClaimPersonName, and tracks the highest PrimaryKeySubNum seen so far (SQL-009, CL_CLAIM_PERSON_NAME_HISTORY).
  2. Create a new name row when requested. NewClaimPersonName increments the cached maximum sub-number, creates a child row through clsClaimPersonName.NewClaimPersonName for the current PersonID, and adds it to the managed collection. Create() seeds blank name fields, a blank phonetic name code, PrimaryFlag = "N", and VoidFlag = "N" as defaults.
  3. Validate required fields and flag values on each dirty row. The row rules require a non-blank last name, require PrimaryFlag to be Y or N, require VoidFlag to be Y or N, and reject a row that is both primary and void (BR-PER-028, BR-PER-029, BR-PER-030, BR-PER-031).
  4. Validate the collection-wide primary selection. When the collection is dirty and non-empty, the collection-level rule counts primary rows and rejects the change unless exactly one row is marked primary (BR-PER-032).
  5. Generate the phonetic name code before insert. PhoneticNameCode's getter calls the shared GetPhoneticNameCode helper, which issues a scalar Oracle call to the phonetic-name package using the row's last, first, and middle names, and returns the derived code for persistence (BR-PER-002, SQL-008, DUAL).
  6. Insert a new name-history row. BeforeInsert builds the insert request with first, last, and middle names, upper-case variants, name-extension code, primary and void flags, the phonetic name code, and the acting user, binding all key values (SQL-002, CL_CLAIM_PERSON_NAME_HISTORY).
  7. On failure: if the insert affects zero rows, AfterInsert adds the standard DB-contention error message; otherwise it marks the row old.
  8. Update an existing name-history row. BeforeUpdate updates only PrimaryFlag, VoidFlag, and update metadata for the row identified by PersonID and PrimaryKeySubNum (SQL-017, CL_CLAIM_PERSON_NAME_HISTORY).
  9. On failure: if the update affects zero rows, AfterUpdate adds the DB-contention error message.
  10. Delete a name-history row. BeforeDelete deletes the row identified by PersonID and PrimaryKeySubNum (SQL-021, CL_CLAIM_PERSON_NAME_HISTORY).
  11. On failure: if the delete does not affect exactly one row, the standard DB-contention error message is added.
  12. Save the managed collection. clsClaimPersonNameCollection.Save calls ApplyEdit() before delegating to MyBase.Save(), so pending in-progress edits on the active row are committed before the collection-level save runs.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Load name history for one person]) --> Read[Retrieve name-history rows]
    Read --> Change{Add or edit a row?}
    Change -->|Add| NewRow[Assign next sub-number<br>and initialize defaults]
    Change -->|Edit| Validate[Validate row and collection]
    NewRow --> Validate
    Validate --> Valid{Validation passes?}
    Valid -->|No| Fail([Broken rules returned])
    Valid -->|Yes| Phonetic[Generate phonetic name code]
    Phonetic --> Save[Insert, update, or delete row]
    Save --> Rows{Expected rows affected?}
    Rows -->|No| Contention([Add DB-contention message])
    Rows -->|Yes| Done([Save completes])

Failure and edge-case behavior

  • PhoneticNameCode's getter has a side effect: every read issues a live Oracle call rather than returning a cached value, so repeated reads repeat the database round trip.
  • A row that is both primary and void is rejected by validation, so a caller cannot silently void the primary name.
  • The class defines UpdateClaimPersonSQL (an update against CL_CLAIM_PERSON.PRIMARY_LAST_NAME/PRIMARY_FIRST_NAME/PRIMARY_MIDDLE_NAME/PRIMARY_NAME_EXTENSION_CODE, SQL-016), but no caller in this source set invokes it during name-history save — the primary name fields on CL_CLAIM_PERSON are not kept in sync by this class.*
  • IsValid on the individual name row short-circuits to True when the row is not dirty, so unmodified rows are never re-validated.

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.Person\clsClaimPersonName.vb
  • Business\SAIF.Business.Claim.Person\clsClaimPersonNameCollection.vb