platform-trust-archive-manage

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.

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 wrong, NOT that Archive is disabled — fix the path before concluding the add-on is missing.

   Operation	Method + Path	Notes
   search-archived-records	POST /search	requires sobjectName + ≥1 filter
   search next page	GET /search/next/{scrollId}	stop when scroll_id == "-1"
   search with sharing rules	POST /search/with-sharing-rules	uses filtersJson object map
   unarchive-records	POST /unarchive	sobjectName + filters
   run-analyzer / report	POST /analyzer/run · GET /analyzer/report
   forget / RTBF + status	POST /rtbf · GET /rtbf/{requestId}
   mask + status	POST /mask · GET /mask/{requestId}
   storage used	GET /storage/archive-used
   execution-detail / failed-records log	GET /log/execution-details-stream-url · GET /log/failed-records-stream-url	query params requestId, reportType

   With the sf CLI, prefix the path with /services/data/v67.0; some MCP/REST tools take the bare path and add the version themselves (tool-dependent — see the reference). Then follow the contract: for searches, supply sobjectName + ≥1 filter; for date filtering use the plural dateRanges array of {field, from, to} with full ISO-8601 datetimes.

4. Branch on the right signal — some operations return HTTP 201 with a body-level success flag (body.statusCode, body.isSuccess). Read references/connect-api-operations.md for which signal to trust per operation; never assume the HTTP status alone means success.
5. Verify after every write — re-read state to confirm the effect (see the Verify-After-Write table below). Async operations (analyzer, RTBF, masking) return a request id you must poll.

Verify-After-Write

Rules / Constraints

Gotchas

Output Expectations

This is a knowledge/API skill — it produces API calls and their interpreted results, plus SOQL against ArchiveActivity. It does not generate deployable metadata. Deliverables per task: the correct operation invocation(s), the right success-signal branching, and a verify-after-write confirmation.

Reference File Index