PlatformEventMigration

Parent Type

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

Declarative Metadata Sample Definition

The following is an example of a PlatformEventMigration component.

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

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

1<?xml version="1.0" encoding="UTF-8"?>
2        <Package xmlns="http://soap.sforce.com/2006/04/metadata">
3          <types>
4            <members>MyEventMigration</members>
5            <name>PlatformEventMigration</name>
6          </types>
7          <version>67.0</version>
8        </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.

1. Before starting a migration, ensure all publish activity has stopped and all subscribers, including triggers and flows, are done processing.
2. 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.
   1<?xml version="1.0" encoding="UTF-8"?>
   2            <PlatformEventMigration xmlns="http://soap.sforce.com/2006/04/metadata">
   3              <masterLabel>My Event Migration</masterLabel>
   4              <eventObject>MyEvent__e</eventObject>
   5            </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.
3. Create the file ~/Desktop/MyMigrationConfig/package.xml and paste this XML as the body of that file.
   1<?xml version="1.0" encoding="UTF-8"?>
   2            <Package xmlns="http://soap.sforce.com/2006/04/metadata">
   3              <types>
   4                <members>MyEventMigration</members>
   5                <name>PlatformEventMigration</name>
   6              </types>
   7              <version>67.0</version>
   8            </Package>

   members should contain the name of the previously created file without the .platformEventMigration extension. version must be 67.0 or higher.
4. 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
      1cd ~/Desktop

   3. Create a clean ZIP without hidden files
      1zip -r migration-config.zip MyMigrationConfig -x "*.DS_Store" -x "__MACOSX"

   On Linux:
   1. Open a terminal
   2. Navigate to the MyMigrationConfig folder
      1cd ~/Desktop/MyMigrationConfig

   3. Create the .zip file
      1zip -r migration-config.zip platformEventMigrations package.xml

5. Using the Salesforce CLI, log in to your org.
   1sf org login web --instance-url $URL --alias my-org

6. Using the Salesforce CLI, upload your .zip file.
   1sf project deploy start --metadata-dir migration-config.zip --target-org my-org

7. Using the Salesforce CLI, get info about your deployment.
   1sf project deploy report --use-most-recent

8. 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:
   1SELECT Id, DeveloperName, MasterLabel, EventObject, MigrationStatus, StartDate, EndDate, HighVolumePosition
   2            FROM PlatformEventMigration
   3            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.