Configuration

The Migration SDK uses two sources of configuration in two blocks: the Migration Plan that contains configuration for a specific migration run, and Migration SDK Options for configuration that is unlikely to change between migration runs.

Configuration Blocks

Migration Plan

The migration plan is a required input in the migration process. It will define the Source and Destination servers and the hooks executed during the migration. Consider the Migration Plan as the steps the Migration SDK will follow to migrate the information from a given Source Server to a given Destination Server.

The IMigrationPlan interface defines the Migration Plan structure. And the easiest path to generate a new Migration Plan is the IMigrationPlanBuilder implementation MigrationPlanBuilder. For that, it is needed a few steps before building a new plan:

Define the required Source server.
Define the required Destination server.
Define the required Migration Type.
Add supplementary hooks.

Source

Optional/Required: Required.

Description: The method MigrationPlanBuilder.FromSourceTableauServer will define the source server by instantiating a new TableauSiteConnectionConfiguration with the following parameters:

serverUrl: Required.
siteContentUrl: Optional.
accessTokenName: Required.
accessToken: Required.

Important

Personal access tokens (PATs) are long-lived authentication tokens that allow you to sign in to the Tableau REST API without requiring hard-coded credentials or interactive sign-in. Revoke and generate a new PAT every day to keep your server secure. Access tokens should not be stored in plain text in application configuration files, and should instead use secure alternatives such as encryption or a secrets management system. If the source and destination sites are on the same server, separate PATs should be used.

Destination

Optional/Required: Required.

Description: The method MigrationPlanBuilder.ToDestinationTableauCloud will define the destination server by instantiating a new TableauSiteConnectionConfiguration with the following parameters:

podUrl: Required.
siteContentUrl: Required. This is the site name on Tableau Cloud.
accessTokenName: Required.
accessToken: Required.

Important

Personal access tokens (PATs) are long-lived authentication tokens that allow you to sign in to the Tableau REST API without requiring hard-coded credentials or interactive signin. Revoke and generate a new PAT every day to keep your server secure. Access tokens should not be stored in plain text in application configuration files, and should instead use secure alternatives such as encryption or a secrets management system. If the source and destination sites are on the same server, separate PATs should be used.

Migration Type

Optional/Required: Required.

Description: The method MigrationPlanBuilder.ForServerToCloud will define the migration type and load all default hooks for a Server to Cloud migration.

Add Hooks

Optional/Required: Optional.

Description: The Plan Builder exposes the properties MigrationPlanBuilder.Hooks, MigrationPlanBuilder.Filters, MigrationPlanBuilder.Mappings, and MigrationPlanBuilder.Transformers. With these properties, it is possible to adjust a given migration plan for specific scenarios. For more details, see the Custom Hooks article.

Build

Optional/Required: Required.

Description: The method MigrationPlanBuilder.Build will generate a Migration Plan ready to be used as an input to a migration process.

Migration SDK Options

MigrationSdkOptions is the configuration class the Migration SDK uses internally to process a migration. It contains adjustable properties that change some engine behaviors. These properties are useful tools to troubleshoot and tune a migration process. Start with this class and others in the Config section for more details.

When writing a C# application, we recommend using a .NET Generic Host to initialize the application. This will enable setting configuration values via appsettings.json which can be passed into userOptions in .AddTableauMigrationSdk. See .NET getting started examples for more info.

When writing a python application, configuration values are set via environment variables. The : delimiter doesn't work with environment variable hierarchical keys on all platforms. For example, the : delimiter is not supported by Bash. The double underscore (__), which is supported on all platforms, automatically replaces any : delimiters in environment variables. All configuration environment variables start with MigrationSDK__.

ContentTypes

Reference: MigrationSdkOptions.ContentTypesOptions.

This is an array of MigrationSdkOptions.ContentTypesOptions. Each array object corresponds to settings for a single content type.

Important

The type values are case-insensitive. Duplicate type key values will result in an exception.

In the following json example config file,

A BatchSize of 201 is applied to the content type User.
A BatchSize of 203 for Project.
A BatchSize of 200 for ServerExtractRefreshTask.

{
    "MigrationSdkOptions": {
        "contentType": [
        {
            "type":"User",
            "batchSize": 201            
        },        
        {
            "type":"Project",
            "batchSize": 203            
        },
        {
            "type":"ServerExtractRefreshTask",
            "batchSize": 200
        }
        ],
    }
}

Python Environment Variables:

MigrationSDK__ContentTypes__<array index>__<content type config key>__Type.
MigrationSDK__ContentTypes__<array index>__<content type config key>__BatchSize.

Here is an example of environment variables you would set. This is equivalent to the previous json example. Note the array indexes. They tie the setting values together in the Migration SDK.

MigrationSDK__ContentTypes__0__Type = User
MigrationSDK__ContentTypes__0__BatchSize = 201
MigrationSDK__ContentTypes__1__Type = Project
MigrationSDK__ContentTypes__1__BatchSize = 203

The following sections describe each setting. They should always be set per content type as described previously. If a setting below is not set for a content type, the Migration SDK falls back to the default value.

ContentTypes.Type

Reference: MigrationSdkOptions.ContentTypes.Type.

Default: blank string.

Reload on Edit?: Yes. The update will apply next time the Migration SDK requests a list of objects.

Description: For each array object, the type key determines which content type the settings apply to. Only supported content types will be considered and all others will be ignored. This key comes from the interface for the content type. This is determined by MigrationPipelineContentType.GetConfigKey(). For example, the key for IUser is User. Content type type values are case insensitive.

ContentTypes.BatchSize

Reference: MigrationSdkOptions.ContentTypes.BatchSize.

Default: MigrationSdkOptions.ContentTypes.Defaults.BATCH_SIZE.

Reload on Edit?: Yes. The update will apply next time the Migration SDK requests a list of objects.

Description: The Migration SDK uses the BatchSize property to define the page size of each List Request. For more details, see the Tableau REST API Paginating Results documentation.

ContentTypes.BatchPublishingEnabled

Reference: MigrationSdkOptions.ContentTypes.BatchPublishingEnabled.

Default: MigrationSdkOptions.ContentTypes.Defaults.BATCH_PUBLISHING_ENABLED.

Reload on Edit?: Yes. The update will apply next time the Migration SDK starts migrating a given content type.

Description: The Migration SDK uses the BatchPublishingEnabled property to select the mode it will publish a given content type. Disabled by default, with this configuration, the SDK will publish the content by using individual REST API calls for each item. When this option is enabled, it is possible to publish content in a batch of items (just for some supported content types).

Supported Content Types:

User by using the method Import Users to Site from CSV;

MigrationParallelism

Reference: MigrationSdkOptions.MigrationParallelism.

Default: MigrationSdkOptions.Defaults.MIGRATION_PARALLELISM.

Python Environment Variable: MigrationSDK__MigrationParallelism

Reload on Edit?: Yes. The update will apply the next time the Migration SDK publishes a new batch.

Description: The Migration SDK uses two methods to publish the content to a destination server: the bulk process, where a single call to the API will push multiple items to the server, and the individual process, where it publishes a single item with a single call to the API. This configuration only applies to the individual process. The SDK uses the MigrationParallelism property to define the number of parallel tasks migrating the same type of content simultaneously. It is possible to tune the Migration SDK processing time with this configuration.

Warning

There are concurrency limits in REST APIs on Tableau Cloud. The current default configuration is the balance between performance without blocking too many resources to the migration process.

Files.DisableFileEncryption

Reference: FileOptions.DisableFileEncryption.

Default: FileOptions.Defaults.DISABLE_FILE_ENCRYPTION.

Python Environment Variable: MigrationSDK__Files__DisableFileEncryption

Reload on Edit?: Yes. The update will apply the next time the Migration SDK executes a migration plan.

Description: As part of the migration process, the Migration SDK has to adjust existing references for file-based content types like Workbooks and Data Sources. The SDK has to download and temporarily store the content in the migration machine to be able to read and edit these files. The Migration SDK uses the DisableFileEncryption property to define whether it will encrypt the temporary file.

Caution

Do not disable file encryption when migrating production content.

Files.RootPath

Reference: FileOptions.RootPath.

Default: FileOptions.Defaults.ROOT_PATH.

Python Environment Variable: MigrationSDK__Files__RootPath

Reload on Edit?: Yes. The update will apply the next time the Migration SDK executes a migration plan.

Description: As part of the migration process, the Migration SDK has to adjust existing references for file-based content types like Workbooks and Data Sources. The SDK has to download and temporarily store the content in the migration machine to be able to read and edit these files. The Migration SDK uses the RootPath property to define the location where it will store the temporary files.

Network.FileChunkSizeKB

Reference: NetworkOptions.FileChunkSizeKB.

Default: NetworkOptions.Defaults.FILE_CHUNK_SIZE_KB.

Python Environment Variable: MigrationSDK__Network__FileChunkSizeKB

Reload on Edit?: Yes. The update will apply the next time the Migration SDK publishes a new file.

Description: As part of the migration process, the Migration SDK has to publish file-based content types like Workbooks and Data Sources. Some of these files are very large. The Migration SDK uses the FileChunkSizeKB property to split these files into smaller pieces, making the publishing process more reliable. For more details, see the Tableau REST API Publishing Resources documentation.

Network.HeadersLoggingEnabled

Reference: NetworkOptions.HeadersLoggingEnabled.

Default: NetworkOptions.Defaults.LOG_HEADERS_ENABLED.

Python Environment Variable: MigrationSDK__Network__HeadersLoggingEnabled

Reload on Edit?: Yes. The update will apply the next time the Migration SDK logs a new HTTP request.

Description: See the logging article for more details.

Network.ContentLoggingEnabled

Reference: NetworkOptions.ContentLoggingEnabled.

Default: NetworkOptions.Defaults.LOG_CONTENT_ENABLED.

Python Environment Variable: MigrationSDK__Network__ContentLoggingEnabled

Reload on Edit?: Yes. The update will apply the next time the Migration SDK logs a new HTTP request.

Description: See the logging article for more details.

Network.BinaryContentLoggingEnabled

Reference: NetworkOptions.BinaryContentLoggingEnabled.

Default: NetworkOptions.Defaults.LOG_BINARY_CONTENT_ENABLED.

Python Environment Variable: MigrationSDK__Network__BinaryContentLoggingEnabled

Reload on Edit?: Yes. The update will apply the next time the Migration SDK logs a new HTTP request.

Description: See the logging article for more details.

Network.ExceptionsLoggingEnabled

Reference: NetworkOptions.ExceptionsLoggingEnabled.

Default: NetworkOptions.Defaults.LOG_EXCEPTIONS_ENABLED.

Python Environment Variable: MigrationSDK__Network__ExceptionsLoggingEnabled

Reload on Edit?: Yes. The update will apply the next time the Migration SDK logs a new HTTP request.

Description: See the logging article for more details.