PlatformEventMigration

Represents configuration settings for a migration from standard volume platform events to high volume platform events.

Important

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

PlatformEventMigration components have the suffix .platformEventMigration and are stored in the PlatformEventMigrations folder.

Version

PlatformEventMigration components are available in API version 67.0 and later.

Fields

Field Name	Description
endDate	Field Type datetime Description Read-only. The date and time when the platform event migration finished.
eventObject	Field Type string Description Required. The API name of the standard volume platform event that needs to be migrated to a high volume platform event.
highVolumePosition	Field Type int Description Read-only. The replay ID that marks where subscribers can begin reading events on the high-volume event stream after the migration finishes.
masterLabel	Field Type string Description Required. The label for the PlatformEventMigration component.
migrationStatus	Field Type picklist Description Read-only. Indicates where the migration is in its lifecycle. Options are Migrating to indicate the event is currently being migrated, or Completed to indicate the migration has finished.
startDate	Field Type datetime Description Read-only. The date and time when the platform event migration started.

Declarative Metadata Sample Definition

The following is an example of a PlatformEventMigration component.

        <?xml version="1.0" encoding="UTF-8"?>
        <PlatformEventMigration xmlns="http://soap.sforce.com/2006/04/metadata">
          <masterLabel>My Event Migration</masterLabel>
          <eventObject>MyEvent__e</eventObject>
        </PlatformEventMigration>

The following is an example package.xml that references the previous definition.

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

Usage

To use the Metadata API to start a migration of a standard volume platform event to a high volume platform event, follow these steps.

Before starting a migration, ensure all publish activity has stopped and all subscribers, including triggers and flows, are done processing.
Next, create a .zip file containing the configuration data. Create a working directory on your desktop: ~/Desktop/MyMigrationConfig Inside this directory, create another directory ~/Desktop/MyMigrationConfig/platformEventMigrations. Inside of that directory, create the file ~/Desktop/MyMigrationConfig/platformEventMigrations/MyEventMigration.platformEventMigration Next and paste this XML as the body of that file and modify the eventObject element to match your standard volume platform event’s API name.
```
            <?xml version="1.0" encoding="UTF-8"?>
            <PlatformEventMigration xmlns="http://soap.sforce.com/2006/04/metadata">
              <masterLabel>My Event Migration</masterLabel>
              <eventObject>MyEvent__e</eventObject>
            </PlatformEventMigration>
          
```
masterLabel can be any string. eventObject must be the API name of the standard volume platform event that you want to migrate to a high volume platform event.

Create the file ~/Desktop/MyMigrationConfig/package.xml and paste this XML as the body of that file.

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

members should contain the name of the previously created file without the .platformEventMigration extension. version must be 67.0 or higher.

Create a .zip file out of your configuration files. On Windows:
1. Select both the platformEventMigrations folder and package.xml file
2. Right-click → Send to → Compressed (zipped) folder
3. Name it migration-config.zip
On Mac:
1. Open Terminal (Applications → Utilities → Terminal)
2. Navigate to your Desktop
```
cd ~/Desktop
```
3. Create a clean ZIP without hidden files
```
zip -r migration-config.zip MyMigrationConfig -x "*.DS_Store" -x "__MACOSX"
```
On Linux:
1. Open a terminal
2. Navigate to the MyMigrationConfig folder
```
cd ~/Desktop/MyMigrationConfig
```
3. Create the .zip file
```
zip -r migration-config.zip platformEventMigrations package.xml
```

Using the Salesforce CLI, log in to your org.

sf org login web --instance-url $URL --alias my-org

Using the Salesforce CLI, upload your .zip file.

sf project deploy start --metadata-dir migration-config.zip --target-org my-org

Using the Salesforce CLI, get info about your deployment.
```
sf project deploy report --use-most-recent
```
To check the status of the migration, in Salesforce click the gear icon → Developer Console. Click "Query Editor" tab. Check "Use Tooling API" checkbox. Run this query after replacing the value for DeveloperName with the value you used:
```
            SELECT Id, DeveloperName, MasterLabel, EventObject, MigrationStatus, StartDate, EndDate, HighVolumePosition
            FROM PlatformEventMigration
            WHERE DeveloperName = 'MyEventMigration'
          
```
You should see your configuration record with: Your MasterLabel, EventObject = Your Platform Event, MigrationStatus = 'MIGRATING' (initially). MigrationStatus will change to COMPLETED when the migration is complete. You’ll also receive an email when the migration is complete. While the migration is running, publishes won’t work and you’ll be unable to create new triggers or flows until the migration finishes.