---
title: Worker profile management
summary: Retrieves and updates the injured-worker profile aggregate through the CCClaimDataApi worker endpoints.
status: draft
owner: SAIF
last_reviewed: 2026-07-30
library: SAIF.Business.Claim.Person
reference_type: package
operation_id: OP-PER-01
trigger: Caller requests a worker by worker ID, edits demographic and status fields, and saves the object.
---

# Worker profile management

Worker profile management retrieves and persists the core injured-worker profile — demographics, contact information, marital and phonetic-name data, and worker-level flags such as fraud conviction, hostile-worker, and support-order indicators. Unlike most other business objects in this library, `clsWorker` does not execute local Oracle SQL; every retrieve and update call is routed through `CCClaimDataApi`, and the phonetic-name code is derived through a call into `clsClaimPersonName`'s shared Oracle-backed helper.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-PER-01 |
| **Trigger** | Caller calls `GetWorker` with a worker ID, edits profile properties, and saves through the BOF API data-portal pipeline |
| **Inputs** | `WorkerID`; demographic and contact fields (birth/death dates, email, gender, phones, marital status, names, tax ID, PMA fields, flags); acting user context from the data portal |
| **Outputs** | `clsWorker` populated from the API response; persisted profile update via `CCClaimDataApi`; derived read-only `PhoneticNameCode`; error message when the API call does not return HTTP `OK` |
| **Primary components** | `clsWorker.GetWorker`, `clsWorker.Criteria.ConfigureRoutes`, `clsWorker.BeforeRetrieve`, `clsWorker.AfterRetrieve`, `clsWorker.BeforeUpdate`, `clsWorker.CreatePersonObject`, `clsWorker.PhoneticNameCode` |
| **Entry point** | `Business\SAIF.Business.Claim.Person\clsWorker.vb` |

## Steps

1. **Configure the API routes.** The nested `Criteria` class resolves the `CCClaimDataApi` client for controller `GeneralWorkerData` and registers a retrieve route `V1/GeneralWorkerData/Worker/{0}` and an update route `V1/GeneralWorkerData/Person`.
2. **Retrieve a worker by ID.** `GetWorker` builds a `Criteria` with the worker ID and calls the data-portal's API access layer, which invokes `BeforeRetrieve` to format the retrieve route with `WorkerID`.
3. **Map the API response into the profile.** `AfterRetrieve` reads the first `ResponseData(Of ClaimPerson)` result; when the status code is HTTP `OK`, it calls `Fill` to copy every profile field (dates, flags translated from `Y`/`N` via `BoolToString`, phone numbers, names, tax ID, PMA fields, and update metadata) from the `ClaimPerson` DTO into the object, then marks the object old.
   - On failure: if the status code is not `OK`, an error message is added (`"An Error occurred when CCClaimDataApi was called to retrieve data for workerId {WorkerID}"`) instead of populating the profile.*
4. **Track first-time birth/death date entry.** During `Fill`, if the birth date or death date is empty on load, the object records that no birth date, or no death date, previously existed, which downstream callers use to decide whether age-at-injury needs to be recalculated on other claims.*
5. **Derive the phonetic name code on demand.** The read-only `PhoneticNameCode` property calls `clsClaimPersonName.GetPhoneticNameCode`, passing the worker's primary last, first, and middle names to the shared Oracle-backed phonetic lookup ([BR-PER-002](../business-rules.md#br-per-002-phonetic-name-generation-is-required-for-name-maintenance), [SQL-008](../sql/sql-008-select.md), [DUAL](../database-tables.md#dual)).
6. **Build the update payload.** `BeforeUpdate` calls `CreatePersonObject`, which maps every in-memory property (dates, flags recomputed from `Y`/`N` markers, phone numbers, names, tax ID, PMA fields, and update metadata) into a `ClaimPerson` DTO, and sets the update route to `V1/GeneralWorkerData/Person`.
7. **Submit the update through the API access layer.** The data-portal's API access layer executes the update call with the mapped DTO as the request body; `AfterUpdate` performs no additional processing.*
8. **Track optimistic-concurrency-relevant edit flags.** `IsValid` recomputes whether `WorkerConflictFlag`, `DeathDate`, and `MaritalStatusCode` were modified during this edit session so downstream save logic and UI can react to those specific changes ([BR-PER-001](../business-rules.md#br-per-001-optimistic-concurrency-applies-to-crud-operations)).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
    Start([Caller requests worker by ID]) --> Route[Format retrieve route with WorkerID]
    Route --> Api[Call CCClaimDataApi GeneralWorkerData]
    Api --> Status{Response status OK?}
    Status -->|No| Error([Add error message; profile not populated])
    Status -->|Yes| Fill[Fill profile fields from ClaimPerson DTO]
    Fill --> Edit[Caller edits profile properties]
    Edit --> Phonetic{PhoneticNameCode read?}
    Phonetic -->|Yes| Derive[Call phonetic name lookup]
    Phonetic -->|No| Save
    Derive --> Save[Build ClaimPerson DTO and call update route]
    Save --> Done([Update submitted through API access layer])
```

## Failure and edge-case behavior

- Because `clsWorker` never issues local SQL, save-result verification (rows-affected or contention checks) is not performed by this object; success is inferred only from the API status code checked during retrieval.*
- `AfterUpdate` is an empty override, so the object does not inspect the update response for errors beyond what the API access layer itself surfaces.*
- `PhoneticNameCode`'s getter has a side effect: reading it issues a live Oracle call through `clsClaimPersonName.GetPhoneticNameCode` rather than returning a cached value.
- `GetEmptyWorker` accepts a worker ID parameter but ignores it and always returns a blank `clsWorker`, so callers relying on it to pre-populate the worker ID will not get one.*

## 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.Person\clsWorker.vb`
- `Business\SAIF.Business.Claim.Person\clsClaimPersonName.vb`