using-salesforce-archive

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, view, 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 (the
```
TrustedServicesArchive
```
/
```
TrustedServicesArchiveBt
```
org permission). 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（拥有
```
TrustedServicesArchive
```
/
```
TrustedServicesArchiveBt
```
组织权限）。所有操作都以此为首要前提。
每个操作除了组织权限外，还需要特定的用户权限——参见下方的权限表。不存在单一的“归档管理员”角色；访问权限按功能划分。

Permissions

权限

Every operation first requires the org to have Salesforce Archive enabled (

hasTrustedServicesArchive

OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt

). 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) — the Connect search endpoint runs the global-search path, gated by Archive Search, not `ViewArchivedRecords`
`search-archived-records-with-sharing-rules` (Agentforce)	`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)

Source of truth: the Connect API resource classes in
trusted-services-archive-connect-impl
→
TrustedServicesArchiveSdkImpl
guards →
TrustedServicesArchive.accessChecks.xml
. Note
search-archived-records
routes through
performArchiverGlobalSearch
(gated by
canRunArchiveSearch
=
ViewSearchPage
); the separate Apex-SDK
searchArchivedRecords()
method is gated by
ViewArchivedRecords
, but the Connect API search endpoint does not use it.

所有操作首先要求组织已启用Salesforce Archive（

hasTrustedServicesArchive

OrgPermissions.TrustedServicesArchive || TrustedServicesArchiveBt

）。在此基础上，每个功能都受独立的用户权限限制。用户无权限执行的调用会返回“未授权”错误——请将错误与下方缺失的权限匹配。

操作	所需用户权限
`search-archived-records` , `get-search-archived-records-next-page`	`ViewSearchPage` （归档搜索）——Connect搜索端点使用全局搜索路径，受归档搜索权限限制，而非 `ViewArchivedRecords`
`search-archived-records-with-sharing-rules` （Agentforce）	`ViewArchivedRecords`
`unarchive-records`	`UnarchiveSdk`
`forget-archived-records` （RTBF） + `get-rtbf-status`	`Rtbf`
`mask-archived-records` + `get-masking-status`	`Rtbf` （掩码与RTBF使用相同的 `Rtbf` 权限——无单独权限）
`run-analyzer` , `get-analyzer-report` , `get-archive-storage-used`	`ArchiveAnalyzer`
`get-execution-details-stream-url` , `get-failed-records-stream-url`	`ViewActivitiesPage` （归档活动）

权威来源：
trusted-services-archive-connect-impl
中的Connect API资源类 →
TrustedServicesArchiveSdkImpl
守卫 →
TrustedServicesArchive.accessChecks.xml
。注意
search-archived-records
通过
performArchiverGlobalSearch
路由（受
canRunArchiveSearch
=
ViewSearchPage
限制）；独立的Apex-SDK
searchArchivedRecords()
方法受
ViewArchivedRecords
限制，但Connect API搜索端点不使用该方法。

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 — follow the contract exactly. 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
```
。
构建并发送调用——严格遵循契约。搜索操作需提供
```
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	The controller rejects an unfiltered request 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.
Never use the deprecated lookups	`global-search-by-id` , `get-global-search-results` , and `view-archived-records` are deprecated with no successor and currently 500. Use `search-archived-records` (+ next-page) instead.
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` 不匹配会返回无日志。
切勿使用已弃用的查询方式	`global-search-by-id` 、 `get-global-search-results` 和 `view-archived-records` 已弃用且无替代方案，当前会返回500错误。请改用 `search-archived-records` （+下一页）。
排除对象不可检索	`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` (Agentforce) 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` （Agentforce）筛选条件为数组	`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`	遵循端到端监控流程时：查找失败/进行中的任务，然后下载其日志