Step-by Step guide to run the Stream migration tool
If you have questions or feedback about the migration tool you can join our Customer Office Hours to talk directly with our engineering team.
Review the Stream (Classic) retirement timeline as some of the dates have been extended to give customers more time for migration.
The article provides step by step guidance on running the migration tool. Before reading the article we advise you to go through, Understand the tool article, which describes concepts of the migration tool.
The tool can be accessed from either of the three places:
- Stream admin center: Stream migration --> Migration tool --> Launch migration tool.
- Microsoft admin center: Set up --> Migrations --> Microsoft Stream.
- [NOT RECOMMENDED. Soon to be deprecated]: SharePoint admin center: Migrations -->Stream tile.
You'll need SharePoint or Global admin credentials to access the migration tool from either SharePoint or Microsoft admin center.
Step 1: Sign in to the Stream Admin Center. Navigate to Stream Migration > Migration tool. Read the documentation and familiarize yourself with the migration process.
Step 2: You can either go to Settings to display a message to your Stream (Classic) users or select Launch Migration tool button.
Step3: Once you select Launch Migration tool button, you land on the Stream connector inside Migration Manager. If you are on global admin cred, it triggers SSO. Otherwise, you would need SharePoint admin credentials. Once you land on the screen, you notice first-run experience (FRE) steps and a Take the tour button.
The screen indicates content is loading as we search your organization for Stream (Classic) content to migrate.
*Note: If you see a green dot on top right corner of your screen, it shows Stream is successfully connected. If it isn't green, the tool won't work. You may need to add the following URLs to allowlist.
https://api.microsoftstream.com/. If you are a GCC tenant, in addition to these two URLs, please also add to allowlist
Note: Migration manager tab and hence the Stream connector is soon going to move to Microsoft admin center, but either SharePoint or global admin credentials work.
Once you're in the Stream connector, you notice two tabs: Scans and Migrations. The Scans tab lets you review the content in the tenant. Migrations is where you migrate videos.
Note: It may take up to 15 minutes to load the containers for the first time when you use the tool.
Step 5: Content keeps loading until 49,500 rows or containers are discovered. Scans tab can load maximum of 50,000 rows. If your organization has more 49,500 container, you need to migrate first 49,500, delete those, and then discover remaining containers. Refer to Migration nuances for large customers section below for details.
Once the first set of containers is discovered, the Take the tour button is enabled. Selecting it displays where on screen each action of the migration process takes place.
The Scans tab displays one line item for every container that exists in the tenant. If the container has at least one published video. Review your content in the Scans tab to identify which containers to migrate.
Scans tab features include:
|Gives an overview of your container data including number of containers, videos inside them, and video sizes.
|To manually discover containers
|Look for new containers
|Inside ‘Add containers’ pane. Surface any new containers added after the last scan.
|Specify single container
|Inside ‘Add containers’ pane. Add a single container path to discover it manually
|Upload a CSV
|Inside ‘Add containers’ pane. Add multiple container paths in a CSV to discover them manually
|Download the Scan summary.
|Scan and Stop buttons
|Discover videos inside containers. These buttons are contextual and appear when individual containers are selected.
|Appears when a container is selected and shows the logs for videos inside that container. Refer to the Scan log and Summary section for details.
|Filter containers by Container type, Contains meeting recording, and Scan status.
|Search by Container name and Container path.
Step 6: To find videos inside a container, you need to scan it. Select a container and choose Scan Container.
As a container is scanned for videos, its status changes from queued, in-progress, finalizing, to complete.
Step 7: After the scan status changes to complete, select Add to Migrations, and choose continue from the side pane to add containers to the Migrations tab.
When you add containers to migrations tab, you can select custom filters from the side pane to migrate only specific videos within the container. If no filters are selected complete container migrates. Read about partial migration filters
Step 8: Once the containers are added, a message appears at the message bar alongside the search button. Navigate to the Migrations tab to review the containers that have been added.
We have automatically mapped the destination paths for some container types like Microsoft 365 groups and users. You can edit them.
Buttons, Filters, and Search on the Migrations tab perform similarly to how they do on the Scans tab. Migrations tab features include:
|Shows the content that has been migrated. It's nil when you land for the first time on this screen
|Starts migrating a selected container
|Cancels any in-progress migration
|Download report button
|Downloads the migration summary
|An archived container appears in the container list but doesn't migrate when all containers are selected. It comes handy when you want to migrate all but a few containers
|Unarchiving a container allows that container to be migrated
|Download migration logs for videos in a container. For sample report, refer to the Scan log and Summary section for details.
|Filter containers by Migration Status, Contains meeting recording, and Container type.
|Search by Container name and Container path
Step 9: Assign a destination path for a container. Select the Assign destination area for any container and it opens right pane as shown below. Select the destination path from the pane.
Note: You may not see all site in the UI due to permissions. Read the FAQ,'I can’t see some of my SP sites while assigning destinations on UI for a single container'
Once you select Save Path, you see that destination appears for the container. Bulk upload destination paths with the Upload destination paths button. To do so, use the CSV template linked in the side pane.
Note: While setting destination paths, give it until the document library or a folder inside it. Any other path causes an error during migration.
Step 10: Select containers you're ready to migrate then select the Migrate button. And then select Continue from the right pane.
Read the instructions in the right pane. Not all metadata associated with the video migrates. Only critical ones such as Title, description, thumbnails, transcripts and permissions migrate. For complete details, refer to Metadata that migrates with video section.
A container's migration status updates to Complete when it's finished migrating.
Take a look at the error statuses and definitionprovided by the platform to resolve videos with error.
Note: While a video is migrating, it can be viewed, but your users won't be able to edit it. You can use the in-product messaging feature to convey this information.
Step 11: Migrated videos are no longer visible on Stream (Classic) but can be discovered on Stream (on SharePoint). To verify that a video has been properly migrated, select any area on the container row. It opens the side pane and displays the destination hyperlink. Select this hyperlink to open the migrated destination. You can play the migrated video from here and verify.
Verify the permissions on a video by selecting the triple dots next to it and navigating to Manage access.
Note: It may take up to an hour for migrated content to soft delete (or be hidden) from Stream (Classic).
Migrate newly added videos after the container was migrated
- If you didn't stop the ingestion of video in Stream (classic) before you begin migration, there are chances that new videos can be added after the container has migrated. In this case, you don’t need to rescan but remigrate the container from Migrations tab.
- During migration we, match the file name in the destination folder with the files being migrated. So, just running the migration again on the container will migrate any additional video added after the first migration.
- If the name of any file is edited after its first migration, remigrating it may result in duplicate videos in the destination folder.
- Also the tool won’t copy a container with the same name from Scans tabs if that is already present in Migrations. See the screenshots below. As mentioned above customers can simply re-migrate the container from Migrations tab.
- Destination path can't be edited once the container has been migrated. So, the newly added video in a container post migration will also migrate to the same location.
- In case customers need to migrate a container to a new location. They can delete the container from Migrations tab and add it back again from Scans. In this case, they can assign a new destination.
- The container can partially migrate due to two reasons, either the admin did partial migration or it can happen in a few corner scenarios as well.
Match Stream (Classic) data with Inventory report (or Power BI dashboard) & tool
There are three sources of data; Stream (Classic)- Let’s call it A, Inventory Report (or Power BI dashboard)- Let’s call it B and Migration tool- Let’s call it C
- A & B should match perfectly. You'll be able to locate all your video in inventory report. Search for a video via video ID in report. You can find this ID at the end of video playback URL, for example, https://web.microsoftstream.com/video/videoid
- B & C will now also match. Earlier, due to lack of support for orphaned videos in the migration tool (C), B and C would not match.
- A & C won't match due to
- Videos may not appear in the same place in tool as they appear in Stream (Classic). Because the tool moves videos in logical groups or containers. Stream (Classic) videos associated with Microsoft 365 groups, Company channel or Stream group always move together and not move with User's container who uploaded the videos. We follow the priority order; Stream group > Microsoft 365 group > Company wide channel > User. Refer to the permissions cases for more information. So, you may see an uploader’s video moving in Microsoft 365 group and hence may not be visible in the Uploader’s user container of the migration tool
Data deletion from Stream (classic)
Once the video migrates to Stream (on SharePoint), it is ‘soft deleted’ or hidden from Stream (classic). Migrated videos were earlier hard deleted 180 days after migration or soft deleted state. Starting June 30, 2023, they will be hard deleted when Stream (Classic) infra is deprecated. Non-migrated videos will also be hard deleted at the same time.
We're doing this change, so admins can access the migrated destination of the videos via inventory report till redirects work, one year after the Stream (classic) end of life. Migrated destination URLs will help admin change the classic links after their expiry
Note: If your videos were hard deleted before June 30, 2023, they won't appear anymore in the Stream (classic) inventory report
Migrating Nuance for large customers
This section may be important for your organization if you're a large customer with more than 40,000 containers. You need to follow the following steps to migrate correctly
- Select the Launch Migration button from Stream admin center and land on the Scans tab. The auto discovery of the container begins.
- You may choose to migrate from either the discovered list of containers or add a container manually, if the desired containers aren't in the list of discovered ones. Total 50,000 containers can be displayed on the screen, but tool auto-discovers 40,000, to keep a buffer of 10,000 container to be discovered manually, if admin needs.
- Admins need to migrate a batch of containers and then delete them from Scans and Migrations. Once deleted, the migrated containers won't be discovered again by the tool. Wait for one day before deleting migrated videos from both tabs, this ensures that there's no status sync discrepancy between Stream and Migration manager platform
- Discover the next chunk of containers by clicking on Look for new Containers button in right pane, inside Add containers. The number of new containers discovered in the subsequent discovery depends on the quota freed from deleting the migrated containers. The total number of containers that can discovered and added manually can't exceed 40,000 and 10,000 respectively. These limits can be allotted between the two categories such that the total containers on the UI at any given point can't exceed 50,000.