---
title: Award payment pending transition
summary: Moves a claim's active award to pending status and resets its benefit payments to in-progress so the payment can be re-approved.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Business.Claim
reference_type: package
operation_id: OP-BC-02
trigger: A caller retrieves the active award for a claim through GetSetAwardPaymentPending and saves it
---

# Award payment pending transition

An award that has already been approved may need to be re-worked — for example when the underlying claim data changes after approval. This operation finds the single active award on a claim, flips it to pending status, and simultaneously rolls the award's benefit payments back to in-progress with the initiator and approver cleared, so the payment must travel through initiation and approval again before it can be issued.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-BC-02 |
| **Trigger** | `clsSetAwardPaymentPending.GetSetAwardPaymentPending(dataPortalInfo, claimID)` followed by `Save()` |
| **Inputs** | `ClaimID`; the acting portal user supplied by the framework as the update user |
| **Outputs** | The SAIF award number and its update number; `HasActiveAward` and `BenefitType`; award status set to pending; benefit payment status set to in-progress; error messages `UpdateError` and `#PAYUPD#` |
| **Primary components** | `clsSetAwardPaymentPending.BeforeRetrieve`, `clsSetAwardPaymentPending.AfterRetrieve`, `clsSetAwardPaymentPending.RetrieveBenefitPayment`, `clsSetAwardPaymentPending.BeforeUpdate`, `clsSetAwardPaymentPending.AfterUpdate`, `clsSetAwardPaymentPending.ProcessBenefitPayment` |
| **Entry point** | `Business\SAIF.Business.Claim\clsSetAwardPaymentPending.vb` |

## Steps

1. **Find the claim's active award.** `BeforeRetrieve` issues a result-set request that selects the SAIF award number and update number from the award table for the claim, filtered to an award status code of `A` ([SQL-025](../sql/SQL-025-saif-business-claim.md), [CL_AWARD](../database-tables.md#cl_award)).
2. **Fill the object from the first row.** `AfterRetrieve` fills the object from row zero of the result set and marks it old. When no row is returned the object stays empty and `HasActiveAward` remains false, so the caller gets a silent no-op rather than an error.
3. **Read the award's benefit payment.** When an active award was found, `RetrieveBenefitPayment` opens a second portal request that selects the benefit type code and update number from the benefit payment table for the award number ([CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)). This statement is not represented in the SQL catalog.*
   - Only the first row is consumed; a `HavePayment` flag is set and the initiator user is reset to a single space so the update in step 6 blanks the column.
   - The object is then marked dirty so the framework will run the update path on save.
4. **Resolve the benefit type.** The `BenefitType` property maps the retrieved benefit type code to its enumerated value through the shared benefit type code map.

   > **Origin**: The benefit type code map is provided by `CodeMappings.GetBenefitTypeMap` in `SAIF.Business` and executed on behalf of this operation; see [Lookup and reference data hydration](../../saif-business/operations/lookup-and-reference-data-hydration.md).
5. **Set the award to pending.** On save, `BeforeUpdate` runs the award update that writes an award status code of `P`, `SYSDATE`, an incremented update number, and the acting user, keyed on the SAIF award number ([BR-011](../business-rules.md#br-011-setting-an-award-to-pending-resets-its-benefit-payments-to-in-progress), [SQL-037](../sql/SQL-037-saif-business-claim.md), [CL_AWARD](../database-tables.md#cl_award)).
   - If exactly one row is not affected: add `UpdateError` with the message "The Award was NOT succesfully updated to Pending" and stop; the benefit payments are left untouched ([BR-008](../business-rules.md#br-008-updatedelete-row-count-must-equal-1)).
6. **Reset the benefit payments.** Only after a successful award update, and only when a payment was found in step 3, `ProcessBenefitPayment` updates the benefit payment rows for the award number, setting the benefit status code to `0`, nulling the approver user, blanking the initiator user, and writing `SYSDATE`, an incremented update number, and the acting user ([BR-011](../business-rules.md#br-011-setting-an-award-to-pending-resets-its-benefit-payments-to-in-progress), [CL_BENEFIT_PAYMENT](../database-tables.md#cl_benefit_payment)). This statement is not represented in the SQL catalog.*
   - If the affected row count is `0`: add error `#PAYUPD#` — "The Payment Records for this Award were NOT succesfully updated to In Progress." ([BR-008](../business-rules.md#br-008-updatedelete-row-count-must-equal-1)).
7. **Report the result.** `Save()` returns success only when the object carries no error messages, so a payment-update failure surfaces to the caller even though the award status change has already been written.
8. **Create, insert, and delete are refused.** The Criteria raises an application exception from its create, insert, and delete SQL properties; the object exists solely to perform the retrieve-then-update transition.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller requests the pending<br>transition for a claim]) --> Sel[Select the active award<br>for the claim]
	Sel --> Found{Active award found?}
	Found -->|No| NoAward([Object stays empty;<br>nothing to save])
	Found -->|Yes| Pay[Read the award's<br>benefit payment row]
	Pay --> Dirty[Mark dirty and<br>blank the initiator]
	Dirty --> Upd[Update award status to pending]
	Upd --> Rows{Rows affected = 1?}
	Rows -->|No| Err([Add UpdateError;<br>payments untouched])
	Rows -->|Yes| HasPay{Benefit payment found?}
	HasPay -->|No| Done([Return success])
	HasPay -->|Yes| PayUpd[Set payment status to in-progress,<br>clear approver and initiator]
	PayUpd --> PRows{Rows affected = 0?}
	PRows -->|Yes| PErr([Add PAYUPD error])
	PRows -->|No| Done
```

## Failure and edge-case behavior

- The award update and the payment update are two separate statements with no transaction boundary in this object, so a payment-update failure leaves the award pending while its payments remain approved.
- Only the first benefit payment row is read; if an award carries several payment rows, the retrieved benefit type and update number reflect only one of them, although the update statement in step 6 is keyed on the award number and therefore affects all of them.*
- A claim with no active award produces neither data nor an error message; the caller must test `HasActiveAward` to distinguish "nothing to do" from "done".
- A claim with more than one active award is not detected; only row zero is used.*
- The initiator user is blanked by writing a single space rather than a null, so downstream readers must treat a blank initiator as "not yet initiated".*
- The object registers no business rules, so nothing prevents transitioning an award that a caller should not be re-opening.

## 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\clsSetAwardPaymentPending.vb`
- `Business\SAIF.Business\mdlCodeMaps.vb`