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

Research: SoT Foundations & Assignments (006)

This document resolves planning unknowns and records decisions for implementing foundations-first backup/restore and assignment-aware restore.

Decision: Foundation object endpoints and permissions

• Decision: Implement “foundation” backup/restore for:
  • Assignment Filters via deviceManagement/assignmentFilters (permission: DeviceManagementConfiguration.ReadWrite.All).
  • Scope Tags via deviceManagement/roleScopeTags (permission: DeviceManagementRBAC.ReadWrite.All).
  • Notification Message Templates via deviceManagement/notificationMessageTemplates (permission: DeviceManagementServiceConfig.ReadWrite.All, with localizedNotificationMessages treated as a future enhancement).
• Rationale: These are explicitly called out as SoT foundations and appear as dependencies in the IntuneManagement reference implementation.
• Alternatives considered:
  • Treat foundations as “manual prerequisites” only (no backup/restore) → rejected because it blocks safe assignment restore.
  • Store only names (no full payload) → rejected because restore needs full object definitions.

Decision: Assignment apply mechanism (Graph)

• Decision: Apply assignments using a per-resource .../{id}/assign Graph action (default), with request body shape:

  {
    "assignments": [
      {
        "target": {
          "@odata.type": "...",
          "groupId": "...",
          "deviceAndAppManagementAssignmentFilterId": "...",
          "deviceAndAppManagementAssignmentFilterType": "Include|Exclude"
        }
      }
    ]
  }
  

  and support type-specific overrides if needed.

• Rationale: Matches the IntuneManagement import approach and aligns with SoT “apply assignments after foundations exist”.

• Alternatives considered:

  • PATCH the resource with an assignments property → rejected because many Intune resources do not support assignment updates via PATCH.
  • Only restore object payloads, never assignments → rejected (SoT requires assignment-aware restore).

Decision: Mapping strategy (deterministic, safe)

• Decision: Produce and persist an “old → new” mapping for foundation objects by matching primarily on displayName (or name-equivalent), with collision handling:
  • If a unique match exists in the target tenant by name: reuse (map old → existing).
  • If no match exists: create (map old → created).
  • If multiple matches exist: create a copy with a predictable suffix and record “created_copy” in the report.
• Rationale: SoT requires determinism and auditability; mapping by opaque IDs is impossible across tenants.
• Alternatives considered:
  • Always create new objects regardless of matches → rejected due to duplication and name collision risk.
  • Hash-based matching (normalize and compare multiple fields) → deferred; start with name-based plus explicit collision handling.

Decision: Where to store mappings and restore decision report

• Decision: Store mapping + decisions in restore_runs.preview (dry-run) and restore_runs.results (execute), optionally mirrored into restore_runs.metadata for fast access.
• Rationale: The schema already supports JSON preview/results; this keeps the first iteration simple and audit-friendly.
• Alternatives considered:
  • Dedicated restore_mappings table → deferred until querying/reporting requirements demand it.

Decision: How to represent foundation snapshots in storage

• Decision: Store foundation snapshots as backup_items rows with:
  • policy_id = null
  • policy_type set to a dedicated type key (e.g. assignmentFilter, roleScopeTag, notificationMessageTemplate)
  • policy_identifier set to the Graph object id
  • payload containing the raw Graph resource
  • metadata containing normalized identifiers used for matching (e.g. displayName).
• Rationale: backup_items.policy_id is nullable; reusing the same snapshot container avoids schema churn.
• Alternatives considered:
  • New “foundation_snapshots” table → rejected for MVP due to extra migrations and duplication.

Decision: Conditional Access restore behavior (safety)

• Decision: Keep Conditional Access restore as preview-only, even in execute mode.
• Rationale: CA depends on identity objects (e.g., named locations) and is security-critical; SoT explicitly allows preview-first for risky items.
• Alternatives considered:
  • Allow CA restore with best-effort group/user mapping → rejected as too risky without complete dependency mapping.

Decision: Scope for assignment-aware restore (initial)

• Decision: Apply assignment mapping for existing supported configuration objects (policy types already in config/tenantpilot.php), focusing first on targets that include:
  • group targeting (groupId)
  • assignment filters (deviceAndAppManagementAssignmentFilterId/Type)
  • role scope tags (roleScopeTagIds) where applicable.
• Rationale: Incrementally delivers value without requiring support for all object classes in SoT.
• Alternatives considered:
  • Expand to named locations / terms of use / authentication strengths immediately → deferred (separate dependency set).