guidewire-core-workflow-b

What this skill does

# Guidewire ClaimCenter Workflow

## Overview

Drive the ClaimCenter claims lifecycle through Cloud API and survive the failure modes that derail naive automation. This is the workflow used by FNOL portals, IVR claims intake, partner-of-record APIs, and reserve-setting jobs. Assumes `guidewire-install-auth` provides the bearer token and `guidewire-sdk-patterns` provides the retrying client with checksum round-trip.

Five production failures this skill prevents:

1. **Duplicate FNOL from multi-source intake** — the same loss event is reported by the caller, the claimant, and the broker; without dedup logic three claims land on the same loss with three reserves.
2. **Payment before reserve** — code creates a payment without first setting a reserve in the matching cost category; API returns `422 reserve-required`.
3. **Authorization-tier violation** — an integration with payment role `cc.payment.write` attempts a payment above its authorization limit; API returns `422 authorization-required` and the payment lands in pending-approval.
4. **Premature settlement** — claim closed before all open reserves are zeroed or all open activities resolved; reopens compound work and generate audit findings.
5. **Reopen vs. new claim confusion** — late-arriving evidence on a closed claim creates a new claim with a different number, breaking the loss-event continuity downstream finance and analytics depend on.

## Prerequisites

- A working auth + SDK layer per `guidewire-install-auth` and `guidewire-sdk-patterns`
- Cloud API roles `cc.claim.write`, `cc.reserve.write`, `cc.payment.write` assigned per least privilege; payment authorization tier matches the integration's expected payment range
- Knowledge of the carrier's loss-cause code list (`AUTO`, `PROPERTY`, `WORKERSCOMP`, etc.) and cost-category configuration (`body`, `parts`, `medical`, `legal`)
- A loss-dedup key strategy (typically: `policyNumber + lossDate + lossCause + reporterId`)

## Instructions

### 1. FNOL with deduplication

Before creating a claim, check whether one already exists for the same loss event. The dedup key combines policy, loss date, loss cause, and the reporting party.

```typescript
async function findExistingClaim(policyNumber: string, lossDate: string, lossCauseCode: string): Promise<Claim | null> {
  const url = `${BASE}/cc/rest/v1/claims?filter=policyNumber+eq+'${policyNumber}'+and+lossDate+eq+'${lossDate}'+and+lossCause.code+eq+'${lossCauseCode}'`;
  const res = await fetch(url, { headers: { Authorization: `Bearer ${await getToken()}` } });
  const body = await res.json();
  return body.data[0] ?? null;
}

const existing = await findExistingClaim(policyNumber, lossDate, lossCauseCode);
if (existing) {
  await addReporterToExistingClaim(existing.attributes.id, reporter); // additional reporter, same loss
  return { status: "deduplicated", claimNumber: existing.attributes.claimNumber };
}
const claim = await createClaim({ policyNumber, lossDate, lossCauseCode, reporter, description });
```

The dedup window is loss-cause-specific. For `AUTO`, same-day same-cause is almost certainly the same event. For `PROPERTY`, weather events can produce multiple legitimate same-cause same-day claims across distinct locations — extend the dedup key with the loss-location ZIP for that line.

### 2. Reserve setting before any payment

Reserves communicate the carrier's expected outflow per cost category. The Cloud API enforces "reserve before payment" — payments without a matching reserve return `422 reserve-required`.

```typescript
await retryable(async () => {
  const res = await fetch(`${BASE}/cc/rest/v1/claims/${claimId}/reserves`, {
    method: "POST",
    headers: { Authorization: `Bearer ${await getToken()}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
    body: JSON.stringify({
      data: { attributes: {
        reserveAmount: { amount: 5000, currency: "usd" },
        costType: { code: "claimcost" },
        costCategory: { code: "body" },
        reserveLine: { exposure: { id: exposureId } },
      } },
    }),
  });
  if (!res.ok) throw await mapError(res, "POST", `/cc/rest/v1/claims/${claimId}/reserves`);
});
```

Reserve adjustments (raise/lower) use PATCH on the reserve resource; checksum round-trip applies. Lowering a reserve below cumulative payments returns `422` — fix payments first or use a reserve transfer.

### 3. Payments with authorization-tier handling

The integration's authorization tier is configured per Service Application in GCC. A payment that exceeds the tier does not error — it lands in `Status: PendingApproval` and waits for a supervisor:

```typescript
const payment = await fetch(`${BASE}/cc/rest/v1/claims/${claimId}/payments`, {
  method: "POST",
  headers: { Authorization: `Bearer ${await getToken()}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
  body: JSON.stringify({ data: { attributes: paymentBody } }),
}).then(r => r.json());

if (payment.data.attributes.status.code === "PendingApproval") {
  await emitPaymentEscalationEvent({ claimId, paymentId: payment.data.attributes.id, amount: paymentBody.amount });
  return { status: "pending-approval", paymentId: payment.data.attributes.id };
}
```

Do not poll the payment for completion. Subscribe to the App Event for payment-status-change and react asynchronously — this is covered in `guidewire-webhooks-integrations`.

### 4. Settlement with completeness gates

A claim should only close when every exposure has either been paid in full, denied, or has reserves zeroed; and every required activity (subro decision, salvage decision, supervisor sign-off) is completed.

```typescript
async function isReadyToSettle(claimId: string): Promise<{ ready: boolean; blockers: string[] }> {
  const claim = await getClaim(claimId, "exposures,activities,reserves");
  const blockers: string[] = [];
  for (const reserve of claim.included.reserves) {
    if (reserve.attributes.status.code === "Open" && reserve.attributes.amount.amount > 0) {
      blockers.push(`reserve ${reserve.id} is ${reserve.attributes.amount.amount} open`);
    }
  }
  for (const activity of claim.included.activities) {
    if (activity.attributes.required && activity.attributes.status.code !== "Completed") {
      blockers.push(`activity ${activity.id} (${activity.attributes.subject}) not completed`);
    }
  }
  return { ready: blockers.length === 0, blockers };
}
```

Only call the close endpoint when `isReadyToSettle` returns `ready: true`. Premature closure works but creates audit findings and forces reopens.

### 5. Reopen vs. new claim

Late-arriving evidence on a closed claim is almost always the same loss event. Reopen the existing claim rather than creating a new one — claim numbers must remain stable for the underlying loss event so finance, analytics, and regulatory reporting continue to roll up correctly.

```typescript
async function handleLateEvidence(claimNumber: string, evidence: Evidence): Promise<Result> {
  const claim = await getClaimByNumber(claimNumber);
  if (claim.attributes.status.code === "Closed") {
    await fetch(`${BASE}/cc/rest/v1/claims/${claim.attributes.id}/reopen`, {
      method: "POST",
      headers: { Authorization: `Bearer ${await getToken()}`, "Idempotency-Key": idempotencyKey },
      body: JSON.stringify({ data: { attributes: { reason: evidence.reason } } }),
    });
  }
  await attachEvidence(claim.attributes.id, evidence);
  return { status: "reopened", claimNumber };
}
```

The reopen endpoint requires a reason — log the evidence type and source so the audit trail explains why the claim was reopened.

## Output

A complete ClaimCenter workflow integration ships with all of the following:

- A FNOL function with a configurable dedup key (per loss-cause line) that returns `{ status: "created" | "deduplicated", claimNumber }`.
- Reserve-setting that runs before any payment in the same cost category, with a transfer/adjustment helper for raising or lowering reserv