Run Your Migration
🕐 5 min read
Before you begin using the SDK, it is essential that you complete the Pre-Migration Checklist. If you don’t complte these items, the migration might not be successful.
Operation order
To successfully migrate, you must understand and follow the order of operations that the Migration SDK uses. Many concepts build on each other and are prerequisites for later steps. For example, projects must be migrated to Tableau Cloud before workbooks in order for workbooks to be published into a project. See the following order of operations to see the order of operations of a migration.
When content is migrated from Tableau Server to Tableau Cloud, the Migration SDK will do a number of things to automate transformation in flight. One of these things is to map users across environments.
On Tableau Server, a username might not be an email. On Tableau Cloud, a username must be a valid email address. For example, John Smith may appear as jsmith on Tableau Server but will be johnsmith@tableau.com on Tableau Cloud. However, things like asset ownership and Tableau permissions assigned to John Smith must follow the user across both environments. We rely on user mapping to ensure that users own the same content on both environments and have access to the same content in both environments.
When a content item is migrated, it generally follows the same migration pattern. The following is a high-level overview of that pattern.
- List: Get a list of content items from the source.
- Map: Map source content items to destination content items.
- Filter: Filter any content items that should not be migrated. Outside of the default filters that the Migration SDK applies, everything is migrated if filters are not provided.
- Pull: Pull any additional information from the source that is required to publish the content item.
- Transform: Change certain properties within the content items to account for things such as server-cloud differences.
- Publish: Publish the content item prepared using the previous steps, to the destination.
- Post-Publish: Perform operations on the destination based so the content items correctly contain properties such as ownership, permissions etc.
There are known exceptions to this pattern such as batch operations, but those exceptions start from this framework as the baseline.
Migration timing
Tableau Cloud undergoes periodic maintenance to sustain the infrastructure supporting Tableau Cloud services. Please review the reserved system maintenance schedule to ensure you do not attempt a migration during reserved system maintenance windows. If Tableau Cloud is unavailable when you attempt a migration, the migration will fail.
Tableau Cloud undergoes major upgrades three times a year. We recommend that you plan your migration to complete before or after an upgrade window. See the quarterly release schedule to understand more about Tableau Cloud upgrades and how to plan around them.
Understanding a migration run
To help you understand what took place in a migration run, the Migration SDK outputs a manifest file as part of the migration result. This manifest catalogs the items that successfully migrated to Tableau Cloud and their current destination on the site.
Logging is also available for the Migration SDK. For more details, see the Migration SDK API Reference documentation.