TGM Expert provides comprehensive outage management for energy assets, enabling operators to track planned, forced, maintenance, and emergency outages with full lifecycle workflow including approval, capacity impact analysis, and financial tracking.

Table of Contents¶

• Overview
• Data Model
• Outage Types
• Outage Lifecycle
• Approval Workflow
• API Reference
• Multi-Tenancy
• Examples

Overview¶

Key Features¶

• Outage Tracking - Record and monitor planned and unplanned outages
• Approval Workflow - Built-in approval process for planned outages
• Capacity Impact - Track lost MW capacity and remaining capacity
• Financial Analysis - Estimate costs and lost revenue from outages
• Root Cause Tracking - Link outages to failures and work orders
• Unit Association - Associate outages with specific generating units
• Auto-numbering - Automatic unique outage number generation (OUT-xxx)

Architecture¶

OutageEvent
  ├── Company (tenant isolation)
  ├── Unit (affected asset)
  ├── WorkOrder (related maintenance)
  ├── Failure (root cause)
  ├── RequestedBy (User)
  └── ApprovedBy (User)

Data Model¶

OutageEvent Entity¶

Database Table¶

-- Table: outage_events
-- Migration: V53__outage_management.sql

CREATE TABLE outage_events (
    id BIGSERIAL PRIMARY KEY,
    company_id BIGINT NOT NULL REFERENCES companies(id),
    outage_number VARCHAR(50) NOT NULL UNIQUE,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    outage_type VARCHAR(30) NOT NULL,
    status VARCHAR(30) NOT NULL DEFAULT 'ACTIVE',
    unit_id BIGINT REFERENCES units(id),
    work_order_id BIGINT REFERENCES work_orders(id),
    failure_id BIGINT REFERENCES failures(id),
    -- ... timing, capacity, financial, approval fields
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Outage Types¶

Outage Lifecycle¶

                 ┌──────────┐
     Create ───> │  ACTIVE  │
                 └────┬─────┘
                      │
            ┌─────────┼──────────┐
            │         │          │
            v         v          v
     ┌───────────┐  ┌──────────┐  ┌───────────┐
     │ COMPLETED │  │ CANCELLED│  │  (stays   │
     └───────────┘  └──────────┘  │  ACTIVE)  │
                                  └───────────┘

Status Transitions¶

Approval Workflow¶

Planned outages go through an approval workflow:

     ┌─────────┐       ┌──────────┐
     │ PENDING │ ────> │ APPROVED │
     └─────────┘       └──────────┘
          │
          └──────────> ┌──────────┐
                       │ REJECTED │
                       └──────────┘

API Reference¶

Base URL¶

/api/outages

Inherited CRUD Endpoints (from BaseApiController)¶

Custom Endpoints¶

Complete Outage¶

POST /api/outages/{id}/complete
Content-Type: application/json

{
  "completionNotes": "Outage resolved. Unit back online at full capacity."
}

Response:

{
  "data": { "id": 1, "status": "COMPLETED", "actualEnd": "2024-01-15T14:30:00" },
  "message": "Outage completed successfully"
}

Get Active Outages¶

GET /api/outages/active?page=1&pageSize=25

Returns all outages with status ACTIVE, ordered by actual start date descending.

Get Outages by Unit¶

GET /api/outages/unit/{unitId}?page=1&pageSize=25

Returns all outages for a specific generating unit, ordered by creation date descending.

Approve Outage¶

POST /api/outages/{id}/approve
Content-Type: application/json

{
  "approvalNotes": "Approved for scheduled maintenance window."
}

Cancel Outage¶

POST /api/outages/{id}/cancel

Pagination Parameters¶

Multi-Tenancy¶

All outage events are scoped to a company through the company_id foreign key. This ensures tenant isolation - users can only see outages belonging to their company.

Examples¶

Create a Planned Outage¶

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

{
  "title": "Annual Turbine Inspection - Unit 3",
  "description": "Scheduled annual inspection of turbine runner and guide vanes",
  "outageType": "PLANNED",
  "unitId": 42,
  "plannedStart": "2024-03-01T08:00:00",
  "plannedEnd": "2024-03-05T18:00:00",
  "capacityMw": 150.000,
  "lostCapacityMw": 150.000,
  "remainingCapacityMw": 0.000,
  "estimatedCost": 250000.00,
  "lostRevenue": 180000.00,
  "requestedById": 10
}

Create an Emergency Outage¶

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

{
  "title": "Emergency Shutdown - Bearing Failure",
  "description": "High vibration alarm triggered emergency shutdown",
  "outageType": "EMERGENCY",
  "unitId": 42,
  "actualStart": "2024-01-15T03:45:00",
  "capacityMw": 150.000,
  "lostCapacityMw": 150.000,
  "rootCause": "Thrust bearing failure due to lubrication system malfunction",
  "failureId": 88,
  "workOrderId": 1234
}

Complete an Outage¶

POST /api/outages/1/complete
Content-Type: application/json

{
  "completionNotes": "Bearing replaced and unit restored to full capacity. Oil analysis performed."
}

Permission Resource Name¶

outage_events

Required permissions: outage_events.read, outage_events.create, outage_events.update, outage_events.delete