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

After this write	Confirm by
run-analyzer	Poll get-analyzer-report until the report is populated
unarchive-records	Re-run search-archived-records — confirm records left the archive
forget-archived-records (RTBF)	Poll get-rtbf-status with the returned request_id
mask-archived-records	Poll get-masking-status with the returned request_id

---

Rules / Constraints

Constraint	Rationale
Search & unarchive require sobjectName + at least one filter	An unfiltered request is rejected with "Search must be based on at least 1 field" — a full-object operation is never allowed.
Date filters must be full ISO-8601 datetimes (2020-01-01T00:00:00Z)	A date-only value (2020-01-01) returns 400 JSON_PARSER_ERROR because the field is typed xsd:dateTime.
Search uses dateRanges (plural array); unarchive uses dateRange (singular)	They are genuinely different fields on the two endpoints; using the wrong shape silently drops the filter or 400s.
Stop pagination when scroll_id == "-1"	Calling get-search-archived-records-next-page with "-1" returns 500.
Log downloads need a real ArchiveActivity Id as requestId + that activity's Type as reportType	The backend resolves the log by the activity record; a mismatched reportType returns no log.
Excluded objects are not retrievable	Feed, History, Relation, Share are not searchable; Files/Attachments are not retrievable via this API — do not promise them.
Query ArchiveActivity via SOQL/Connect, never Flow	ArchiveActivity has isProcessEnabled=false, so a Flow "Get Records" element on it fails with "You can't get ArchiveActivity records in a flow."

---

Gotchas

Issue	Resolution
Treating HTTP 201 as success	Several operations return 201 with a body-level outcome. Branch on body.statusCode (search) or body.isSuccess (with-sharing-rules), not the HTTP code.
run-analyzer.isRunning used as a signal	It is always null; the endpoint only populates message. Poll get-analyzer-report to confirm completion instead.
search-archived-records-with-sharing-rules filters as an array	filtersJson must be a JSON-encoded object map {"Field":"Value"}, not an array of {field,value}; the array form returns isSuccess:false "No valid filters provided".
Log url treated as present because status is 201	get-*-stream-url returns {url}; url: null means no log was resolved. Always check url != null.
Misreading get-archive-storage-used	usedStorage[]/availableStorage[] are parallel positional arrays: index 0=org DATA, 1=org FILE, 2=archive RECORDS, 3=archive FILE. availableStorage[2]/[3] are always 0 (archive tier is unmetered) — that means "not tracked", not "full".
Expecting ArchiveActivity in a Flow	It is not Flow-enabled (isProcessEnabled=false). Use SOQL/Connect/Reports.
Hitting unarchive caps	Unarchive processes ≤1000 matched records per request and ≤50 requests/hour/org, and restores the whole archived hierarchy of each match.
RTBF/masking caps	criteria ≤10 entries (one per object); ≤10,000 root records/day (shared between RTBF and masking); masking is irreversible. Both RTBF and masking are gated by the same Rtbf user permission.

---

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

File	When to read
references/connect-api-operations.md	Before constructing any Archive Connect API call — full per-operation contracts, success signals, and limits
references/archive-activity-entity.md	For any job-status / failure / progress / log task — ArchiveActivity field reference and its link to the log-download endpoints
examples/monitor-failed-jobs.md	To follow an end-to-end monitoring flow: find failed/in-progress jobs, then download their logs