Migrators Reference

There are currently two types of migrators: browser migrators, and file migrators. Browser migrators will migrate various resources from another browser. A file migrator allows the user to migrate data through an intermediary file (like passwords from a .CSV file).

Browser migrators

MigratorBase class

class MigratorBase()

Shared prototype for migrators.

To implement a migrator: 1. Import this module. 2. Create a subclass of MigratorBase for your new migrator. 3. Override the key static getter with a unique identifier for the browser

that this migrator migrates from.

If the migrator supports multiple profiles, override the sourceProfiles Here we default for single-profile migrator.
Implement getResources(aProfile) (see below).
For startup-only migrators, override startupOnlyMigrator.
Add the migrator to the MIGRATOR_MODULES structure in MigrationUtils.sys.mjs.

MigratorBase.enabled: Returns true if the migrator is configured to be enabled. This is controlled by the browser.migrate.<BROWSER_KEY>.enabled boolean preference.

MigratorBase.startupOnlyMigrator

OVERRIDE IF AND ONLY IF the migrator is a startup-only migrator (For now, that is just the Firefox migrator, see bug 737381). Default: false.

Startup-only migrators are different in two ways: - they may only be used during startup. - the user-profile is half baked during migration. The folder exists,

but it’s only accessible through MigrationUtils.profileStartup. The migrator can call MigrationUtils.profileStartup.doStartup at any point in order to initialize the profile.

MigratorBase.brandImage

type: string

This method should get overridden to return an icon url of the browser to be imported from. By default, this will just use the default Favicon image.

MigratorBase.displayNameL10nID

type: string

This must be overridden to return a Fluent string ID mapping to the display name for this migrator. These strings should be defined in migrationWizard.ftl.

MigratorBase.key

type: string

This must be overridden to return a simple string identifier for the migrator, for example “firefox”, “chrome”, “opera-gx”. This key is what is used as an identifier when calling MigrationUtils.getMigrator.

MigratorBase.canGetPermissions()

Returns:: Promise.<(boolean|string)> –

MigratorBase.getLastUsedDate()

OVERRIDE in order to provide an estimate of when the last time was that somebody used the browser. It is OK that this is somewhat fuzzy - history may not be available (or be wiped or not present due to e.g. incognito mode).

If not overridden, the promise will resolve to the Unix epoch.

Returns:: Promise.<Date> – A Promise that resolves to the last used date.

MigratorBase.getMigrateData(aProfile)

This method returns a number that is the bitwise OR of all resource types that are available in aProfile. See MigrationUtils.resourceTypes for each resource type.

Arguments:

aProfile (object|string) – The profile from which data may be imported, or an empty string in the case of a single-profile migrator.

Returns:

number –

MigratorBase.getPermissions(_win)

Subclasses should implement this if special permissions need to be requested from the user or the operating system in order to perform a migration with this MigratorBase. This will be called only if hasPermissions resolves to false.

The returned Promise will resolve to true if permissions were successfully obtained, and false otherwise. Implementors should ensure that if a call to getPermissions resolves to true, that the MigratorBase will be able to get read access to all of the resources it needs to do a migration.

Arguments:

_win (DOMWindow) – The top-level DOM window hosting the UI that is requesting the permission. This can be used to, for example, anchor a file picker window to the same window that is hosting the migration UI.

Returns:

Promise.<boolean> –

MigratorBase.getResources(_aProfile)

MUST BE OVERRIDDEN.

Returns an array of “migration resources” objects for the given profile, or for the “default” profile, if the migrator does not support multiple profiles.

Each migration resource should provide: - a type getter, returning any of the migration resource types (see

MigrationUtils.resourceTypes).

a migrate method, taking two arguments, aCallback(bool success, object details), for migrating the data for this resource. It may do its job synchronously or asynchronously. Either way, it must call aCallback(bool aSuccess, object details) when it’s done. In the case of an exception thrown from migrate, it’s taken as if aCallback(false, {}) is called. The details argument is sometimes optional, but conditional on how the migration wizard wants to display the migration state for the resource.

Note: In the case of a simple asynchronous implementation, you may find MigrationUtils.wrapMigrateFunction handy for handling aCallback easily.

For each migration type listed in MigrationUtils.resourceTypes, multiple migration resources may be provided. This practice is useful when the data for a certain migration type is independently stored in few locations. For example, the mac version of Safari stores its “reading list” bookmarks in a separate property list.

Note that the importation of a particular migration type is reported as successful if _any_ of its resources succeeded to import (that is, called, aCallback(true, {})). However, completion-status for a particular migration type is reported to the UI only once all of its migrators have called aCallback.

NOTE: The returned array should only include resources from which data can be imported. So, for example, before adding a resource for the BOOKMARKS migration type, you should check if you should check that the bookmarks file exists.

Arguments:

_aProfile (object|string) – The profile from which data may be imported, or an empty string in the case of a single-profile migrator. In the case of multiple-profiles migrator, it is guaranteed that aProfile is a value returned by the sourceProfiles getter (see above).

Returns:

Promise.<Array.<MigratorResource>>|Array.<MigratorResource> –

MigratorBase.getSourceProfiles()

OVERRIDE IF AND ONLY IF the source supports multiple profiles.

Returns array of profile objects from which data may be imported. The object should have the following keys:

id - a unique string identifier for the profile name - a pretty name to display to the user in the UI

Only profiles from which data can be imported should be listed. Otherwise the behavior of the migration wizard isn’t well-defined.

For a single-profile source (e.g. safari, ie), this returns null, and not an empty array. That is the default implementation.

Returns:: Array.<object>|null –

MigratorBase.hasPermissions()

Subclasses should implement this if special checks need to be made to determine if certain permissions need to be requested before data can be imported. The returned Promise resolves to true if the required permissions have been granted and a migration could proceed.

Returns:: Promise.<boolean> –

MigratorBase.isSourceAvailable()

Checks to see if one or more profiles exist for the browser that this migrator migrates from.

Returns:: Promise.<boolean> – True if one or more profiles exists that this migrator can migrate resources from.

MigratorBase.migrate(aItems, aStartup, aProfile, aProgressCallback)

Arguments:

aItems (number) – A bitfield with bits from MigrationUtils.resourceTypes flipped to indicate what types of resources should be migrated.
aStartup (boolean) – True if this migration is occurring during startup.
aProfile (object|string) – The other browser profile that is being migrated from.
aProgressCallback (function|null) – An optional callback that will be fired once a resourceType has finished migrating. The callback will be passed the numeric representation of the resource type followed by a boolean indicating whether or not the resource was migrated successfully and optionally an object containing additional details.

Chrome and Chrome variant migrators

The ChromeProfileMigrator is subclassed ino order to provide migration capabilities for variants of the Chrome browser.

ChromeProfileMigrator class

class ChromeProfileMigrator()

Chrome profile migrator. This can also be used as a parent class for migrators for browsers that are variants of Chrome.

ChromeProfileMigrator._getChromeUserDataPathIfExists(noRemapping=false)

Returns a Promise that resolves to the data path containing the Local State and profile directories for this browser.

Arguments:

noRemapping (boolean) – Set to true to bypass any remapping that might have occurred on platforms where the data path changes once permission has been granted.

Returns:

Promise.<string> –

BraveProfileMigrator class

class BraveProfileMigrator(): Brave migrator

CanaryProfileMigrator class

class CanaryProfileMigrator(): Chrome Canary Not available on Linux

ChromeBetaMigrator class

class ChromeBetaMigrator(): Chrome Beta migrator

ChromeDevMigrator class

class ChromeDevMigrator(): Chrome Dev - Linux only (not available in Mac and Windows)

Chromium360seMigrator class

class Chromium360seMigrator(): Chromium 360 migrator

ChromiumEdgeMigrator class

class ChromiumEdgeMigrator(): Edge (Chromium-based) migrator

ChromiumEdgeBetaMigrator class

class ChromiumEdgeBetaMigrator(): Edge Beta (Chromium-based) migrator

ChromiumProfileMigrator class

class ChromiumProfileMigrator(): Chromium migrator

OperaProfileMigrator class

class OperaProfileMigrator(): Opera migrator

OperaGXProfileMigrator class

class OperaGXProfileMigrator(): Opera GX migrator

VivaldiProfileMigrator class

class VivaldiProfileMigrator(): Vivaldi migrator

EdgeProfileMigrator class

class EdgeProfileMigrator()

Edge (EdgeHTML) profile migrator

EdgeProfileMigrator.getSourceProfiles()

Returns:: Array|null – Somewhat counterintuitively, this returns null to indicate “There is only 1 (default) profile”. See MigrationUtils.sys.mjs for slightly more info on how sourceProfiles is used.

FirefoxProfileMigrator class

class FirefoxProfileMigrator()

Firefox profile migrator. Currently, this class only does “pave over” migrations, where various parts of an old profile overwrite a new profile. This is distinct from other migrators which attempt to import old profile data into the existing profile.

This migrator is what powers the “Profile Refresh” mechanism.

IEProfileMigrator class

class IEProfileMigrator(): Internet Explorer profile migrator

File migrators

FilePickerConfigurationFilter()

Arguments:

title (string) – The title for the filter. Example: “CSV Files”
extensionPattern (string) – A matching pattern for the filter. Example: “*.csv”

FilePickerConfiguration()

Arguments:

title (string) – The title that should be assigned to the native file picker window.
filters (Array.<FilePickerConfigurationFilter>) – One or more extension filters that should be applied to the native file picker window to make selection easier.

FileMigratorBase class

class FileMigratorBase()

Base class for a migration that involves reading a single file off of the disk that the user picks using a file picker. The file might be generated by another browser or some other application.

FileMigratorBase.displayedResourceTypes

type: Array.<string>

Returns a list of one or more resource types that should appear to be in progress of migrating while the file migration occurs. Notably, this does not need to match the resource types that are returned by FileMigratorBase.migrate.

FileMigratorBase.enabled

type: boolean

Returns true if the migrator is configured to be enabled.

FileMigratorBase.progressHeaderL10nID

type: string

This getter should be overridden to return a Fluent string ID for what the migration wizard header should be while the file migration is underway.

FileMigratorBase.successHeaderL10nID

type: string

This getter should be overridden to return a Fluent string ID for what the migration wizard header should be while the file migration is done.

FileMigratorBase.brandImage

type: string

This getter should get overridden to return an icon url to represent the file to be imported from. By default, this will just use the default Favicon image.

FileMigratorBase.displayNameL10nID

type: string

This must be overridden to return a Fluent string ID mapping to the display name for this migrator. These strings should be defined in migrationWizard.ftl.

FileMigratorBase.key

type: string

This must be overridden to return a simple string identifier for the migrator, for example “password-csv”. This key is what is used as an identifier when calling MigrationUtils.getFileMigrator.

FileMigratorBase.getFilePickerConfig()

A subclass of FileMigratorBase will eventually open a native file picker for the user to select the file from their file system.

Subclasses need to override this method in order to configure the native file picker.

Returns:: Promise.<FilePickerConfiguration> –

FileMigratorBase.migrate(_filePath)

Called to perform the file migration once the user makes a selection from the native file picker. This will not be called if the user chooses to cancel the native file picker.

Arguments:

_filePath (string) – The path that the user selected from the native file picker.

PasswordFileMigrator class

class PasswordFileMigrator(): A file migrator for importing passwords from CSV or TSV files. CSV files are more common, so this is what we show as the file type for the display name, but this FileMigrator accepts both.