> For the complete documentation index, see [llms.txt](https://helpdesk.augmentt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.augmentt.com/modules/secure/purview/retention.md). # Retention Retention keeps or deletes content automatically, on a schedule you control, so information doesn't linger past a legal hold requirement or a company records policy — and doesn't get destroyed before it should. Microsoft splits this into two genuinely different objects, and Augmentt keeps that split rather than blending them: * A **retention policy** is container-level: it targets locations (mailboxes, SharePoint sites, OneDrive accounts, Teams chats/channels) and applies to everything in them. * A **retention label** is item-level: a tag applied to an individual email, document, or record, carrying its own retention behavior independent of where that item lives. {% hint style="warning" %} Purview is a separately licensed add-on, not part of the base Secure module. If a client isn't authorized for it, this tab shows a message directing you to contact **** instead of the usual controls. {% endhint %} You'll find it at **Secure > Purview > Retention**, split into **Retention policies**, **Labels**, and **Templates** (covering both). ## Retention policies The **Retention policies** list shows each policy's: * **Status** — Active / Not active (retention policies don't have DLP's Test/Enforce concept), shown as e.g. "Active (Pending)" or "Active (Pending Deletion)" while a change is still propagating. * **Scope** — one of three shapes: **entire tenant** (every workload location included with `All`), **static** (specific groups/sites named explicitly), or an **adaptive scope** (a dynamic, query-based scope Augmentt surfaces read-only — it isn't editable from Augmentt, only viewable). * **Locations** — per-workload include/exclude detail across Exchange, SharePoint, OneDrive, Teams channel messages, and Teams chat messages, each independently scoped. * **Duration** and **Action at end of period**. * **Admin units** (`PolicyRBACScopes`) and Microsoft sync status. ### Every field in a retention policy | Field | What it controls | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** / **Comment** | Display name and admin-facing description. Name can't be changed after creation via Microsoft's `Set-RetentionCompliancePolicy` — only comment and settings. | | **Enabled** | Whether the policy is active. | | **Locations** | Exchange, SharePoint, OneDrive — toggled independently in Augmentt's create/edit flow. (Teams channel/chat locations exist on live policies and are shown, but see the constraint below.) | | **Exchange scope mode** | **Entire tenant** (`ExchangeLocation: ['All']`) or **selected groups** (specific distribution groups / mail-enabled security groups — not Microsoft 365 Groups, which Exchange retention locations don't accept). | | **Included / excluded groups** | Only meaningful in "selected groups" mode; exclusions can't overlap with inclusions. | | **Retention duration** | A number of days, or `Unlimited`. | | **Duration display hint** | Years / Months / Days — purely a display convenience Microsoft stores alongside the raw day count. | | **Retention action** (on the underlying rule) | **Retain items only** (`Keep`), **retain then delete** (`KeepAndDelete`), or **delete only, no retention** (`Delete`). | | **Expiration date option** | When the retention clock starts: from **creation** (`CreationAgeInDays`) or **last modification** (`ModificationAgeInDays`). Not applicable when duration is `Unlimited`. | One Microsoft constraint carries straight through to the UI: a single **static** retention policy can't mix Teams locations with Exchange/SharePoint/OneDrive — Teams retention needs its own separate policy. Augmentt's create/edit flow only exposes Exchange, SharePoint, and OneDrive toggles for that reason; Teams-scoped policies exist and are viewable, but aren't created or edited through the same flow (see **What Retention doesn't do yet** below). {% hint style="warning" %} After a create, edit, or delete, a policy can show **Pending Propagation** while Microsoft finishes applying the change — Microsoft Purview can take up to a week to fully propagate a retention policy. Editing stays unavailable until sync completes. Separately, an edit that touches **both** the policy-level fields (locations, scope, enabled) **and** the underlying rule fields (duration, action, expiration option) requires two sequential Microsoft writes — the policy update lands first, then the rule update is queued once distribution finishes. Augmentt surfaces a warning when your edit falls into this dual-update case, since it takes noticeably longer and shows Pending Propagation in between. {% endhint %} Creating and deploying a retention policy follows the same template → deploy pattern as DLP: pick a template (or start blank), then at deploy time choose duration, end-of-period action, when the clock starts, and the locations/scope — Augmentt never defaults the scope choice, you choose entire-tenant vs. selected-groups every time. ## Retention labels The **Labels** tab manages retention labels (Microsoft's `ComplianceTag` object) directly, with no template/deploy layer of their own. Each label's settings mirror Microsoft's own "Define label settings" step in the Purview portal: * **Name** — locked after creation; only description/settings can change afterward. * **Description for users** (`Notes`) and **description for admins** (`Comment`) — the same user-facing/admin-facing pairing sensitivity labels use (tooltip vs. comment). * **Label settings mode** — three mutually exclusive modes: * **Retain items forever or for a specific period** (`retain`) — holds items during the retention period. Underlying action is `Keep` or `KeepAndDelete`. * **Delete items automatically when a period ends, without retaining them first** (`enforce`) — no hold during the period; the action is fixed to `Delete` once the period ends. * **Mark items as a record without any retention behavior** (`justLabel`) — classification only, no duration/action/type fields apply. * **Retention duration** (retain/enforce modes only) — presets of 1 / 3 / 7 years, or a custom day count; `Unlimited` is offered only in **Retain** mode (Enforce doesn't support it on create). * **Retention action** (retain mode only, since enforce is always `Delete`) — **Keep** or **Keep, then delete** (`KeepAndDelete`). * **Retention type** — when the clock starts: **created** (`CreationAgeInDays`), **modified** (`ModificationAgeInDays`), or **labeled** (`TaggedAgeInDays`); Microsoft's event-based option (`EventAgeInDays`) exists but isn't offered as a selectable option in Augmentt's create/edit form. * **Label kind** — Retain, Record, or Regulatory record — read from the live label's `Regulatory`/`IsRecordLabel` flags; this reflects Microsoft's classification of the label rather than something set through the settings-mode form above. As with Microsoft's own portal, **retention action and retention type are create-only** — Microsoft's `Set-ComplianceTag` cannot change them after the fact, so editing a label only lets you touch description fields and (within limits) duration. ## Default templates Purview ships with **no built-in retention policy or label templates**. A retention policy template is created by converting an existing live Exchange Online policy on a connected tenant into a template — there's no seeded starter library of retention presets (no default "7-year financial records" or "delete after 90 days" template pre-populated for you). Retention labels have no template/deploy layer at all yet; they're created and managed directly, one tenant at a time. ## Fleet view Switching to **All Companies** on the Retention Policies or Retention Labels tabs shows every connected tenant with a simple status per tenant — loading, a count of policies/labels, empty, or an integration error — so you can scan for retention coverage gaps across your whole client base before drilling into any one tenant. This is one request per connected tenant, since Microsoft has no single cross-tenant Purview API. ## How deployment actually works Everything you create or change here is applied to the customer's tenant through Microsoft's **Security & Compliance PowerShell** cmdlets (the same plane behind the Purview compliance portal), not the Microsoft Graph API. Augmentt queues the change as a background task against the tenant and polls it to completion. ## What Retention doesn't do yet * Retention **policy** templates currently only convert from a live **Exchange Online** policy — SharePoint, OneDrive, and Teams retention templating/deployment are expected in a future release. You can still see and manage existing SharePoint/OneDrive-scoped policies through the deploy/edit flow's location toggles; it's the *template conversion* path that's Exchange-only today. * Teams-scoped retention policies (channel messages / chat messages) aren't created or edited through Augmentt's policy flow, since Microsoft requires them to be a separate, Teams-only static policy type. * Adaptive-scope policies are shown read-only; the adaptive scope query itself isn't editable from Augmentt. * Retention labels have no template/deploy layer — they're managed directly per tenant. ## Posture-check resolution There is **no dedicated Retention entry in Compliance Audit today**. The platform's posture-check registry (`SECURE_CHECK_TYPES`) has exactly one retention-adjacent entry, `DELETED_USER_ONE_DRIVE_RETENTION` ("deleted user OneDrive retention") — and that check is about how long a departed user's OneDrive is preserved after their account is removed, a completely different feature from Purview retention policies/labels. It is not a proxy for whether a client has any retention policy or label configured, and Compliance Audit does not otherwise score retention policy/label posture one way or the other. Since it doesn't move a score, here's the risk case for retention that's worth articulating on its own: * **Records that disappear before they should** — without a retention policy, a departing employee's mailbox or a project's SharePoint site can be deleted (accidentally or on offboarding) along with everything a legal hold, tax authority, or contract dispute might later need. A retention policy holds that content regardless of user or admin action. * **Records that never expire and become a liability** — data kept indefinitely "just in case" is also the data a breach or subpoena exposes. A well-set duration + delete action is a defensible, auditable answer to "why do you still have this," which matters for GDPR-style right-to-erasure and general data-minimization expectations. * **Inconsistent legal-hold behavior** — a retention label lets a specific record (e.g., a signed contract) carry its own retention rule independent of where someone later moves or copies it, which a purely location-based policy can't guarantee. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://helpdesk.augmentt.com/modules/secure/purview/retention.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.