managing-managed-event-subscription

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Managing ManagedEventSubscription

管理ManagedEventSubscription

Create, read, update, and delete

ManagedEventSubscription

metadata — the Salesforce construct for durably subscribing to platform event channels with managed replay tracking.

创建、读取、更新和删除

ManagedEventSubscription

元数据——这是Salesforce中用于通过托管重放跟踪持久订阅平台事件通道的结构。

Scope

适用范围

In scope: Generating and modifying
```
.managedEventSubscription-meta.xml
```
files for create, read, update, and delete operations
Out of scope: Creating the underlying platform event (
```
__e
```
) channel itself; Flow-based or Apex-based event subscriptions; deploying metadata to an org
Only generate one file — the
```
.managedEventSubscription-meta.xml
```
file. Do NOT generate the referenced platform event object or any other metadata type.

包含范围：生成和修改
```
.managedEventSubscription-meta.xml
```
文件以执行创建、读取、更新和删除操作
排除范围：创建底层平台事件（
```
__e
```
）通道；基于Flow或Apex的事件订阅；将元数据部署到组织
仅生成一个文件——
```
.managedEventSubscription-meta.xml
```
文件。请勿生成引用的平台事件对象或任何其他元数据类型。

Clarifying Questions

澄清问题

Before generating, confirm if not already clear:

What is the topic name? (see format table in
```
references/topic-name-formats.md
```
)
What is the developer name? (required for Create — alphanumeric and underscores only, no spaces; optional for Read/Update/Delete if
```
Id
```
is known)
What is the label (human-readable name)?
What default replay preset —
```
LATEST
```
(default) or
```
EARLIEST
```
?
What error recovery replay preset —
```
LATEST
```
(default) or
```
EARLIEST
```
?
What should the initial state be —
```
RUN
```
(active) or
```
STOP
```
(inactive)? (default:
```
RUN
```
)

在生成之前，若尚未明确请确认：

主题名称是什么？（请查看
```
references/topic-name-formats.md
```
中的格式表格）
开发者名称是什么？（创建操作必填——仅允许字母数字和下划线，不能有空格；若已知
```
Id
```
，读取/更新/删除操作可选）
标签（人类可读名称）是什么？
默认重放预设是
```
LATEST
```
（默认）还是
```
EARLIEST
```
？
错误恢复重放预设是
```
LATEST
```
（默认）还是
```
EARLIEST
```
？
初始状态应该是
```
RUN
```
（激活）还是
```
STOP
```
（停用）？（默认：
```
RUN
```
）

Required Inputs

必填输入

Gather or infer before proceeding:

Operation: create, read, update, or delete
DeveloperName: required for Create (becomes the filename); optional for Read/Update/Delete if
```
Id
```
is provided instead
Id: Tooling API record Id — can be used to identify the subscription for Read/Update/Delete instead of DeveloperName
label: human-readable label (can include spaces)
topicName: event channel path — read
```
references/topic-name-formats.md
```
for valid formats (platform events, change events, custom channels)
defaultReplay:
```
LATEST
```
or
```
EARLIEST
```
(default:
```
LATEST
```
)
errorRecoveryReplay:
```
LATEST
```
or
```
EARLIEST
```
(default:
```
LATEST
```
)
state:
```
RUN
```
or
```
STOP
```
(default:
```
RUN
```
) —
```
PAUSE
```
is reserved for internal platform use and will be rejected with
```
INVALID_INPUT
```
version: Metadata API version (default: match org API version, e.g.
```
67.0
```
)

开始前需收集或推断以下信息：

操作类型：创建、读取、更新或删除
DeveloperName：创建操作必填（将作为文件名）；若提供
```
Id
```
，读取/更新/删除操作可选
Id：Tooling API记录ID——可替代DeveloperName用于识别读取/更新/删除操作的订阅
label：人类可读标签（可包含空格）
topicName：事件通道路径——请阅读
```
references/topic-name-formats.md
```
获取有效格式（平台事件、变更事件、自定义通道）
defaultReplay：
```
LATEST
```
或
```
EARLIEST
```
（默认：
```
LATEST
```
）
errorRecoveryReplay：
```
LATEST
```
或
```
EARLIEST
```
（默认：
```
LATEST
```
）
state：
```
RUN
```
或
```
STOP
```
（默认：
```
RUN
```
）——
```
PAUSE
```
为平台内部保留使用，会被
```
INVALID_INPUT
```
拒绝
version：Metadata API版本（默认：匹配组织API版本，例如
```
67.0
```
）

Workflow

工作流程

Create

创建

Gather inputs — confirm DeveloperName, label, topicName, defaultReplay, errorRecoveryReplay, state, version. Apply defaults for any omitted fields. If DeveloperName is not provided, ask the user — do not derive it from the label.
Confirm the topic exists — ask the user to confirm the event channel already exists in the org before proceeding. Do NOT generate the platform event object yourself — that is out of scope for this skill. If the user says it doesn't exist yet, stop and direct them to create it first using the
```
generating-platform-event
```
skill, then return here.
Read the template — load
```
assets/managed-event-subscription-template.xml
```
as the starting structure.

Generate the file — produce

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

filled with user-provided values.

Verify — run the checklist below before presenting output.
Guide the user on subscribing — after deployment, the subscription can be identified for Pub/Sub API
```
ManagedSubscribe
```
RPC calls using either the
```
DeveloperName
```
or the record
```
Id
```
. To retrieve the
```
Id
```
, run:
```
SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'
```
via the Tooling API.

收集输入——确认DeveloperName、label、topicName、defaultReplay、errorRecoveryReplay、state、version。对遗漏字段应用默认值。若未提供DeveloperName，请询问用户——不要从label推导。
确认主题存在——请用户确认事件通道已在组织中存在后再继续。请勿自行生成平台事件对象——这超出了本技能的范围。如果用户表示通道尚未存在，请停止操作并引导其先使用
```
generating-platform-event
```
技能创建，之后再返回此处。

读取模板——加载

assets/managed-event-subscription-template.xml

作为初始结构。

生成文件——生成填充了用户提供值的

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

文件。

验证——在呈现输出前运行下方的检查清单。
指导用户订阅——部署完成后，可通过
```
DeveloperName
```
或记录
```
Id
```
在Pub/Sub API的
```
ManagedSubscribe
```
RPC调用中识别该订阅。若要获取
```
Id
```
，请通过Tooling API执行：
```
SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'
```
。

Read

读取

Identify the subscription — accept either
```
Id
```
or
```
DeveloperName
```
; prefer
```
Id
```
if provided.

Show the file path —

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

(if DeveloperName known).

Retrieve and display — read and present the current XML content.

识别订阅——接受
```
Id
```
或
```
DeveloperName
```
；若同时提供优先使用
```
Id
```
。

显示文件路径——

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

（若已知DeveloperName）。

检索并展示——读取并呈现当前XML内容。

Update

更新

Identify the subscription — accept either
```
Id
```
or
```
DeveloperName
```
; prefer
```
Id
```
if provided.
Read the existing file — load current content before modifying.
Apply changes — update only the specified fields; preserve all others.
Read
references/update-constraints.md
for fields that cannot be changed after creation.
Verify — run the checklist below before presenting output.

识别订阅——接受
```
Id
```
或
```
DeveloperName
```
；若同时提供优先使用
```
Id
```
。
读取现有文件——修改前加载当前内容。
应用变更——仅更新指定字段；保留所有其他字段。
**阅读
```
references/update-constraints.md
```
**了解创建后无法修改的字段。
验证——在呈现输出前运行下方的检查清单。

Delete

删除

Identify the subscription — accept either
```
Id
```
or
```
DeveloperName
```
; confirm with the user before proceeding.
Warn — deleting a ManagedEventSubscription permanently removes replay tracking state.
Produce deletion instructions — explain how to remove the file and deploy the destructive change using
```
destructiveChanges.xml
```
.
Read
references/delete-guide.md
for the destructive deployment procedure.

识别订阅——接受
```
Id
```
或
```
DeveloperName
```
；执行前请与用户确认。
警告——删除ManagedEventSubscription会永久移除重放跟踪状态。
生成删除说明——解释如何移除文件并通过
```
destructiveChanges.xml
```
部署破坏性变更。
**阅读
```
references/delete-guide.md
```
**获取破坏性部署流程。

Rules / Constraints

规则/约束

Constraint	Rationale
`<topicName>` must use a valid path prefix	Platform events use `/event/Name__e` ; change events use `/data/Name` ; see `references/topic-name-formats.md` for all formats
`<defaultReplay>` and `<errorRecoveryReplay>` must be `LATEST` or `EARLIEST`	These are the only valid enum values; any other value fails metadata validation
`<state>` must be `RUN` or `STOP`	`PAUSE` is reserved for internal platform use — the API rejects it with `INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP`
All six required elements must be present	`topicName` , `defaultReplay` , `errorRecoveryReplay` , `label` , `state` , `version` are all required; omitting any causes a deploy error
DeveloperName must be unique within the org	Duplicate names cause `DUPLICATE_DEVELOPER_NAME` errors
Do not include `<namespacePrefix>` , `<id>` , or `<createdDate>`	Read-only platform fields; including them causes deployment failures in unpackaged orgs

约束	理由
`<topicName>` 必须使用有效的路径前缀	平台事件使用 `/event/Name__e` ；变更事件使用 `/data/Name` ；所有格式请查看 `references/topic-name-formats.md`
`<defaultReplay>` 和 `<errorRecoveryReplay>` 必须为 `LATEST` 或 `EARLIEST`	这些是唯一有效的枚举值；任何其他值都会导致元数据验证失败
`<state>` 必须为 `RUN` 或 `STOP`	`PAUSE` 为平台内部保留使用——API会以 `INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP` 拒绝该值
必须包含所有六个必填元素	`topicName` 、 `defaultReplay` 、 `errorRecoveryReplay` 、 `label` 、 `state` 、 `version` 均为必填项；遗漏任何一项都会导致部署错误
DeveloperName在组织内必须唯一	重复名称会导致 `DUPLICATE_DEVELOPER_NAME` 错误
请勿包含 `<namespacePrefix>` 、 `<id>` 或 `<createdDate>`	这些是平台只读字段；在未打包组织中包含它们会导致部署失败

Gotchas

常见问题

Issue	Resolution
`The topicName field is invalid` on deploy	Wrong format or the event doesn't exist in the org — read `references/topic-name-formats.md` for correct path
Replay state lost after delete + recreate	Deleting discards stored replay position; recreating starts from `defaultReplay` — avoid reusing the same DeveloperName after delete
`INVALID_TYPE` on SOQL query	ManagedEventSubscription is only queryable via Tooling API, not standard SOQL
`EARLIEST` replay on high-volume channels	Can trigger up to 72 hours of backlog replay on activation; always confirm with the user
Metadata not supported in older orgs	ManagedEventSubscription requires API v60.0+; check org API version
`eventChannel` or `isActive` in generated XML	These are wrong field names — use `topicName` and `state` ( `RUN` / `STOP` ) instead
`PAUSE` state in generated XML	`PAUSE` is reserved for internal platform use and will be rejected with `INVALID_INPUT` — only use `RUN` or `STOP`
User unsure how to identify subscription for Pub/Sub API	Both `DeveloperName` and record `Id` can be used with `ManagedSubscribe` RPC — retrieve the `Id` via Tooling API if needed: `SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'`
Changes not reflected immediately in Pub/Sub API	After create/update/delete, the Pub/Sub API can take up to ~2 minutes to reflect the new config; if ManagedSubscribe returns NOT_FOUND, wait and retry

问题	解决方案
部署时提示 `The topicName field is invalid`	格式错误或事件在组织中不存在——请阅读 `references/topic-name-formats.md` 获取正确路径
删除后重新创建导致重放状态丢失	删除操作会丢弃存储的重放位置；重新创建会从 `defaultReplay` 开始——删除后避免重复使用相同的DeveloperName
SOQL查询时提示 `INVALID_TYPE`	ManagedEventSubscription仅可通过Tooling API查询，无法通过标准SOQL查询
高容量通道使用 `EARLIEST` 重放	激活时可能触发长达72小时的积压重放；请务必与用户确认
旧版本组织不支持该元数据	ManagedEventSubscription需要API v60.0+；请检查组织API版本
生成的XML中包含 `eventChannel` 或 `isActive`	这些是错误的字段名称——请使用 `topicName` 和 `state` （ `RUN` / `STOP` ）替代
生成的XML中包含 `PAUSE` 状态	`PAUSE` 为平台内部保留使用，会被 `INVALID_INPUT` 拒绝——仅使用 `RUN` 或 `STOP`
用户不确定如何在Pub/Sub API中识别订阅	`DeveloperName` 和记录 `Id` 均可用于 `ManagedSubscribe` RPC——若需要 `Id` ，请通过Tooling API获取： `SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'`
变更未立即在Pub/Sub API中生效	创建/更新/删除后，Pub/Sub API最多可能需要2分钟才能反映新配置；若ManagedSubscribe返回NOT_FOUND，请等待并重试

Verification Checklist

验证清单

Before presenting any generated XML:

Does

<topicName>

follow a valid path format per

references/topic-name-formats.md

? (

/event/Name__e

/data/NameChangeEvent

/data/ChangeEvents

/event/Name__chn

/data/Name__chn

)

Is
```
<defaultReplay>
```
exactly
```
LATEST
```
or
```
EARLIEST
```
?
Is
```
<errorRecoveryReplay>
```
exactly
```
LATEST
```
or
```
EARLIEST
```
?
Is
```
<state>
```
exactly
```
RUN
```
or
```
STOP
```
? (
```
PAUSE
```
is invalid for user-created subscriptions)
Is
```
<label>
```
populated?
Is
```
<version>
```
present (e.g.
```
67.0
```
)?
Are read-only fields (
```
<id>
```
,
```
<createdDate>
```
,
```
<namespacePrefix>
```
) absent?
Does the filename match the DeveloperName exactly?

在呈现任何生成的XML前：

<topicName>

是否遵循

references/topic-name-formats.md

中的有效路径格式？（例如

/event/Name__e

、

/data/NameChangeEvent

、

/data/ChangeEvents

、

/event/Name__chn

、

/data/Name__chn

）

```
<defaultReplay>
```
是否恰好为
```
LATEST
```
或
```
EARLIEST
```
？
```
<errorRecoveryReplay>
```
是否恰好为
```
LATEST
```
或
```
EARLIEST
```
？
```
<state>
```
是否恰好为
```
RUN
```
或
```
STOP
```
？（
```
PAUSE
```
对用户创建的订阅无效）
```
<label>
```
是否已填充？
```
<version>
```
是否存在（例如
```
67.0
```
）？
是否不存在只读字段（
```
<id>
```
、
```
<createdDate>
```
、
```
<namespacePrefix>
```
）？
文件名是否与DeveloperName完全匹配？

Output Expectations

输出预期

Create / Update:

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

— this is the only file to generate

Delete: instructions to remove the file and deploy via
```
destructiveChanges.xml
```
Read: display of existing file contents

创建/更新：

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

——这是唯一需要生成的文件

删除：移除文件并通过
```
destructiveChanges.xml
```
部署的说明
读取：现有文件内容的展示

Cross-Skill Integration

跨技能集成

Need	Delegate to
Create the platform event channel ( `__e` ) being subscribed to	`generating-platform-event` skill
Subscribe via Flow (Process Automation)	`generating-flow` skill
Deploy metadata to org	`deploying-metadata` skill

需求	委托至
创建要订阅的平台事件通道（ `__e` ）	`generating-platform-event` 技能
通过Flow（流程自动化）订阅	`generating-flow` 技能
将元数据部署到组织	`deploying-metadata` 技能

Reference File Index

参考文件索引

File	When to read
`assets/managed-event-subscription-template.xml`	Before generating any new subscription — use as starting structure
`references/topic-name-formats.md`	When setting `<topicName>` — covers platform events, change events, and custom channels
`references/update-constraints.md`	During Update workflow — to check which fields are immutable post-creation
`references/delete-guide.md`	During Delete workflow — for destructive change deployment procedure

文件	阅读时机
`assets/managed-event-subscription-template.xml`	生成任何新订阅之前——用作初始结构
`references/topic-name-formats.md`	设置 `<topicName>` 时——涵盖平台事件、变更事件和自定义通道
`references/update-constraints.md`	更新工作流程期间——检查哪些字段在创建后不可变
`references/delete-guide.md`	删除工作流程期间——获取破坏性变更部署流程