TenantAtlas/specs/006-sot-foundations-assignments/spec.md

Feature Specification: SoT Foundations & Assignments

Feature Branch: 006-sot-foundations-assignments
Created: 2025-12-25
Status: Draft
Input: User description: "SoT Foundations & Assignments: implement backup/restore foundations (assignment filters, scope tags, notification templates) and add assignment-aware backup/restore pipeline with ID mapping for core Intune objects; keep Conditional Access restore preview-only until named locations/mapping exist."

User Scenarios & Testing (mandatory)

User Story 1 - Restore Foundations First (Priority: P1)

As an admin, I want to back up and restore the core "foundation" objects that other configurations depend on (assignment filters, scope tags, and compliance notification templates), so that later restores can reliably re-apply assignments and dependencies.

Why this priority: Without these foundations, restores either fail or must skip assignments/dependencies, which reduces trust and makes outcomes unpredictable.

Independent Test: In a test tenant with at least one filter, one scope tag, and one notification template: create a backup snapshot, then restore into a tenant where they are missing. Verify that the restored objects exist and that a mapping from old IDs to new IDs is produced.

Acceptance Scenarios:

1. Given a tenant with assignment filters, When a backup is created and later restored into a tenant missing those filters, Then missing filters are created and the restore reports the old→new identifier mapping.
2. Given a tenant with scope tags, When a restore runs, Then scope tags are restored before any dependent objects are applied.
3. Given a tenant with compliance notification templates, When a restore runs, Then templates are restored before applying compliance policy scheduled actions.

---

User Story 2 - Apply Assignments Safely (Priority: P2)

As an admin, I want restores to apply assignments for supported configuration objects using the foundation mappings, so that a restore reproduces intended targeting while staying safe and auditable.

Why this priority: Restoring payloads without assignments is incomplete; restoring assignments without safe mapping can be dangerous.

Independent Test: Restore a small set of supported configurations that include assignments with filters and scope tags. Verify that assignments are applied when mappings exist, and skipped with a clear reason when mappings are missing.

Acceptance Scenarios:

1. Given a configuration object whose assignments reference filters/scope tags that exist (or can be mapped), When restore executes, Then assignments are applied and reported as applied.
2. Given a configuration object whose assignments reference a missing dependency (e.g., an unknown filter), When restore executes, Then the assignment is skipped (not broadly applied) and a human-readable reason is recorded.
3. Given an object restore with name collisions, When the system cannot unambiguously match a target, Then it creates a copy with a predictable suffix and records this decision in the restore report.

---

User Story 3 - Conditional Access Stays Preview-Only (Priority: P3)

As an admin, I want to preview Conditional Access (CA) policies and their dependencies, but I do not want CA restore to execute automatically until dependency mapping is supported.

Why this priority: CA is security-critical and often depends on other objects (like named locations) and identity references. A preview still delivers value without risking outages.

Independent Test: Include CA policies in a backup and run restore in "preview" mode. Verify preview shows intended actions and highlights missing dependencies, while execute mode does not apply CA changes.

Acceptance Scenarios:

1. Given a backup containing CA policies, When a restore preview is generated, Then CA items appear in preview with a clear "preview-only" indicator.
2. Given a restore execution (non-dry-run), When CA items are included, Then the system does not apply CA changes and records them as preview-only/skipped.

Edge Cases

• Missing permissions: backup/restore continues for other object types and clearly reports which categories failed due to permissions.
• Name collisions: multiple objects share the same display name; system must avoid ambiguous updates.
• Missing identity references: group/user references cannot be resolved; system must skip the assignment and report.
• Large tenants: operations must cope with pagination and partial failures without losing auditability.
• Throttling/transient failures: system retries safely and produces a final report if some items could not be processed.

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST support backup and restore of foundation objects: assignment filters, scope tags, and compliance notification templates.
• FR-002: System MUST restore foundation objects before applying any dependent configurations.
• FR-003: System MUST produce an identifier mapping report (old→new) for restored foundation objects.
• FR-004: System MUST apply assignments for supported configurations using the identifier mapping.
• FR-005: System MUST skip assignments that cannot be safely mapped (e.g., missing dependencies) and MUST record a clear skip reason.
• FR-006: System MUST be able to run in preview mode that produces the same decision report as execute mode, without making changes.
• FR-007: System MUST NOT delete objects in the target tenant as part of restore.
• FR-008: System MUST record an audit trail for backup and restore actions, including outcomes, partial failures, and skipped items.
• FR-009: System MUST prevent conflicting simultaneous restore executions for the same tenant (single-writer safety).
• FR-010: System MUST keep Conditional Access restore as preview-only until dependency mapping for CA is supported.

Key Entities (include if feature involves data)

• Foundation Object Snapshot: A captured representation of an assignment filter, scope tag, or notification template.
• Assignment Snapshot: Captured targeting rules associated with a configuration object.
• Restore Mapping: A mapping of source identifiers to newly created target identifiers.
• Restore Report: A structured outcome summary containing applied items, skipped items, reasons, and any created copies.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In a tenant with at least 10 foundation objects, a full foundations restore completes with ≥ 99% of items either applied or explicitly skipped with a reason.
• SC-002: For supported configuration objects with assignments, ≥ 95% of assignments are either applied correctly or skipped with a clear reason (no silent failures).
• SC-003: Restore preview generation for 100 selected items completes in under 2 minutes in a typical admin environment.
• SC-004: Admins can complete a restore workflow (preview → execute) with no ambiguous outcomes: every selected item ends in Applied / Created Copy / Skipped / Failed with a recorded reason.