integration-eventing-subscription-configure

SKILL.md

Managing ManagedEventSubscription

Create, read, update, and delete ManagedEventSubscription metadata — the Salesforce construct for durably subscribing to platform event channels with managed replay tracking.

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.

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)

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)

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 platform-custom-object-generate 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.

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.

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.

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.

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

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

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?

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

Cross-Skill Integration

Need
Delegate to

Create the platform event channel (__e) being subscribed to
platform-custom-object-generate skill

Subscribe via Flow (Process Automation)
automation-flow-generate skill

Deploy metadata to org
platform-metadata-deploy skill

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