Run a Migration

1. Activate your license

The very first screen asks for your MigrateStream license key. Paste it in and continue. Once verified, the key is remembered in this browser, so you will not be asked again on future visits unless it changes or expires.

If you do not have a key yet, or you want to know what one covers and where it comes from, see Your license key on the setup page.

2. Connect Salesforce and Google Drive

Log in with Salesforce first (a normal redirect to Salesforce's own login page - MigrateStream never sees your password). Once connected, connect Google Drive from the step that follows - a popup window opens Google's own consent screen. MigrateStream only ever requests the drive.file scope: it can only see files and folders it creates or that you explicitly pick, never your whole Drive.

The connect step, with Salesforce already connected.

If Salesforce refuses the login, or the app reports that it cannot read data from your org, the org's one-time setup has not been done. See If it does not connect.

3. Choose which files to migrate

Pick a scope - either every file in the org, or files linked to one or more specific objects (with live counts and total size shown before you commit to anything). An advanced filter lets you type your own SOQL condition (for example, only files modified in the last 30 days) with a live preview of how many files and how much data that narrows things down to. From there, an optional refinement table lets you browse the exact file list and exclude specific ones - each row's file name and linked record both link straight to the real record in Salesforce, and a file linked to more than one record shows a tooltip noting there are others.

Choosing a scope, with live counts before you commit.

The advanced filter box takes just the condition part of a query - the part that would normally follow WHERE - not a full query. MigrateStream already supplies its own SELECT/FROM/base condition, so:

• Valid: LastModifiedDate = LAST_N_DAYS:30
• Valid: FileType = 'PDF' AND ContentSize > 1000000
• Not valid: SELECT Id FROM ContentVersion WHERE FileType = 'PDF' - remove the SELECT/FROM part; type only the condition after WHERE.
• Not valid: anything with LIMIT, ORDER BY, GROUP BY, or OFFSET - these control the whole query, not a single condition, so they aren't accepted here.

A trailing semicolon (a common leftover from testing a query in Developer Console first) is stripped automatically - you don't need to remove it yourself. Any of these problems is explained in plain language right where you typed the filter, before anything is sent to Salesforce.

4. Choose where the files go

Pick the destination folder, and optionally have MigrateStream sort files into subfolders for you instead of putting every file in one place.

The destination step. Folder mapping is optional.

• Pick a folder in My Drive or a Shared Drive using Google's own folder picker.
• Need a brand new folder? Google's picker can only choose a folder that already exists.
  • Once you have picked a folder, type a name into the optional "Create a subfolder here" field.
  • Clicking Continue creates it inside the folder you picked.
  • That new subfolder then becomes the actual destination, and the summary screen shows it as such.
  • Leave the field blank to migrate straight into the folder you picked.
• Using Firefox and the picker shows an error? For example, "The API developer key is invalid".
  • This is a Firefox privacy setting, not a MigrateStream problem: Enhanced Tracking Protection can stop Google's picker from verifying your session.
  • To fix it, click the shield icon in your address bar, turn off Enhanced Tracking Protection for this site, and try again.
• Optionally, sort files into subfolders automatically instead of putting every file in one place.
• Every object in your selection gets mapped, not just one. If your selection spans more than one object (Accounts and Cases, for example), you get one row per object, each with its own field to name subfolders by.
• What the folder structure looks like:
  • Each mapped object gets its own folder inside the destination, named after the object (for example, "Account").
  • Inside that, one subfolder per distinct value of the field you chose (for example, "Acme Corp").
  • A record whose chosen field is blank gets an "Unfiled" subfolder inside its own object's folder.
  • A file with no link to any mapped object at all goes to a shared "Unfiled" folder at the destination's top level instead.
• See exactly where files will land before you start: a live example appears under each row.
• Blank values are counted for you. If any records have a blank value in the field you chose, the summary step tells you how many before you commit to running the migration.
• Records that share a name never collide. An Account and a Case both named "Acme" stay separate, because each object's folder keeps its own records.
• Mapping is by field value, not by individual record. Two different Account records that share the exact same value in your chosen field will share one folder.
  • Want a separate folder per record regardless of shared values? Choose Id as the naming field. Every record's Id is unique, so this always gives one folder per record.

5. Review the summary, then start

• The summary screen shows file count, total size, the largest file, and a time estimate.
• Preparing the summary takes a while on a large selection. Before Start Migration unlocks, MigrateStream checks your selection against Salesforce and checks your destination for files already migrated. On a selection of several thousand files that is minutes, not seconds, and the screen names each phase as it runs rather than sitting on one static line.
• The same screen shows your current license usage against your data cap, so you can see up front whether this run fits within your license.

6. While it runs

• A persistent stepper above the screen shows where you are in the overall flow once the run starts.
• The run screen is a live table. Every file appears up front and updates in place.
  • Each file moves through planned, migrating, migrated, skipped, or failed.
  • A row of live counts sits next to the progress ring, so the run's shape is readable at a glance.
  • Migrated and skipped files' names link straight to the file in Google Drive.
• Pause and resume at any point. Pause shows an immediate "Pausing, finishing current file..." state, then becomes available to resume once nothing is left in flight.
• Cancel asks for a single confirmation, then stops cleanly.
• If your Google or Salesforce session needs reconnecting mid-run, MigrateStream pauses and asks you to reconnect rather than failing anything.
• A brief network interruption recovers on its own (a Wi-Fi drop, or a background browser tab being throttled).
  • It is called out in the warnings panel once it recovers, rather than failing the file.
  • Only a genuinely permanent failure counts against the Failed total.
• Keep the tab in the foreground for the fastest transfer. Browsers do slow down background tabs' network activity. The run screen reminds you of this too.

The run screen. Every file is listed up front and updates in place.

7. When it finishes, and your report

• When it finishes, download the CSV report, and retry only the files that failed if there were any.
• Or use "Rerun Same Selection" or "Start a New Migration" to go again.

The completion screen, with the report ready to download.

The downloadable Migration Report CSV is more detailed than the on-screen run table, built for a support investigation or an audit trail rather than a glance.

• Its columns, always in this exact order: File Name, Extension, Size (bytes), ContentDocumentId, ContentVersionId, Linked Record Id, Linked Record Name, Linked Object, Linked Record Count, Source Org Id, Status, Destination Folder Path, Drive File Name, Drive File Id, Drive Link, Started At, Completed At, Error.
• File Name is the file's title in Salesforce; Drive File Name is what the file is actually called in Google Drive, as reported by Drive at upload. They differ when the Salesforce title has no extension: the migration appends the file's real extension so the file opens correctly, and never changes a title that already ends with it. Drive File Name is blank for rows that uploaded nothing this run, such as skipped files, which keep the name they already had.
• On a migration using per-record subfolders, a migrated row's Linked Record columns show the link that decided its folder; the Linked Record Name is then the value of the naming field you chose, which is the record's name whenever the Name field was chosen. Linked Record Count says how many linked records the file had among your selected objects; a count of 2 or more means other links existed that did not decide the folder.
• One caution when re-running a migration: a file changed in Salesforce after it was migrated is not re-pulled by a Skip run, so verify any file you have edited since. This note used to be appended inside the CSV itself and is now here and on screen at export instead, so the file stays plain data.
• A file with no linked record (an "All Files" scope run, or a file genuinely not linked to anything) simply leaves the three Linked columns blank.
• A file the run never got to (cancelled mid-run, or left over after a cancelled run) leaves Started At and Completed At blank too, rather than a made-up value.

Running it again later

• Re-running automatically skips files already migrated. Files are matched by the file itself, not its name, so a Google Doc or Sheet you renamed afterward is still recognized correctly. The check looks across the whole destination rather than only the subfolder a file would land in, so a file already migrated is recognized even if your folder naming has changed since.
• Re-running does not pull content updates. If a file's content changes in Salesforce after it has already been migrated, re-running does not detect or pull that update. This tool moves files, it does not keep two systems in sync over time.