/platform-trust-archive-manage

name: platform-trust-archive-manage
description: "ALWAYS USE THIS SKILL for anything involving Salesforce Archive (also called Trusted Services Archive) — search, view, unarchive, analyze, mask, and erase (RTBF) archived records via the Archive Connect API, and reading archive job status from the ArchiveActivity object. TRIGGER when: user mentions Salesforce Archive, Trusted Services Archive, archive/unarchive records, ArchiveActivity, archive jobs, archive policy, archive analyzer, archived record search, archive storage, archive failure logs, right to be forgotten / RTBF on archived data, or masking archived PII — including phrasings like 'find records that were archived', 'restore archived data', 'why did the archive job fail', 'download the archive failure log', or 'monitor my archive jobs', AND even when they ask you to explain, give guidance, or write a runbook/doc about these topics rather than run code. SKIP when: the user wants generic data-export/backup unrelated to the Archive add-on, or wants to build the archive policy UI metadata."
metadata:
  version: "1.0"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"

Salesforce Archive

Operate Salesforce Archive (also called Trusted Services Archive) through its Connect API and the `ArchiveActivity` job-metadata object. This skill covers how to search and restore archived records, run the analyzer, handle RTBF erasure and PII masking, check storage, and — the part most often missed — how to read archive job status from `ArchiveActivity` and use a job's Id + Type to download its logs.

Scope

• **In scope**: Calling the Archive Connect API operations under `/platform/data-resilience/archive/`; querying the `ArchiveActivity` object via SOQL/Connect; correlating a job's `ArchiveActivity` record with its log-download endpoints; the verify-after-write pattern for each async operation.
• **Out of scope**: Defining archive policies / `ArchivePolicyDefinition` metadata; building UI; generating Flows over archive data (`ArchiveActivity` is **not** Flow-queryable — see Gotchas); generic backup/export tooling unrelated to the add-on.

---

Required Inputs

Gather or infer before acting:

• **Operation intent**: search (this is also how you view archived records), unarchive, analyze, mask, RTBF, storage check, or job-status/log lookup.
• **Target sObject** (`sobjectName`): required for search and unarchive.
• **Filters**: search and unarchive require `sobjectName` + at least one filter.
• **For log downloads**: the `requestId` (an `ArchiveActivity` Id, `8qv…` prefix) of a completed, log-producing job, and `reportType` = that activity's `Type`.

Preconditions (confirm or surface to the user if a call returns a not-permitted error):

• The **org** must have Salesforce Archive enabled. Every operation is gated on this first.
• Each operation requires a **specific user permission** on top of the org gate — see the Permissions table below. There is no single "archive admin" role; access is per-capability.

---

Permissions

Every operation first requires the org to have Salesforce Archive enabled. On top of that org gate, each capability is gated by a distinct **user permission**. A call the user isn't permitted for fails with a "not permitted" error — match the error to the missing permission below.

| Operation | User permission required | |-----------|--------------------------| | `search-archived-records`, `get-search-archived-records-next-page` | `ViewSearchPage` (Archive Search) — **not** `ViewArchivedRecords` | | `search-archived-records-with-sharing-rules` | `ViewArchivedRecords` | | `unarchive-records` | `UnarchiveSdk` | | `forget-archived-records` (RTBF) + `get-rtbf-status` | `Rtbf` | | `mask-archived-records` + `get-masking-status` | `Rtbf` (masking shares the same `Rtbf` permission — **not** a separate entitlement) | | `run-analyzer`, `get-analyzer-report`, `get-archive-storage-used` | `ArchiveAnalyzer` | | `get-execution-details-stream-url`, `get-failed-records-stream-url` | `ViewActivitiesPage` (Archive Activities) |

---

Workflow

All steps are sequential within a task. Read the referenced file the first time you touch that area.

1. **Identify the operation and read the contract** — do not rely on general knowledge of the Archive API, which has non-obvious contracts. Load `references/connect-api-operations.md` for the exact request/response shape, required inputs, and per-operation gotchas of every Archive Connect API operation. Do this before constructing any call (e.g. `dateRanges` plural vs singular, `isSuccess` flag vs HTTP status, `url: null` meaning no log).

2. **For job status / monitoring, read the data model** — when the task involves archive jobs, failures, progress, counts, or logs, load `references/archive-activity-entity.md` for the `ArchiveActivity` field reference and how it links to the Connect API. Query `ArchiveActivity` via SOQL or Connect — **not** Flow. For a worked end-to-end example (find failed/in-progress jobs, then pull their execution-detail and failed-records logs), load `examples/monitor-failed-jobs.md`.

3. **Construct and send the call** — every operation is a `{method, path, body}` REST call. Send it with whatever Connect/REST API tool your environment provides (an MCP server that invokes Connect/REST APIs, the `sf` CLI, or any REST client). Two path rules are critical (full per-operation contracts are in `references/connect-api-operations.md`):

• **The operation names in this skill are NOT URL paths.** `search-archived-records`, `unarchive-records`, etc. are labels; never put them in the path. Use the short literal paths below (each relative to base `/platform/data-resilience/archive`). Sending the operation name as a path segment (e.g. `/…/archive/search-archived-records`) returns **404**.
• **The path stops at `/platform/data-resilience/archive/…` — there is NO `/connect` segment**, even though this is a Connect API. A **404 / `NOT_FOUND` here means the path is wr