# Quickstart: Adding a New Operation

## 1. Register Run Type
Add your new type constant to `App\Support\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):

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

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

// 3. Return View Link
return redirect(\App\Support\OperationRunLinks::viewUrl($tenant, $run));
```

## 4. Instrument Job
In your Job:

```php
public function handle(\App\Services\OperationRunService $service)
{
    try {
        // ... do work ...
        
        // Success
        $service->updateRun($this->run, status: 'completed', outcome: 'succeeded', summaryCounts: [
            'processed' => 100,
        ]);
    } catch (\Throwable $e) {
        // Failure
        $service->failRun($this->run, $e);
    }
}
```

## Notes: Monitoring & Run-Standard (Graph safety)

- **RBAC Wizard** (`TenantResource`): group search is **delegated-Graph-based** and the picker is **disabled without a delegated token**.
- **Restore Wizard** (`RestoreRunResource`): group mapping stays **DB-only** (Directory Cache / `entra_groups`) during the mapping phase — **no Graph calls** there; fallback helper text is always visible.