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):

// 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:

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.

1.6 KiB Raw Blame History