Back to Details

using-salesforce-archive

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Salesforce Archive

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.
OperationUser 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.
  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 — 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.
  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.
所有步骤在任务内按顺序执行。首次接触相关领域时请阅读参考文件。
  1. 确定操作并阅读契约——不要依赖对Archive API的一般认知，其契约存在非显而易见的细节。加载
    references/connect-api-operations.md
    获取每个Archive Connect API操作的确切请求/响应格式、必要输入和各操作的注意事项。在构建任何调用前完成此步骤（例如
    dateRanges
    复数与单数的区别、
    isSuccess
    标志与HTTP状态的区别、
    url: null
    表示无日志）。
  2. 任务状态/监控需阅读数据模型——当任务涉及归档任务、失败、进度、计数或日志时，加载
    references/archive-activity-entity.md
    获取
    ArchiveActivity
    字段参考及其与Connect API的关联方式。通过SOQL或Connect查询
    ArchiveActivity
    ——不要使用Flow。如需端到端示例（查找失败/进行中的任务，然后获取其执行详情和失败记录日志），请加载
    examples/monitor-failed-jobs.md
    。
  3. 构建并发送调用——严格遵循契约。搜索操作需提供
    sobjectName
    + ≥1筛选条件；日期筛选使用复数
    dateRanges
    数组，格式为
    {field, from, to}
    ，包含完整ISO-8601日期时间。
  4. 根据正确信号分支处理——部分操作返回HTTP 201状态码并带有体级成功标志（
    body.statusCode
    、
    body.isSuccess
    ）。阅读
    references/connect-api-operations.md
    了解每个操作应信任的信号；切勿仅通过HTTP状态码判断成功。
  5. 每次写入后验证——重新读取状态以确认操作效果（参见下方的写后验证表）。异步操作（分析器、RTBF、掩码）会返回请求ID，需轮询该ID。

Verify-After-Write

写后验证

After this writeConfirm 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

规则/约束

ConstraintRationale
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

注意事项

IssueResolution
Treating HTTP 201 as successSeveral 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 capsUnarchive 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

参考文件索引

FileWhen 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
遵循端到端监控流程时：查找失败/进行中的任务，然后下载其日志