<?xml version="1.0" encoding="UTF-8"?>
<ManagedEventSubscription xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- Required: EARLIEST or LATEST — replay position on normal startup -->
    <defaultReplay>{DEFAULT_REPLAY}</defaultReplay>
    <!-- Required: EARLIEST or LATEST — replay position after an error recovery -->
    <errorRecoveryReplay>{ERROR_RECOVERY_REPLAY}</errorRecoveryReplay>
    <!-- Required: Human-readable label -->
    <label>{LABEL}</label>
    <!-- Required: RUN (active) or STOP (inactive) — PAUSE is reserved for internal use and will be rejected -->
    <state>{STATE}</state>
    <!-- Required: Event channel path — see references/topic-name-formats.md for valid formats
         Platform event:            /event/Name__e
         Custom PE channel:         /event/Name__chn
         All-objects change events: /data/ChangeEvents
         Single-object change event:/data/ObjectNameChangeEvent
         Custom change channel:     /data/Name__chn -->
    <topicName>{TOPIC_NAME}</topicName>
    <!-- Required: Metadata API version (e.g. 67.0) -->
    <version>{VERSION}</version>
</ManagedEventSubscription>

# 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
<?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
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <version>67.0</version>
</Package>
```

### Step 4 — Deploy

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

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `INVALID_CROSS_REFERENCE_KEY` | DeveloperName not found | Confirm the exact name with `sf api request rest "/services/data/v67.0/tooling/query/?q=SELECT+DeveloperName+FROM+ManagedEventSubscription"` |
| Subscription reappears or Pub/Sub returns NOT_FOUND after delete | ~2 minute propagation delay in Pub/Sub API service | Wait 2 minutes before attempting any operation on the same topic |

# 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

| Channel type | Format | Example |
|---|---|---|
| Platform event | `/event/<Name>__e` | `/event/Order_Fulfillment__e` |
| Custom platform event channel | `/event/<Name>__chn` | `/event/MyChannel__chn` |
| All-objects change event channel | `/data/ChangeEvents` | `/data/ChangeEvents` |
| Single-object change event | `/data/<Object>ChangeEvent` | `/data/AccountChangeEvent` |
| Custom change event channel | `/data/<Name>__chn` | `/data/MyChangeChannel__chn` |

## 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

| Error | Cause | Fix |
|---|---|---|
| `The topicName field is invalid` | Missing `/event/` or `/data/` prefix, or wrong suffix | Use the full path format from the table above |
| `The topicName field is invalid` | Referenced event/channel does not exist in the org | Create the platform event or channel first |

# Update Constraints for ManagedEventSubscription

## Fields That Can Be Updated

| Field | Notes |
|-------|-------|
| `<label>` | Can be changed at any time |
| `<state>` | Toggle between `RUN` and `STOP` — `PAUSE` is reserved for internal use and will be rejected |
| `<defaultReplay>` | Can be changed, but see warning below |
| `<errorRecoveryReplay>` | Can be changed at any time |

## Fields That Cannot Be Changed After Creation

| Field | Why |
|-------|-----|
| `<topicName>` | Changing the channel requires delete + recreate; the platform ties replay state to the original channel |
| DeveloperName (filename) | Renaming requires delete + recreate; rename-in-place is not supported by the Metadata API |

## 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