TenantAtlas/specs/054-unify-runs-suitewide/quickstart.md

Quickstart: Adding a New Operation

1. Register Run Type

Add your new type constant to App\Enums\OperationRunType (if using Enums) or just use the string convention resource.action.

2. Implement Idempotency Inputs

Define what makes a run "unique" for your feature.

• Example: ['scope' => 'full'] vs ['scope' => 'policy', 'policy_id' => 1].

3. Use OperationRunService

In your Start Action (Controller/Livewire):

// 1. Ensure Run
$run = $service->ensureRun($tenant, 'my_resource.action', $inputs, auth()->user());

// 2. Dispatch Job (if new)
if ($run->wasRecentlyCreated) {
    MyJob::dispatch($run, $inputs);
}

// 3. Return View Link
return redirect()->route('tenant.monitoring.operations.show', [$tenant, $run]);

4. Instrument Job

In your Job:

public function handle()
{
    // Update to Running
    $this->run->updateStatus(status: 'running');

    try {
        // ... do work ...
        
        // Success
        $this->run->updateStatus(
            status: 'completed', 
            outcome: 'succeeded', 
            summary: ['processed' => 100]
        );
    } catch (\Throwable $e) {
        // Failure
        $this->run->fail($e);
    }
}