platform-trust-archive-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过其Connect API和

ArchiveActivity

任务元数据对象操作Salesforce Archive（也称为Trusted Services Archive）。本Skill涵盖如何搜索和恢复归档记录、运行分析器、处理RTBF擦除和PII掩码、检查存储，以及最常被忽略的部分——如何从

ArchiveActivity

读取归档任务状态，并使用任务的Id + Type下载其日志。

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.

包含范围：调用
```
/platform/data-resilience/archive/
```
下的Archive Connect API操作；通过SOQL/Connect查询
```
ArchiveActivity
```
对象；将任务的
```
ArchiveActivity
```
记录与其日志下载端点关联；每个异步操作的写后验证模式。
排除范围：定义归档策略/
```
ArchivePolicyDefinition
```
元数据；构建UI；基于归档数据生成Flow（
```
ArchiveActivity
```
不支持Flow查询——参见注意事项）；与该附加组件无关的通用备份/导出工具。

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.

执行操作前需收集或推断：

操作意图：搜索（这也是查看归档记录的方式）、取消归档、分析、掩码、RTBF、存储检查或任务状态/日志查询。
目标sObject（
```
sobjectName
```
）：搜索和取消归档操作必填。
筛选条件：搜索和取消归档需要
```
sobjectName
```
+ 至少一个筛选条件。
日志下载：已完成且生成日志的任务的
```
requestId
```
（
```
ArchiveActivity
```
Id，前缀为
```
8qv…
```
），以及
```
reportType
```
= 该活动的
```
Type
```
。

前置条件（如果调用返回未授权错误，需确认或告知用户）：

组织必须启用Salesforce Archive。所有操作均以此为前提。
每个操作除了组织层面的权限外，还需要特定的用户权限——参见下方的权限表。不存在单一的“归档管理员”角色；权限按功能划分。

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)

所有操作首先要求组织已启用Salesforce Archive。在此基础上，每个功能都受不同的用户权限限制。用户无权限执行的调用会返回“未授权”错误——请将错误与下方缺失的权限匹配。

操作	所需用户权限
`search-archived-records` , `get-search-archived-records-next-page`	`ViewSearchPage` （归档搜索）——不是 `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` （掩码与 `Rtbf` 权限共用——无单独权限）
`run-analyzer` , `get-analyzer-report` , `get-archive-storage-used`	`ArchiveAnalyzer`
`get-execution-details-stream-url` , `get-failed-records-stream-url`	`ViewActivitiesPage` （归档活动）

Workflow

工作流程

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

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).
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
```
.

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.

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

任务内的所有步骤均为顺序执行。首次接触某领域时，请阅读参考文件。

识别操作并阅读契约——不要依赖Archive API的通用知识，其契约存在非直观的细节。加载
```
references/connect-api-operations.md
```
以获取每个Archive Connect API操作的确切请求/响应格式、必填输入和各操作的注意事项。构建任何调用前都需执行此步骤（例如
```
dateRanges
```
复数与单数的区别、
```
isSuccess
```
标志与HTTP状态的区别、
```
url: null
```
表示无日志）。
任务状态/监控需阅读数据模型——当任务涉及归档任务、失败、进度、计数或日志时，加载
```
references/archive-activity-entity.md
```
获取
```
ArchiveActivity
```
字段参考及其与Connect API的关联方式。通过SOQL或Connect查询
```
ArchiveActivity
```
——不要使用Flow。如需端到端示例（查找失败/进行中的任务，然后拉取其执行详情和失败记录日志），请加载
```
examples/monitor-failed-jobs.md
```
。

构建并发送调用——所有操作均为

{method, path, body}

格式的REST调用。使用环境提供的任意Connect/REST API工具发送调用（调用Connect/REST API的MCP服务器、

sf

CLI或任何REST客户端）。以下两条路径规则至关重要（完整的各操作契约见

references/connect-api-operations.md

）：

本Skill中的操作名称并非URL路径。
```
search-archived-records
```
、
```
unarchive-records
```
等为标签；切勿将其放入路径。请使用下方的简短字面路径（均相对于基础路径
```
/platform/data-resilience/archive
```
）。将操作名称作为路径段发送（例如
```
/…/archive/search-archived-records
```
）会返回404。
路径止于
/platform/data-resilience/archive/…
——不存在
/connect
段，尽管这是Connect API。此处返回404 /
NOT_FOUND
表示路径错误，而非Archive已禁用——在判定附加组件缺失前，请先修正路径。

操作	方法 + 路径	备注
search-archived-records	`POST /search`	需要 `sobjectName` + ≥1筛选条件
搜索下一页	`GET /search/next/{scrollId}`	当 `scroll_id == "-1"` 时停止
带共享规则的搜索	`POST /search/with-sharing-rules`	使用 `filtersJson` 对象映射
unarchive-records	`POST /unarchive`	`sobjectName` + 筛选条件
运行分析器/获取报告	`POST /analyzer/run` · `GET /analyzer/report`
擦除/RTBF + 状态	`POST /rtbf` · `GET /rtbf/{requestId}`
掩码 + 状态	`POST /mask` · `GET /mask/{requestId}`
已用存储	`GET /storage/archive-used`
执行详情/失败记录日志	`GET /log/execution-details-stream-url` · `GET /log/failed-records-stream-url`	查询参数 `requestId` 、 `reportType`

使用

sf

CLI时，请在路径前添加

/services/data/v67.0

；部分MCP/REST工具仅需提供裸路径，自行添加版本号（取决于工具——参见参考文档）。然后遵循契约：搜索操作需提供

sobjectName

+ ≥1筛选条件；日期筛选需使用复数形式

dateRanges

数组，包含

{field, from, to}

和完整的ISO-8601日期时间格式。

根据正确信号分支处理——部分操作返回HTTP 201并带有主体级成功标志（
```
body.statusCode
```
、
```
body.isSuccess
```
）。请阅读
```
references/connect-api-operations.md
```
了解每个操作需信任的信号；切勿仅通过HTTP状态判断成功。
每次写入后验证——重新读取状态以确认操作效果（参见下方的写后验证表）。异步操作（分析器、RTBF、掩码）会返回请求ID，需轮询该ID。

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`

执行写入操作后	验证方式
`run-analyzer`	轮询 `get-analyzer-report` 直至报告填充完成
`unarchive-records`	重新运行 `search-archived-records` ——确认记录已移出归档
`forget-archived-records` （RTBF）	使用返回的 `request_id` 轮询 `get-rtbf-status`
`mask-archived-records`	使用返回的 `request_id` 轮询 `get-masking-status`

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

约束	原因
搜索和取消归档需要 `sobjectName` + 至少一个筛选条件	未筛选的请求会被拒绝，提示“搜索必须基于至少一个字段”——绝不允许全对象操作。
日期筛选必须使用完整的ISO-8601日期时间格式（ `2020-01-01T00:00:00Z` ）	仅日期值（ `2020-01-01` ）会返回 `400 JSON_PARSER_ERROR` ，因为字段类型为 `xsd:dateTime` 。
搜索使用 `dateRanges` （复数数组）；取消归档使用 `dateRange` （单数）	这两个端点的字段确实不同；使用错误格式会静默丢弃筛选条件或返回400错误。
当 `scroll_id == "-1"` 时停止分页	使用 `"-1"` 调用 `get-search-archived-records-next-page` 会返回500错误。
日志下载需要真实的 `ArchiveActivity` Id作为 `requestId` + 该活动的 `Type` 作为 `reportType`	后端通过活动记录解析日志； `reportType` 不匹配会返回无日志。
排除的对象无法检索	`Feed` 、 `History` 、 `Relation` 、 `Share` 不可搜索；Files/Attachments无法通过本API检索——请勿承诺提供这些内容。
通过SOQL/Connect查询 `ArchiveActivity` ，切勿使用Flow	`ArchiveActivity` 的 `isProcessEnabled=false` ，因此Flow中的“获取记录”元素会失败，提示“无法在Flow中获取ArchiveActivity记录。”

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.

问题	解决方案
将HTTP 201视为成功	部分操作返回201并带有主体级结果。请根据 `body.statusCode` （搜索）或 `body.isSuccess` （ `with-sharing-rules` ）分支处理，而非HTTP状态码。
使用 `run-analyzer.isRunning` 作为信号	该字段始终为 `null` ；端点仅填充 `message` 。请改为轮询 `get-analyzer-report` 确认完成。
`search-archived-records-with-sharing-rules` 筛选条件为数组	`filtersJson` 必须是JSON编码的对象映射 `{"Field":"Value"}` ，而非 `{field,value}` 数组；数组形式会返回 `isSuccess:false "No valid filters provided"` 。
因状态为201而认为日志 `url` 存在	`get-*-stream-url` 返回 `{url}` ； `url: null` 表示未解析到日志。请始终检查 `url != null` 。
误读 `get-archive-storage-used`	`usedStorage[]` / `availableStorage[]` 为并行位置数组：索引0=组织数据，1=组织文件，2=归档记录，3=归档文件。 `availableStorage[2]` / `[3]` 始终为0（归档层无计量）——这表示“未跟踪”，而非“已满”。
期望在Flow中使用 `ArchiveActivity`	它不支持Flow（ `isProcessEnabled=false` ）。请使用SOQL/Connect/报表。
达到取消归档上限	取消归档每个请求最多处理≤1000条匹配记录，每个组织每小时≤50个请求，并恢复每个匹配项的整个归档层级。
RTBF/掩码上限	`criteria` ≤10个条目（每个对象一个）；每天≤10,000条根记录（RTBF和掩码共用）；掩码不可逆。RTBF和掩码均受相同的 `Rtbf` 用户权限限制。

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.

这是一个知识/API Skill——它生成API调用及其解析结果，以及针对

ArchiveActivity

的SOQL查询。它不生成可部署的元数据。每个任务的交付物：正确的操作调用、正确的成功信号分支处理，以及写后验证确认。

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

文件	阅读时机
`references/connect-api-operations.md`	构建任何Archive Connect API调用前——完整的各操作契约、成功信号和限制
`references/archive-activity-entity.md`	处理任何任务状态/失败/进度/日志任务时—— `ArchiveActivity` 字段参考及其与日志下载端点的关联
`examples/monitor-failed-jobs.md`	遵循端到端监控流程时：查找失败/进行中的任务，然后下载其日志