Managing Managed Event Subscription

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

1. 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. 2. 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. 3. Read the template — load assets/managed-event-subscription-template.xml as the starting structure. 4. Generate the file — produce managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml filled with user-provided values. 5. Verify — run the checklist below before presenting output. 6. 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

1. Identify the subscription — accept either Id or DeveloperName; prefer Id if provided. 2. Show the file path — managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml (if DeveloperName known). 3. Retrieve and display — read and present the current XML content.

Update

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

Delete

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

---

Rules / Constraints

---

Gotchas

---

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

---

Reference File Index

Deleting a ManagedEventSubscription

Warning

Deleting a ManagedEventSubscription permanently destroys its stored replay position. If you recreate the subscription, it will start from its <defaultReplay> — it will not resume from where it left off.

DELETE is safe to call regardless of the subscription's current state — it atomically stops any running subscription, clears the committed Replay ID, and removes the record. No prior STOP transition is required.

After deletion, avoid reusing the same DeveloperName immediately — the Pub/Sub API service can take up to ~2 minutes to reflect the deletion. Create a new record with a different name if immediate re-creation is needed.

Procedure

Step 1 — Remove the metadata file

Delete the file from your project:

managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml

Step 2 — Create a destructiveChanges.xml

In your deployment package root, create destructiveChanges.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members><DeveloperName></members>
        <name>ManagedEventSubscription</name>
    </types>
    <version>67.0</version>
</Package>

Replace <DeveloperName> with the exact developer name of the subscription to delete.

Step 3 — Create an empty package.xml

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>67.0</version>
</Package>

Step 4 — Deploy

sf project deploy start --manifest package.xml --post-destructive-changes destructiveChanges.xml --target-org <alias>

Common Errors

topicName Formats for ManagedEventSubscription

The <topicName> field requires a full channel path, not just an API name. The correct format depends on the type of event channel.

Valid Formats

Rules

• The path prefix (/event/ or /data/) is required — omitting it causes "The topicName field is invalid" deploy error
• The referenced event or channel must exist in the org before deploying the subscription
• topicName is immutable after creation — to change it, delete and recreate the subscription

Common Errors

Update Constraints for ManagedEventSubscription

Fields That Can Be Updated

Fields That Cannot Be Changed After Creation

defaultReplay Change Warning

Changing <defaultReplay> from LATEST to EARLIEST on an existing subscription will cause it to re-replay all available events from the earliest retained position on the next activation. On high-volume event channels this can create a large backlog. Always confirm intent with the user before making this change.

Procedure for Immutable Field Changes

If the user needs to change <topicName> or DeveloperName:

1. Export current subscription config 2. Delete the existing subscription (see references/delete-guide.md) 3. Create a new subscription with the desired values 4. Note: replay tracking state from the old subscription is lost