# 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.