TGM Expert provides comprehensive warranty management for energy assets, enabling operators to track warranty contracts, covered assets, and warranty claims through their full lifecycle from submission to payment.

Table of Contents¶

• Overview
• Data Model
• Warranty Types
• Warranty Lifecycle
• Claims Workflow
• API Reference
• Warranty Contracts API
• Warranty Claims API
• Multi-Tenancy
• Examples

Overview¶

Key Features¶

• Contract Management - Track warranty contracts with providers, terms, and coverage
• Asset Coverage - Link warranty contracts to specific assets (units)
• Claims Processing - Full claim lifecycle from draft to payment
• Expiry Tracking - Identify expiring and expired warranties proactively
• Financial Tracking - Track claimed amounts, approved amounts, and payments
• Provider Management - Store provider contact details per contract

Architecture¶

WarrantyContract
  ├── Company (tenant isolation)
  ├── WarrantyContractAsset[] (covered assets)
  │     └── Unit
  └── WarrantyClaim[] (claims against contract)
        ├── Unit (affected asset)
        ├── WorkOrder (related maintenance)
        ├── Failure (root cause)
        ├── SubmittedBy (User)
        └── ReviewedBy (User)

Data Model¶

WarrantyContract Entity¶

WarrantyContractAsset Entity¶

WarrantyClaim Entity¶

Database Tables¶

-- Migration: V54__warranty_management.sql
-- Tables: warranty_contracts, warranty_contract_assets, warranty_claims

Warranty Types¶

Warranty Lifecycle¶

Contract Status¶

Claims Workflow¶

  ┌───────┐     ┌───────────┐     ┌──────────────┐     ┌──────────┐
  │ DRAFT │ ──> │ SUBMITTED │ ──> │ UNDER_REVIEW │ ──> │ APPROVED │ ──> ┌──────┐
  └───────┘     └───────────┘     └──────────────┘     └──────────┘     │ PAID │ ──> ┌────────┐
                                         │                              └──────┘     │ CLOSED │
                                         │                                           └────────┘
                                         └──────────────────────────> ┌──────────┐
                                                                      │ REJECTED │
                                                                      └──────────┘

Claim Status Transitions¶

API Reference¶

Warranty Contracts API¶

Base URL¶

/api/warranties

Inherited CRUD Endpoints¶

Custom Endpoints¶

Get Expiring Warranties¶

GET /api/warranties/expiring?daysAhead=90&page=1&pageSize=25

Returns warranties that will expire within the specified number of days. Default is 90 days.

Get Expired Warranties¶

GET /api/warranties/expired?page=1&pageSize=25

Returns all warranties that are still marked ACTIVE but have passed their end date.

Get Assets Covered by Warranty¶

GET /api/warranties/{id}/assets

Response:

{
  "data": [
    {
      "id": 1,
      "coverageDetails": "Full turbine coverage including runner and guide vanes",
      "serialNumber": "TRB-2024-001"
    }
  ]
}

Add Asset to Warranty¶

POST /api/warranties/{id}/assets
Content-Type: application/json

{
  "unitId": 42,
  "coverageDetails": "Full turbine coverage",
  "serialNumber": "TRB-2024-001"
}

Warranty Claims API¶

Base URL¶

/api/warranty-claims

Inherited CRUD Endpoints¶

Custom Endpoints¶

Submit Claim¶

POST /api/warranty-claims/{id}/submit

Transitions the claim from DRAFT to SUBMITTED and records the submission date.

Review Claim¶

POST /api/warranty-claims/{id}/review
Content-Type: application/json

{
  "reviewNotes": "Claim is valid and within warranty terms.",
  "approved": true
}

Set approved: false to reject the claim. The reviewNotes will be stored as the rejection reason for rejected claims.

Close Claim¶

POST /api/warranty-claims/{id}/close

Marks the claim as CLOSED and records the resolution date.

Multi-Tenancy¶

All warranty contracts and claims are scoped to a company through the company_id foreign key. Users can only access warranty data belonging to their company.

Examples¶

Create a Warranty Contract¶

POST /api/warranties
Content-Type: application/json

{
  "contractNumber": "WAR-2024-001",
  "title": "GE Turbine Extended Warranty - Unit 3",
  "description": "5-year extended warranty covering turbine runner, guide vanes, and shaft assembly",
  "warrantyType": "EXTENDED",
  "providerName": "GE Renewable Energy",
  "providerContact": "John Smith",
  "providerEmail": "john.smith@ge.com",
  "providerPhone": "+1-555-0123",
  "startDate": "2024-01-01T00:00:00",
  "endDate": "2029-01-01T00:00:00",
  "coverageDescription": "Full parts and labor for turbine mechanical components",
  "maxClaimAmount": 5000000.00,
  "deductible": 25000.00,
  "contractCost": 750000.00,
  "exclusions": "Damage caused by operator negligence or force majeure events"
}

Create a Warranty Claim¶

POST /api/warranty-claims
Content-Type: application/json

{
  "title": "Runner Blade Crack - Unit 3",
  "description": "Crack discovered during annual inspection on blade 4",
  "warrantyContractId": 1,
  "unitId": 42,
  "failureId": 88,
  "workOrderId": 1234,
  "claimedAmount": 350000.00,
  "incidentDate": "2024-06-15T10:00:00"
}

Permission Resource Names¶

warranty_contracts  - for contract CRUD
warranty_claims     - for claim CRUD