---
title: Timeliness of first payment evaluation
summary: Evaluates whether a claim's first time-loss payment was made on time by invoking the sp82067_TimelinessOf1stPayment stored procedure and rolling the due date onto the next state working day.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim
reference_type: package
operation_id: OP-BC-08
trigger: A caller requests the first-payment timeliness assessment for a claim through GetTimelinessOfFirstPayment
---

# Timeliness of first payment evaluation

Oregon workers' compensation law obliges an insurer to make the first time-loss payment within a statutory window of accepting the claim, and missing that window carries a penalty. This operation asks an Oracle procedure to assemble everything needed to judge that window — knowledge date, disability date, authorization and attempt dates, the calculated due date, the first payment actually issued, and the procedure's own timeliness verdict — and returns it as a read-only reporting object. The one piece of logic the operation adds itself is calendar handling: a due date that falls on a state holiday or weekend is reported as the next working day.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-BC-08 |
| **Trigger** | `clsTimelinessOfFirstPayment.GetTimelinessOfFirstPayment(dataPortalInfo, claimID, fromClaimDetail)` |
| **Inputs** | `ClaimID`; an optional flag indicating that the request originates from the claim detail screen |
| **Outputs** | Claim request code; claim type code; compensation-is-due, payment-is-timely, payments-exist, and rush-check flags; decision request, disability, knowledge, time-loss attempt, time-loss authorization, first issue, and time-loss due dates; first payment identifier; first initiator user; timely payment code; a return message |
| **Primary components** | `clsTimelinessOfFirstPayment.Criteria`, `clsTimelinessOfFirstPayment.BeforeRetrieve`, `clsTimelinessOfFirstPayment.AfterRetrieve`, `clsTimelinessOfFirstPayment.TimeLossDueDate` |
| **Entry point** | `Business\SAIF.Business.Claim\clsITimelinessOfFirstPayment.vb` |

## Steps

1. **Capture the claim and request scope.** The shared factory builds a Criteria holding the claim identifier and the claim-detail flag, then asks the framework data-access layer to retrieve the object.
2. **Bind the procedure call.** `BeforeRetrieve` switches the request to stored-procedure mode, names the timeliness procedure, tags the request, binds the claim identifier, and adds an output cursor named `recordset` ([SQL-023](../sql/SQL-023-saif-business-claim.md)).
   - When the caller set the claim-detail flag, an additional six-character request-type parameter carrying the literal value `Detail` is bound; otherwise the parameter is omitted entirely, so the procedure sees a different signature depending on the caller.
3. **Read the returned row.** `AfterRetrieve` opens the cursor and, when a row is present, reads the claim request code, claim type code, the compensation-is-due, payment-is-timely, payments-exist, and rush-check flags, the decision request, disability, knowledge, time-loss attempt, time-loss authorization and first issue dates, the first payment identifier, the first initiator user, the timely payment code, and the return message.
4. **Read the due date on the state calendar.** The time-loss due date is read as a plain date and stored in a smart date bound to the state holidays calendar rather than SAIF's own calendar, so that statutory deadlines follow the state's non-working days.
5. **Roll a non-working due date forward.** The public due-date property returns the stored date when it falls on a working day, and otherwise returns the next working day on the state calendar ([BR-016](../business-rules.md#br-016-time-loss-due-dates-falling-on-a-non-working-day-roll-to-the-next-state-working-day)).
6. **Handle a read failure.** Any exception raised while reading the row is caught and the inner exception's message is written into the return message property.
7. **Handle a missing claim.** When the cursor returns no row at all, the operation adds an error message with the text "Claim Not Found".
8. **Expose null checks.** Helper members report whether each date and the return message are empty, so a caller can distinguish an unset date from a real one without comparing to a sentinel value.
9. **Return the read-only object.** The object is marked read-only at construction and its create, insert, update, and delete SQL properties raise an application exception.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller requests the first-payment<br>timeliness assessment]) --> Detail{Called from<br>claim detail?}
	Detail -->|Yes| WithType[Bind claim id plus the<br>Detail request type]
	Detail -->|No| NoType[Bind claim id only]
	WithType --> Proc[Execute the timeliness procedure]
	NoType --> Proc
	Proc --> Row{Row returned?}
	Row -->|No| NotFound([Add Claim Not Found error])
	Row -->|Yes| Read[Read codes, flags, dates<br>and the return message]
	Read --> Cal[Store the due date on the<br>state holidays calendar]
	Cal --> Work{Due date is a<br>working day?}
	Work -->|Yes| AsIs([Report the due date as read])
	Work -->|No| Next([Report the next<br>state working day])
```

## Failure and edge-case behavior

- The request-type parameter is conditionally bound, so the procedure receives a different parameter list depending on the caller; a procedure signature change would break only one of the two paths.
- The catch block writes the inner exception's message without checking that an inner exception exists, so a top-level exception during the read raises a null-reference error out of the operation rather than being recorded.
- The "no row" branch reuses an error key belonging to a different class, so callers filtering error messages by key will not find the expected identifier.*
- The due-date property silently substitutes a different date than the one stored, so a caller comparing the reported due date against the procedure's raw output will see a mismatch on holidays and weekends.
- A direct load entry point exists that fills nothing because its fill routine is an empty template stub; objects created that way carry no data.*
- Despite the file name, no timeliness interface is declared or implemented; the class inherits the framework business base only.
- The object is read-only, so no part of the assessment can be written back.

## 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\clsITimelinessOfFirstPayment.vb`