> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SLA Management — Admin Guide

> Feature: SLA Definition Management & Configuration Spec: PF-83 Last Updated: 2026-03-17

**Feature:** SLA Definition Management & Configuration\
**Spec:** PF-83\
**Last Updated:** 2026-03-17

***

## Overview

This guide covers administrative configuration for SLA Management: creating and managing SLA definitions, configuring module settings, and assigning permissions.

## Permission Model

### Permission Keys

| Permission                 | Description                                              |
| -------------------------- | -------------------------------------------------------- |
| `pf.sla.view`              | Read access to SLA dashboard, definitions, and instances |
| `pf.sla.definition.manage` | Create, edit, and deactivate SLA definitions             |
| `pf.sla.instance.manage`   | Pause, resume, and extend SLA instances                  |
| `pf.sla.settings.manage`   | Configure SLA module settings                            |

### RLS Enforcement

All SLA tables enforce multi-tenant isolation via the `pf_has_org_access` SECURITY DEFINER function. Only users within the same organization can access SLA data. UPDATE policies include `WITH CHECK` clauses.

## Initial Setup

### Step 1: Configure Module Settings

SLA-related settings are stored in `pf_module_settings` (one row per organization):

| Setting                   | Type    | Description                                        | Recommendation  |
| ------------------------- | ------- | -------------------------------------------------- | --------------- |
| Default warning threshold | INTEGER | Percentage of deadline at which "at-risk" triggers | 75–80%          |
| Max active instances      | INTEGER | Cap on concurrent active SLA instances per org     | Start with 1000 |
| Max definitions           | INTEGER | Cap on SLA definitions per org                     | Start with 50   |

### Step 2: Create SLA Definitions

1. Navigate to **Settings** → **SLA** → **Definitions**
2. Click **New Definition**
3. Fill in:
   * **Name** — Descriptive label (e.g., "Lead Response Time")
   * **SLA Type** — `response_time`, `resolution_time`, `follow_up`, or `custom`
   * **Owning Core** — Which module this SLA belongs to (e.g., `ce`, `hr`, `rh`)
   * **Trigger Event** — The `fw_domain_events` event type that starts the clock
   * **Completion Event** — The event type that stops the clock
   * **Target Duration (hours)** — The deadline
   * **Warning Threshold (%)** — When to flag as "at-risk" (default: 80%)
   * **Escalation Config** — Optional escalation levels with notification targets
   * **Priority Overrides** — Optional per-priority deadline adjustments
4. Click **Save**

### Step 3: Assign Permissions

| Role             | Recommended Permissions                                             |
| ---------------- | ------------------------------------------------------------------- |
| org\_admin       | All SLA permissions                                                 |
| platform\_admin  | `pf.sla.view`, `pf.sla.definition.manage`, `pf.sla.settings.manage` |
| Staff / Managers | `pf.sla.view`                                                       |

**To assign:**

1. Go to **Settings** → **Roles & Permissions**
2. Select the role
3. Enable the required SLA permissions
4. Save

## Database Tables

| Table                | Purpose            | Key Fields                                                                                                                                                  |
| -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pf_sla_definitions` | SLA templates      | `id`, `organization_id`, `name`, `sla_type`, `owning_core`, `trigger_event_type`, `completion_event_type`, `target_duration_hours`, `warning_threshold_pct` |
| `pf_sla_instances`   | Running SLA clocks | `id`, `organization_id`, `definition_id`, `status`, `started_at`, `deadline_at`, `elapsed_seconds`, `remaining_seconds`, `percentage_elapsed`               |

## Event Integration

SLA Management publishes these events to `fw_domain_events`:

| Event Type                 | When Fired                         |
| -------------------------- | ---------------------------------- |
| `pf_sla_warning_triggered` | Instance crosses warning threshold |
| `pf_sla_breached`          | Instance exceeds deadline          |
| `pf_sla_completed`         | Instance completed within deadline |

These events can trigger PF-10 notifications for escalation.

## Best Practices

1. **Start simple** — Create 2–3 critical SLA definitions before expanding
2. **Set realistic thresholds** — Warning at 75–80% gives staff time to act
3. **Audit regularly** — Review compliance rates monthly; adjust targets as needed
4. **Least privilege** — Grant `definition.manage` only to admins; most staff need only `view`
5. **Use priority overrides** — Different urgency levels may need different deadlines

## Troubleshooting

| Issue                             | Solution                                                                                  |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| Definition not creating instances | Verify trigger event type matches events in `fw_domain_events`                            |
| Permission changes not reflecting | Permission queries have 5-minute stale time; wait or hard refresh                         |
| Instance never completes          | Check that the completion event type is correct and the event is actually being published |
| Too many active instances         | Review and increase the max active instances setting, or archive old definitions          |

## References

* [PF-83 Spec](../../specs/pf/specs/PF-83-sla-management-platform-layer.md)
* [User Guide](sla-management-user-guide.md)
* [Runbook](sla-management-runbook.md)
* [Migration Notes](sla-management-migration-notes.md)